本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 设置 Microsoft Entra ID App-Only 身份验证用于 SharePoint Microsoft Entra ID App-Only 身份验证 (`ENTRA_ID_APP_ONLY`) 是 SharePoint 数据源的推荐身份验证方法。它使用 OAuth 2.0 客户端凭证（仅限应用程序）流程：Microsoft Entra 应用程序使用证书进行身份验证，因此在抓取时或查询时不涉及用户登录。这是唯一支持文档级访问控制 (ACL) 的身份验证方法。有关与替代`OAUTH2_APP`方法的比较，请参见[身份验证方法](kb-managed-ds-sharepoint.md#kb-managed-sharepoint-auth-methods)。 此设置跨越两个系统——Microsoft Entra ID和你的 AWS 账户——证书是将它们联系在一起的凭据。连接器将证书（包括私钥）作为 PKCS \#12 (`.p12`) 文件存储在 Amazon S3 中，并使用它来签署微软的身份验证断言；匹配的公共证书将上传到 Entra 应用程序注册中，以便微软可以验证这些断言。 **需要管理权限** 此设置需要 Microsoft Entra ID 管理员（全局管理员或特权角色管理员）来注册应用程序、配置权限并授予管理员同意。如果您使用`Sites.Selected`权限范围，则还需要 SharePoint 管理员来授予每个站点的访问权限。下面的**安装步骤和角色**表列出了每个步骤所需的访问权限。 ## 设置步骤和角色 此过程同时涉及 Microsoft Entra ID AWS 管理员和管理员。根据组织中职责的划分方式，可以由一个人或几个人来完成这些步骤。使用下表确定每个步骤所需的访问权限。 **设置步骤和每个步骤所需的访问权限** | 步骤 | 你在做什么 | 需要访问权限 | | --- | --- | --- | | 1. 注册应用程序 | 创建 Entra 应用程序注册并记录其客户端和租户 ID。 | Microsoft Entra ID 管理员（全局管理员或特权角色管理员） | | 2. 添加权限并授予同意 | 为您的配置分配应用程序权限并授予管理员同意。 | 微软 Entra ID 管理员 | | 3. 生成证书 | 使用 OpenSSL 创建自签名证书和 PKCS \#12 (.p12) 捆绑包。 | 任何拥有本地终端的人（需要 OpenSSL） | | 4. 将公共证书上传到 Entra | 将公共证书添加到应用程序注册的密钥中。 | 微软 Entra ID 管理员 | | 5. 授予每个站点的访问权限（Sites.Selected仅限） | 通过 Microsoft Graph API 向应用程序授予访问每个 SharePoint 站点的权限。 | 微软 Entra ID 管理员 | | 6. 将证书上传到 Amazon S3 | 将.p12捆绑包存储在 Amazon S3 存储桶中。 | AWS 管理员（亚马逊 S3） | | 7. 创建密钥 | 将凭证存储在 AWS Secrets Manager 密钥中。 | AWS 管理员（Secrets Manager） | | 8. 授予服务角色对证书的访问权限 | 将 Amazon S3 读取权限添加到您的知识库服务角色。 | AWS 管理员 (IAM) | ## 选择您的配置 在开始之前，请做出两个决定。它们决定您在步骤 2 中分配的权限以及如何授予网站访问权限。 + **Document-level 访问控制 (ACL)**-决定数据源是否按每个用户的 SharePoint 权限筛选查询结果。ACL 爬网需要额外的 Microsoft Graph 和 SharePoint 权限。创建数据源后，您无法更改此设置。有关更多信息，请参阅 [Document-level 访问控制](kb-managed-ds-sharepoint-acl.md)。 + **权限范围**-决定应用程序是可以读取租户中的所有 SharePoint 站点（**所有站点**，最简单的选项），还是只能读取您明确授予的站点（**`Sites.Selected`**最低权限选项）。在第 5 步中`Sites.Selected`完成了每个站点的额外授权，之后添加的任何网站都需要自己的授权。 这两个选项的组合将选择下一节中的一个权限集。 ## 权限参考 分配与您的配置相匹配的应用程序权限。所有权限均为**应用程序**权限（非委托），并且每个权限都需要管理员同意。连接器对两个 Microsoft 资源进行身份验证：**Microsoft Graph**（用于枚举站点，对于 ACL，用于解析用户和群组）和 **SharePoint**REST API（用于读取网站内容，对于 ACL，则为项目级权限）。 **重要** 在 Entra 门户中添加这些权限时，请选择**应用程序权限**选项卡，而不是**委派权限**。 App-only 身份验证使用应用程序权限。 选择您的配置选项卡，查看要分配的确切的 Microsoft Graph 和 SharePoint 权限。 ------ #### [ All sites, no ACLs ] **所有网站，仅限内容** | API | 权限 | 用途 | | --- | --- | --- | | Microsoft Graph | Sites.Read.All | 枚举并读取所有 SharePoint 站点。 | | SharePoint | Sites.Read.All | 通过 SharePoint REST API 阅读网站内容。 | ------ #### [ All sites, with ACLs ] **所有带有 ACL 的站点** | API | 权限 | 用途 | | --- | --- | --- | | Microsoft Graph | Sites.Read.All | 枚举并读取所有 SharePoint 站点。 | | Microsoft Graph | User.Read.All | 为用户解析文档级 ACL。 | | Microsoft Graph | GroupMember.Read.All | 解决文档级 ACL 的群组成员资格问题。 | | SharePoint | Sites.FullControl.All | 读取 ACL 搜索的项目级别权限，并在查询时验证访问权限。 Sites.Read.All不足以进行此项检查。 | ------ #### [ Sites.Selected, no ACLs ] **Sites.Selected，仅限内容** | API | 权限 | 用途 | | --- | --- | --- | | Microsoft Graph | Sites.Selected | 仅访问你明确授权的网站（Microsoft Graph）。 | | SharePoint | Sites.Selected | 仅访问您明确授予的站点 (SharePoint REST)。在步骤 5 中为每个站点授予该read角色。 | ------ #### [ Sites.Selected, with ACLs ] **Sites.Selected，带有 ACL** | API | 权限 | 用途 | | --- | --- | --- | | Microsoft Graph | Sites.Selected | 仅访问你明确授权的网站（Microsoft Graph）。 | | Microsoft Graph | User.Read.All | 为用户解析文档级 ACL。 | | Microsoft Graph | GroupMember.Read.All | 解决文档级 ACL 的群组成员资格问题。 | | SharePoint | Sites.Selected | 仅访问您明确授权的网站。在步骤 5 中为每个站点授予fullcontrol角色（读取 ACL 的项目级权限所必需的）。 | ------ **注意** `Sites.FullControl.All`授予对租户中每个站点的广泛访问权限。如果您的组织需要最低权限，请在步骤 5 中使用`Sites.Selected`并授予每个站点的访问权限。 ## 您在设置过程中收集的值 在完成这些步骤时，您可以创建或收集以下值。您可以在创建数据源时使用它们。有关更多信息，请参阅 [Connect SharePoint 数据源](kb-managed-ds-sharepoint-connect.md)。 **值参考** | 值 | 创建于 | 用于 | | --- | --- | --- | | 应用程序（客户端）ID | 步骤 1 | 秘密 (clientId)。 | | 目录（租户）ID | 步骤 1 | 数据源tenantId。 | | 证书 — PKCS \#12 bundle (.p12) 及其密码 | 步骤 3 | 捆绑包（证书加私钥）已上传到 Amazon S3（步骤 6）；密码存储在密钥中（certificatePassword）。 | | 证书-公共证书 (.cer) | 步骤 3 | 同一份证书的公开部分，上传到 Entra 应用程序注册处（步骤 4）。 | | 亚马逊 S3 存储桶名称和密钥 | 步骤 6 | 数据源certificateS3Path。 | | 密钥 ARN | 步骤 7 | 数据源secretArn。 | ## 第 1 步：在 Microsoft Entra ID 中注册应用程序 1. 登录 [Microsoft Entra 管理中心](https://entra.microsoft.com/)。 1. 在左侧导航栏中，展开 **Entra ID**，然后选择**应用程序注册**。 1. 选择 “**新注册**”。 1. 在 “**名称**” 中，输入描述性名称，例如。`bedrock-sharepoint-connector` 1. 对于**支持的帐户类型**，请选择 “**仅限此组织目录中的帐户（单租户）**”。 1. **将重定向 URI** 留空。不需要重定向 URI，因为应用程序使用的是客户端凭证流程，而不是交互式登录流程。 1. 选择**注册**。 1. 在应用程序**概述**页面上，记录**应用程序（客户端）ID** 和**目录（租户）ID**。稍后你需要两个。 ## 第 2 步：添加 API 权限并授予管理员同意 从中为您的配置添加权限[权限参考](#kb-managed-sharepoint-entra-permissions)。 1. 在您的应用程序注册中，选择 **API 权限**，然后选择**添加权限**。 1. 选择 **Microsoft Graph**，然后选择**应用程序权限**。为您的配置搜索并选择每个 Microsoft Graph 权限，然后选择**添加权限**。 1. 再次选择 “**添加权限”**。选择 **SharePoint**（在 **Microsoft API** 下），然后选择 “**应用程序权限”**。为您的配置选择每项 SharePoint 权限，然后选择**添加权限**。 1. 在 **API 权限**页面上，选择 **[您的组织] 授予管理员同意**，然后确认。未经管理员同意，应用程序无法访问 SharePoint 数据。 **注意** Microsoft Entra ID App-Only 身份验证使用证书（来自步骤 3）作为凭据，因此您无需为此应用程序创建客户端密钥。 ## 步骤 3：生成身份验证证书 生成自签名证书并将其打包为 PKCS \#12 (`.p12`) 捆绑包。该捆绑包包含证书及其受密码保护的私钥。您将公共证书上传到 Entra（步骤 4），将`.p12`捆绑包上传到 Amazon S3（步骤 6）。选择操作系统的选项卡以查看命令。 **注意** Amazon Bedrock 从`.p12`捆绑包中读取私钥以签署身份验证断言，因此捆绑包必须有密码保护并安全存储。随机选择一个强度高的密码——你将其存储在秘密中，如`certificatePassword`步骤 7 所示。 ------ #### [ Linux or macOS (OpenSSL) ] **生成私钥和自签名证书** ``` openssl req -x509 -newkey rsa:2048 -keyout private_key.pem -out certificate.cer \ -days 365 -nodes \ -subj "/CN={{bedrock-sharepoint-connector}}" ``` **Package 将证书和密钥打包为 PKCS \#12 (`.p12`) 捆绑包** 出现提示时，请输入强导出密码。为步骤 7 录制下来。 ``` openssl pkcs12 -export -out certificate.p12 \ -inkey private_key.pem -in certificate.cer ``` 您现在有三个文件：私钥 (`private_key.pem`)、公共证书 (`certificate.cer`) 和捆绑包 (`certificate.p12`)。您在步骤 4 中将公共证书上传到 Entra，在步骤 6 中将`.p12`捆绑包上传到 Amazon S3。 ------ #### [ Windows (PowerShell) ] **生成自签名证书** 以下 PowerShell 命令生成有效期为一年 2048 位 RSA 自签名证书，并将其存储在当前用户的证书存储中。{{your-password}}替换为一个强的随机密码——你可以将其存储在秘密中，如`certificatePassword`步骤 7 所示。 ``` $cert = New-SelfSignedCertificate ` -Subject "CN={{bedrock-sharepoint-connector}}" ` -CertStoreLocation "Cert:\CurrentUser\My" ` -KeyAlgorithm RSA ` -KeyLength 2048 ` -KeyExportPolicy Exportable ` -NotAfter (Get-Date).AddYears(1) ``` **导出公共证书** ``` Export-Certificate -Cert $cert -FilePath certificate.cer -Type CERT ``` **导出 PKCS \#12 (`.p12`) 捆绑包** ``` $password = ConvertTo-SecureString -String "{{your-password}}" -Force -AsPlainText Export-PfxCertificate -Cert $cert -FilePath certificate.p12 -Password $password ``` 现在，您有两个文件：公共证书 (`certificate.cer`) 和捆绑包 (`certificate.p12`)。您在步骤 4 中将公共证书上传到 Entra，在步骤 6 中将`.p12`捆绑包上传到 Amazon S3。 ------ **重要** 将`.p12`捆绑包存储在 Amazon S3 中（不是`.pem`或`.cer`文件）。该捆绑包包含 Amazon Bedrock 用于进行身份验证的私钥。 Document-level 访问控制 (ACL) 需要`.p12`格式。对于没有 ACL 的仅内容抓取，您可以改为存储 PEM-encoded 证书；由于`.p12`适用于每种配置，因此本指南自始至终都使用。`.p12` **注意** 默认情况下，该证书的有效期为一年。证书过期会导致所有同步失败，因此请在证书到期之前轮换证书。要更改有效期，请调整`-days`选项 (openSSL) 或`-NotAfter`参数 (PowerShell)。有关轮换步骤，请参阅[轮换证书](kb-managed-ds-sharepoint-troubleshooting.md#kb-managed-ds-sharepoint-rotate-cert)。 ## 第 4 步：将公共证书上传到 Entra 1. 在应用程序注册中，选择 “**证书和机密**”，然后选择 “**证书**” 选项卡。 1. 选择**上传证书**，然后选择您在步骤 3 中生成的`certificate.cer`文件（仅限公共证书，切勿将`.p12`捆绑包或私钥上传到 Entra）。 1. 选择**添加**。 ## 第 5 步（Sites.Selected 仅限）：授予每个站点的访问权限 **注意** 仅当您在步骤 2 中选择了`Sites.Selected`权限范围时，此步骤才适用。如果您使用了所有站点作用域（`Sites.Read.All`或`Sites.FullControl.All`），请跳至。[第 6 步：将证书上传到 Amazon S3](#kb-managed-sharepoint-entra-step6) 使用`Sites.Selected`，您可以通过 Microsoft Graph API 单独授予连接器应用程序访问每个 SharePoint 站点的权限。这需要一份单独的临时申请`Sites.FullControl.All`，该申请只能用于执行补助金。Amazon Bedrock 从来没有看到这个临时应用程序或其证书。 1. **创建临时授予者应用程序。**在 Entra 管理中心，将第二个应用程序（例如`bedrock-sharepoint-granter`）注册为没有重定向 URI 的单租户。添加 Microsoft Graph `Sites.FullControl.All` 应用程序权限，授予管理员同意，然后创建客户端密钥。记录其客户端 ID 和密钥值。 1. **获取授予者应用程序的访问令牌。**将占位符替换为授予者应用程序的客户端 ID 和密钥以及您的租户 ID。 ``` curl -s -X POST \ "https://login.microsoftonline.com/{{TENANT_ID}}/oauth2/v2.0/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials" \ -d "client_id={{GRANTER_CLIENT_ID}}" \ -d "client_secret={{GRANTER_CLIENT_SECRET}}" \ -d "scope=https://graph.microsoft.com/.default" ``` 响应中包含`access_token`。在接下来的命令中将其用作不记名令牌。 1. **将每个网站的网址解析为一个站点 ID。**使用网站的主机名和服务器相对路径。 ``` curl -s \ "https://graph.microsoft.com/v1.0/sites/{{contoso}}.sharepoint.com:/sites/{{engineering}}" \ -H "Authorization: Bearer {{ACCESS_TOKEN}}" ``` 响应中的`id`字段是站点 ID。 1. **授予连接器应用程序访问该站点的权限。**`read`用于仅限内容的爬网或 ACL 爬网`fullcontrol`。{{CONNECTOR\_CLIENT\_ID}}替换为步骤 1 中的应用程序（客户端）ID。 ``` curl -s -X POST \ "https://graph.microsoft.com/v1.0/sites/{{SITE_ID}}/permissions" \ -H "Authorization: Bearer {{ACCESS_TOKEN}}" \ -H "Content-Type: application/json" \ -d '{ "roles": ["{{fullcontrol}}"], "grantedToIdentities": [{ "application": { "id": "{{CONNECTOR_CLIENT_ID}}", "displayName": "{{bedrock-sharepoint-connector}}" } }] }' ``` 1. 对数据源中包含的每个站点重复解析和授权命令。完成后，您可以删除临时授予者应用程序；每个站点的授权仍然有效。 **重要** Per-site 补助金不具有追溯力。如果您稍后向数据源添加站点，请在下次同步之前授予连接器应用程序访问该站点的权限，否则其内容不会被抓取。 ## 第 6 步：将证书上传到 Amazon S3 将步骤 3 中的`.p12`捆绑包上传到知识库所在 AWS 区域的 Amazon S3 存储桶。记录存储桶名称和密钥——您可以将其用作数据源`certificateS3Path`。 ``` aws s3api put-object \ --bucket {{your-certificate-bucket}} \ --key {{certs/certificate.p12}} \ --body certificate.p12 \ --server-side-encryption AES256 ``` **注意** 我们建议您在证书对象上启用服务器端加密，并将存储桶限制为需要它的委托人。该捆绑包包含私钥。 ## 第 7 步：创建 Secrets Manager 密钥 将凭证存储在 AWS Secrets Manager 密钥中。对于 Entra ID App-Only 身份验证，请包括以下键值对： + `clientId`（必填）— 步骤 1 中的应用程序（客户端）ID。 + `certificatePassword`（推荐）— 您在步骤 3 中为`.p12`捆绑包设置的密码。参见下面的注释。 ``` { "clientId": "{{your-client-id}}", "certificatePassword": "{{your-certificate-password}}" } ``` 使用以下命令创建密钥 AWS Command Line Interface： ``` aws secretsmanager create-secret \ --name {{bedrock-sharepoint-creds}} \ --secret-string file://secret.json ``` 记录响应中的秘密 ARN。您可以将其用作数据源`secretArn`。 **注意** 设置`certificatePassword`为您在步骤 3 中创建`.p12`分发包时使用的密码。如果您省略此字段，Amazon Bedrock 将使用您的应用程序的客户端 ID 作为密码打开捆绑包，因此该捆绑包必须使用客户端 ID 作为其密码创建。我们建议您始终设置明确的高熵密码，并安全地存储私钥。 **注意** **改用 PEM 证书。**本指南使用适用于所有配置的`.p12`捆绑包。如果您仅抓取内容（没有文档级访问控制），则可以改用 PEM 证书。在这种情况下，仅将*公共*证书上传到 Amazon S3（不是`.p12`捆绑包），并将私钥存储在密钥中`privateKey`（未加密 base64 编码的 PKCS \#8，没有标题行），以代替：`certificatePassword` ``` { "clientId": "{{your-client-id}}", "privateKey": "{{your-base64-pkcs8-private-key}}" } ``` ## 步骤 8：向服务角色授予证书访问权限 您的知识库服务角色必须能够从 Amazon S3 读取证书对象。将以下语句添加到角色的权限策略中，将存储桶名称和密钥替换为您的值。 ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "S3ListCertificateBucket", "Effect": "Allow", "Action": ["s3:ListBucket"], "Resource": ["arn:aws:s3:::{{your-certificate-bucket}}"], "Condition": { "StringEquals": { "aws:ResourceAccount": ["{{123456789012}}"] } } }, { "Sid": "S3GetCertificate", "Effect": "Allow", "Action": ["s3:GetObject"], "Resource": [ "arn:aws:s3:::{{your-certificate-bucket}}/{{certs/certificate.p12}}", "arn:aws:s3:::{{your-certificate-bucket}}/{{certs/certificate.p12}}.metadata.json" ], "Condition": { "StringEquals": { "aws:ResourceAccount": ["{{123456789012}}"] } } } ] } ``` **注意** 该策略还允许对证书旁边的可选`.metadata.json`文件进行读取权限。Amazon Bedrock 不需要此文件；包括权限可以防止出现访问错误（如果存在）。 **如果证书对象使用 AWS KMS 密钥加密** 中的上传命令[第 6 步：将证书上传到 Amazon S3](#kb-managed-sharepoint-entra-step6)使用 Amazon S3-managed 加密 (`AES256`)，无需额外权限。相反，如果您使用客户托管的 KMS 密钥 (SSE-KMS) 使用 Amazon S3 服务器端加密对证书对象进行加密，则服务角色还需要对该密钥的`kms:Decrypt`权限，并且密钥的策略必须允许该角色使用该密钥。使用 AWS 托管`aws/s3`密钥加密的对象不需要此额外授权。 ``` { "Sid": "KmsDecryptCertificate", "Effect": "Allow", "Action": ["kms:Decrypt"], "Resource": ["arn:aws:kms:{{us-west-2}}:{{123456789012}}:key/{{your-key-id}}"] } ``` 只需要读取权限`kms:Decrypt`。有关更多信息，请参阅对 [AWS KMS 密钥使用服务器端加密 (SSE-KMS)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html)。 有关知识库服务角色权限的完整集合，请参阅[访问数据来源的权限](kb-permissions.md#kb-permissions-access-ds)。 ## 后续步骤 现在，您拥有了创建数据源所需的一切：秘密 ARN、您的租户 ID 以及证书的 Amazon S3 位置。要使用 AWS 管理控制台 或 API 创建 SharePoint 数据源，请参阅[Connect SharePoint 数据源](kb-managed-ds-sharepoint-connect.md)。 **重要** 要进行`ENTRA_ID_APP_ONLY`身份验证，即使禁用 ACL，也必须在创建数据源时提供`certificateS3Path`。使用此身份验证类型创建且没有证书 SharePoint 的数据源失败。