适用于 .NET 的 Amazon SDK V3 已进入维护模式。

我们建议您迁移到 [适用于 .NET 的 Amazon SDK V4](https://docs.amazonaws.cn/sdk-for-net/v4/developer-guide/welcome.html)。有关如何迁移的更多详细信息和信息，请参阅我们的[维护模式公告](https://www.amazonaws.cn/blogs/developer/aws-sdk-for-net-v3-maintenance-mode-announcement/)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 通过 适用于 .NET 的 Amazon SDK 进行单点登录
<a name="sso"></a>

Amazon IAM Identity Center 是一项基于云的单点登录（SSO）服务，可以轻松地集中管理所有 Amazon Web Services 账户和云应用程序的 SSO 访问。有关完整详细信息，请参阅 [IAM Identity Center 用户指南](https://docs.amazonaws.cn/singlesignon/latest/userguide/)。

如果您不熟悉开发工具包如何与 IAM Identity Center 交互，请参阅以下信息。

## 高级互动模式
<a name="w2aac13b7b7b1"></a>

总体而言，开发工具包与 IAM Identity Center 交互的方式与以下模式类似：

1. 通常通过 [IAM Identity Center 控制台](https://console.amazonaws.cn/singlesignon)配置 IAM Identity Center，并邀请 SSO 用户参与。

1. 用户计算机上的共享 Amazon `config` 文件将使用 SSO 信息进行更新。

1. 用户通过 IAM Identity Center 登录，并获得为其配置的 Amazon Identity and Access Management（IAM）权限的短期凭证。这种登录可以通过非 SDK 工具（如 Amazon CLI）启动，也可以通过 .NET 应用程序以编程方式启动。

1. 用户继续完成他们的工作。当他们运行其它使用 SSO 的应用程序时，他们无需再次登录即可打开应用程序。

本主题的其余部分提供了设置和使用 Amazon IAM Identity Center 的参考信息。它提供了比[配置 SDK 身份验证](creds-idc.md)中基本 SSO 设置更高级的补充信息。如果您不熟悉 Amazon 的 SSO，则可能需要先查看该主题以获取基本信息，然后查看以下教程以了解 SSO 的实际操作情况：
+ [教程：仅限 .NET 应用程序](sso-tutorial-app-only.md)
+ [教程： Amazon CLI 和.NET 应用程序](sso-tutorial-cli-and-app.md)

本主题包含下列部分：
+ [先决条件](#sso-prereq)
+ [设置 SSO 配置文件](#sso-profiles)
+ [生成和使用 SSO 令牌](#sso-generate-use-token-overview)
+ [其他资源](#sso-resources)
+ [教程](#sso-tutorial-links)

## 先决条件
<a name="sso-prereq"></a>

在使用 IAM Identity Center 之前，您必须执行某些任务，例如选择身份来源以及配置相关 Amazon Web Services 账户和应用程序。有关更多信息，请参阅以下内容：
+ 有关这些任务的更多信息，请参阅《IAM Identity Center 用户指南》**中的[入门](https://docs.amazonaws.cn/singlesignon/latest/userguide/getting-started.html)。
+ 有关具体任务示例，请参阅本主题末尾的教程列表。但是，在尝试教程之前，请务必查看本主题中的信息。

## 设置 SSO 配置文件
<a name="sso-profiles"></a>

在相关 Amazon Web Services 账户中[配置了](https://docs.amazonaws.cn/singlesignon/latest/userguide/getting-started.html) IAM Identity Center 后，必须将 SSO 的指定配置文件添加到用户的共享 Amazon `config` 文件中。此配置文件用于连接到 *[Amazon 访问门户](https://docs.amazonaws.cn/singlesignon/latest/userguide/using-the-portal.html)*，该门户返回已为用户配置的 IAM 权限的短期凭证。

共享 `config` 文件通常名为 `%USERPROFILE%\.aws\config`（Windows）和 `~/.aws/config`（Linux 和 macOS）。您可以使用首选的文本编辑器为 SSO 添加新的配置文件。或者，您可以使用 `aws configure sso` 命令。有关此命令的更多信息，请参阅**《Amazon Command Line Interface用户指南》中的[将 Amazon CLI 配置为使用 IAM Identity Center](https://docs.amazonaws.cn/cli/latest/userguide/cli-configure-sso.html)。

新的配置文件类似于以下内容：

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

新配置文件的设置定义如下。前两个设置定义了 Amazon 访问门户。另外两个设置是一对设置，它们共同定义了已为用户配置的权限。所有四个设置都是必需的。

**`sso_start_url`**  
指定指向企业的 [Amazon 访问门户](https://docs.amazonaws.cn/singlesignon/latest/userguide/using-the-portal.html)的 URL。要找到此值，请打开 [IAM Identity Center 控制台](https://console.amazonaws.cn/singlesignon)，选择**设置**，然后找到**门户 URL**。

**`sso_region`**  
包含访问门户主机的 Amazon Web Services 区域。这是您在启用 IAM Identity Center 时选择的区域。它可能与您用于其它任务的区域不同。  
有关 Amazon Web Services 区域及代码的完整列表，请参阅《Amazon Web Services 一般参考》中的[区域端点](https://docs.amazonaws.cn/general/latest/gr/rande.html#regional-endpoints) **。

**`sso_account_id`**  
通过 Amazon Organizations 服务添加 Amazon Web Services 账户的 ID。要查看可用账户列表，请前往 [IAM Identity Center 控制台](https://console.amazonaws.cn/singlesignon)并打开 **Amazon Web Services 账户**页面。您为此设置选择的账户 ID 将与您计划为 `sso_role_name` 设置提供的值相对应，如下所示。

**`sso_role_name`**  
IAM Identity Center 权限集的名称。此权限集定义了通过 IAM Identity Center 向用户授予的权限。  
以下过程是查找此设置值的一种方法。  

1. 前往 [IAM Identity Center 控制台](https://console.amazonaws.cn/singlesignon)并打开 **Amazon Web Services 账户**页面。

1. 选择一个账户即可显示其详细信息。您选择的账户将包含您要向其授予 SSO 权限的 SSO 用户或组。

1. 查看分配给该账户的用户和组列表，找到感兴趣的用户或组。您在 `sso_role_name` 设置中指定的权限集是与此用户或组关联的权限集之一。
为该设置指定值时，请使用权限集名称而不是 Amazon 资源名称（ARN）。  
权限集附有 IAM 策略和自定义权限策略。有关更多信息，请参阅《IAM Identity Center 用户指南》**中的[权限集](https://docs.amazonaws.cn/singlesignon/latest/userguide/permissionsets.html)。

## 生成和使用 SSO 令牌
<a name="sso-generate-use-token-overview"></a>

要使用 SSO，用户必须先生成临时令牌，然后使用该令牌访问相应的 Amazon 应用程序和资源。对于 .NET 应用程序，您可以使用以下方法生成和使用这些临时令牌：
+ 创建 .NET 应用程序，必要时先生成令牌然后使用该令牌。
+ 使用 Amazon CLI 生成令牌，然后在 .NET 应用程序中使用该令牌。

这些方法将在以下各节中介绍，并在[教程](#sso-tutorial-links)中进行了演示。

**重要**  
您的应用程序必须引用以下 NuGet 程序包，这样 SSO 解析才能生效：  
`AWSSDK.SSO`
`AWSSDK.SSOOIDC`
未能引用这些程序包将导致*运行时系统*异常。

### 仅限 .NET 应用程序
<a name="sso-generate-use-token-app-only-summary"></a>

本节介绍如何创建 .NET 应用程序，在必要时生成临时 SSO 令牌，然后使用该令牌。有关此过程的完整教程，请参阅[仅使用 .NET 应用程序的 SSO 教程](sso-tutorial-app-only.md)。

#### 以编程方式生成和使用 SSO 令牌
<a name="sso-generate-token-prog"></a>

除了使用 Amazon CLI，您还可以通过编程方式生成 SSO 令牌。

为此，您的应用程序会为 SSO 配置文件创建一个 [https://docs.amazonaws.cn/sdkfornet/v3/apidocs/items/Runtime/TAWSCredentials.html](https://docs.amazonaws.cn/sdkfornet/v3/apidocs/items/Runtime/TAWSCredentials.html) 对象，该对象会加载临时凭证（如果有）。然后，您的应用程序必须将 `AWSCredentials` 对象转换为 [https://docs.amazonaws.cn/sdkfornet/v3/apidocs/items/Runtime/TSSOAWSCredentials.html](https://docs.amazonaws.cn/sdkfornet/v3/apidocs/items/Runtime/TSSOAWSCredentials.html) 对象并设置一些 [Options](https://docs.amazonaws.cn/sdkfornet/v3/apidocs/items/Runtime/TSSOAWSCredentialsOptions.html) 属性，包括用于在必要时提示用户输入登录信息的回调方法。

下面的代码片段中显示了此方法。

**重要**  
您的应用程序必须引用以下 NuGet 程序包，这样 SSO 解析才能生效：  
`AWSSDK.SSO`
`AWSSDK.SSOOIDC`
未能引用这些程序包将导致*运行时系统*异常。

```
static AWSCredentials LoadSsoCredentials()
{
    var chain = new CredentialProfileStoreChain();
    if (!chain.TryGetAWSCredentials("my-sso-profile", out var credentials))
        throw new Exception("Failed to find the my-sso-profile profile");

    var ssoCredentials = credentials as SSOAWSCredentials;

    ssoCredentials.Options.ClientName = "Example-SSO-App";
    ssoCredentials.Options.SsoVerificationCallback = args =>
    {
        // Launch a browser window that prompts the SSO user to complete an SSO sign-in.
        // This method is only invoked if the session doesn't already have a valid SSO token.
        // NOTE: Process.Start might not support launching a browser on macOS or Linux. If not,
        //       use an appropriate mechanism on those systems instead.
        Process.Start(new ProcessStartInfo
        {
            FileName = args.VerificationUriComplete,
            UseShellExecute = true
        });
    };

    return ssoCredentials;
}
```

如果没有相应的 SSO 令牌可用，则会启动默认浏览器窗口并打开相应的登录页面。例如，如果您使用 IAM Identity Center 作为**身份来源**，则用户会看到类似如下的登录页面：

![\[Amazon IAM Identity Center 登录页面。\]](http://docs.amazonaws.cn/sdk-for-net/v3/developer-guide/images/SSO-login-bjs.png)


**注意**  
您为 `SSOAWSCredentials.Options.ClientName` 提供的文本字符串不能有空格。如果字符串确实有空格，则会出现*运行时系统*异常。

[仅使用 .NET 应用程序的 SSO 教程](sso-tutorial-app-only.md)

### Amazon CLI 和.NET 应用程序
<a name="sso-generate-use-token-cli-and-app-summary"></a>

本节介绍如何使用 Amazon CLI 生成临时 SSO 令牌，以及如何在应用程序中使用该令牌。有关此过程的完整教程，请参阅[使用 Amazon CLI 和.NET 应用程序的 SSO 教程](sso-tutorial-cli-and-app.md)。

#### 使用 Amazon CLI 生成 SSO 令牌
<a name="sso-generate-token-cli"></a>

除了以编程方式生成临时 SSO 令牌外，您还可以使用 Amazon CLI 生成令牌。以下信息将为您演示如何操作。

用户创建启用 SSO 的配置文件后（如[上一节](#sso-profiles)所示），他们将从 Amazon CLI 中运行 `aws sso login` 命令。他们必须确保包含带有启用 SSO 的配置文件名称的 `--profile` 参数。如下例所示:

```
aws sso login --profile my-sso-profile
```

如果用户想在当前临时令牌到期后生成新的临时令牌，他们可以再次运行相同的命令。

#### 在 .NET 应用程序中使用生成的 SSO 令牌
<a name="sso-use-profile-dotnet"></a>

以下信息向您展示了如何使用已经生成的临时令牌。

**重要**  
您的应用程序必须引用以下 NuGet 程序包，这样 SSO 解析才能生效：  
`AWSSDK.SSO`
`AWSSDK.SSOOIDC`
未能引用这些程序包将导致*运行时系统*异常。

您的应用程序为 SSO 配置文件创建一个 [https://docs.amazonaws.cn/sdkfornet/v3/apidocs/items/Runtime/TAWSCredentials.html](https://docs.amazonaws.cn/sdkfornet/v3/apidocs/items/Runtime/TAWSCredentials.html) 对象，该对象会加载之前由 Amazon CLI 生成的临时凭证。这与[访问应用程序中的凭证和配置文件](creds-locate.md)中所示的方法类似，其形式如下：

```
static AWSCredentials LoadSsoCredentials()
{
    var chain = new CredentialProfileStoreChain();
    if (!chain.TryGetAWSCredentials("my-sso-profile", out var credentials))
        throw new Exception("Failed to find the my-sso-profile profile");

    return credentials;
}
```

然后将 `AWSCredentials` 对象传递给服务客户端的构造函数。例如：

```
var S3Client_SSO = new AmazonS3Client(LoadSsoCredentials());
```

**注意**  
如果您的应用程序已构建为使用 `[default]` 配置文件进行 SSO，则无需使用 `AWSCredentials` 来加载临时凭证。在这种情况下，应用程序可以创建不带参数的 Amazon 服务客户端，类似于“`var client = new AmazonS3Client();`”。

[使用 Amazon CLI 和.NET 应用程序的 SSO 教程](sso-tutorial-cli-and-app.md)

## 其他资源
<a name="sso-resources"></a>

如需其它帮助，请参阅以下资源：
+ [什么是 IAM Identity Center？](https://docs.amazonaws.cn/singlesignon/latest/userguide/what-is.html)
+ [将 Amazon CLI 配置为使用 IAM Identity Center](https://docs.amazonaws.cn/cli/latest/userguide/cli-configure-sso.html#sso-configure-profile)
+ [在Amazon Toolkit for Visual Studio中使用 IAM Identity Center 凭证](https://docs.amazonaws.cn/toolkit-for-visual-studio/latest/user-guide/sso-credentials.html)

## 教程
<a name="sso-tutorial-links"></a>

**Topics**
+ [先决条件](#sso-prereq)
+ [设置 SSO 配置文件](#sso-profiles)
+ [生成和使用 SSO 令牌](#sso-generate-use-token-overview)
+ [其他资源](#sso-resources)
+ [教程](#sso-tutorial-links)
+ [教程：仅限 .NET 应用程序](sso-tutorial-app-only.md)
+ [教程： Amazon CLI 和.NET 应用程序](sso-tutorial-cli-and-app.md)