Using the AWS CLI tools with Teleport and AWS IAM Identity Center

Report an issue with this page

This guide will show you how to configure the aws command-line tool to use access granted via Teleport and AWS Identity Center.

How it works

For a deep dive into how Teleport manages AWS Identity Center access works you can read the main AWS IAM Identity Center guide. For the purposes of this guide, it's enough to understand that Teleport manages the creation and deletion of AWS Account Assignments based on a users's Account Assignment grants, either from their standing Teleport Roles, Access List membership or approved Access Requests.

You can access these Teleport-managed Accounts and Permission Set assignments with the AWS CLI tools by using sso login and AWS profiles.

Prerequisites

Before you begin, you will need:

• A Teleport-managed AWS Identity Center organization. See our getting started guide for setting up an Identity Center integration.
• The AWS CLI tools, installed as per the AWS installation guide
• The SSO Start URL and AWS Region for your Identity Center organization. Ask your AWS administrator for the appropriate values.

Step 1/2. Configure the AWS SSO Session

This step configures the AWS CLI tools to use SSO for authentication. You can either configure this manually, or via the aws configure sso-session wizard.

Wizard

Invoke the AWS SSO configuration wizard by running the following command and answering the questions asked by the wizard.

$ aws configure sso-session

You will need to pick a name for the SSO session; this is just a local name for this particular SSO configuration. For this example we are using my-identity-center.

$ aws configure sso-session
SSO session name: my-identity-center
SSO start URL [None]: https://d-12234567890.awsapps.com/start
SSO region [None]: us-east-1
SSO registration scopes [sso:account:access]:

Manual Configuration

You can configure SSO authentication manually by editing your .aws/config file. The above example would look like this:

[sso-session my-identity-center]
sso_start_url = https://d-12234567890.awsapps.com/start
sso_region = us-east-1
sso_registration_scopes = sso:account:access

Testing the SSO Session

To test the SSO configuration, try logging into AWS via SSO.

$ aws sso login --sso-session my-identity-center

This will launch a browser-based flow that will log you into AWS via Teleport and ask you confirm the AWS CLI tool's access to AWS using your account.

Step 2/2. Creating AWS Profiles

You will need to create a separate AWS CLI profile for each AWS Account and Permission Set you want to access. These profiles will reference the SSO Session created above, which tells the AWS tools to use SSO authentication when the profile is active.

Again you can do this either via an aws configure wizard, or editing your /.aws/config file directly.

info

You can create as many profiles as you like, so repeat this step for as many AWS Account / Permission Set pairs that you need.

Wizard

To create a profile that uses given SSO session, invoke the SSO configuration wizard with the following commands, and answering the questions it asks:

$ aws configure sso

The wizard asks several questions about the profile to create, but for our purposes, only selecting the AWS Account and Role are important.

Firstly, select the AWS account this profile will use. The wizard will offer you a list of available AWS accounts based on your current Account Assignments, if you are only permitted to use a single AWS account, the wizard automatically picks that and skips the question.

There are 2 AWS accounts available to you.
> Staging, [email protected] (058264527036)
  Production, [email protected] (637423191929)

Next, select the AWS Role to assume when this profile is active. Identity Center Permission Sets are provisioned onto AWS accounts as Roles, so select the role with the same name as the Permission Set you want to use.

There are 3 roles available to you.
  SecurityAudit
> AdministratorAccess
  PowerUserAccess

Again, if only one option is available the wizard will automatically select that and skip the question.

After several generic AWS profile questions (e.g. default AWS region, default output format, etc), the wizard will ask for the profile name. For this example, given that the profile will use the AdminAccess role on the Staging account we will call it admin-on-staging.

Manual Configuration

While helpful, the aws configure sso wizard requires currently-assigned Accounts and Permission Sets to work with. You can pre-configure an AWS profile to use Account Assignments that you currently do not have access to by editing your ~/.aws/config file and adding the profile directly.

For example, the admin-on-staging profile we created above looks like this:

[profile admin-on-staging]
sso_session = my-identity-center
sso_account_id = 058264527036
sso_role_name = AdministratorAccess
region = us-east-1

Testing the profile

You can test the profile by running aws sts get-caller-identity and verifying the returned user ID and assumed Role. For example:

$ aws sts get-caller-identity --profile admin-on-staging
{
    "UserId": "AROA123456789AEXAMPLE:[email protected]",
    "Account": "058264527036",
    "Arn": "arn:aws:sts::058264527036:assumed-role/AWSReservedSSO_AdministratorAccess_69450ffeac834ef7/[email protected]"
}

Once you have validate that the profile is configured correctly, you can use the --profile argument in any aws subcommand select it and use the corresponding Identity Center Account assignment in that operation.

info

You can also use this profile with other tools that support the standard AWS client environment variables. Set the profile by setting the AWS_PROFILE environment variable. For example:

$ AWS_PROFILE=admin-on-staging ./some-aws-tool

Troubleshooting

"Invalid Callback" error

If AWS presents you with an "invalid Callback URL" error message, the most likely problem is an incorrect AWS region in your sso-session configuration.

"Error loading SSO Token" error

The AWS cache directory has probably been deleted. Log in again with aws sso login --sso-session ${SSO_SESSION_NAME}, where ${SSO_SESSION_NAME} is the name of your configured SSO session.

Next Steps

• Learn how to request Just-in-Time access to an Account Assignment.
• Take a deeper dive into fundamental Teleport concepts used in Identity Center integration such as RBAC, JIT Access Requests, and Access Lists.
• Learn how Teleport uses RBAC, JIT Access Requests and Access Lists to manage AWS Identity Center Account Assignments in the AWS IAM Identity Center guide

Further reading

For a broader introduction to using the AWS CLI with IAM Identity Center, see the AWS Configuring IAM Identity Center authentication with the AWS CLI guide.