Workload Federation with AWS

Namespace relies on Workload Identity Federation to allow Namespace to interact with different systems, instead of relying on pre-shared keys which can be more easily compromised.

Accessing Namespace resources from AWS

Identity Federation with AWS allows your AWS-based workloads to identify themselves to Namespace using short-lived secure credentials. To enable this federation, we rely on AWS Cognito to establish a OpenID Connect provider, and then we configure your Namespace workspace to trust that AWS Cognito Identity Pool.

Create an AWS Cognito Identity Pool

Open the Cognito console at https://console.aws.amazon.com/cognito/ and click on Create identity pool in the section Identity pools.
Check the options Authenticated Access and Custom developer provider.
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.
Under Developer provider name enter namespace.so.
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

Open the Dashboard and copy your Workspace ID.

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.

Accessing Namespace resources using STS Web Identity

AWS STS Web Identity Federation is a simpler alternative to Cognito that issues short-lived OIDC tokens directly from your AWS account, without requiring an identity pool. Any AWS workload with an IAM role (EC2, Lambda, ECS, etc.) can use this approach.

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.

Accessing AWS resources from Namespace

Identity Federation with AWS allows your Namespace workloads to identify themselves to AWS using short-lived secure credentials. To enable this federation, create an IAM OIDC identity provider for Namespace federation in the AWS Management Console.

Create a Namespace OIDC identity provider

Open the IAM console at https://console.aws.amazon.com/iam/ and in the navigation pane, choose Identity providers, and click Add provider.
Select OpenID Connect as a Provider type and fill in https://federation.namespaceapis.com as the Provider URL.
The expected thumbprint is a053375bfe84e8b748782c7cee15827a6af5a405.
For Audience, type sts.amazonaws.com.
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

Open the IAM console at https://console.aws.amazon.com/iam/.
In the navigation pane, choose Roles and click Create role.

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 complete Namespace workspace identifier (found in the Dashboard). The workspace ID includes the tenant_ prefix; for example, tenant_123456789ab.

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

Accessing AWS resources from a Namespace workload

Obtain AWS credentials.
nsc aws assume-role --role_arn <role-arn> --write_env aws.env
In this command, <role-arn> is the ARN of the IAM role created for federated access.
Apply the obtained credentials.
source aws.env

Access AWS resources.

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

Pulling private ECR images on instances

When creating an instance through the Compute API, you can pull private images from Amazon ECR by having Namespace federate with AWS to obtain a ECR authorization token automatically. The resolved token is used both to pull the instance’s own container images and is written into the guest’s Docker/nerdctl configuration (/root/.docker/config.json), so subsequent docker pull and nerdctl pull commands from inside the instance authenticate to the same registries. This builds on the federated IAM role created in Accessing AWS resources from Namespace.

Grant the IAM role permission to pull from ECR

Attach a policy to the federated role allowing it to obtain an authorization token and pull images:

aws iam put-role-policy \
  --role-name <your-federated-role> \
  --policy-name allow-ecr-pull \
  --policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Action": [
        "ecr:GetAuthorizationToken",
        "ecr:BatchCheckLayerAvailability",
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage"
      ],
      "Resource": "*"
    }]
  }'

ecr:GetAuthorizationToken must be granted on "Resource": "*". The remaining actions may be scoped to specific repository ARNs.

Reference the registry when creating an instance

Set additional_registries on the CreateInstance request, keyed by your ECR host (<account-id>.dkr.ecr.<region>.amazonaws.com). Namespace infers the AWS region from this host, assumes the role via the trust relationship configured above, and uses the resulting token to pull the image:

{
	"containers": [
		{
			"name": "app",
			"image_ref": "<account-id>.dkr.ecr.<region>.amazonaws.com/my-repo:latest"
		}
	],
	"additional_registries": {
		"<account-id>.dkr.ecr.<region>.amazonaws.com": {
			"authentication": {
				"ecr_token_from_aws_federation": {
					"role_arn": "arn:aws:iam::<aws-account-id>:role/<your-federated-role>"
				}
			}
		}
	}
}

The registry host key must exactly match the ECR host in image_ref. See the AdditionalRegistry.Authenticator reference for all available authentication options.

Products

Platform

Administration

Accessing Namespace resources from AWS

Create an AWS Cognito Identity Pool

Establish a trust relationship in Namespace

Obtain Namespace credentials from a AWS workload

Accessing Namespace resources using STS Web Identity

Enable outbound web identity federation

Grant your IAM role permission to call GetWebIdentityToken

Establish a trust relationship in Namespace

Authenticate from your workload

Accessing AWS resources from Namespace

Create a Namespace OIDC identity provider

Create a IAM role for federated access

Accessing AWS resources from a Namespace workload

Pulling private ECR images on instances

Grant the IAM role permission to pull from ECR

Reference the registry when creating an instance

​Accessing Namespace resources from AWS

Create an AWS Cognito Identity Pool

Establish a trust relationship in Namespace

Obtain Namespace credentials from a AWS workload

​Accessing Namespace resources using STS Web Identity

Enable outbound web identity federation

Grant your IAM role permission to call GetWebIdentityToken

Establish a trust relationship in Namespace

Authenticate from your workload

​Accessing AWS resources from Namespace

Create a Namespace OIDC identity provider

Create a IAM role for federated access

Accessing AWS resources from a Namespace workload

​Pulling private ECR images on instances

Grant the IAM role permission to pull from ECR

Reference the registry when creating an instance

Accessing Namespace resources from AWS

Accessing Namespace resources using STS Web Identity

Accessing AWS resources from Namespace

Pulling private ECR images on instances