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 OIDC provider (an industry standard), and then we configure your Namespace workspace to trust that AWS Cognito Identity Pool.

To use Identity Federation the nsc CLI is required (minimum version 0.261).

Creating a AWS Cognito Identity Pool

A AWS Cognito Identity Pool is required to establish a trust relationship with Namespace.

Go to AWS' management console, and select "Cognito" in your region of choice.
Select Create identity pool
Within the dialog, select Authenticated Access and Custom developer provider.
Select an existing IAM Role to use with Cognito, or create a new one. Note: This is not necessary to establish a trust relationship with Namespace, as Namespace never issues AWS requests.
Enter namespace.so as "Developer provider name". This is important as nsc auth exchange-aws-cognito-token will request that Cognito produces a token for the login provider namespace.so.
Give the new identity pool a name: you can pick any name.
And finally, head over to the final screen and press Create identity pool.
Make note of the Identity pool ID, we'll need it later. It's of the format {region}:{guid}. E.g. eu-central-1:b35d4239-99ea-48be-a5e6-68afbcefd649.

Establishing a trust relationship in Namespace

Run nsc login and login to the Workspace where you want to establish the trust relationship.
Run nsc workspace describe and take note of the Tenant ID, we'll need it later.
- Or run
```
export NSC_TENANT_ID=$(nsc workspace describe -o json | jq -r .tenant_id)
```

And finally run the following command to establish the trust relationship:

nsc auth trust-aws-cognito-identity-pool \
  --aws_region $REGION \
  --identity_pool $GUID \
  --tenant_id $NSC_TENANT_ID

Obtain Namespace credentials from a AWS workload

Ensure that your AWS workload's IAM role has access to the Cognito Identity Pool we created above.

To obtain Namespace credentials, run:

nsc auth exchange-aws-cognito-token \
    --aws_region $REGION \
    --identity_pool $GUID \
    --tenant_id $NSC_TENANT_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.

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 IAM OIDC identity provider for Namespace federation in AWS Management Console.

Creating Namespace OIDC identity provider

To create an IAM OIDC identity provider using AWS Management Console:

Open the IAM console at https://console.aws.amazon.com/iam/ and in the navigation pane, choose Identity providers, and then choose Add provider.
For Configure provider, choose OpenID Connect.
For Provider URL, type https://federation.namespaceapis.com, click Get thumbprint and verify that the thumbprint is equal to a053375bfe84e8b748782c7cee15827a6af5a405.
For Audience, type sts.amazonaws.com.
Verify the information that you have provided. When you are done choose Add provider.

Alternatively you can use AWS CLI for this (assuming that access to AWS account is configured for CLI):

aws iam create-open-id-connect-provider \
    --url=https://federation.namespaceapis.com \
    --thumbprint-list=a053375bfe84e8b748782c7cee15827a6af5a405 \
    --client-id-list=sts.amazonaws.com

The next step is to assign an IAM role to Namespace identity provider to allow federated access.

Creating a role for federated access

To create a role for Namespace IdP using AWS Management Console:

Open the IAM console at https://console.aws.amazon.com/iam/.
In the navigation pane, choose Roles, then choose Create role and select the Custom trust policy role type.
For Custom trust policy, use the following JSON template (you need to set IDP_ARN and NSC_TENANT_ID values):

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Effect": "Allow",
			"Action": "sts:AssumeRoleWithWebIdentity",
			"Principal": {
				"Federated": "${IDP_ARN}"
			},
			"Condition": {
				"StringLike": {
					"federation.namespaceapis.com:aud": "sts.amazonaws.com",
					"federation.namespaceapis.com:sub": "${NSC_TENANT_ID}/*"
				}
			}
		}
	]
}

where IDP_ARN is the ARN of Namespace IdP previously created, and NSC_TENANT_ID is the workspace identifier that can be retrieved using nsc workspace describe command.

Choose Next and add permissions policies to the role (federated workloads would have these permissions).

Obtaining AWS credentials from a Namespace workload

To obtain AWS credentials, run:

nsc aws assume-role --role_arn $NSC_AWS_ROLE_ARN --write_env aws.env

where NSC_AWS_ROLE_ARN is the ARN of Namespace IdP role created in the previous step.

This command should succeed and write aws.env file with credentials (set as environment variables) to access AWS resources. Run source aws.env to export environment variables from the file.