AWS connections

The aws connection type represents credentials for one or more Amazon Web Services (AWS) accounts. It has singleton cardinality, so configuration contains at most one aws connection. Individual accounts are represented by account authentication entries inside that connection.

Unlike most built-in types, AWS uses the aws lookup strategy. Consumers look up an account number or Amazon Resource Name (ARN), not a URL host.

Configure AWS

app-config.yaml

connections:
  - type: aws
    title: Company AWS accounts
    roleName: BackstageReadRole
    region: eu-west-1
    auth:
      - method: account
        title: Main account
        mainAccount: true
        profile: backstage-main
      - method: account
        title: Production workload account
        accountId: '123456789012'
        roleName: BackstageReadRole

The main account is the fallback for lookups without an exact account entry. It also supplies the source credentials when the connection-level roleName is used to assume a role in another account.

Connection fields

Field	Type	Required	Description
roleName	string	No	Role to assume in an account that does not have its own authentication entry.
partition	string	No	AWS partition for connection-level role assumption. Requires roleName.
region	string	No	AWS region associated with connection-level role assumption. Requires roleName.
externalId	string	No	External ID passed during connection-level role assumption. Requires roleName.
webIdentityTokenFile	string	No	Path to a web identity token used during connection-level role assumption. Requires roleName.

externalId and webIdentityTokenFile are mutually exclusive.

account authentication method

The account method supports these fields:

Field	Type	Required	Description
accountId	string	Conditional	AWS account number represented by the entry. Required unless mainAccount is true.
mainAccount	boolean	Conditional	Marks the entry as the fallback and source of credentials for connection-level role assumption. Set it to true when accountId is omitted.
accessKeyId	string	No	Static access key ID. Must be configured with secretAccessKey.
secretAccessKey	string	No	Static secret access key. Must be configured with accessKeyId.
profile	string	No	Local AWS profile used for the account.
roleName	string	No	Role to assume in this entry's account.
partition	string	No	AWS partition for the entry's role. Requires roleName.
region	string	No	AWS region for the account or role.
externalId	string	No	External ID passed when assuming the entry's role. Requires roleName.
webIdentityTokenFile	string	No	Path to a web identity token used when assuming the entry's role. Requires roleName.

The AWS type validates the complete connection:

• Account IDs must be unique.
• Only one entry can set mainAccount: true.
• The main account cannot define roleName.
• Static access-key fields must be supplied together.
• profile cannot be combined with static access keys or roleName.
• webIdentityTokenFile cannot be combined with static access keys, profile, or externalId.
• A connection-level roleName requires a main-account entry.

Lookup and selection

Consumers can supply accountId, arn, or both. When both are present, accountId takes precedence. The type extracts the account number from a valid ARN when accountId is omitted.

Selection follows this order:

1. Return the entry whose accountId matches the query.
2. Return the entry marked mainAccount when no exact entry exists.
3. Return no match when neither entry exists.

A malformed ARN causes an InputError instead of falling back to the main account.

Plugin scoping can restrict which account entries a plugin can see. The selection order applies only to the entries that remain visible to that plugin.

For example, to give one plugin access to a specific account and another plugin access to a different account:

app-config.yaml

connections:
  - type: aws
    auth:
      - method: account
        title: Catalog account
        accountId: '111111111111'
        match:
          plugins:
            - catalog
      - method: account
        title: Scaffolder account
        accountId: '222222222222'
        match:
          plugins:
            - scaffolder

The catalog plugin only sees account 111111111111, and the scaffolder plugin only sees account 222222222222.

An entry marked mainAccount is subject to the same scoping rules. When a lookup falls back to the main account, the main-account entry must be visible to the calling plugin. If the main-account entry is scoped to other plugins, the fallback does not apply and the lookup returns no match.

Consume an AWS connection

const connection = await connections.find({
  type: 'aws',
  query: {
    arn: 'arn:aws:iam::123456789012:role/BackstageReadRole',
  },
  authMethods: ['account'],
});

connection.auth.method; // 'account'
connection.auth.accountId; // string | undefined
connection.auth.roleName; // string | undefined

The returned fields are static inputs to an AWS credential provider. The connection service does not load profiles, read web identity token files, or perform role assumption.

Return to the built-in connection type index.