先决条件使用 aws configure sso 向导配置您的配置文件使用 aws configure sso-session 向导仅配置您的 sso-session 部分使用 config 文件手动配置登录到 IAM Identity Center 会话使用 IAM Identity Center 配置文件运行命令退出 IAM Identity Center 会话故障排除相关资源

使用 Amazon CLI 配置 IAM Identity Center 身份验证

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

（推荐）SSO 令牌提供程序配置。
遗留的不可刷新配置。

有关使用持有者身份验证（不使用账户 ID 和角色）的信息，请参阅《Amazon CodeCatalyst 用户指南》中的进行设置以将 Amazon CLI 与 CodeCatalyst 一起使用。

注意

有关使用带 Amazon CLI 命令的 IAM Identity Center 的指导过程，请参阅教程：使用 IAM 身份中心在 Amazon CLI 中运行 Amazon S3 命令。

主题

先决条件
使用 aws configure sso 向导配置您的配置文件
使用 aws configure sso-session 向导仅配置您的 sso-session 部分
使用 config 文件手动配置
登录到 IAM Identity Center 会话
使用 IAM Identity Center 配置文件运行命令
退出 IAM Identity Center 会话
故障排除
相关资源

先决条件

安装 Amazon CLI。有关更多信息，请参阅安装或更新最新版本的 Amazon CLI。
您必须先有权访问 IAM Identity Center 中的 SSO 身份验证。选择下列方法之一来访问您的 Amazon 凭证。

请按照《Amazon IAM Identity Center 用户指南》的入门中的说明操作。此过程激活 IAM Identity Center，创建管理用户并添加适当的最低权限集。

注意

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

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

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

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

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

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

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

收集运行 aws configure sso 所需的 SSO Start URL 和 SSO Region 值
1. 在 Amazon 访问门户中，选择用于开发的权限集，然后选择访问密钥链接。
2. 在获取凭证对话框中，选择与您的操作系统匹配的选项卡。
3. 选择 IAM Identity Center 凭证方法以获取 SSO Start URL 和 SSO Region 值。
或者，从版本 2.22.0 开始，您可以使用发布者 URL 来代替启动 URL。发布者 URL 位于 Amazon IAM Identity Center 控制台上的下列位置之一：
- 在控制面板页面上，发布者 URL 位于设置摘要中。
- 在设置页面上，发布者 URL 位于身份源设置中。
有关要注册哪些范围值的信息，请参阅《IAM Identity Center 用户指南》中的 OAuth 2.0 访问范围。

使用 `aws configure sso` 向导配置您的配置文件

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

在首选终端中运行 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
```
从版本 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
```
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，开头为 https://oidc.us-east-1.amazonaws.com/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
  显示更多显示更少

从所示列表中选择要使用的 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)

从所示列表中选择要使用的 IAM 角色。如果只有一个角色可用，Amazon CLI 会自动选择该角色并跳过提示。
```
Using the account ID 123456789011
There are 2 roles available to you.
> ReadOnly
  FullAccess
```
指定默认输出格式、向其发送命令的默认 Amazon Web Services 区域，以及配置文件的名称。如果指定 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>
```
最后一条消息描述了完成的配置文件配置。现在，您可以使用此配置文件请求凭证。使用 aws sso login 命令请求和检索运行命令所需的凭证。有关说明，请参阅登录到 IAM Identity Center 会话。

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

使用 `aws configure sso-session` 向导仅配置您的 `sso-session` 部分

注意

此配置与旧版 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

使用 `config` 文件手动配置

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

config 文件的 sso-session 部分用于对获取 SSO 访问令牌的配置变量进行分组，然后可以用来获取 Amazon 凭证。使用了以下设置：

（必需）sso_start_url
（必需）sso_region
sso_account_id
sso_role_name
sso_registration_scopes

您可以定义 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-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 令牌配置场景都需要 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/cache 目录下的磁盘上，文件名基于会话名称。

注意

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

要手动向命名配置文件中添加 IAM Identity Center 支持，必须将以下键和值添加到 config 文件中的配置文件定义中。

您可以在 .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

要运行命令，您必须首先登录到 IAM Identity Center 会话来请求和检索临时凭证。

有关 config 和 credentials 文件的更多信息，请参阅Amazon CLI 中的配置和凭证文件设置。

注意

登录过程可能会提示您允许 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 无法自动打开浏览器，则会显示手动启动登录过程的说明，具体取决于所使用的授权类型。

在使用 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 配置文件运行命令

登录后，您可以使用您的凭证通过关联的命名配置文件来调用 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 会话

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


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

故障排除

如果您遇到 Amazon CLI 使用问题，请参阅排查 Amazon CLI 错误以了解故障排除步骤。