Skip to content

Using ECS Server Mode

Overview

AWS provides the ability for ECS Tasks to assume an IAM role via an HTTP endpoint defined via the AWS_CONTAINER_CREDENTIALS_FULL_URI shell ENV variable.

All AWS SDK clients using the the same ECS Server container credentials endpoint URL will utilize the same AWS IAM Role. Note that this feature is also compatible with the HTTP Client Provider.

aws-sso can emulate this ECS service and allow any process to utilize one or more IAM roles backed by AWS Identity Center/SSO.

One important distinction between aws-sso and this ECS Server, is that the ECS Server does not have access to the SecureStore. The only SSO or IAM credentials it has available to it are those you manually load into it's memory.

Security Considerations

The aws-sso ECS Server is intended to run on hosts where a single user has access. The security of your IAM credentials is dependent on nobody else being able to talk to the server. Due to a limitation of the AWS SDK, SSL/TLS is not well supported, which means that enabling HTTP Authentication may not be enough to protect your credentials.

Starting the ECS Server

The server runs in the foreground to make it easy to start via systemd and Docker.

aws-sso ecs server

Will start the server on localhost:4144. For security purposes, the aws-sso ECS Server will default listen on localhost (127.0.0.1) port 4144. You may select an alternative IP/port via the --bind-ip and --port flags.

Running the ECS Server in the background

The recommended way to run the ECS server in the background is via the aws-sso-cli-ecs-server Docker image and the aws-sso ecs docker [start|stop] commands as this will automatically configure your SSL key pair and bearer token from the secure store in the most secure means possible.

Note: For security, by default the Docker container will default listen the host's loopback interface (127.0.0.1), but you can enable it listening on other interfaces using the --bind-ip flag.

ECS Server security

The ECS Server supports both SSL/TLS encryption as well as HTTP Authentication. Together, they allow using the aws-sso ECS Server on multi-user systems in a secure manner.

Important: Failure to configure HTTP Authentication and SSL/TLS encryption risks any user on the system running the aws-sso ECS Server access to your AWS IAM authentication tokens.

ECS Server SSL Certificate

Important: Due to a bug in the AWS SDK you can not easily enable SSL at this time. I'd greatly appreciate people to upvote my ticket with AWS and help get it greater visibility at AWS and hopefully addressed sooner rather than later.

You will need to create an SSL certificate which is signed by a well trusted CA such as DigiCert, Let's Encrypt, Thwate, etc. Currently, the AWS SDK does NOT support self-signed certificates or private CA's for this endpoint.

Once you have your certificate and private key, you will need to save them into the aws-sso secure store:

aws-sso setup ecs ssl --private-key localhost.key --cert-chain localhost.crt

Important: At this point, you should delete the private key file localhost.key for security.

The localhost.crt file will be automatically trusted by the aws-sso client if it uses the same secure store so it will be able to validate the server before uploading any IAM credentials.

If you lose your certificate, you can print it via:

aws-sso setup ecs ssl --print

Note: At this time, there is no way to extract the SSL Private Key from the Secure Store.

Using self-signed certificates

In theory, you can add your self-signed certificate or custom CA into the AWS SDK certificate bundle. However, this file is SDK specific (the Boto3 SDK ships with it's own cacert.pem while the Go v2 SDK uses the system default bundle). Managing this is not just language specific, but likely to be site-specific so getting this to work is left as an exercise to the reader.

ECS Server HTTP Authentication

The way to configure HTTP Authentication is with a bearer token as documented by AWS.

Once you have selected a sufficiently secure secret to use as the bearer token, you can load it into the Secure Store via:

aws-sso setup ecs auth --bearer-token '<token>`

Note: Unlike the $AWS_CONTAINER_AUTHORIZATION_TOKEN variable, do not include the prefix Bearer in the token value.

Important: You must choose a strong secret value for your bearer token secret! This is what prevents anyone else from using your IAM credentials without your permission. Your bearer token should be long and random enough to prevent bruteforce attacks.

Environment variables

$AWS_CONTAINER_CREDENTIALS_FULL_URI

AWS clients and aws-sso should use:

export AWS_CONTAINER_CREDENTIALS_FULL_URI=http://localhost:4144/

Note: If you have configured an SSL certificate as described above, use https://localhost:4144.

$AWS_CONTAINER_CREDENTIALS_RELATIVE_URI

It is important to not set AWS_CONTAINER_CREDENTIALS_RELATIVE_URI as that takes precidence for AWS_CONTAINER_CREDENTIALS_FULL_URI and it is not compatible with aws-sso.

$AWS_CONTAINER_AUTHORIZATION_TOKEN

Specify the HTTP Authentication token used to authenticate communication between the ECS Server and clients (aws-sso and AWS SDK/CLI). Should be specified in the format of Bearer <auth token value>.

Selecting a role via ECS Server

Before you can assume a role, you must select an IAM role for the aws-sso ecs server to present to clients.

aws-sso ecs load

Will start the interactive profile selector. Or you may specify the --profile flag or the --account and --role flags to specify the role on the command line.

Note: Subsequent calls to aws-sso ecs load will alter the current IAM Role for all AWS Client SDKs using it.

Assuming a role via ECS Server

Ensure you have exported the following shell ENV variable:

export AWS_CONTAINER_CREDENTIALS_FULL_URI=http://localhost:4144/

Note: If you have configured an SSL certificate as described above, use https://localhost:4144/.

Then just:

aws sts get-caller-identity

should show that you are using the IAM Role you loaded into the ecs server process.

Determining the current role

Since only one role can be loaded at any given time in the default slot, there may be times you would like to quickly determine the current role without resorting to an IAM call:

aws-sso ecs profile

will return the currently loaded default profile.

Unloading role credentials

If you would like to remove the default IAM Role credentials:

aws-sso ecs unload

Storing multiple roles at a time

There may be cases where you would like to make multiple roles available at the same time without running multiple copies of the ECS server via aws-sso ecs server. Each role is stored in a unique named slot based on the ProfileName which is either set via Profile or the ProfileFormat configuration options.

Loading

Specify aws-sso ecs load --slotted ... and the individual role will be stored in it's unique named slot based on it's profile name.

Listing Profiles

To see a list of profiles loaded in named slots use aws-sso ecs list.

Querying

Accessing the individual credentials is done via the profile query parameter:

export AWS_CONTAINER_CREDENTIALS_FULL_URI=http://localhost:4144/slot/ExampleProfileName

Note: If you have configured an SSL certificate as described above, use httpss://localhost:4144/slot/ExampleProfileName.

Would utilize the ExampleProfileName role. Note that the profile value value in the URL must be URL Escaped.

Unloading

To remove a specific IAM Role credential from a named slot in the ECS Server, you can use:

aws-sso ecs unload --profile <profile>

Errors

The ECS Server API endpoint generates errors with the following JSON format:

{
    "code": "<HTTP error code>",
    "message": "<message>"
}

Authentication

Support for the $AWS_CONTAINER_AUTHORIZATION_TOKEN environment variable is supported.

HTTPS Transport

HTTPS support is a work in progress. Right now, due to a limitation with the AWS SDK only SSL certificates signed by CA that the AWS SDK trusts will work. If you think this feature would be useful to you, please leave a comment so AWS knows they should prioritize this work.