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

# 在桌面上设置 Amazon Quick 以进行企业部署
<a name="desktop-enterprise-setup"></a>


|  | 
| --- |
|    适用于：企业版和标准版  | 


|  | 
| --- |
|    目标受众：系统管理员  | 

要在桌面上使用 Amazon Quick 进行企业部署，管理员必须配置企业单点登录 (SSO)，以便组织中的用户可以使用其公司凭证登录。此设置将贵组织的 OpenID Connect (OIDC) 兼容身份提供商 (IdP) 连接到 Amazon Quick。

**注意**  
如果您使用的是免费或高级帐户，则此部分不适用于您。继续[开始使用](getting-started-desktop.md)。

该设置按顺序包括以下步骤：

1. 在您的 IdP 中创建 OIDC 应用程序。

1. 在 IAM 身份中心创建可信令牌发行者 (TTI)（仅使用 IAM 身份中心进行身份验证的账户才需要）。

1. 在 Amazon Quick 管理控制台中配置扩展程序访问权限。

1. 将桌面应用程序分发给您的用户。

本指南提供了 Microsoft Entra ID、Okta 和 Ping Identity（PingFederate 和 PingOne）的 IdP-specific 说明。请参阅下方针对您的特定身份提供商的说明。

## 企业登录的工作原理
<a name="desktop-enterprise-how-it-works"></a>

Amazon Quick 桌面应用程序使用 OIDC 协议对用户进行身份验证。当用户选择**企业登录**时，应用程序会打开浏览器窗口并重定向到您的 IdP 的授权端点。然后，应用程序使用代码交换校验密钥 (PKCE) 将生成的授权码交换为令牌。

Amazon Quick 会验证令牌并将用户映射到您账户中的身份。对于使用 IAM 身份中心的账户，TTI 会将 OIDC 令牌中的`email`声明映射到身份`emails.value`存储中的属性。对于使用 IAM 联合身份验证的账户，Amazon Quick 会直接通过电子邮件映射用户。在这两种情况下，您的 IdP 中的电子邮件地址都必须与 Amazon Quick 中用户的电子邮件地址完全匹配。

## 先决条件
<a name="desktop-enterprise-prerequisites"></a>

在开始之前，请确认您已具备以下条件：
+ 具有有效 Amazon Quick 订阅的 AWS 账户，该账户使用 IAM 身份中心或 IAM 联合身份验证进行身份验证。Amazon Quick 账户的主区域（身份区域）必须是美国东部（弗吉尼亚北部）（us-east-1）。
+ 管理员访问您的 Amazon Quick 账户。
+ 访问您的 IdP，并有权创建 OIDC 应用程序注册。

**重要**  
Amazon Quick 账户的主区域（身份区域）必须是美国东部（弗吉尼亚北部）（us-east-1）。桌面应用程序的所有推理也使用此区域。虽然网络版 Amazon Quick 可以在其他区域使用，但桌面应用程序会连接到 us-east-1 进行身份验证和推断。

## 步骤 1：在您的身份提供商中创建 OIDC 应用程序
<a name="desktop-enterprise-step1"></a>

在您的 IdP 中注册公共 OIDC 客户端应用程序。Amazon Quick 桌面应用程序使用此客户端通过 PKCE 的授权码流对用户进行身份验证。不需要客户机密钥。

桌面应用程序需要刷新令牌才能保持长时间的会话。刷新令牌的配置方式取决于您的 IdP：
+ **Microsoft Entra ID** — 必须授予`offline_access`作用域。否则，用户必须经常重新进行身份验证。
+ **Okta** — 必须在应用程序上启用 “刷新令牌” 授予类型，并且必须授予`offline_access`作用域。
+ **Ping 身份** — 必须启用 “刷新令牌” 授予类型，并且必须授予`offline_access`作用域。对于 PingFederate，还必须**在 OIDC 策略中启用 “刷新时返回 ID 令牌授权**” 设置。

为您的身份提供者选择说明。

### Microsoft Entra ID
<a name="desktop-enterprise-entra-id"></a>

有关详细说明，请参阅 Microsoft [Entra 文档中的注册应用程序](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app)。

**创建 Entra ID 应用程序注册**

1. 在 Azure 门户中，导航到**微软 Entra ID → 应用程序注册 → 新**注册。

1. 配置以下设置：    
[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/quick/latest/userguide/desktop-enterprise-setup.html)

1. 选择**注册**。

1. 在**概**述页面上，记下**应用程序（客户端）ID** 和**目录（租户）ID**。在后续步骤中需要这些值。

这是公开的客户注册。PKCE 由公共客户端的 Entra ID 自动强制执行。

**配置 API 权限**

1. 在应用程序注册中，导航到 **API 权限 → 添加权限 → Microsoft Graph → 委托权限**。

1. 添加以下权限：`openid`、`email`、`profile`、`offline_access`。

1. 选择**添加权限**。

1. 如果您的组织需要，请选择 **[您的组织] 授予管理员同意**。

**配置身份验证设置**

1. 在应用程序注册中，导航到**身份验证**。

1. 在 **“高级设置”** 下，将 “**允许公共客户端流**” 设置为 **“是”**。

1. 确认`http://localhost:18080`它已列在 “**移动和桌面应用程序**” 下。

1. 选择**保存**。

您的 OIDC 终端节点使用以下格式。`<TENANT_ID>`替换为您的目录（租户）ID。


| Field | Value | 
| --- | --- | 
| 发布者 URL | https://login.microsoftonline.com/<TENANT\_ID>/v2.0 | 
| 授权端点 | https://login.microsoftonline.com/<TENANT\_ID>/oauth2/v2.0/authorize | 
| 令牌端点 | https://login.microsoftonline.com/<TENANT\_ID>/oauth2/v2.0/token | 
| JWKS URI | https://login.microsoftonline.com/<TENANT\_ID>/discovery/v2.0/keys | 

### Okta
<a name="desktop-enterprise-okta"></a>

有关详细说明，请参阅 Okta 文档中的[创建 OpenID Connect 应用程序集成。](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm)

**创建 Okta OIDC 原生应用程序**

1. 在 Okta 管理员控制台中，导航到**应用程序 → 应用程序 → 创建应用程序集成**。

1. 选择 **OIDC-OpenID Connect 作为登录方法**。

1. 选择 “**本机应用程序**” 作为应用程序类型，然后选择 “**下一步**”。

1. 配置以下设置：    
[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/quick/latest/userguide/desktop-enterprise-setup.html)

1. 选择**保存**。

1. 在 “**常规**” 选项卡上，记下**客户端 ID**。

对于本机应用程序，Okta 会自动强制执行 PKCE (S256)。

**配置作用域**

1. 在 Okta 管理员控制台中，导航到**安全 → API → 授权服务器**，然后选择您的授权服务器（例如，**默认**）。

1. 在 “**范围**” 选项卡上，确认是否启用了以下范围：`openid`、`email`、`profile`、`offline_access`。

1. 在 “**访问策略**” 选项卡上，验证分配给此应用程序的策略是否允许`Authorization Code`和`Refresh Token`授权类型。

**验证身份验证设置**

1. 在应用程序集成中，转到 “**常规**” 选项卡。

1. 在 **“常规设置”** 下，确认应用程序类型为 “**本机**”，“客户端身份验证” 为 “**无**”（公共客户端），并且 PKCE 为**必填项**。

1. 在 “**登录**” 下，确认`http://localhost:18080`它已列为重定向 URI。

1. 如果您进行了任何更改，请选择 “**保存**”。

您的 OIDC 终端节点使用以下格式。`<OKTA_DOMAIN>`替换为您的 Okta 域名（例如，`your-org.okta.com`）。


| Field | Value | 
| --- | --- | 
| 发布者 URL | https://<OKTA\_DOMAIN>/oauth2/default | 
| 授权端点 | https://<OKTA\_DOMAIN>/oauth2/default/v1/authorize | 
| 令牌端点 | https://<OKTA\_DOMAIN>/oauth2/default/v1/token | 
| JWKS URI | https://<OKTA\_DOMAIN>/oauth2/default/v1/keys | 

### Ping Identity
<a name="desktop-enterprise-ping-identity"></a>

为你的 Ping 身份产品选择使用说明。

#### PingFederate
<a name="desktop-enterprise-pingfederate"></a>

有关详细说明，请参阅 Ping [Identity 文档 PingFederate中的设置 OIDC 应用程序](https://docs.pingidentity.com/solution-guides/customer_use_cases/htg_oidc_app_setup_pf.html)。

**创建 PingFederate OIDC 客户端**

1. 在 PingFederate 管理控制台中，前往**应用程序 → OAuth → 客户端**，然后选择**添加**客户端。

1. 在 “**客户端 ID**” 字段中，输入此客户的唯一标识符。

1. 在**名称**字段中，输入 `Amazon Quick Desktop`。

1. 对于 “**客户机身份验证**”，选择 “**无**”。

1. 在 “**重定向 URI**” 部分中，输入`http://localhost:18080`并选择**添加**。

1. 在 “**允许的授权类型**” 列表中，选择 “**授权码**” 和 “**刷新令牌**”。

1. 选中 “**需要验证密钥才能进行代码交换 (PKCE)**” 复选框。

1. 在 “**常用范围**” 下，授予以下权限：`openid``email`、`profile`、、`offline_access`。

1. 选择**保存**。

1. 记下**客户端 ID**。在后续步骤中，您需要使用此值。

**配置 OIDC 策略**

1. 在 PingFederate 管理控制台中，前往 “**应用程序” → “OAuth” → OpenID Connect 策略**管理。

1. 选择与此客户端关联的 OIDC 策略，或者选择**添加策略**来创建一个。

1. 选中 “**刷新时返回 ID 令牌” 复**选框。这样可以确保桌面应用程序在刷新会话时收到包含当前声明的新 ID 令牌。

1. 在 A **tt** ribute Contract 下，验证`email`声明是否包含并映射到身份验证源中的相应用户属性。在初始身份验证和刷新令牌授予期间发放的令牌中，`email`声明必须存在。

1. 选择**保存**。

您的 OIDC 终端节点使用以下格式。`<PINGFEDERATE_HOST>`替换为您的 PingFederate 服务器主机名。


| Field | Value | 
| --- | --- | 
| 发布者 URL | https://<PINGFEDERATE\_HOST> | 
| 授权端点 | https://<PINGFEDERATE\_HOST>/as/authorization.oauth2 | 
| 令牌端点 | https://<PINGFEDERATE\_HOST>/as/token.oauth2 | 
| JWKS URI | https://<PINGFEDERATE\_HOST>/pf/JWKS | 

#### PingOne
<a name="desktop-enterprise-pingone"></a>

有关详细说明，请参阅 Ping [Identity 文档中的编辑应用程序-原生](https://docs.pingidentity.com/pingone/applications/p1_edit_application_native.html)。

**创建 PingOne OIDC 原生应用程序**

1. 在 PingOne 管理员控制台中，前往**应用程序 → 应用程序**，然后选择 **\+** 图标。

1. 输入`Amazon Quick Desktop`作为应用程序名称。

1. 在 “**应用程序类型**” 部分中，选择**本机**，然后选择**保存**。

1. 在**配置**选项卡上，选择**编辑**并配置以下设置：    
[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/quick/latest/userguide/desktop-enterprise-setup.html)

1. 选择**保存**。

1. 在**资源**选项卡上，添加以下范围：`openid`、`email`、`profile`、`offline_access`。

1. 在 “**属性映射**” 选项卡上，验证`email`属性是否已映射到用户的电子邮件地址。

1. 将应用程序切换为 “**已启用”**。

1. 记下 “**配置**” 选项卡中的 “**客户端 ID****” 和 “环境 ID**”。

**注意**  
 PingOne 域名因地区而异。以下示例使用`.com`。将该域替换为适合您环境的域（例如`.ca``.eu`、或`.asia`）。

您的 OIDC 终端节点使用以下格式。`<ENV_ID>`替换为您的 PingOne 环境 ID。


| Field | Value | 
| --- | --- | 
| 发布者 URL | https://auth.pingone.com/<ENV\_ID>/as | 
| 授权端点 | https://auth.pingone.com/<ENV\_ID>/as/authorize | 
| 令牌端点 | https://auth.pingone.com/<ENV\_ID>/as/token | 
| JWKS URI | https://auth.pingone.com/<ENV\_ID>/as/jwks | 

## 步骤 2：在 IAM 身份中心创建可信令牌发行者
<a name="desktop-enterprise-step2"></a>

**注意**  
只有当您的 Amazon Quick 账户使用 AWS Identity and Access Management 身份中心进行身份验证时，才需要执行此步骤。如果您的账户使用 IAM 联合，请跳过此步骤并继续执行步骤 3。

TTI 告诉 IAM 身份中心信任来自您的 IdP 的令牌以及如何将其映射到 IAM 身份中心用户。您可以在 AWS Identity and Access Management 身份中心控制台或 CLI 中创建 TT AWS I。

有关更多信息，请参阅 Ident *AWS Identity and Access Management ity Center 用户指南*[中的设置可信令牌颁发者](https://docs.aws.amazon.com/singlesignon/latest/userguide/setuptrustedtokenissuer.html)。

**在 IAM 身份中心控制台中创建 TTI**

1. 打开[AWS Identity and Access Management 身份中心控制台](https://console.aws.amazon.com/singlesignon)。

1. 选择**设置**。

1. 在**设置**页面上，选择**身份验证**选项卡。

1. 在**可信令牌发布者**下，选择**创建可信令牌发布者**。

1. 在 “**设置外部 IdP 以发行可信令牌” 页面的 “可信****令牌颁发者详细信息**” 下，配置以下内容：    
[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/quick/latest/userguide/desktop-enterprise-setup.html)

1. 在 “映射**属性**” 下，配置 IAM Identity Center 用来查找用户的属性映射：    
[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/quick/latest/userguide/desktop-enterprise-setup.html)
**重要**  
身份提供商属性必须与您的 IdP 在令牌中包含的声明相匹配，IAM Identity Center 属性必须唯一标识您的身份存储中的用户。最常见的映射是 `email` →`emails.value`，但您的组织可能会使用不同的属性，例如`sub`或自定义声明。令牌声明中的值必须与 IAM Identity Center 中相应属性的值完全匹配。

1. 选择**创建可信令牌发布者**。

1. 请注意**可信令牌发行者 AR** N。您在下一个步骤中需要用到它。

或者，要使用 CLI 创建 TT AWS I，请运行以下命令。`<IDC_INSTANCE_ARN>`替换为您的 IAM Identity Center 实例 Amazon 资源名称 (ARN) 和`<ISSUER_URL>`步骤 1 中的颁发者 URL。

```
aws sso-admin create-trusted-token-issuer \
  --instance-arn <IDC_INSTANCE_ARN> \
  --name "AmazonQuickDesktop" \
  --trusted-token-issuer-type OIDC_JWT \
  --trusted-token-issuer-configuration '{
    "OidcJwtConfiguration": {
      "IssuerUrl": "<ISSUER_URL>",
      "ClaimAttributePath": "email",
      "IdentityStoreAttributePath": "emails.value",
      "JwksRetrievalOption": "OPEN_ID_DISCOVERY"
    }
  }'
```

请注意输出`TrustedTokenIssuerArn`中的。您在下一个步骤中需要用到它。

下表列出了每个身份提供者的颁发者 URL。


| 身份提供者 | 发布者 URL | 
| --- | --- | 
| Microsoft Entra ID | https://login.microsoftonline.com/<TENANT\_ID>/v2.0 | 
| Okta | https://<OKTA\_DOMAIN>/oauth2/default | 
| PingFederate | https://<PINGFEDERATE\_HOST> | 
| PingOne | https://auth.pingone.com/<ENV\_ID>/as | 

## 步骤 3：在 Amazon Quick 管理控制台中配置扩展程序访问权限
<a name="desktop-enterprise-step3"></a>

**添加扩展访问权限**

1. 登录 Amazon Quick 管理控制台。

1. 在 “**权限**” 下，选择 “**扩展访问**权限”。

1. 选择**添加分机访问权限**。

1. （可选）如果您的账户使用 IAM Identity Center，则会出现 “**可信令牌发行者设置**” 步骤。输入以下信息：    
[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/quick/latest/userguide/desktop-enterprise-setup.html)

   对于使用 IAM 联合身份验证的账户，此步骤不会出现。

1. 选择 “**快速扩展” 的桌面应用程序**，然后选择 “**下一步**”。

1. 输入 Amazon Quick 扩展详情：    
[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/quick/latest/userguide/desktop-enterprise-setup.html)

1. 选择**添加**。
**重要**  
在选择 “**添加**” 之前，请验证所有值是否正确。扩展程序访问配置在创建后无法编辑。如果任何值不正确，则必须删除扩展程序访问权限并创建新的访问权限。

**创建扩展**

1. 在 Amazon Quick 控制台的左侧导航栏中，在 “**连接应用程序和数据**” 下方，选择 “**扩展**”。

1. 选择 “**添加扩展**”。

1. 选择您之前创建**的用于快速访问扩展程序的桌面应用程序**。选择**下一步**。

1. 选择**创建**。

## 步骤 4：下载并分发桌面应用程序
<a name="desktop-enterprise-step4"></a>

配置企业登录后，请自行下载并安装桌面应用程序来验证设置。在**登录屏幕上选择 Enterpris** e 登录，然后使用您的公司凭据进行身份验证，以确认配置正在运行。有关下载和安装步骤，请参阅[开始使用](getting-started-desktop.md)。

如果登录失败，请根据步骤 1 中的 OIDC 端点验证您在步骤 3 中输入的值。如果任何值不正确，请删除**权限 → 扩展程序访问权限下的扩展访问**权限，然后使用正确的值重复步骤 3。

验证设置后，请引导用户[开始使用](getting-started-desktop.md)查看下载、安装和登录说明。

## 问题排查
<a name="desktop-enterprise-troubleshooting"></a>

`redirect_mismatch`错误  
验证 IdP 中的重定向 URI 是否准确`http://localhost:18080`且已配置为公共客户端或本机平台。

登录后未找到用户  
IdP 令牌中的电子邮件必须与 IAM Identity Center 中用户的电子邮件地址完全匹配。确认已配置用户，并且两个系统中的电子邮件地址是否相同。

令牌验证失败  
验证 TTI 中的发卡机构 URL 是否与 IdP 的 OIDC 配置中的发卡机构 URL 完全匹配。

同意或许可错误（微软 Entra ID）  
在 Azure 门户中授予管理员对所需的 API 权限的同意。导航到应用程序注册的 **API 权限**页面，然后选择 **[您的组织] 授予管理员同意**。

会话经常过期  
确认您的 IdP 已配置为发放刷新令牌。对于 Microsoft Entra ID，`offline_access`范围是必填的。对于 Okta，必须启用 “刷新令牌” 授予类型，并且必须授予`offline_access`范围。对于 Ping 身份，必须启用刷新令牌授权类型，并且必须授予`offline_access`范围。对于 PingFederate，还要确认**在 OIDC 策略中选择了 “刷新时返回 ID 令牌**”。

`invalid_scope`错误（Okta）  
确认`offline_access`您的授权服务器上已启用该功能。导航到 “**安全” → “API” → “授权服务器” → “默**认” → “范围”，然后确认范围存在。还要验证应用程序的访问策略是否允许刷新令牌授权类型。

应用程序未启用 (PingOne)  
如果身份验证在未进入 PingOne登录页面的情况下立即失败，请确认 PingOne 管理员控制台中的应用程序切换开关已设置为 “**启用**”。

刷新后缺少电子邮件索赔 (PingFederate)  
验证`email`索赔是否包含在 OIDC 政策的 **“属性合同”** 中，并映射到正确的用户属性。映射必须生成对初始身份验证和刷新令牌授予的`email`声明。