# 使用 Amazon CLI 配置 IAM Identity Center 身份验证
<a name="cli-configure-sso"></a>

本主题提供的说明可帮助您了解如何使用 Amazon IAM Identity Center（IAM Identity Center）配置 Amazon CLI，以检索运行 Amazon CLI 命令所需的凭证。可采用两种主要方式来使用 IAM Identity Center 验证用户身份，从而获取通过 `config` 文件运行 Amazon CLI 命令所需的凭证：
+ **（推荐）**SSO 令牌提供程序配置。
+ 遗留的不可刷新配置。

有关使用持有者身份验证（不使用账户 ID 和角色）的信息，请参阅《Amazon CodeCatalyst 用户指南》中**的[进行设置以将 Amazon CLI 与 CodeCatalyst 一起使用](https://docs.amazonaws.cn/codecatalyst/latest/userguide/set-up-cli.html)。

**注意**  
有关使用带 Amazon CLI 命令的 IAM Identity Center 的指导过程，请参阅[教程：使用 IAM 身份中心在 Amazon CLI 中运行 Amazon S3 命令](cli-configure-sso-tutorial.md)。

**主题**
+ [先决条件](#cli-configure-sso-prereqs)
+ [使用 `aws configure sso` 向导配置您的配置文件](#cli-configure-sso-configure)
+ [使用 `aws configure sso-session` 向导仅配置您的 `sso-session` 部分](#cli-configure-sso-session)
+ [使用 `config` 文件手动配置](#cli-configure-sso-manual)
+ [登录到 IAM Identity Center 会话](#cli-configure-sso-login)
+ [使用 IAM Identity Center 配置文件运行命令](#cli-configure-sso-use)
+ [退出 IAM Identity Center 会话](#cli-configure-sso-logout)
+ [问题排查](#cli-configure-sso-tshoot)
+ [相关资源](#cli-configure-sso-resources)

## 先决条件
<a name="cli-configure-sso-prereqs"></a>
+ 安装 Amazon CLI。有关更多信息，请参阅 [安装或更新最新版本的 Amazon CLI](getting-started-install.md)。
+ 您必须先有权访问 IAM Identity Center 中的 SSO 身份验证。选择下列方法之一来访问您的 Amazon 凭证。

### 我尚未通过 IAM Identity Center 确立访问权限
<a name="idc-access"></a>

请按照《Amazon IAM Identity Center 用户指南》**的[入门](https://docs.amazonaws.cn/singlesignon/latest/userguide/getting-started.html)中的说明操作。此过程激活 IAM Identity Center，创建管理用户并添加适当的最低权限集。

**注意**  
创建应用最低权限的权限集。除非您的雇主已为此目的创建自定义权限集，否则建议使用预定义的 `PowerUserAccess` 权限集。

退出门户并重新登录以查看您的 Amazon Web Services 账户、编程访问详细信息以及 `Administrator` 和 `PowerUserAccess` 选项。在使用开发工具包时选择 `PowerUserAccess`。

### 我已通过我的雇主管理的联邦身份提供者（例如 Azure AD 或 Okta）获得对 Amazon 的访问权限
<a name="federated-access"></a>

通过身份提供者的门户登录 Amazon。如果您的云管理员已向您授予 `PowerUserAccess`（开发人员）权限，您将看到您有权访问的 Amazon Web Services 账户和您的权限集。在您的权限集名称旁边，可以看到有关使用该权限集手动或以编程方式访问账户的选项。

自定义实现可能会产生不同的体验，例如不同的权限集名称。如果您不确定要使用哪个权限集，请联系 IT 团队以寻求帮助。

### 我已通过雇主管理的 Amazon 访问门户获得对 Amazon 的访问权限
<a name="accessportal-access"></a>

通过您的 Amazon 访问门户登录到 Amazon。如果您的云管理员已向您授予 `PowerUserAccess`（开发人员）权限，您将看到您有权访问的 Amazon Web Services 账户和您的权限集。在您的权限集名称旁边，可以看到有关使用该权限集手动或以编程方式访问账户的选项。

### 我已通过我的雇主管理的联合自定义身份提供者获得对 Amazon 的访问权限
<a name="customfederated-access"></a>

请联系您的 IT 团队以寻求帮助。

访问 IAM Identity Center 后，通过执行以下操作收集 IAM Identity Center 信息：

1. 收集运行 `aws configure sso` 所需的 `SSO Start URL` 和 `SSO Region` 值

   1. 在 Amazon 访问门户中，选择用于开发的权限集，然后选择**访问密钥**链接。

   1. 在**获取凭证**对话框中，选择与您的操作系统匹配的选项卡。

   1. 选择 **IAM Identity Center 凭证**方法以获取 `SSO Start URL` 和 `SSO Region` 值。

1. 或者，从版本 2.22.0 开始，您可以使用发布者 URL 来代替启动 URL。发布者 URL 位于 Amazon IAM Identity Center 控制台上的下列位置之一：
   + 在**控制面板**页面上，发布者 URL 位于设置摘要中。
   + 在**设置**页面上，发布者 URL 位于**身份源**设置中。

1. 有关要注册哪些范围值的信息，请参阅《IAM Identity Center 用户指南》**中的 [OAuth 2.0 访问范围](https://docs.amazonaws.cn/singlesignon/latest/userguide/customermanagedapps-saml2-oauth2.html#oidc-concept)。

## 使用 `aws configure sso` 向导配置您的配置文件
<a name="cli-configure-sso-configure"></a>

**在 Amazon CLI 中配置 IAM Identity Center 配置文件：**

1. 在首选终端中运行 `aws configure sso` 命令。

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

   创建会话名称，并提供 IAM Identity Center 启动 URL 或发布者 URL、托管 IAM Identity Center 目录的 Amazon Web Services 区域和注册范围。

   ```
   $ 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
   ```

   要获得双栈支持，请使用双栈 SSO 起始 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
   ```

   从版本 **2.22.0** 开始，代码交换的证明密钥（PKCE）授权默认用于 Amazon CLI，并且必须在带浏览器的设备上使用。要继续使用设备授权，请附加 `--use-device-code` 选项。

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

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

   跳过该会话名称并提供 IAM Identity Center 启动 URL 以及托管 Identity Center 目录的 Amazon 区域。

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

   对于双栈支持：

   ```
   $ 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. Amazon CLI 将尝试打开您的默认浏览器，以便登录到您的 IAM Identity Center 账户。此过程可能会提示您允许 Amazon CLI 访问您的数据。由于 Amazon CLI 基于 SDK for Python 而构建，因此权限消息可能包含 `botocore` 名称的变体。
   + **如果 Amazon CLI 无法打开浏览器**，则会显示手动启动登录过程的说明，具体取决于所使用的授权类型。

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

     从版本 2.22.0 开始，代码交换的证明密钥（PKCE）授权默认用于 Amazon CLI。显示的 URL 是唯一 URL，开头为：
     + IPv4：*https://oidc.us-east-1.amazonaws.com/authorize*
     + 双栈：*https://oidc.us-east-1.api.aws/authorize*

     PKCE 授权 URL 必须在您登录到的同一台设备上打开，并且必须用于带浏览器的设备。

     ```
     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 ]

     对于版本 2.22.0 之前的版本，Amazon CLI 默认使用 OAuth 2.0 设备授权。对于更新的版本，您可以使用 `--use-device-code` 选项启用此方法。

     设备授权 URL 无需在您登录到的同一台设备上打开，并且可用于带或不带浏览器的设备。端点格式取决于您的配置：
     + IPv4：*https://device.sso.us-west-2.amazonaws.com/*
     + 双栈：*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. 从所示列表中选择要使用的 Amazon 账户。如果您只被授权使用一个账户，Amazon CLI 会自动选择该账户并跳过提示。

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

1. 从所示列表中选择要使用的 IAM 角色。如果只有一个角色可用，Amazon CLI 会自动选择该角色并跳过提示。

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

1. 指定[默认输出格式](cli-configure-files.md#cli-config-output)、向其发送命令的[默认 Amazon Web Services 区域](cli-configure-files.md#cli-config-region)，以及[配置文件的名称](cli-configure-files.md)。如果指定 `default` 作为配置文件名称，此配置文件将变为使用的默认配置文件。在以下示例中，用户输入默认区域、默认输出格式和配置文件的名称。

   ```
   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. 最后一条消息描述了完成的配置文件配置。现在，您可以使用此配置文件请求凭证。使用 `aws sso login` 命令请求和检索运行命令所需的凭证。有关说明，请参阅[登录到 IAM Identity Center 会话](#cli-configure-sso-login)。

### 生成的配置文件
<a name="cli-configure-sso-generated"></a>

执行这些步骤会在 `config` 文件中创建 `sso-session` 部分和命名配置文件，具体如下所示：

------
#### [ 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
```

对于双栈支持：

```
[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
```

对于双栈支持：

```
[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
```

------

## 使用 `aws configure sso-session` 向导仅配置您的 `sso-session` 部分
<a name="cli-configure-sso-session"></a>

**注意**  
此配置与旧版 IAM Identity Center 不兼容。

`aws configure sso-session` 命令会更新 `~/.aws/config` 文件中的 `sso-session` 部分。运行 `aws configure sso-session` 命令并提供 IAM Identity Center 启动 URL 或发布者 URL 以及托管 IAM Identity Center 目录的 Amazon 区域。

```
$ 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
```

要获得双栈支持，请使用双栈 SSO 起始 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
```

## 使用 `config` 文件手动配置
<a name="cli-configure-sso-manual"></a>

IAM Identity Center 配置信息存储在 `config` 文件中，可以使用文本编辑器对其进行编辑。要手动向命名配置文件中添加 IAM Identity Center 支持，必须向 `config` 文件中添加密钥和值。

### IAM Identity Center 配置文件
<a name="cli-configure-sso-manual-config"></a>

`config` 文件的 `sso-session` 部分用于对获取 SSO 访问令牌的配置变量进行分组，然后可以用来获取 Amazon 凭证。使用了以下设置：
+ **（必需）**`sso\$1start\$1url`
+ **（必需）**`sso\$1region`
+ `sso\$1account\$1id`
+ `sso\$1role\$1name`
+ `sso\$1registration\$1scopes`

您可以定义 `sso-session` 部分并将其与配置文件相关联。必须在 `sso-session` 部分配置 `sso_region` 和 `sso_start_url` 设置。通常，必须在 `profile` 部分配置 `sso_account_id` 和 `sso_role_name` 设置，以便 SDK 可以请求 SSO 凭证。

以下示例将 SDK 配置为请求 SSO 凭证并支持自动令牌刷新：

```
[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
```

要获得双栈支持，请使用双栈 SSO 起始 URL 格式：

```
[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
```

这也允许在多个配置文件中重复使用 `sso-session` 配置：

```
[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
```

要获得双栈支持，请使用双栈 SSO 起始 URL 格式：

```
[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
```

但是，并不是所有 SSO 令牌配置场景都需要 `sso_account_id` 和 `sso_role_name`。如果您的应用程序仅使用支持持有者身份验证的 Amazon 服务，则不需要传统 Amazon 凭证。持有者身份验证是一种 HTTP 身份验证方案，它使用称为持有者令牌的安全令牌。在这种情况下，不需要 `sso_account_id` 和 `sso_role_name`。请参阅 Amazon 服务的单独指南，以确定其是否支持持有者令牌授权。

此外，可以作为 `sso-session` 的一部分配置注册范围。范围是 OAuth 2.0 中的一种机制，用于限制应用程序对用户账户的访问。应用程序可以请求一个或多个范围，向应用程序签发的访问令牌将仅限于授予的范围。这些范围定义了为已注册的 OIDC 客户端请求授权的权限和客户端检索的访问令牌。以下示例将 `sso_registration_scopes` 设置为提供已列出账户/角色的访问权限：

```
[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
```

对于双栈支持：

```
[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
```

身份验证令牌缓存到 `sso/cache` 目录下的磁盘上，文件名基于会话名称。

### 遗留的 IAM Identity Center 配置文件
<a name="cli-configure-sso-manual-legacy"></a>

**注意**  
使用遗留的不可刷新配置不支持自动令牌刷新。建议使用 SSO 令牌配置。

要手动向命名配置文件中添加 IAM Identity Center 支持，必须将以下键和值添加到 `config` 文件中的配置文件定义中。
+ `sso\$1start\$1url`
+ `sso\$1region`
+ `sso\$1account\$1id`
+ `sso\$1role\$1name`

您可以在 `.aws/config` 文件中包括有效的任何其他键和值。下面是一个 IAM Identity Center 配置文件示例：

```
[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
```

对于双栈支持：

```
[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
```

要运行命令，您必须首先[登录到 IAM Identity Center 会话](#cli-configure-sso-login)来请求和检索临时凭证。

有关 `config` 和 `credentials` 文件的更多信息，请参阅[Amazon CLI 中的配置和凭证文件设置](cli-configure-files.md)。

## 登录到 IAM Identity Center 会话
<a name="cli-configure-sso-login"></a>

**注意**  
登录过程可能会提示您允许 Amazon CLI 访问您的数据。由于 Amazon CLI 基于 SDK for Python 而构建，因此权限消息可能包含 `botocore` 名称的变体。

要检索和缓存一组 IAM Identity Center 凭证，请运行以下 Amazon CLI 命令，打开您的默认浏览器并验证您的 IAM Identity Center 登录信息。

```
$ 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
```

将缓存您的 IAM Identity Center 会话凭证，并且 Amazon CLI 会使用它们安全地检索在配置文件中指定的用于 IAM 角色的 Amazon 凭证。

### 如果 Amazon CLI 无法打开您的浏览器
<a name="cli-configure-sso-login-browser"></a>

如果 Amazon CLI 无法自动打开浏览器，则会显示手动启动登录过程的说明，具体取决于所使用的授权类型。

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

从版本 2.22.0 开始，代码交换的证明密钥（PKCE）授权默认用于 Amazon CLI。显示的 URL 是唯一 URL，开头为：
+ IPv4：*https://oidc.us-east-1.amazonaws.com/authorize*
+ 双栈：*https://oidc.us-east-1.api.aws/authorize*

PKCE 授权 URL 必须在您登录到的同一台设备上打开，并且必须用于带浏览器的设备。

```
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 ]

对于版本 2.22.0 之前的版本，Amazon CLI 默认使用 OAuth 2.0 设备授权。对于更新的版本，您可以使用 `--use-device-code` 选项启用此方法。

设备授权 URL 无需在您登录到的同一台设备上打开，并且可用于带或不带浏览器的设备。

```
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
```

------

在使用 `aws sso login` 命令的 `--sso-session` 参数登录时，您还可以指定使用哪个 `sso-session` 配置文件。该 `sso-session` 选项不适用于旧版 IAM Identity Center。

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

从版本 2.22.0 开始，默认使用 PKCE 授权。要使用设备授权进行登录，请添加 `--use-device-code` 选项。

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

身份验证令牌缓存到 `~/.aws/sso/cache` 目录下的磁盘上，其文件名基于 `sso_start_url`。

## 使用 IAM Identity Center 配置文件运行命令
<a name="cli-configure-sso-use"></a>

登录后，您可以使用您的凭证通过关联的命名配置文件来调用 Amazon CLI 命令。以下示例显示使用配置文件的命令：

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

只要您登录 IAM Identity Center 并且这些缓存的凭证未过期，Amazon CLI 就会在需要时自动续订过期的 Amazon 凭证。但是，如果您的 IAM Identity Center 凭证过期，则必须通过再次登录您的 IAM Identity Center 账户来显式续订它们。

## 退出 IAM Identity Center 会话
<a name="cli-configure-sso-logout"></a>

使用完 IAM Identity Center 配置文件后，可以让凭证过期，或运行以下命令，删除缓存的凭证。

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

## 问题排查
<a name="cli-configure-sso-tshoot"></a>

如果您遇到 Amazon CLI 使用问题，请参阅[排查 Amazon CLI 错误](cli-chap-troubleshooting.md)以了解故障排除步骤。

## 相关资源
<a name="cli-configure-sso-resources"></a>

其他资源如下所示。
+ [Amazon CLI 的 Amazon IAM Identity Center 概念](cli-configure-sso-concepts.md)
+ [教程：使用 IAM 身份中心在 Amazon CLI 中运行 Amazon S3 命令](cli-configure-sso-tutorial.md)
+ [安装或更新最新版本的 Amazon CLI](getting-started-install.md)
+ [Amazon CLI 中的配置和凭证文件设置](cli-configure-files.md)
+ 《Amazon CLI 版本 2 中参考》中的 [https://docs.amazonaws.cn/cli/latest/reference/configure/sso.html](https://docs.amazonaws.cn/cli/latest/reference/configure/sso.html)**
+ 《Amazon CLI 版本 2 中参考》中的 [https://docs.amazonaws.cn/cli/latest/reference/configure/sso-session.html](https://docs.amazonaws.cn/cli/latest/reference/configure/sso-session.html)**
+ 《Amazon CLI 版本 2 中参考》中的 [https://docs.amazonaws.cn/cli/latest/reference/sso/login.html](https://docs.amazonaws.cn/cli/latest/reference/sso/login.html)**
+ 《Amazon CLI 版本 2 中参考》中的 [https://docs.amazonaws.cn/cli/latest/reference/sso/logout.html](https://docs.amazonaws.cn/cli/latest/reference/sso/logout.html)**
+ 《Amazon CodeCatalyst 用户指南》**中的[设置为将 Amazon CLI 与 CodeCatalyst 一起使用](https://docs.amazonaws.cn/codecatalyst/latest/userguide/set-up-cli.html)
+ 《IAM Identity Center 用户指南》**中的 [OAuth 2.0 访问范围](https://docs.amazonaws.cn/singlesignon/latest/userguide/customermanagedapps-saml2-oauth2.html#oidc-concept)
+ 《IAM Identity Center 用户指南》**中的[入门教程](https://docs.amazonaws.cn/singlesignon/latest/userguide/tutorials.html)