# Configuring IAM Identity Center authentication with the AWS CLI
<a name="cli-configure-sso"></a>

This topic provides instructions on how to configure the AWS CLI with AWS IAM Identity Center (IAM Identity Center) to retrieve credentials to run AWS CLI commands. There are primarily two ways to authenticate users with IAM Identity Center to get credentials to run AWS CLI commands through the `config` file: 
+ **(Recommended)** SSO token provider configuration.
+ Legacy non-refreshable configuration.

For information on using bearer auth, which uses no account ID and role, see [Setting up to use the AWS CLI with CodeCatalyst](https://docs.aws.amazon.com/codecatalyst/latest/userguide/set-up-cli.html) in the *Amazon CodeCatalyst User Guide*.

**Note**  
For a guided process of using IAM Identity Center with AWS CLI commands, see [Tutorial: Using IAM Identity Center to run Amazon S3 commands in the AWS CLI](cli-configure-sso-tutorial.md).

**Topics**
+ [Prerequisites](#cli-configure-sso-prereqs)
+ [Configure your profile with the `aws configure sso` wizard](#cli-configure-sso-configure)
+ [Configure only your `sso-session` section with `aws configure sso-session` wizard](#cli-configure-sso-session)
+ [Manual configuration using the `config` file](#cli-configure-sso-manual)
+ [Sign in to an IAM Identity Center session](#cli-configure-sso-login)
+ [Run a command with your IAM Identity Center profile](#cli-configure-sso-use)
+ [Sign out of your IAM Identity Center sessions](#cli-configure-sso-logout)
+ [Troubleshooting](#cli-configure-sso-tshoot)
+ [Related resources](#cli-configure-sso-resources)

## Prerequisites
<a name="cli-configure-sso-prereqs"></a>
+ Install the AWS CLI. For more information, see [Installing or updating to the latest version of the AWS CLI](getting-started-install.md).
+ You must first have access to SSO authentication within IAM Identity Center. Choose one of the following methods to access your AWS credentials.

### I do not have established access through IAM Identity Center
<a name="idc-access"></a>

Follow the instructions in [Getting started](https://docs.aws.amazon.com/singlesignon/latest/userguide/getting-started.html) in the *AWS IAM Identity Center User Guide*. This process activates IAM Identity Center, creates an administrative user, and adds an appropriate least-privilege permission set.

**Note**  
Create a permission set that applies least-privilege permissions. We recommend using the predefined `PowerUserAccess` permission set, unless your employer has created a custom permission set for this purpose. 

Exit the portal and sign in again to see your AWS accounts, programmatic access details, and options for `Administrator` or `PowerUserAccess`. Select `PowerUserAccess` when working with the SDK.

### I already have access to AWS through a federated identity provider managed by my employer (such as Azure AD or Okta)
<a name="federated-access"></a>

Sign in to AWS through your identity provider’s portal. If your Cloud Administrator has granted you `PowerUserAccess` (developer) permissions, you see the AWS accounts that you have access to and your permission set. Next to the name of your permission set, you see options to access the accounts manually or programmatically using that permission set. 

Custom implementations might result in different experiences, such as different permission set names. If you're not sure which permission set to use, contact your IT team for help. 

### I already have access to AWS through the AWS access portal managed by my employer
<a name="accessportal-access"></a>

Sign in to AWS through your AWS access portal. If your Cloud Administrator has granted you `PowerUserAccess` (developer) permissions, you see the AWS accounts that you have access to and your permission set. Next to the name of your permission set, you see options to access the accounts manually or programmatically using that permission set. 

### I already have access to AWS through a federated custom identity provider managed by my employer
<a name="customfederated-access"></a>

Contact your IT team for help.

After gaining access to IAM Identity Center, gather your IAM Identity Center information by performing the following:

1. Gather your `SSO Start URL` and `SSO Region` values that you need to run `aws configure sso`

   1. In your AWS access portal, select the permission set you use for development, and select the **Access keys** link.

   1. In the **Get credentials** dialog box, choose the tab that matches your operating system. 

   1. Choose the **IAM Identity Center credentials** method to get the `SSO Start URL` and `SSO Region` values.

1. Alternatively, starting with version 2.22.0, you can use the Issuer URL instead of the Start URL. The Issuer URL is located in the AWS IAM Identity Center console in one of the following locations:
   + On the **Dashboard** page, the Issuer URL is in the settings summary.
   + On the **Settings** page, the Issuer URL is in the **Identity source** settings. 

1. For information on which scopes value to register, see [OAuth 2.0 Access scopes](https://docs.aws.amazon.com/singlesignon/latest/userguide/customermanagedapps-saml2-oauth2.html#oidc-concept) in the *IAM Identity Center User Guide*.

## Configure your profile with the `aws configure sso` wizard
<a name="cli-configure-sso-configure"></a>

**To configure an IAM Identity Center profile for your AWS CLI:**

1. In your preferred terminal, run the `aws configure sso` command.

------
#### [ (Recommended) IAM Identity Center ]

   Create a session name, provide your IAM Identity Center start URL or the issuer URL, the AWS Region that hosts the IAM Identity Center directory, and the registration scope.

   ```
   $ aws configure sso
   SSO session name (Recommended): my-sso
   SSO start URL [None]: https://my-sso-portal.awsapps.com/start
   SSO region [None]: us-east-1
   SSO registration scopes [None]: sso:account:access
   ```

   For dual-stack support, use the dual-stack SSO start URL:

   ```
   $ aws configure sso
   SSO session name (Recommended): my-sso
   SSO start URL [None]: https://ssoins-1234567890abcdef.portal.us-east-1.app.aws
   SSO region [None]: us-east-1
   SSO registration scopes [None]: sso:account:access
   ```

   Proof Key for Code Exchange (PKCE) authorization is used by default for the AWS CLI starting with version **2.22.0** and must be used on devices with a browser. To continue to use Device authorization, append the `--use-device-code` option.

   ```
   $ aws configure sso --use-device-code
   ```

------
#### [ Legacy IAM Identity Center ]

   Skip the session name and provide your IAM Identity Center start URL and the AWS Region that hosts the Identity Center directory. 

   ```
   $ aws configure sso
   SSO session name (Recommended):
   SSO start URL [None]: https://my-sso-portal.awsapps.com/start
   SSO region [None]:us-east-1
   ```

   For dual-stack support:

   ```
   $ aws configure sso
   SSO session name (Recommended):
   SSO start URL [None]: https://ssoins-1234567890abcdef.portal.us-east-1.app.aws
   SSO region [None]:us-east-1
   ```

------

1. The AWS CLI attempts to open your default browser for the sign in process of your IAM Identity Center account. This process may prompt you to allow the AWS CLI access to your data. Since the AWS CLI is built on top of the SDK for Python, permission messages may contain variations of the `botocore` name.
   + **If the AWS CLI cannot open the browser**, instructions to manually start the sign in process are displayed based on the type of authorization you are using. 

------
#### [ PKCE authorization ]

     Proof Key for Code Exchange (PKCE) authorization is used by default for the AWS CLI starting with version 2.22.0. The URL displayed is a unique URL starting with:
     + IPv4: *https://oidc.us-east-1.amazonaws.com/authorize*
     + Dual-stack: *https://oidc.us-east-1.api.aws/authorize*

     PKCE authorization URLs must be opened on the same device you're signing in to and must be used for a device with a browser.

     ```
     Attempting to automatically open the SSO authorization page in your 
     default browser.
     If the browser does not open or you wish to use a different device to 
     authorize the request, open the following URL:
     
     https://oidc.us-east-1.amazonaws.com/authorize?<abbreviated>
     ```

------
#### [ Device authorization ]

     The OAuth 2.0 device authorization is used by the AWS CLI for versions older than 2.22.0. You can enable this method on newer versions by using the `--use-device-code` option.

     Device authorization URLs do not need to be opened on the same device you're signing in to and can be used for a device with or without a browser. The endpoint format depends on your configuration:
     + IPv4: *https://device.sso.us-west-2.amazonaws.com/*
     + Dual-stack: *https://device.sso.us-west-2.api.aws/*

     ```
     If the browser does not open or you wish to use a different device to 
     authorize this request, open the following URL:
     https://device.sso.us-west-2.amazonaws.com/
     
     Then enter the code:
     QCFK-N451
     ```

------

1. Select the AWS account to use from the displayed list. If you are authorized to use only one account, the AWS CLI automatically selects that account and skips the prompt.

   ```
   There are 2 AWS accounts available to you.
   > DeveloperAccount, developer-account-admin@example.com (123456789011) 
     ProductionAccount, production-account-admin@example.com (123456789022)
   ```

1. Select the IAM role to use from the displayed list. If there is only one role available, the AWS CLI automatically selects that role and skips the prompt.

   ```
   Using the account ID 123456789011
   There are 2 roles available to you.
   > ReadOnly
     FullAccess
   ```

1. Specify the [default output format](cli-configure-files.md#cli-config-output), the [default AWS Region](cli-configure-files.md#cli-config-region) to send commands to, and a [name for the profile](cli-configure-files.md). If you specify `default` as the profile name, this profile becomes the default profile used. In the following example, the user enters a default Region, default output format, and the name of the profile.

   ```
   Default client Region [None]: us-west-2<ENTER>
   CLI default output format (json if not specified) [None]: json<ENTER>
   Profile name [123456789011_ReadOnly]: my-dev-profile<ENTER>
   ```

1. A final message describes the completed profile configuration. You can now use this profile to request credentials. Use the `aws sso login` command to request and retrieve the credentials needed to run commands. For instructions, see [Sign in to an IAM Identity Center session](#cli-configure-sso-login).

### Generated configuration file
<a name="cli-configure-sso-generated"></a>

These steps result in creating the `sso-session` section and named profile in the `config` file that looks like the following:

------
#### [ IAM Identity Center ]

```
[profile my-dev-profile]
sso_session = my-sso
sso_account_id = 123456789011
sso_role_name = readOnly
region = us-west-2
output = json

[sso-session my-sso]
sso_region = us-east-1
sso_start_url = https://my-sso-portal.awsapps.com/start
sso_registration_scopes = sso:account:access
```

For dual-stack support:

```
[profile my-dev-profile]
sso_session = my-sso
sso_account_id = 123456789011
sso_role_name = readOnly
region = us-west-2
output = json

[sso-session my-sso]
sso_region = us-east-1
sso_start_url = https://ssoins-1234567890abcdef.portal.us-east-1.app.aws
sso_registration_scopes = sso:account:access
```

------
#### [ Legacy IAM Identity Center ]

```
[profile my-dev-profile]
sso_start_url = https://my-sso-portal.awsapps.com/start
sso_region = us-east-1
sso_account_id = 123456789011
sso_role_name = readOnly
region = us-west-2
output = json
```

For dual-stack support:

```
[profile my-dev-profile]
sso_start_url = https://ssoins-1234567890abcdef.portal.us-east-1.app.aws
sso_region = us-east-1
sso_account_id = 123456789011
sso_role_name = readOnly
region = us-west-2
output = json
```

------

## Configure only your `sso-session` section with `aws configure sso-session` wizard
<a name="cli-configure-sso-session"></a>

**Note**  
This configuration is not compatible with the legacy IAM Identity Center.

The `aws configure sso-session` command updates the `sso-session` sections in the `~/.aws/config` file. Run the `aws configure sso-session` command and provide your IAM Identity Center start URL or issuer URL and the AWS Region that hosts the IAM Identity Center directory. 

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

For dual-stack support, use the dual-stack SSO start URL:

```
$ aws configure sso-session
SSO session name: my-sso
SSO start URL [None]: https://ssoins-1234567890abcdef.portal.us-east-1.app.aws
SSO region [None]: us-east-1
SSO registration scopes [None]: sso:account:access
```

## Manual configuration using the `config` file
<a name="cli-configure-sso-manual"></a>

IAM Identity Center configuration information is stored in the `config` file and can be edited using a text editor. To manually add IAM Identity Center support to a named profile, you must add keys and values to the `config` file. 

### IAM Identity Center configuration file
<a name="cli-configure-sso-manual-config"></a>

The `sso-session` section of the `config` file is used to group configuration variables for acquiring SSO access tokens, which can then be used to acquire AWS credentials. The following settings are used:
+ **(Required)** `sso\$1start\$1url`
+ **(Required)** `sso\$1region`
+ `sso\$1account\$1id`
+ `sso\$1role\$1name`
+ `sso\$1registration\$1scopes`

You define an `sso-session` section and associate it to a profile. The `sso_region` and `sso_start_url` settings must be set within the `sso-session` section. Typically, `sso_account_id` and `sso_role_name` must be set in the `profile` section so that the SDK can request SSO credentials. 

The following example configures the SDK to request SSO credentials and supports automated token refresh: 

```
[profile dev]
sso_session = my-sso
sso_account_id = 111122223333
sso_role_name = SampleRole

[sso-session my-sso]
sso_region = us-east-1
sso_start_url = https://my-sso-portal.awsapps.com/start
```

For dual-stack support, use the dual-stack SSO start URL format:

```
[profile dev]
sso_session = my-sso
sso_account_id = 111122223333
sso_role_name = SampleRole

[sso-session my-sso]
sso_region = us-east-1
sso_start_url = https://ssoins-1234567890abcdef.portal.us-east-1.app.aws
```

This also allows `sso-session` configurations to be reused across multiple profiles: 

```
[profile dev]
sso_session = my-sso
sso_account_id = 111122223333
sso_role_name = SampleRole

[profile prod]
sso_session = my-sso
sso_account_id = 111122223333
sso_role_name = SampleRole2

[sso-session my-sso]
sso_region = us-east-1
sso_start_url = https://my-sso-portal.awsapps.com/start
```

For dual-stack support, use the dual-stack SSO start URL format:

```
[profile dev]
sso_session = my-sso
sso_account_id = 111122223333
sso_role_name = SampleRole

[profile prod]
sso_session = my-sso
sso_account_id = 111122223333
sso_role_name = SampleRole2

[sso-session my-sso]
sso_region = us-east-1
sso_start_url = https://ssoins-1234567890abcdef.portal.us-east-1.app.aws
```

However, `sso_account_id` and `sso_role_name` aren't required for all scenarios of SSO token configuration. If your application only uses AWS services that support bearer authentication, then traditional AWS credentials are not needed. Bearer authentication is an HTTP authentication scheme that uses security tokens called bearer tokens. In this scenario, `sso_account_id` and `sso_role_name` aren't required. See the individual guide for your AWS service to determine if it supports bearer token authorization.

Additionally, registration scopes can be configured as part of a `sso-session`. Scope is a mechanism in OAuth 2.0 to limit an application's access to a user's account. An application can request one or more scopes, and the access token issued to the application will be limited to the scopes granted. These scopes define the permissions requested to be authorized for the registered OIDC client and access tokens retrieved by the client. The following example sets `sso_registration_scopes` to provide access for listing accounts/roles: 

```
[sso-session my-sso]
sso_region = us-east-1
sso_start_url = https://my-sso-portal.awsapps.com/start
sso_registration_scopes = sso:account:access
```

For dual-stack support:

```
[sso-session my-sso]
sso_region = us-east-1
sso_start_url = https://ssoins-1234567890abcdef.portal.us-east-1.app.aws
sso_registration_scopes = sso:account:access
```

The authentication token is cached to disk under the `sso/cache` directory with a filename based on the session name. 

### Legacy IAM Identity Center configuration file
<a name="cli-configure-sso-manual-legacy"></a>

**Note**  
Automated token refresh isn't supported using the legacy non-refreshable configuration. We recommend using the SSO token configuration.

To manually add IAM Identity Center support to a named profile, you must add the following keys and values to the profile definition in the `config` file.
+ `sso\$1start\$1url`
+ `sso\$1region`
+ `sso\$1account\$1id`
+ `sso\$1role\$1name`

You can include any other keys and values that are valid in the `.aws/config` file. The following example is an IAM Identity Center profile:

```
[profile my-sso-profile]
sso_start_url = https://my-sso-portal.awsapps.com/start
sso_region = us-west-2
sso_account_id = 111122223333
sso_role_name = SSOReadOnlyRole
region = us-west-2
output = json
```

For dual-stack support:

```
[profile my-sso-profile]
sso_start_url = https://ssoins-1234567890abcdef.portal.us-east-1.app.aws
sso_region = us-west-2
sso_account_id = 111122223333
sso_role_name = SSOReadOnlyRole
region = us-west-2
output = json
```

To run commands, you must first [Sign in to an IAM Identity Center session](#cli-configure-sso-login) to request and retrieve your temporary credentials.

For more information on the `config` and `credentials` files, see [Configuration and credential file settings in the AWS CLI](cli-configure-files.md).

## Sign in to an IAM Identity Center session
<a name="cli-configure-sso-login"></a>

**Note**  
The sign in process may prompt you to allow the AWS CLI access to your data. Since the AWS CLI is built on top of the SDK for Python, permission messages may contain variations of the `botocore` name.

To retrieve and cache a set of IAM Identity Center credentials, run the following command for the AWS CLI to open your default browser and verify your IAM Identity Center log in. 

```
$ aws sso login --profile my-dev-profile
SSO authorization page has automatically been opened in your default browser. 
Follow the instructions in the browser to complete this authorization request.
Successfully logged into Start URL: https://my-sso-portal.awsapps.com/start
```

Your IAM Identity Center session credentials are cached and the AWS CLI uses them to securely retrieve AWS credentials for the IAM role specified in the profile. 

### If the AWS CLI can't open your browser
<a name="cli-configure-sso-login-browser"></a>

If the AWS CLI cannot automatically open your browser, instructions to manually start the sign in process are displayed based on the type of authorization you are using. 

------
#### [ PKCE authorization ]

Proof Key for Code Exchange (PKCE) authorization is used by default for the AWS CLI starting with version 2.22.0. The URL displayed is a unique URL starting with:
+ IPv4: *https://oidc.us-east-1.amazonaws.com/authorize*
+ Dual-stack: *https://oidc.us-east-1.api.aws/authorize*

PKCE authorization URLs must be opened on the same device you're signing in to and must be used for a device with a browser.

```
Attempting to automatically open the SSO authorization page in your 
default browser.
If the browser does not open or you wish to use a different device to 
authorize the request, open the following URL:

https://oidc.us-east-1.amazonaws.com/authorize?<abbreviated>
```

------
#### [ Device authorization ]

The OAuth 2.0 device authorization is used by the AWS CLI for versions older than 2.22.0. You can enable this method on newer versions by using the `--use-device-code` option.

Device authorization URLs do not need to be opened on the same device you're signing in to and can be used for a device with or without a browser.

```
If the browser does not open or you wish to use a different device to 
authorize this request, open the following URL:
https://device.sso.us-west-2.amazonaws.com/

Then enter the code:
QCFK-N451
```

------

You can also specify which `sso-session` profile to use when logging in using the `--sso-session` parameter of the `aws sso login` command. The `sso-session` option is not available for legacy IAM Identity Center.

```
$ aws sso login --sso-session my-dev-session
```

Starting with version 2.22.0, PKCE authorization is the default. To use device authorization for signing in, add the `--use-device-code` option.

```
$ aws sso login --profile my-dev-profile --use-device-code
```

The authentication token is cached to disk under the `~/.aws/sso/cache` directory with a filename based on the `sso_start_url`. 

## Run a command with your IAM Identity Center profile
<a name="cli-configure-sso-use"></a>

Once logged in, you can use your credentials to invoke AWS CLI commands with the associated named profile. The following example shows a command using a profile:

```
$ aws sts get-caller-identity --profile my-dev-profile
```

As long as you are signed in to IAM Identity Center and those cached credentials are not expired, the AWS CLI automatically renews expired AWS credentials when needed. However, if your IAM Identity Center credentials expire, you must explicitly renew them by logging in to your IAM Identity Center account again.

## Sign out of your IAM Identity Center sessions
<a name="cli-configure-sso-logout"></a>

When you are done using your IAM Identity Center profile, you can let your credentials expire or run the following command to delete your cached credentials.

```
$ aws sso logout
Successfully signed out of all SSO profiles.
```

## Troubleshooting
<a name="cli-configure-sso-tshoot"></a>

If you come across issues using the AWS CLI, see [Troubleshooting errors for the AWS CLI](cli-chap-troubleshooting.md) for troubleshooting steps.

## Related resources
<a name="cli-configure-sso-resources"></a>

Additional resources are as follows.
+ [AWS IAM Identity Center concepts for the AWS CLI](cli-configure-sso-concepts.md)
+ [Tutorial: Using IAM Identity Center to run Amazon S3 commands in the AWS CLI](cli-configure-sso-tutorial.md)
+ [Installing or updating to the latest version of the AWS CLI](getting-started-install.md)
+ [Configuration and credential file settings in the AWS CLI](cli-configure-files.md)
+ [https://docs.aws.amazon.com/cli/latest/reference/configure/sso.html](https://docs.aws.amazon.com/cli/latest/reference/configure/sso.html) in the *AWS CLI version 2 Reference*
+ [https://docs.aws.amazon.com/cli/latest/reference/configure/sso-session.html](https://docs.aws.amazon.com/cli/latest/reference/configure/sso-session.html) in the *AWS CLI version 2 Reference*
+ [https://docs.aws.amazon.com/cli/latest/reference/sso/login.html](https://docs.aws.amazon.com/cli/latest/reference/sso/login.html) in the *AWS CLI version 2 Reference*
+ [https://docs.aws.amazon.com/cli/latest/reference/sso/logout.html](https://docs.aws.amazon.com/cli/latest/reference/sso/logout.html) in the *AWS CLI version 2 Reference*
+ [Setting up to use the AWS CLI with CodeCatalyst](https://docs.aws.amazon.com/codecatalyst/latest/userguide/set-up-cli.html) in the *Amazon CodeCatalyst User Guide*
+ [OAuth 2.0 Access scopes](https://docs.aws.amazon.com/singlesignon/latest/userguide/customermanagedapps-saml2-oauth2.html#oidc-concept) in the *IAM Identity Center User Guide*
+ [Getting started tutorials](https://docs.aws.amazon.com/singlesignon/latest/userguide/tutorials.html) in the *IAM Identity Center User Guide*

# AWS IAM Identity Center concepts for the AWS CLI
<a name="cli-configure-sso-concepts"></a>

This topic describes the key concepts of AWS IAM Identity Center (IAM Identity Center). IAM Identity Center is a cloud-based IAM service that simplifies user access management across multiple AWS accounts, applications, SDKs, and tools by integrating with existing identity providers (IdP). It enables secure single sign-on, permission management, and auditing through a centralized user portal, streamlining identity and access governance for organizations.

**Topics**
+ [

## What is IAM Identity Center
](#cli-configure-sso-concepts-what)
+ [

## Terms
](#cli-configure-sso-terms)
+ [

## How IAM Identity Center works
](#cli-configure-sso-concepts-process)
+ [

## Additional resources
](#cli-configure-sso-concepts-resources)

## What is IAM Identity Center
<a name="cli-configure-sso-concepts-what"></a>

IAM Identity Center is a cloud-based identity and access management (IAM) service that enables you to centrally manage access to multiple AWS accounts and business applications.

It provides a user portal where authorized users can access the AWS accounts and applications they've been granted permission to, using their existing corporate credentials. This allows organizations to enforce consistent security policies and streamline user access management.

Regardless of which IdP you use, IAM Identity Center abstracts those distinctions away. For example, you can connect Microsoft Azure AD as described in the blog article [The Next Evolution in IAM Identity Center](https://aws.amazon.com/blogs/aws/the-next-evolution-in-aws-single-sign-on/).

**Note**  
For information on using bearer auth, which uses no account ID and role, see [Setting up to use the AWS CLI with CodeCatalyst](https://docs.aws.amazon.com/codecatalyst/latest/userguide/set-up-cli.html) in the *Amazon CodeCatalyst User Guide*.

## Terms
<a name="cli-configure-sso-terms"></a>

Common terms when using IAM Identity Center are as follows:

**Identity Provider (IdP)**  
An identity management system such as IAM Identity Center, Microsoft Azure AD, Okta, or your own corporate directory service.

**AWS IAM Identity Center**  
IAM Identity Center is the AWS owned IdP service. Formerly known as AWS Single Sign-On, SDKs and tools keep the `sso` API namespaces for backward compatibility. For more information, see [IAM Identity Center rename](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html#renamed) in the *AWS IAM Identity Center User Guide*.

**AWS access portal URL, SSO start URL, Start URL**  
Your organization's unique IAM Identity Center URL to access your authorized AWS accounts, services, and resources.

**Issuer URL**  
Your organization's unique IAM Identity Center issuer URL for programmatic access for your authorized AWS accounts, services, and resources. Starting with version 2.22.0 of the AWS CLI, issuer URL can be used interchangeably with the start URL.

**Federation**  
The process of establishing trust between IAM Identity Center and an identity provider to enable single sign-on (SSO).

**AWS accounts**  
The AWS accounts that you provide users access to through AWS IAM Identity Center.

**Permission sets, AWS credentials, credentials, sigv4 credentials**  
Predefined collections of permissions that can be assigned to users or groups to grant access to AWS services.

**Registration scopes, access scopes, scopes**  
Scopes are a mechanism in OAuth 2.0 to limit an application's access to a user's account. An application can request one or more scopes, and the access token issued to the application is limited to the scopes granted. For information on scopes, see [Access scopes](https://docs.aws.amazon.com/singlesignon/latest/userguide/customermanagedapps-saml2-oauth2.html#oidc-concept) in the *IAM Identity Center User Guide*.

**Tokens, refresh token, access token**  
Tokens are temporary security credentials that are issued to you upon authentication. These tokens contain information about your identity and the permissions you've been granted.  
When you access an AWS resource or application through the IAM Identity Center portal, your token is presented to AWS for authentication and authorization. This allows AWS to verify your identity and ensure you have the necessary permissions to perform your requested actions.   
The authentication token is cached to disk under the `~/.aws/sso/cache` directory with a JSON filename based on the session name.

**Session**  
An IAM Identity Center session refers to the period of time that a user is authenticated and authorized to access AWS resources or applications. When a user signs in to the IAM Identity Center portal, a session is established, and the user's token is valid for a specified duration. For more information on setting session durations, see [Set session duration](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtosessionduration.html) in the *AWS IAM Identity Center User Guide*.  
During the session, you can navigate between different AWS accounts and applications without having to re-authenticate, as long as their session remains active. When the session expires, sign in again to renew your access.  
IAM Identity Center sessions help to provide a seamless user experience while also enforcing security best practices by limiting the validity of user access credentials.

**Authorization code grant with PKCE, PKCE, Proof Key for Code Exchange**  
Starting with version 2.22.0, Proof Key for Code Exchange (PKCE) is an OAuth 2.0 authentication grant flow for devices with a browser. PKCE is a simple and safe way to authenticate and obtain consent to access your AWS resources from desktops and mobile devices with web browsers. This is the default authorization behavior. For more information on PKCE, see [Authorization Code Grant with PKCE](https://docs.aws.amazon.com/singlesignon/latest/userguide/customermanagedapps-saml2-oauth2.html#auth-code-grant-pkce) in the *AWS IAM Identity Center User Guide*.

**Device authorization grant**  
An OAuth 2.0 authentication grant flow for devices with or without a web browser. For more information on setting session durations, see [Device Authorization Grant](https://docs.aws.amazon.com/singlesignon/latest/userguide/customermanagedapps-saml2-oauth2.html#device-auth-grant) in the *AWS IAM Identity Center User Guide*.

## How IAM Identity Center works
<a name="cli-configure-sso-concepts-process"></a>

IAM Identity Center integrates with your organization's identity provider, such as IAM Identity Center, Microsoft Azure AD, or Okta. Users authenticate against this identity provider, and IAM Identity Center then maps those identities to the appropriate permissions and access within your AWS environment.

The following IAM Identity Center workflow assumes you have already configured your AWS CLI to use IAM Identity Center:

1. In your preferred terminal, run the `aws sso login` command.

1. Sign in to your AWS access portal to start a new session. 
   + When you start a new session, you receive a refresh token and access token that is cached.
   + If you already have an active session, the existing session is reused and expires when the existing session expires.

1. Based on the profile you've set up in your `config` file, IAM Identity Center assumes the appropriate permission sets, granting access to the relevant AWS accounts and applications. 

1. The AWS CLI, SDKs, and Tools use your assumed IAM role to make calls to AWS services such as creating Amazon S3 buckets until that session expires.

1. The access token from IAM Identity Center is checked hourly and is automatically refreshed using the refresh token.
   + If the access token is expired, the SDK or tool uses the refresh token to get a new access token. These tokens' session durations are then compared, and if the refresh token is not expired IAM Identity Center provides a new access token.
   + If the refresh token has expired, then no new access tokens are provided and your session has ended.

1. Sessions end after refresh tokens expire, or when you manually log out using the `aws sso logout` command. Cached credentials are removed. To continue accessing services using IAM Identity Center, you must start a new session using the the `aws sso login` command.

## Additional resources
<a name="cli-configure-sso-concepts-resources"></a>

Additional resources are as follows.
+ [Configuring IAM Identity Center authentication with the AWS CLI](cli-configure-sso.md)
+ [Tutorial: Using IAM Identity Center to run Amazon S3 commands in the AWS CLI](cli-configure-sso-tutorial.md)
+ [Installing or updating to the latest version of the AWS CLI](getting-started-install.md)
+ [Configuration and credential file settings in the AWS CLI](cli-configure-files.md)
+ [https://docs.aws.amazon.com/cli/latest/reference/configure/sso.html](https://docs.aws.amazon.com/cli/latest/reference/configure/sso.html) in the *AWS CLI version 2 Reference*
+ [https://docs.aws.amazon.com/cli/latest/reference/configure/sso-session.html](https://docs.aws.amazon.com/cli/latest/reference/configure/sso-session.html) in the *AWS CLI version 2 Reference*
+ [https://docs.aws.amazon.com/cli/latest/reference/sso/login.html](https://docs.aws.amazon.com/cli/latest/reference/sso/login.html) in the *AWS CLI version 2 Reference*
+ [https://docs.aws.amazon.com/cli/latest/reference/sso/logout.html](https://docs.aws.amazon.com/cli/latest/reference/sso/logout.html) in the *AWS CLI version 2 Reference*
+ [Setting up to use the AWS CLI with CodeCatalyst](https://docs.aws.amazon.com/codecatalyst/latest/userguide/set-up-cli.html) in the *Amazon CodeCatalyst User Guide*
+ [IAM Identity Center rename](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html#renamed) in the *AWS IAM Identity Center User Guide*
+ [OAuth 2.0 Access scopes](https://docs.aws.amazon.com/singlesignon/latest/userguide/customermanagedapps-saml2-oauth2.html#oidc-concept) in the *IAM Identity Center User Guide*
+ [Set session duration](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtosessionduration.html) in the *AWS IAM Identity Center User Guide*
+ [Getting started tutorials](https://docs.aws.amazon.com/singlesignon/latest/userguide/tutorials.html) in the *IAM Identity Center User Guide*

# Tutorial: Using IAM Identity Center to run Amazon S3 commands in the AWS CLI
<a name="cli-configure-sso-tutorial"></a>

This topic describes how to configure the AWS CLI to authenticate users with current AWS IAM Identity Center (IAM Identity Center) to retrieve credentials to run AWS Command Line Interface (AWS CLI) commands for Amazon Simple Storage Service (Amazon S3). 

**Topics**
+ [

## Step 1: Authentication in IAM Identity Center
](#cli-configure-sso-tutorial-authentication)
+ [

## Step 2: Gather your IAM Identity Center information
](#cli-configure-sso-tutorial-gather)
+ [

## Step 3: Create Amazon S3 buckets
](#cli-configure-sso-tutorial-buckets)
+ [

## Step 4: Install the AWS CLI
](#cli-configure-sso-tutorial-install)
+ [

## Step 5: Configure your AWS CLI profile
](#cli-configure-sso-tutorial-configure)
+ [

## Step 6: Log in to IAM Identity Center
](#cli-configure-sso-tutorial-login.title)
+ [

## Step 7: Run Amazon S3 commands
](#cli-configure-sso-tutorial-commands)
+ [

## Step 8: Log out of IAM Identity Center
](#cli-configure-sso-tutorial-logout)
+ [

## Step 9: Clean up resources
](#cli-configure-sso-tutorial-cleanup)
+ [

## Troubleshooting
](#cli-configure-sso-tutorial-tshoot)
+ [

## Additional resources
](#cli-configure-sso-tutorial-resources.title)

## Step 1: Authentication in IAM Identity Center
<a name="cli-configure-sso-tutorial-authentication"></a>

Gain access to SSO authentication within IAM Identity Center. Choose one of the following methods to access your AWS credentials.

### I do not have established access through IAM Identity Center
<a name="idc-access"></a>

Follow the instructions in [Getting started](https://docs.aws.amazon.com/singlesignon/latest/userguide/getting-started.html) in the *AWS IAM Identity Center User Guide*. This process activates IAM Identity Center, creates an administrative user, and adds an appropriate least-privilege permission set.

**Note**  
Create a permission set that applies least-privilege permissions. We recommend using the predefined `PowerUserAccess` permission set, unless your employer has created a custom permission set for this purpose. 

Exit the portal and sign in again to see your AWS accounts, programmatic access details, and options for `Administrator` or `PowerUserAccess`. Select `PowerUserAccess` when working with the SDK.

### I already have access to AWS through a federated identity provider managed by my employer (such as Azure AD or Okta)
<a name="federated-access"></a>

Sign in to AWS through your identity provider’s portal. If your Cloud Administrator has granted you `PowerUserAccess` (developer) permissions, you see the AWS accounts that you have access to and your permission set. Next to the name of your permission set, you see options to access the accounts manually or programmatically using that permission set. 

Custom implementations might result in different experiences, such as different permission set names. If you're not sure which permission set to use, contact your IT team for help. 

### I already have access to AWS through the AWS access portal managed by my employer
<a name="accessportal-access"></a>

Sign in to AWS through your AWS access portal. If your Cloud Administrator has granted you `PowerUserAccess` (developer) permissions, you see the AWS accounts that you have access to and your permission set. Next to the name of your permission set, you see options to access the accounts manually or programmatically using that permission set. 

### I already have access to AWS through a federated custom identity provider managed by my employer
<a name="customfederated-access"></a>

Contact your IT team for help.

## Step 2: Gather your IAM Identity Center information
<a name="cli-configure-sso-tutorial-gather"></a>

After gaining access to AWS, gather your IAM Identity Center information by performing the following:

1. Gather your `SSO Start URL` and `SSO Region` values that you need to run `aws configure sso`

   1. In your AWS access portal, select the permission set you use for development, and select the **Access keys** link.

   1. In the **Get credentials** dialog box, choose the tab that matches your operating system. 

   1. Choose the **IAM Identity Center credentials** method to get the `SSO Start URL` and `SSO Region` values.

1. Alternatively, starting with version 2.22.0, you can use the new Issuer URL instead of the Start URL. The Issuer URL is located in the AWS IAM Identity Center console in one of the following locations:
   + On the **Dashboard** page, the Issuer URL is in the settings summary.
   + On the **Settings** page, the Issuer URL is in the **Identity source** settings. 

1. For information on which scopes value to register, see [OAuth 2.0 Access scopes](https://docs.aws.amazon.com/singlesignon/latest/userguide/customermanagedapps-saml2-oauth2.html#oidc-concept) in the *IAM Identity Center User Guide*.

## Step 3: Create Amazon S3 buckets
<a name="cli-configure-sso-tutorial-buckets"></a>

Sign in to the AWS Management Console and open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/).

For this tutorial, create a few buckets to be later retrieved in a list.

## Step 4: Install the AWS CLI
<a name="cli-configure-sso-tutorial-install"></a>

Install the AWS CLI following the instructions for your operating system. For more information, see [Installing or updating to the latest version of the AWS CLI](getting-started-install.md).

Once installed, you can verify the installation by opening your preferred terminal and running the following command. This should display your installed version of the AWS CLI. 

```
$ aws --version
```

## Step 5: Configure your AWS CLI profile
<a name="cli-configure-sso-tutorial-configure"></a>

Configure your profile using one of the following methods

### Configure your profile with the `aws configure sso` wizard
<a name="li-configure-sso-tutorial-configure-wizard"></a>

The `sso-session` section of the `config` file is used to group configuration variables for acquiring SSO access tokens, which can then be used to acquire AWS credentials. The following settings are used:
+ **(Required)** `sso\$1start\$1url`
+ **(Required)** `sso\$1region`
+ `sso\$1account\$1id`
+ `sso\$1role\$1name`
+ `sso\$1registration\$1scopes`

You define an `sso-session` section and associate it to a profile. The `sso_region` and `sso_start_url` settings must be set within the `sso-session` section. Typically, `sso_account_id` and `sso_role_name` must be set in the `profile` section so that the SDK can request SSO credentials. 

The following example configures the SDK to request SSO credentials and supports automated token refresh: 

```
$ aws configure sso
SSO session name (Recommended): my-sso
SSO start URL [None]: https://my-sso-portal.awsapps.com/start
SSO region [None]: us-east-1
SSO registration scopes [None]: sso:account:access
```

For dual-stack support, you can use the dual-stack SSO start URL format:

```
$ aws configure sso
SSO session name (Recommended): my-sso
SSO start URL [None]: https://ssoins-1234567890abcdef.portal.us-east-1.app.aws
SSO region [None]: us-east-1
SSO registration scopes [None]: sso:account:access
```

Proof Key for Code Exchange (PKCE) authorization is used by default for the AWS CLI starting with version 2.22.0 and must be used on devices with a browser. To continue to use Device authorization, append the `--use-device-code` option.

```
$ aws configure sso --use-device-code
```

### Manual configuration using the `config` file
<a name="cli-configure-sso-tutorial-configure-manual"></a>

The `sso-session` section of the `config` file is used to group configuration variables for acquiring SSO access tokens, which can then be used to acquire AWS credentials. The following settings are used:
+ **(Required)** `sso\$1start\$1url`
+ **(Required)** `sso\$1region`
+ `sso\$1account\$1id`
+ `sso\$1role\$1name`
+ `sso\$1registration\$1scopes`

You define an `sso-session` section and associate it to a profile. `sso_region` and `sso_start_url` must be set within the `sso-session` section. Typically, `sso_account_id` and `sso_role_name` must be set in the `profile` section so that the SDK can request SSO credentials. 

The following example configures the SDK to request SSO credentials and supports automated token refresh: 

```
[profile my-dev-profile]
sso_session = my-sso
sso_account_id = 111122223333
sso_role_name = SampleRole

[sso-session my-sso]
sso_region = us-east-1
sso_start_url = https://my-sso-portal.awsapps.com/start
sso_registration_scopes = sso:account:access
```

For dual-stack support, use the dual-stack SSO start URL format:

```
[profile my-dev-profile]
sso_session = my-sso
sso_account_id = 111122223333
sso_role_name = SampleRole

[sso-session my-sso]
sso_region = us-east-1
sso_start_url = https://ssoins-1234567890abcdef.portal.us-east-1.app.aws
sso_registration_scopes = sso:account:access
```

The authentication token is cached to disk under the `~/.aws/sso/cache` directory with a filename based on the session name. 

## Step 6: Log in to IAM Identity Center
<a name="cli-configure-sso-tutorial-login.title"></a>

**Note**  
The sign in process may prompt you to allow the AWS CLI access to your data. Since the AWS CLI is built on top of the SDK for Python, permission messages may contain variations of the `botocore` name.

To retrieve and cache your IAM Identity Center credentials, run the following command for the AWS CLI to open your default browser and verify your IAM Identity Center log in.

```
$ aws sso login --profile my-dev-profile
```

Starting with version 2.22.0, PKCE authorization is the default. To use device authorization for signing in, add the `--use-device-code` option.

```
$ aws sso login --profile my-dev-profile --use-device-code
```

## Step 7: Run Amazon S3 commands
<a name="cli-configure-sso-tutorial-commands"></a>

To list the buckets you created earlier, use the [https://docs.aws.amazon.com/cli/latest/reference/s3/ls.html](https://docs.aws.amazon.com/cli/latest/reference/s3/ls.html) command. The following example lists all of your Amazon S3 buckets.

```
$ aws s3 ls
2018-12-11 17:08:50 my-bucket
2018-12-14 14:55:44 my-bucket2
```

## Step 8: Log out of IAM Identity Center
<a name="cli-configure-sso-tutorial-logout"></a>

When you are done using your IAM Identity Center profile, run the following command to delete your cached credentials.

```
$ aws sso logout
Successfully signed out of all SSO profiles.
```

## Step 9: Clean up resources
<a name="cli-configure-sso-tutorial-cleanup"></a>

After you're done with this tutorial, clean up any resources you created during this tutorial that you no longer need, including Amazon S3 buckets.

## Troubleshooting
<a name="cli-configure-sso-tutorial-tshoot"></a>

If you come across issues using the AWS CLI, see [Troubleshooting errors for the AWS CLI](cli-chap-troubleshooting.md) for common troubleshooting steps.

## Additional resources
<a name="cli-configure-sso-tutorial-resources.title"></a>

Additional resources are as follows.
+ [AWS IAM Identity Center concepts for the AWS CLI](cli-configure-sso-concepts.md)
+ [Configuring IAM Identity Center authentication with the AWS CLI](cli-configure-sso.md)
+ [Installing or updating to the latest version of the AWS CLI](getting-started-install.md)
+ [Configuration and credential file settings in the AWS CLI](cli-configure-files.md)
+ [https://docs.aws.amazon.com/cli/latest/reference/configure/sso.html](https://docs.aws.amazon.com/cli/latest/reference/configure/sso.html) in the *AWS CLI version 2 Reference*
+ [https://docs.aws.amazon.com/cli/latest/reference/configure/sso-session.html](https://docs.aws.amazon.com/cli/latest/reference/configure/sso-session.html) in the *AWS CLI version 2 Reference*
+ [https://docs.aws.amazon.com/cli/latest/reference/sso/login.html](https://docs.aws.amazon.com/cli/latest/reference/sso/login.html) in the *AWS CLI version 2 Reference*
+ [https://docs.aws.amazon.com/cli/latest/reference/sso/logout.html](https://docs.aws.amazon.com/cli/latest/reference/sso/logout.html) in the *AWS CLI version 2 Reference*
+ [Setting up to use the AWS CLI with CodeCatalyst](https://docs.aws.amazon.com/codecatalyst/latest/userguide/set-up-cli.html) in the *Amazon CodeCatalyst User Guide*
+ [OAuth 2.0 Access scopes](https://docs.aws.amazon.com/singlesignon/latest/userguide/customermanagedapps-saml2-oauth2.html#oidc-concept) in the *IAM Identity Center User Guide*
+ [Getting started tutorials](https://docs.aws.amazon.com/singlesignon/latest/userguide/tutorials.html) in the *IAM Identity Center User Guide*