Workload Federation with AWS

Create an AWS Cognito Identity Pool

1. Open the Cognito console at https://console.aws.amazon.com/cognito/ and click on Create identity pool in the section Identity pools.

2. Check the options Authenticated Access and Custom developer provider.

3. Select an existing IAM role to use with Cognito, or create a new one.

   AWS requires you to associate an IAM role with the identity pool. The role can have minimal permissions as the pool will be used to access Namespace resources, not AWS resources.

4. Under Developer provider name enter namespace.so.

5. Pick an arbitrary name for the identity pool and create the identity pool.

AWS will print the ID of the new identity pool. It's of the format {region}:{guid}.

Establish a trust relationship in Namespace

1. Open the Dashboard and copy your Workspace ID.
2. Use the CLI to establish the trust relationship:

   nsc auth trust-aws-cognito-identity-pool \
       --aws_region <region> \
       --identity_pool <guid> \
       --tenant_id <workspace-id>

Obtain Namespace credentials from a AWS workload

Using an IAM role with permissions to access the Cognito Identity Pool, you can obtain Namespace credentials as follows:

nsc auth exchange-aws-cognito-token \
    --aws_region <region> \
    --identity_pool <guid> \
    --tenant_id <workspace-id>

This command should succeed with the name of workspace you've signed in to. It stores a short-lived token that will be used automatically in subsequent calls.

When testing locally, you can select an AWS profile by passing --aws_profile.

Enable outbound web identity federation

This is a one-time setting per AWS account. It enables STS to issue OIDC tokens on behalf of your AWS principals.

export AWS_PROFILE=<your-aws-profile>
 
aws --profile "$AWS_PROFILE" iam enable-outbound-web-identity-federation

Note the IssuerIdentifier in the response. You can retrieve it again at any time:

aws --profile "$AWS_PROFILE" iam get-outbound-web-identity-federation-info

Grant your IAM role permission to call GetWebIdentityToken

Your workload's IAM role needs permission to obtain tokens. Add an inline policy to the role:

aws --profile "$AWS_PROFILE" iam put-role-policy \
  --role-name <your-workload-role> \
  --policy-name allow-get-web-identity-token \
  --policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Action": "sts:GetWebIdentityToken",
      "Resource": "*"
    }]
  }'

Establish a trust relationship in Namespace

Use the issuer URL and account ID to configure Namespace to trust tokens from your AWS account:

ISSUER=$(aws --profile "$AWS_PROFILE" iam get-outbound-web-identity-federation-info \
  --query IssuerIdentifier --output text)
ACCOUNT=$(aws --profile "$AWS_PROFILE" sts get-caller-identity --query Account --output text)
 
nsc auth trust-relationships add \
  --issuer "$ISSUER" \
  --subject-match "arn:aws:iam::${ACCOUNT}:role/<your-workload-role>"

To trust any role in the account, use a wildcard:

  --subject-match "arn:aws:iam::${ACCOUNT}:role/*"

Authenticate from your workload

From within your AWS workload (no additional instance setup required — the AWS CLI picks up credentials from the instance metadata automatically):

TOKEN=$(aws sts get-web-identity-token \
  --audience https://federation.namespaceapis.com \
  --signing-algorithm ES384 \
  --region us-east-1 \
  --query WebIdentityToken --output text)
 
nsc auth exchange-oidc-token --token "$TOKEN"

--audience and --signing-algorithm are required by the API. Both ES384 (ECDSA P-384) and RS256 are accepted; ES384 is recommended. --region must point to a regional STS endpoint — the global endpoint does not support this call. --query WebIdentityToken --output text is a CLI convenience to extract just the token string from the JSON response.

Create a Namespace OIDC identity provider

1. Open the IAM console at https://console.aws.amazon.com/iam/ and in the navigation pane, choose Identity providers, and click Add provider.

2. Select OpenID Connect as a Provider type and fill in https://federation.namespaceapis.com as the Provider URL.

   The expected thumbprint is a053375bfe84e8b748782c7cee15827a6af5a405.

3. For Audience, type sts.amazonaws.com.

4. Verify the information that you have provided. When you are done choose Add provider.

Note down the ARN of your newly created identity provider. It is of the form arn:aws:iam::<aws-account-id>:oidc-provider/federation.namespaceapis.com.

Create a IAM role for federated access

1. Open the IAM console at https://console.aws.amazon.com/iam/.

2. In the navigation pane, choose Roles and click Create role.

3. Select the Custom trust policy role type, using the following JSON template as the policy:

   {
   	"Version": "2012-10-17",
   	"Statement": [
   		{
   			"Effect": "Allow",
   			"Action": "sts:AssumeRoleWithWebIdentity",
   			"Principal": {
   				"Federated": "<identity-provider-arn>"
   			},
   			"Condition": {
   				"StringLike": {
   					"federation.namespaceapis.com:aud": "sts.amazonaws.com",
   					"federation.namespaceapis.com:sub": "<workspace-id>/*"
   				}
   			}
   		}
   	]
   }

   Replace <identity-provider-arn> with the ARN of the new identity provider, and <workspace-id> with your Namespace workspace identifier (found in the Dashboard).

4. Choose Next and add the desired permissions policies for your federated workloads.

Accessing AWS resources from a Namespace workload

1. Obtain AWS credentials.

   $
   nsc aws assume-role --role_arn <identity-provider-arn> --write_env aws.env

   In this command, <identity-provider-arn> is the ARN of the new identity provider.

2. Apply the obtained credentials.

   $
   source aws.env

3. Access AWS resources.

   $
   aws s3 cp test.txt s3://amzn-s3-demo-bucket/test2.txt