@backstage/integration-aws-node

@backstage/integration-aws-node

This package providers helpers for fetching AWS account credentials to be used by AWS SDK clients in backend packages and plugins.

Backstage app configuration

Users of plugins and packages that use this library will configure their AWS account information and credentials in their Backstage app config. Users can configure IAM user credentials, IAM roles, and profile names for their AWS accounts in their Backstage config.

If the AWS integration configuration is missing, the credentials manager from this package will fall back to the AWS SDK default credentials chain for resources in the main AWS account. The default credentials chain for Node resolves credentials in the following order of precedence:

1. Environment variables
2. SSO credentials from token cache
3. Web identity token credentials
4. Shared credentials files
5. The EC2/ECS Instance Metadata Service

See more about the AWS SDK default credentials chain in the AWS SDK for Javascript Developer Guide.

Configuration examples:

aws:
  # The main account is used as the source of credentials for calling
  # the STS AssumeRole API to assume IAM roles in other AWS accounts.
  # This section can be omitted to fall back to the AWS SDK's default creds chain.
  mainAccount:
    accessKeyId: ${MY_ACCESS_KEY_ID}
    secretAccessKey: ${MY_SECRET_ACCESS_KEY}

  # Account credentials can be configured individually per account
  accounts:
    # Credentials can come from a role in the account
    - accountId: '111111111111'
      roleName: 'my-iam-role-name'
      externalId: 'my-external-id'

    # Credentials can come from other AWS partitions
    - accountId: '222222222222'
      partition: 'aws-other'
      roleName: 'my-iam-role-name'
      # The STS region to use for the AssumeRole call
      region: 'not-us-east-1'
      # The creds to use when calling AssumeRole
      accessKeyId: ${MY_ACCESS_KEY_ID_FOR_ANOTHER_PARTITION}
      secretAccessKey: ${MY_SECRET_ACCESS_KEY_FOR_ANOTHER_PARTITION}

    # Credentials can come from static credentials
    - accountId: '333333333333'
      accessKeyId: ${MY_OTHER_ACCESS_KEY_ID}
      secretAccessKey: ${MY_OTHER_SECRET_ACCESS_KEY}

    # Credentials can come from a profile in a shared config file on disk
    - accountId: '444444444444'
      profile: my-profile-name

    # Credentials can come from the AWS SDK's default creds chain
    - accountId: '555555555555'

  # Credentials for accounts can fall back to a common role name.
  # This is useful for account discovery use cases where the account
  # IDs may not be known when writing the static config.
  # If all accounts have a role with the same name, then the "accounts"
  # section can be omitted entirely.
  accountDefaults:
    roleName: 'my-backstage-role'
    externalId: 'my-id'

Integrate new plugins

Backend plugins can provide an AWS ARN or account ID to this library in order to retrieve a credential provider for the relevant account that can be fed directly to an AWS SDK client. The AWS SDK for Javascript V3 must be used.

const awsCredentialsManager = DefaultAwsCredentialsManager.fromConfig(config);

// provide the account ID explicitly
const credProvider = await awsCredentialsManager.getCredentialProvider({
  accountId,
});
// OR extract the account ID from the ARN
const credProvider = await awsCredentialsManager.getCredentialProvider({ arn });
// OR provide neither to get main account's credentials
const credProvider = await awsCredentialsManager.getCredentialProvider({});

// Example constructing an AWS Proton client with the returned credential provider
const client = new ProtonClient({
  region,
  credentialDefaultProvider: () => credProvider.sdkCredentialProvider,
});

Depending on the nature of your plugin, you may either have the user specify the relevant ARN or account ID in a catalog entity annotation or in the static Backstage app configuration for your plugin.

For example, you can create a new catalog entity annotation for your plugin containing either an AWS account ID or ARN:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  annotations:
    # Plugin annotation to specify an AWS account ID
    my-plugin.io/aws-account-id: '123456789012'
    # Plugin annotation to specify the AWS ARN of a specific resource
    my-other-plugin.io/aws-dynamodb-table: 'arn:aws:dynamodb:us-east-2:123456789012:table/example-table'

In your plugin, read the annotation value so that you can retrieve the credential provider:

const MY_AWS_ACCOUNT_ID_ANNOTATION = 'my-plugin.io/aws-account-id';

const getAwsAccountId = (entity: Entity) =>
  entity.metadata.annotations?.[MY_AWS_ACCOUNT_ID_ANNOTATION]);

Alternatively, you can create a new Backstage app configuration field for your plugin:

# app-config.yaml
my-plugin:
  # Statically configure the AWS account ID to use
  awsAccountId: '123456789012'
my-other-plugin:
  # Statically configure the AWS ARN of a specific resource
  awsDynamoDbTable: 'arn:aws:dynamodb:us-east-2:123456789012:table/example-table'

In your plugin, read the configuration value so that you can retrieve the credential provider:

// Read an account ID from your plugin's configuration
const awsCredentialsManager = DefaultAwsCredentialsManager.fromConfig(config);
const accountId = config.getOptionalString('my-plugin.awsAccountId');
const credProvider = await awsCredentialsManager.getCredentialProvider({
  accountId,
});

// Or, read an AWS ARN from your plugin's configuration
const awsCredentialsManager = DefaultAwsCredentialsManager.fromConfig(config);
const arn = config.getString('my-other-plugin.awsDynamoDbTable');
const credProvider = await awsCredentialsManager.getCredentialProvider({ arn });

Links

• The Backstage homepage