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

# 在桌面上设置 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. 在 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 会验证令牌并将用户映射到您账户中的身份。您的 IdP 中的电子邮件地址必须与 Amazon Quick 中用户的电子邮件地址完全匹配。

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

在开始之前，请确认您已具备以下条件：
+ 一个拥有有效 Amazon Quick 订阅的 AWS 账户。Amazon Quick 账户的主区域（身份区域）必须是美国东部（弗吉尼亚北部）（us-east-1）。支持所有身份类型，包括 IAM 身份中心、IAM 联合身份验证和原生 Amazon Quick (username/password) 用户。
+ 管理员访问您的 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：在 Amazon Quick 管理控制台中配置扩展程序访问权限
<a name="desktop-enterprise-step2"></a>

**添加分机访问权限**

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

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

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

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. 选择**创建**。

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

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

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

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

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

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

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

令牌验证失败  
验证扩展程序访问配置中的发行者 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`声明。