# 启用对 Athena API 的联合访问
<a name="access-federation-saml"></a>

此部分介绍允许组织中的用户或客户端应用程序调用 Amazon Athena API 操作的联合身份访问。在这种情况下，组织的用户没有 Athena 的直接访问权限。相反，您在 AWS 外部的 Microsoft Active Directory 中管理用户凭证。Active Directory 支持 [SAML 2.0](https://wiki.oasis-open.org/security)（安全断言标记语言 2.0）。

要在此方案中对用户进行身份验证，请使用支持 SAML.2.0 的 JDBC 或 ODBC 驱动程序，访问 Active Directory 联合身份验证服务 (AD FS) 3.0 并允许客户端应用程序调用 Athena API 操作。

有关更多信息对于 AWS 的 SAML 2.0 支持，请参阅《IAM 用户指南**》中的 [关于 SAML 2.0 联合身份验证](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_saml.html)。

**注意**  
特定类型的身份提供者（IdP），即 Windows Server 中包括的 Active Directory 联合身份验证服务（AD FS 3.0）支持对 Athena API 的联合访问。联合访问与 IAM Identity Center 可信身份传播功能不兼容。访问通过支持 SAML 2.0 的 JDBC 或 ODBC 驱动程序版本建立。有关更多信息，请参阅 [通过 JDBC 连接到 Amazon Athena](connect-with-jdbc.md) 和 [通过 ODBC 连接到 Amazon Athena](connect-with-odbc.md)。

**Topics**
+ [开始前的准备工作](#access-federation-before-you-begin)
+ [了解身份验证流程](#access-federation-diagram)
+ [过程：对 Athena API 启用基于 SAML 的联合访问](#access-federation-procedure)

## 开始前的准备工作
<a name="access-federation-before-you-begin"></a>

 在开始之前，请满足以下先决条件：
+ 在组织中，安装并配置 ADFS 3.0 作为您的 IdP。
+ 在用于访问 Athena 的客户端上，安装和配置最新可用版本的 JDBC 或 ODBC 驱动程序。驱动程序必须包括对与 SAML 2.0 兼容的联合身份访问的支持。有关更多信息，请参阅 [通过 JDBC 连接到 Amazon Athena](connect-with-jdbc.md) 和 [通过 ODBC 连接到 Amazon Athena](connect-with-odbc.md)。

## 了解身份验证流程
<a name="access-federation-diagram"></a>

下图将说明对 Athena API 进行联合访问的身份验证过程。

![\[对 Athena API 的联合访问示意图。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/athena-saml-based-federation.png)


1. 您组织中的用户使用具有 JDBC 或 ODBC 驱动程序的客户端应用程序，请求组织的 IdP 进行身份验证。该 IdP 是 ADFS 3.0。

1. IdP 根据 Active Directory（组织的身份存储）对用户进行身份验证。

1. IdP 构建一个具有用户相关信息的 SAML 断言，并将此断言通过 JDBC 或 ODBC 驱动程序发送到客户端应用程序。

1. JDBC 或 ODBC 驱动程序调用 AWS Security Token Service [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) API 操作，将其传递给以下参数：
   + SAML 提供商的 ARN
   + 要代入的角色的 ARN
   + 来自 IdP 的 SAML 断言

   有关更多信息，请参阅 [AWS Security Token Service API 参考](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html)中的 *AssumeRoleWithSAML*。

1. 通过 JDBC 或 ODBC 驱动程序发送到客户端应用程序的 API 相应包含临时安全凭证。

1. 客户端应用程序使用临时安全凭证调用 Athena API 操作，从而允许您的用户访问 Athena API 操作。

## 过程：对 Athena API 启用基于 SAML 的联合访问
<a name="access-federation-procedure"></a>

该过程在组织的 IdP 与 AWS 账户之间建立信任关系，以实现对 Amazon Athena API 操作的基于 SAML 的联合访问。

**要启用对 Athena API 的联合访问，请执行以下操作：**

1. 在组织中，将 AWS 注册为您 IdP 中的服务提供商 (SP)。此过程称为*信赖方信任*。有关更多信息，请参阅《IAM 用户指南**》中的 [使用信赖方信任配置您的 SAML 2.0 IdP](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml_relying-party.html)。作为此任务的一部分，请执行以下步骤：

   1. 从以下 URL 获取示例 SAML 元数据文档：[https://signin.aws.amazon.com/static/saml-metadata.xml](https://signin.aws.amazon.com/static/saml-metadata.xml)。

   1. 在您组织的 IdP（ADFS）中，生成一个等同元数据 XML 文件，将您的 IdP 描述为 AWS 的身份提供者。您的元数据文件必须包括发布者名称、创建日期、过期日期以及 AWS 用来验证来自您组织的身份验证响应（断言）的密钥。

1. 在 IAM 控制台中，创建一个 SAML 身份提供程序实体。有关更多信息，请参阅《IAM 用户指南**》中的[创建 SAML 身份提供者](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml.html)。作为此步骤的一部分，请执行以下操作：

   1. 通过 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 打开 IAM 控制台。

   1. 上载此过程的第 1 步中由 IdP (ADFS) 生成的 SAML 元数据文档。

1. 在 IAM 控制台中，为您的 IdP 创建一个或多个 IAM 角色。有关更多信息，请参阅《IAM 用户指南》**中的[针对第三方身份提供程序创建角色（联合）](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp.html)。作为此步骤的一部分，请执行以下操作：
   + 在角色的权限策略中，列出允许您组织的用户在 AWS 中执行的操作。
   + 在角色的信任策略中，将在此过程第 2 步中创建的 SAML 提供商实体设置为主体。

   这将在您的组织与 AWS 之间建立信任关系。

1. 在您组织的 IdP (ADFS) 中，定义可将您组织中的用户或组映射到 IAM 角色的断言。将用户和组映射到 IAM 角色也称为*断言规则*。请注意，您的组织中不同的用户和组可能映射到不同的 IAM 角色。

   有关配置 ADFS 中的映射的信息，请参阅博客文章：[使用 Windows Active Directory、ADFS 和 SAML 2.0 启用 AWS 的联合身份验证](https://aws.amazon.com/blogs/security/enabling-federation-to-aws-using-windows-active-directory-adfs-and-saml-2-0/)。

1. 安装和配置具有 SAML 2.0 支持的 JDBC 或 ODBC 驱动程序。有关更多信息，请参阅 [通过 JDBC 连接到 Amazon Athena](connect-with-jdbc.md) 和 [通过 ODBC 连接到 Amazon Athena](connect-with-odbc.md)。

1. 指定从您应用程序到 JDBC 或 ODBC 驱动程序的连接字符串。有关应用程序应使用的连接字符串的信息，请参阅《*JDBC 驱动程序安装和配置指南*》中的“*使用 Active Directory 联合身份验证服务 (ADFS) 凭证提供程序*”或《*ODBC 驱动程序安装和配置指南*》中的类似主题，可从 [通过 JDBC 连接到 Amazon Athena](connect-with-jdbc.md) 和 [通过 ODBC 连接到 Amazon Athena](connect-with-odbc.md) 主题以 PDF 格式下载。

   下面大致概述了配置驱动程序的连接字符串：

   1. 在 `AwsCredentialsProviderClass configuration` 中，设置 `com.simba.athena.iamsupport.plugin.AdfsCredentialsProvider`，指示您希望通过 ADFS IdP 使用基于 SAML 2.0 的身份验证。

   1. 对于 `idp_host`，请提供 ADFS IdP 服务器的主机名。

   1. 对于 `idp_port`，请提供 ADFS IdP 侦听 SAML 断言请求的端口号。

   1. 对于 `UID` 和 `PWD`，请提供 AD 域用户凭证。在 Windows 上，如果使用驱动程序时未提供 `UID` 和 `PWD`，则驱动程序尝试获取登录到 Windows 计算机用户的用户凭证。

   1. （可选）将 `ssl_insecure` 设置为 `true`。在这种情况下，驱动程序不会检查 ADFS IdP 服务器的 SSL 证书的真实性。如果没有将 ADFS IdP 的 SSL 证书配置为受驱动程序信任，则需要设置为 `true`。

   1. 要启用 Active Directory 域用户或组与一个或多个 IAM 角色的映射（如此过程中第 4 步所述），请在 JDBC 或 ODBC 连接的 `preferred_role` 中，为驱动程序连接指定要代入的 IAM 角色 (ARN)。指定 `preferred_role` 是可选的，在角色不是断言规则中列出的第一个角色时非常有用。

   作为此过程的结果，将发生以下操作：

   1. JDBC 或 ODBC 驱动程序调用 AWS STS [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) API，并向其传递断言，如[架构示意图](#access-federation-diagram)中的第 4 步所示。

   1. AWS 确保代入角色的请求来自 SAML 提供商实体中引用的 IdP。

   1. 如果请求成功，AWS STS [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) API 操作会返回一组临时安全凭证，您的客户端应用程序即可用其向 Athena 发出已签名的请求。

      现在，您的应用程序拥有当前用户的相关信息，并且可以通过编程方式访问 Athena。