Setting up AWS Single Sign-On

Why?

AWS SSO is required for using Amazon Bedrock models, for example with Claude Code. If you are only using Codex, you do not need this.

Setting up AWS SSO allows any tool using the AWS SDK to authenticate as well, so it affords substantial flexibility.

It is possible to use Azure or Google Cloud Platform instead of AWS, but that is not documented here yet.

1. NIH-specific Account provisioning

Warning

This section is NIH-specific; other institutions will have a different process. Once you can successfully authenticate to the SSO start URL for your institution, continue to step 2, “AWS CLI v2 setup”.

Prerequisites:

  1. You have an AWS STRIDES account already set up.

  2. You have the list of people to include in a security group who will be able to log in to AWS.

First, you need to get the relevant accounts added to the AWS Identity Center, which enables SSO. This is a manual setup on CIT’s part since NIH’s integration with EntraID is not yet complete.

This initial setup only needs to be done once per group.

  • Submit a Cloud Operations Support Request on ServiceNow. Include:

    • AWS account name and number

    • List of people: names, usernames, and emails

    • Existing security group name to use, or the name of a new security group for CIT to create with these users

    • The role to assign users in the security group. We are currently using NIH-AWS-PowerUser, one of the standard roles set up in an AWS STRIDES account.

  • After answering any follow-up questions from CIT:

    • CIT will either send each user an email directly or cause one to be sent through AWS. The email will contain your username, a temporary password, and a URL.

    • Visit the URL, log in, change the password, and set up MFA.

Tip

You are complete with this phase when you can successfully log in to https://nih.awsapps.com/start.

2. AWS CLI v2 setup

AWS CLI v2 is used to authenticate with AWS. Claude Code uses it to refresh credentials whenever possible, and it is also useful for working with API keys if you end up needing that; see Amazon Bedrock keys for more on this.

Tip

You are complete with this phase when you open a new terminal, run aws and get:

aws: [ERROR]: the following arguments are required: command

3. Set up AWS SSO

Run aws configure sso and respond as follows.

The items you need to type or paste are indicated with ** below. Otherwise, press Enter to accept defaults. The account number 00001 is a placeholder; replace it with your actual account number in every command.

As part of this process, a browser window will open where you need to authenticate.

** SSO session name (Recommended): aws-claude
** SSO start URL [None]: https://nih.awsapps.com/start
** SSO region [None]: us-east-1
   SSO registration scopes [sso:account:access]:
   Attempting to open your default browser.
   If the browser does not open, open the following URL:

   https://oidc.us-east-1.amazonaws.com/authorize?response_type=c.......

   The only AWS account available to you is: 00001
   Using the account ID 00001
   The only role available to you is: AWSPowerUserAccess
   Using the role name "AWSPowerUserAccess"
** Default client Region [None]: us-east-1
   CLI default output format (json if not specified) [None]:
   Profile name [AWSPowerUserAccess-00001]:
   To use this profile, specify the profile name using --profile, as shown:

   aws sts get-caller-identity --profile AWSPowerUserAccess-00001

You can inspect the resulting config in ~/.aws/config.

Then run the command it suggests at the end, again using your actual account number:

aws sts get-caller-identity --profile AWSPowerUserAccess-00001

We want to use this profile by default, so export these environment variables, for example in ~/.bashrc:

export AWS_PROFILE="AWSPowerUserAccess-00001"
export AWS_REGION=us-east-1

Source your shell config or open a new terminal, then run the same command without explicitly specifying the profile:

aws sts get-caller-identity

To inspect your current credentials, including expiration time, run:

aws configure export-credentials

If you ever need to refresh credentials manually, run:

aws sso login

This opens a browser. It may immediately report that your credentials have been shared successfully and can be used until your session expires.

Tip

You are complete with this phase when aws sso login opens the browser flow successfully and the page says, “Your credentials have been shared successfully and can be used until your session expires. You can now close this tab.”

4. Routine usage

Once AWS SSO is set up, it usually does not need to be changed and you just use it to refresh credentials.

The typical use-case for this repo is to use refresh.py, which automatically handles this for you.

The SSO session lasts for as long as the AWS account admins have configured. It can be hours or days before you need to log in again. Within that window, the AWS SDK automatically refreshes the shorter-lived (typically 1-hr) role credentials as needed.

Warning

This automatic refreshing of the short-lived credentails only works on the local machine. See Login model for why.

This means that if you are working on a remote machine, and the short-lived credentials expire every hour, you will need to run refresh.py every hour.

To streamline this as much as possible, you may want to ensure that:

  • you have an SSH key set up on the remote host

  • you have the ssh agent running with that key

  • you create an alias like alias r='refresh.py --remote biowulf.nih.gov' (or whatever host name you are working on).

Then it becomes a matter of hitting r on the local machine once an hour.

At any point, running this on a local machine will open a browser for reauthentication:

aws sso login