---
slug: "external/accounts/setup"
version: "0.1"
title: "External Accounts — Setup"
summary: "A manager obtains, generated by the key custodian, exactly what to configure at the provider for an external account: certificates, key sets, policies and the commands that apply them."
status: "draft"
targetFrameworkVersion: "0.6.0"
category: "key-management"
parties:
  - role: "Account manager"
    requirement: "REQUIRED"
    member: "issuer"
    identifierScope: "any"
  - role: "Key custodian"
    requirement: "REQUIRED"
    member: "recipient"
proofRequirement:
  requirement: "RECOMMENDED"
  rationale: "Authority is the caller's standing at the custodian, which a verified proof or a transport-authenticated sender establishes. A proof is recommended so the read is attributable on every transport, relayed ones included."
sideEffects:
  level: "none"
  rationale: "Generates text from the account. Persists nothing, and never contacts the provider."
exposure:
  discloses: "metadata"
  ingests: "none"
  actsAsSubject: false
  rationale: "Discloses public material — a CA certificate, a JWKS, a certificate — and provider policies and commands derived from the account's settings and bindings. No private key, no secret."
retention:
  class: "transient"
  rationale: "Regenerated on demand; nothing stored."
errorCodes:
  - code: "external:notFound"
    meaning: "No account with this id exists in the named context that the caller may see. See the family conventions §2."
    retryable: false
related:
  - "external/accounts/create"
  - "external/accounts/probe"
  - "external/accounts/keys/rotate"
---

## Abstract

An account becomes usable when its provider trusts the custodian's key. The **External Accounts — Setup** Trust Task returns what that takes, **generated** from the account rather than written by hand:

- **`aws-roles-anywhere`**: the trust anchor's CA certificate and the `aws rolesanywhere` commands; a role whose trust policy accepts only this account's certificate subject; a permissions policy at the bindings' ceiling; the current CRL and its `import-crl` command.
- **`gcp-wif-pinned`**: the JWKS file and the `gcloud iam workload-identity-pools … create-oidc --jwk-json-path` commands, with an attribute condition on the token subject; the bucket IAM binding.
- **`azure-cert`**: the certificate and `az ad app credential reset --cert`; the role assignment.
- **`oauth2-private-key-jwt`**: the public key to register; **`sui-signer`**: the address to fund.

The custodian never asks for the provider's administrator credentials, and nobody types an identifier into a trust policy by hand. Every model is **pinned** — the provider holds the custodian's public material — so none of it makes the custodian reachable from the internet ([conventions §3](../../../_shared/0.1/CONVENTIONS.md#3-network-exposure)).

## Status of this Document

This specification is a **draft** ([SPEC §5.3](/SPEC.md#53-maturity-levels)). It targets framework version 0.6.0 and may change without a version bump while it remains a draft ([SPEC §5.2](/SPEC.md#52-compatibility-rules)).

## Conformance

The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **MAY** and **OPTIONAL** in this document are to be interpreted as described in [BCP 14](https://www.rfc-editor.org/info/bcp14) when, and only when, they appear in all capitals.

A conforming producer and consumer satisfy [SPEC §7.1 and §7.2](/SPEC.md#7-minimum-requirements) in addition to the requirements stated here, and the family conventions in [`external/_shared/0.1/CONVENTIONS.md`](../../../../external/_shared/0.1/CONVENTIONS.md).

A conforming **custodian** (`recipient`):

1. **MUST** generate the artifacts from the account's current settings, public material and bindings, so that the permissions it suggests are no wider than the union of the bindings' ceilings.
2. **MUST** condition every generated trust policy on this account's own identity (the certificate subject for `aws-roles-anywhere`, the token subject for `gcp-wif-pinned`), so that a second account under the same anchor or pool cannot assume the role.
3. **MUST** include a pending rotation's successor key beside the current one, so that the provider can accept both while the rotation is confirmed.
4. **MUST NOT** include any private key or secret, and **MUST NOT** contact the provider.

## Definitions

- **AccountSetupArtifacts** — as [`external/_shared/0.1/accounts.schema.json`](../../../_shared/0.1/accounts.schema.json). Artifacts are files; steps refer to them by name.

## Request

A manager (`issuer`) asks the custodian (`recipient`). Authority: `external-accounts-manage` in the account's context.

### Setup for an AWS account

```json
{
  "id": "urn:uuid:00000000-0000-4000-8000-000000000015",
  "type": "https://trusttasks.org/spec/external/accounts/setup/0.1#request",
  "issuer": "did:example:community-console",
  "recipient": "did:example:custodian",
  "issuedAt": "2026-10-10T10:00:00Z",
  "threadId": "urn:uuid:00000000-0000-4000-8000-000000000108",
  "payload": {
    "context": "community",
    "id": "eu-s3-primary"
  }
}
```

## Response

The sub-schema reachable via `$anchor: "response"`.

### What to run at AWS

```json
{
  "id": "urn:uuid:00000000-0000-4000-8000-000000000016",
  "type": "https://trusttasks.org/spec/external/accounts/setup/0.1#response",
  "issuer": "did:example:custodian",
  "recipient": "did:example:community-console",
  "issuedAt": "2026-10-10T10:00:01Z",
  "threadId": "urn:uuid:00000000-0000-4000-8000-000000000108",
  "payload": {
    "setup": {
      "model": "aws-roles-anywhere",
      "artifacts": [
        {
          "name": "trust-anchor.pem",
          "mediaType": "application/x-pem-file",
          "content": "-----BEGIN CERTIFICATE-----\nMIIBszCCAVmgAwIBAgIUQ29tbXVuaXR5IENBIGV4YW1wbGUwCgYIKoZIzj0EAwIw\n-----END CERTIFICATE-----\n"
        },
        {
          "name": "trust-policy.json",
          "mediaType": "application/json",
          "content": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"Service\":\"rolesanywhere.amazonaws.com\"},\"Action\":[\"sts:AssumeRole\",\"sts:TagSession\",\"sts:SetSourceIdentity\"],\"Condition\":{\"StringEquals\":{\"aws:PrincipalTag/x509Subject/CN\":\"eu-s3-primary\"},\"ArnEquals\":{\"aws:SourceArn\":\"arn:aws:rolesanywhere:eu-west-1:123456789012:trust-anchor/0b2f7c9e-6a51-4d3e-9b1a-3c5d7e9f1a2b\"}}}]}"
        },
        {
          "name": "permissions-policy.json",
          "mediaType": "application/json",
          "content": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Action\":[\"s3:PutObject\",\"s3:GetObject\",\"s3:DeleteObject\"],\"Resource\":\"arn:aws:s3:::community-rooms-eu/rooms/*\"}]}"
        }
      ],
      "steps": [
        {
          "description": "Create the trust anchor from the custodian's CA certificate.",
          "command": "aws rolesanywhere create-trust-anchor --name community-eu-s3-primary --source sourceType=CERTIFICATE_BUNDLE,sourceData={x509CertificateData=file://trust-anchor.pem} --enabled"
        },
        {
          "description": "Create the role, trusting only certificates for this account under that anchor.",
          "command": "aws iam create-role --role-name community-rooms-storage --assume-role-policy-document file://trust-policy.json"
        },
        {
          "description": "Allow the role only object reads, writes and deletes under rooms/ in the bucket.",
          "command": "aws iam put-role-policy --role-name community-rooms-storage --policy-name rooms-objects --policy-document file://permissions-policy.json"
        },
        {
          "description": "Create the profile that maps the anchor to the role.",
          "command": "aws rolesanywhere create-profile --name community-eu-s3-primary --role-arns arn:aws:iam::123456789012:role/community-rooms-storage --enabled"
        }
      ]
    }
  }
}
```

## Security & Privacy

### Data carried

An account reference in; public material, policies and commands out.

### Correlation

The artifacts name the provider account and resources, as the account's settings do.

### Retention

Nothing stored. An administrator saving the files keeps only public material.

### Consent/purpose

Generating setup confers nothing; applying it at the provider is the administrator's act, under the provider's own access control.
