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

This topic describes how to configure the Amazon CLI to authenticate users with current Amazon IAM Identity Center (IAM Identity Center) to retrieve credentials to run Amazon Command Line Interface (Amazon 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 Amazon CLI](#cli-configure-sso-tutorial-install)
+ [Step 5: Configure your Amazon 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 Amazon credentials.

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

Follow the instructions in [Getting started](https://docs.amazonaws.cn/singlesignon/latest/userguide/getting-started.html) in the *Amazon 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 Amazon Web Services accounts, programmatic access details, and options for `Administrator` or `PowerUserAccess`. Select `PowerUserAccess` when working with the SDK.

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

Sign in to Amazon through your identity provider’s portal. If your Cloud Administrator has granted you `PowerUserAccess` (developer) permissions, you see the Amazon Web Services 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 Amazon through the Amazon access portal managed by my employer
<a name="accessportal-access"></a>

Sign in to Amazon through your Amazon access portal. If your Cloud Administrator has granted you `PowerUserAccess` (developer) permissions, you see the Amazon Web Services 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 Amazon 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 Amazon, 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 Amazon 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 Amazon 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.amazonaws.cn/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 Amazon Web Services Management Console and open the Amazon S3 console at [https://console.amazonaws.cn/s3/](https://console.amazonaws.cn/s3/).

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

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

Install the Amazon CLI following the instructions for your operating system. For more information, see [Installing or updating to the latest version of the Amazon 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 Amazon CLI. 

```
$ aws --version
```

## Step 5: Configure your Amazon 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 Amazon 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 Amazon 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 Amazon 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 Amazon CLI access to your data. Since the Amazon 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 Amazon 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.amazonaws.cn/cli/latest/reference/s3/ls.html](https://docs.amazonaws.cn/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 Amazon CLI, see [Troubleshooting errors for the Amazon 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.
+ [Amazon IAM Identity Center concepts for the Amazon CLI](cli-configure-sso-concepts.md)
+ [Configuring IAM Identity Center authentication with the Amazon CLI](cli-configure-sso.md)
+ [Installing or updating to the latest version of the Amazon CLI](getting-started-install.md)
+ [Configuration and credential file settings in the Amazon CLI](cli-configure-files.md)
+ [https://docs.amazonaws.cn/cli/latest/reference/configure/sso.html](https://docs.amazonaws.cn/cli/latest/reference/configure/sso.html) in the *Amazon CLI version 2 Reference*
+ [https://docs.amazonaws.cn/cli/latest/reference/configure/sso-session.html](https://docs.amazonaws.cn/cli/latest/reference/configure/sso-session.html) in the *Amazon CLI version 2 Reference*
+ [https://docs.amazonaws.cn/cli/latest/reference/sso/login.html](https://docs.amazonaws.cn/cli/latest/reference/sso/login.html) in the *Amazon CLI version 2 Reference*
+ [https://docs.amazonaws.cn/cli/latest/reference/sso/logout.html](https://docs.amazonaws.cn/cli/latest/reference/sso/logout.html) in the *Amazon CLI version 2 Reference*
+ [Setting up to use the Amazon CLI with CodeCatalyst](https://docs.amazonaws.cn/codecatalyst/latest/userguide/set-up-cli.html) in the *Amazon CodeCatalyst User Guide*
+ [OAuth 2.0 Access scopes](https://docs.amazonaws.cn/singlesignon/latest/userguide/customermanagedapps-saml2-oauth2.html#oidc-concept) in the *IAM Identity Center User Guide*
+ [Getting started tutorials](https://docs.amazonaws.cn/singlesignon/latest/userguide/tutorials.html) in the *IAM Identity Center User Guide*