本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 使用令牌控制用户访问文档
**注意**
功能支持因所用索引类型和搜索 API 而异。要查看您使用的索引类型和搜索 API 是否支持此功能，请参阅[索引类型](https://docs.aws.amazon.com/kendra/latest/dg/hiw-index-types.html)。
**重要**
Amazon Kendra GenAI 企业版索引不支持基于令牌的用户访问控制。
您可以控制哪些用户或组可以访问索引中的某些文档或在搜索结果中查看某些文档。这称为用户上下文筛选。这是一种个性化搜索，其优点是可以控制对文档的访问权限。例如，并非所有在公司门户网站上搜索信息的团队都应该访问绝密的公司文档，这些文档也不应与所有用户相关。只有获得绝密文档访问权限的特定用户或团队组才能在搜索结果中看到这些文档。
Amazon Kendra 企业和开发者索引支持使用以下令牌类型进行基于令牌的用户访问控制：
+ Open ID
+ 带有共享密钥的 JWT
+ 带有公有密钥的 JWT
+ JSON
Amazon Kendra 可用于为您的检索和搜索应用程序提供安全的企业搜索。在查询和检索期间，根据`AttributeFilters`请求中`UserContext`提供的 Amazon Kendra 内容筛选搜索结果。 Amazon Kendra 读取其连接器在抓取和摄取期间收集的文档访问控制列表 (ACLs)。检索和搜索结果返回时 URLs 指向原始文档存储库以及简短的摘录。对完整文档的访问仍由原始存储库强制执行。
**Topics**
+ [
# 使用 OpenID
](create-index-access-control-tokens-openid.md)
+ [
# 使用带有共享密钥的 JSON Web 令牌（JWT）
](create-index-access-control-tokens-jwtshared.md)
+ [
# 使用带有公有密钥的 JSON Web 令牌（JWT）
](create-index-access-control-tokens-jwtpublic.md)
+ [
# 使用 JSON
](create-index-access-control-tokens-json.md)
# 使用 OpenID
要将 Amazon Kendra 索引配置为使用 OpenID 令牌进行访问控制，您需要来自 OpenID 提供程序的 JWKS（JSON Web 密钥集）URL。在大多数情况下，JWKS URL 采用以下格式：`https://domain-name/.well_known/jwks.json`（如果他们关注的是 OpenID 发现）。
以下示例说明在创建索引时如何使用 OpenID 进行用户访问控制。
------
#### [ Console ]
1. 选择**创建索引**以开始创建新索引。
1. 在**指定索引详细信息**页面上，为您的索引指定名称和描述。
1. 对于 **IAM 角色**，选择一个角色或选择**创建新角色**，并指定角色名称来创建新角色。IAM 角色的前缀为“AmazonKendra-”。
1. 将所有其他字段保留为默认值。选择**下一步**。
1. 在**配置用户访问控制**页面上，在**访问控制设置**下，选择**是**以使用令牌进行访问控制。
1. 在**令牌配置**下，选择 **OpenID** 作为**令牌类型**。
1. 指定**签名密钥 URL**。该 URL 应指向一组 JSON Web 密钥。
1. （*可选*）在**高级配置**下：
1. 指定要在 ACL 检查中使用的**用户名**。
1. 指定要在 ACL 检查中使用的一个或多个**组**。
1. 指定将验证颁发机构的**颁发机构**。
1. 指定**客户端 ID**。您必须指定与 JWT 中的受众相匹配的正则表达式。
1. 在**配置详细信息**页面中，选择**开发者版本**。
1. 选择**创建**以创建索引。
1. 等待索引创建完成。Amazon Kendra 会为索引预配硬件。此操作可能需要一些时间。
------
#### [ CLI ]
要使用 JSON 输入文件通过 AWS CLI 创建索引，请先使用所需参数创建一个 JSON 文件：
```
{
"Name": "user-context",
"Edition": "ENTERPRISE_EDITION",
"RoleArn": "arn:aws:iam::account-id:role:/my-role",
"UserTokenConfigurations": [
{
"JwtTokenTypeConfiguration": {
"KeyLocation": "URL",
"Issuer": "optional: specify the issuer url",
"ClaimRegex": "optional: regex to validate claims in the token",
"UserNameAttributeField": "optional: user",
"GroupAttributeField": "optional: group",
"URL": "https://example.com/.well-known/jwks.json"
}
}
],
"UserContextPolicy": "USER_TOKEN"
}
```
您可以覆盖默认的用户和组字段名称。`UserNameAttributeField` 的默认值为“user”。`GroupAttributeField` 的默认值为“groups”。
接下来，使用输入文件调用 `create-index`。例如，如果您的 JSON 文件名为 `create-index-openid.json`，则可以使用以下名称：
```
aws kendra create-index --cli-input-json file://create-index-openid.json
```
------
#### [ Python ]
```
response = kendra.create_index(
Name='user-context',
Edition='ENTERPRISE_EDITION',
RoleArn='arn:aws:iam::account-id:role:/my-role',
UserTokenConfigurations=[
{
"JwtTokenTypeConfiguration": {
"KeyLocation": "URL",
"Issuer": "optional: specify the issuer url",
"ClaimRegex": "optional: regex to validate claims in the token",
"UserNameAttributeField": "optional: user",
"GroupAttributeField": "optional: group",
"URL": "https://example.com/.well-known/jwks.json"
}
}
],
UserContextPolicy='USER_TOKEN'
)
```
------
# 使用带有共享密钥的 JSON Web 令牌（JWT）
以下示例说明在创建索引时如何使用带有共享密钥令牌的 JSON Web Token（JWT）进行用户访问控制。
------
#### [ Console ]
1. 选择**创建索引**以开始创建新索引。
1. 在**指定索引详细信息**页面上，为您的索引指定名称和描述。
1. 对于 **IAM 角色**，选择一个角色或选择**创建新角色**，并指定角色名称来创建新角色。该 IAM 角色将带有前缀 “AmazonKendra-”。
1. 将所有其他字段保留为默认值。选择**下一步**。
1. 在**配置用户访问控制**页面上，在**访问控制设置**下，选择**是**以使用令牌进行访问控制。
1. 在**令牌配置**下，选择**带有共享密钥的 JWT** 作为**令牌类型**。
1. 在**用于签名共享密钥的参数**下，选择**密钥类型**。您可以使用现有的 AWS Secrets Manager 共享密钥或创建一个新共享密钥。
要创建新共享密钥，请选择**新建**，然后按照下列步骤操作：
1. 在 “**新 AWS Secrets Manager 密钥**” 下，指定**密钥名称**。保存公有密钥时，将添加前缀 `AmazonKendra-`。
1. 指定**键 ID**。键 ID 是一个提示，指示哪些键用于保护令牌的 JSON Web 签名。
1. 为令牌选择签名**算法**。这是用于保护 ID 令牌的加密算法。有关 RSA 的更多信息，请参阅 [RSA 密码术](https://tools.ietf.org/html/rfc3447)。
1. 通过输入 base64 URL 编码的密钥来指定**共享密钥**。您也可以选择**生成密钥**来为您生成密钥。您必须确保该密钥是 base64 URL 编码的密钥。
1. （*可选*）指定共享密钥何时有效。您可以指定密钥有效期的开始日期、截止日期，或同时指定两者。该密钥将在指定的时间间隔内有效。
1. 选择**保存密钥**以保存新密钥。
1. （*可选*）在**高级配置**下：
1. 指定要在 ACL 检查中使用的**用户名**。
1. 指定要在 ACL 检查中使用的一个或多个**组**。
1. 指定将验证颁发机构的**颁发机构**。
1. 指定**声明 ID**。您必须指定与 JWT 中的受众相匹配的正则表达式。
1. 在**配置详细信息**页面中，选择**开发者版本**。
1. 选择**创建**以创建索引。
1. 等待您的索引创建完成。 Amazon Kendra 为您的索引配置硬件。此操作可能需要一些时间。
------
#### [ CLI ]
您可以将 JWT 令牌与内部共享密钥一起使用。 AWS Secrets Manager该密钥必须是 base64 URL 编码的密钥。你需要 Secrets Manager ARN，而且你的 Amazon Kendra 角色必须有权访问该`GetSecretValue`资源。 Secrets Manager 如果您使用加密 Secrets Manager 资源 AWS KMS，则该角色还必须有权访问解密操作。
要使用 JSON 输入文件创建索引，请先 AWS CLI 使用所需参数创建一个 JSON 文件：
```
{
"Name": "user-context",
"Edition": "ENTERPRISE_EDITION",
"RoleArn": "arn:aws:iam::account-id:role:/my-role",
"UserTokenConfigurations": [
{
"JwtTokenTypeConfiguration": {
"KeyLocation": "SECRET_MANAGER",
"Issuer": "optional: specify the issuer url",
"ClaimRegex": "optional: regex to validate claims in the token",
"UserNameAttributeField": "optional: user",
"GroupAttributeField": "optional: group",
"SecretManagerArn": "arn:aws:secretsmanager:us-west-2:account id:secret:/my-user-context-secret
}
}
],
"UserContextPolicy": "USER_TOKEN"
}
```
您可以覆盖默认的用户和组字段名称。`UserNameAttributeField` 的默认值为“user”。`GroupAttributeField` 的默认值为“groups”。
接下来，使用输入文件调用 `create-index`。例如，如果您的 JSON 文件名为 `create-index-openid.json`，则可以使用以下名称：
```
aws kendra create-index --cli-input-json file://create-index-openid.json
```
密钥必须采用以下格式 AWS Secrets Manager：
```
{
"keys": [
{
"kid": "key_id",
"alg": "HS256|HS384|HS512",
"kty": "OCT",
"use": "sig", //this value can be sig only for now
"k": "secret",
"nbf":"ISO1806 date format"
"exp":"ISO1806 date format"
}
]
}
```
有关 JWT 的更多信息，请参阅 [jwt.io](http://jwt.io)。
------
#### [ Python ]
您可以将 JWT 令牌与内部共享密钥一起使用。 AWS Secrets Manager该密钥必须是 base64 URL 编码的密钥。你需要 Secrets Manager ARN，而且你的 Amazon Kendra 角色必须有权访问该`GetSecretValue`资源。 Secrets Manager 如果您使用加密 Secrets Manager 资源 AWS KMS，则该角色还必须有权访问解密操作。
```
response = kendra.create_index(
Name='user-context',
Edition='ENTERPRISE_EDITION',
RoleArn='arn:aws:iam::account-id:role:/my-role',
UserTokenConfigurations=[
{
"JwtTokenTypeConfiguration": {
"KeyLocation": "URL",
"Issuer": "optional: specify the issuer url",
"ClaimRegex": "optional: regex to validate claims in the token",
"UserNameAttributeField": "optional: user",
"GroupAttributeField": "optional: group",
"SecretManagerArn": "arn:aws:secretsmanager:us-west-2:account id:secret:/my-user-context-secret"
}
}
],
UserContextPolicy='USER_TOKEN'
)
```
------
# 使用带有公有密钥的 JSON Web 令牌（JWT）
以下示例说明在创建索引时如何使用带有公有密钥的 JSON Web Token（JWT）进行用户访问控制。有关 JWT 的更多信息，请参阅 [jwt.io](http://jwt.io)。
------
#### [ Console ]
1. 选择**创建索引**以开始创建新索引。
1. 在**指定索引详细信息**页面上，为您的索引指定名称和描述。
1. 对于 **IAM 角色**，选择一个角色或选择**创建新角色**，并指定角色名称来创建新角色。该 IAM 角色将带有前缀 “AmazonKendra-”。
1. 将所有其他字段保留为默认值。选择**下一步**。
1. 在**配置用户访问控制**页面上，在**访问控制设置**下，选择**是**以使用令牌进行访问控制。
1. 在**令牌配置**下，选择**带有公有密钥的 JWT** 作为**令牌类型**。
1. 在**用于签名公有密钥的参数**下，选择**密钥类型**。您可以使用现有的 AWS Secrets Manager 密钥或创建一个新密钥。
要创建新密钥，请选择**新建**，然后按照下列步骤操作：
1. 在 “**新 AWS Secrets Manager 密钥**” 下，指定**密钥名称**。保存公有密钥时，将添加前缀 `AmazonKendra-`。
1. 指定**键 ID**。键 ID 是一个提示，指示哪些键用于保护令牌的 JSON Web 签名。
1. 为令牌选择签名**算法**。这是用于保护 ID 令牌的加密算法。有关 RSA 的更多信息，请参阅 [RSA 密码术](https://tools.ietf.org/html/rfc3447)。
1. 在**证书属性**下，指定*可选*的**证书链**。证书链由证书列表组成。它以服务器的证书开头，以根证书结尾。
1. *可选* 指定**指纹**。它是证书的哈希值，可计算出所有证书数据及其签名。
1. 指定**指数**。这是 RSA 公有密钥的指数值。它以 base64URL UInt 编码的值表示。
1. 指定**模数**。这是 RSA 公有密钥的指数值。它以 base64URL UInt 编码的值表示。
1. 选择**保存密钥**以保存新密钥。
1. （*可选*）在**高级配置**下：
1. 指定要在 ACL 检查中使用的**用户名**。
1. 指定要在 ACL 检查中使用的一个或多个**组**。
1. 指定将验证颁发机构的**颁发机构**。
1. 指定**客户端 ID**。您必须指定与 JWT 中的受众相匹配的正则表达式。
1. 在**配置详细信息**页面中，选择**开发者版本**。
1. 选择**创建**以创建索引。
1. 等待您的索引创建完成。 Amazon Kendra 为您的索引配置硬件。此操作可能需要一些时间。
------
#### [ CLI ]
您可以将 JWT 与 AWS Secrets Manager内部的公有密钥一起使用。你需要 Secrets Manager ARN，而且你的 Amazon Kendra 角色必须有权访问该`GetSecretValue`资源。 Secrets Manager 如果您使用加密 Secrets Manager 资源 AWS KMS，则该角色还必须有权访问解密操作。
要使用 JSON 输入文件创建索引，请先 AWS CLI 使用所需参数创建一个 JSON 文件：
```
{
"Name": "user-context",
"Edition": "ENTERPRISE_EDITION",
"RoleArn": "arn:aws:iam::account id:role:/my-role",
"UserTokenConfigurationList": [
{
"JwtTokenTypeConfiguration": {
"KeyLocation": "SECRET_MANAGER",
"Issuer": "optional: specify the issuer url",
"ClaimRegex": "optional: regex to validate claims in the token",
"UserNameAttributeField": "optional: user",
"GroupAttributeField": "optional: group",
"SecretManagerArn": "arn:aws:secretsmanager:us-west-2:account id:secret:/my-user-context-secret
}
}
], "UserContextPolicy": "USER_TOKEN"
}
```
您可以覆盖默认的用户和组字段名称。`UserNameAttributeField` 的默认值为“user”。`GroupAttributeField` 的默认值为“groups”。
接下来，使用输入文件调用 `create-index`。例如，如果您的 JSON 文件名为 `create-index-openid.json`，则可以使用以下名称：
```
aws kendra create-index --cli-input-json file://create-index-openid.json
```
密钥必须采用以下格式 Secrets Manager：
```
{
"keys": [
{
"alg": "RS256|RS384|RS512",
"kty": "RSA", //this can be RSA only for now
"use": "sig", //this value can be sig only for now
"n": "modulus of standard pem",
"e": "exponent of standard pem",
"kid": "key_id",
"x5t": "certificate thumprint for x.509 cert",
"x5c": [
"certificate chain"
]
}
]
}
```
有关 JWT 的更多信息，请参阅 [jwt.io](http://jwt.io)。
------
#### [ Python ]
```
response = kendra.create_index(
Name='user-context',
Edition='ENTERPRISE_EDITION',
RoleArn='arn:aws:iam::account id:role:/my-role',
UserTokenConfigurationList=[
{
"JwtTokenTypeConfiguration": {
"KeyLocation": "URL",
"Issuer": "optional: specify the issuer url",
"ClaimRegex": "optional: regex to validate claims in the token",
"UserNameAttributeField": "optional: user",
"GroupAttributeField": "optional: group",
"SecretManagerArn": "arn:aws:secretsmanager:us-west-2:account id:secret:/my-user-context-secret"
}
}
],
UserContextPolicy='USER_TOKEN'
)
```
------
# 使用 JSON
以下示例说明在创建索引时如何使用 JSON 进行用户访问控制。
**警告**
JSON 令牌是未经验证的有效负载。只有当对 Amazon Kendra 的请求来自可信服务器而不是浏览器时，才应使用此选项。
------
#### [ Console ]
1. 选择**创建索引**以开始创建新索引。
1. 在**指定索引详细信息**页面上，为您的索引指定名称和描述。
1. 对于 **IAM 角色**，选择一个角色或选择**创建新角色**，并指定角色名称来创建新角色。IAM 角色的前缀为“AmazonKendra-”。
1. 将所有其他字段保留为默认值。选择**下一步**。
1. 在**配置用户访问控制**页面上，在**访问控制设置**下，选择**是**以使用令牌进行访问控制。
1. 在**令牌配置**下，选择 **JSON** 作为**令牌类型**。
1. 指定要在 ACL 检查中使用的**用户名**。
1. 指定要在 ACL 检查中使用的一个或多个**组**。
1. 选择**下一步**。
1. 在**配置详细信息**页面中，选择**开发者版本**。
1. 选择**创建**以创建索引。
1. 等待索引创建完成。Amazon Kendra 会为索引预配硬件。此操作可能需要一些时间。
------
#### [ CLI ]
要使用 JSON 输入文件通过 AWS CLI 创建索引，请先使用所需参数创建一个 JSON 文件：
```
{
"Name": "user-context",
"Edition": "ENTERPRISE_EDITION",
"RoleArn": "arn:aws:iam::account-id:role:/my-role",
"UserTokenConfigurations": [
{
"JsonTokenTypeConfiguration": {
"UserNameAttributeField": "user",
"GroupAttributeField": "group"
}
}
],
"UserContextPolicy": "USER_TOKEN"
}
```
接下来，使用输入文件调用 `create-index`。例如，如果您的 JSON 文件名为 `create-index-openid.json`，则可以使用以下名称：
```
aws kendra create-index --cli-input-json file://create-index-openid.json
```
如果您未使用适用于 AWS IAM Identity Center 的 Open ID，则可以将 JSON 格式的令牌发送给我们。如果这样做，则必须指定 JSON 令牌中的哪个字段包含用户名，哪个字段包含组。组字段值必须是 JSON 字符串数组。例如，如果您使用 SAML，您的令牌可能类似于以下内容：
```
{
"username" : "user1",
"groups": [
"group1",
"group2"
]
}
```
`TokenConfiguration` 指定用户名和组字段名称：
```
{
"UserNameAttributeField":"username",
"GroupAttributeField":"groups"
}
```
------
#### [ Python ]
```
response = kendra.create_index(
Name='user-context',
Edition='ENTERPRISE_EDITION',
RoleArn='arn:aws:iam::account-id:role:/my-role',
UserTokenConfigurations=[
{
"JwtTokenTypeConfiguration": {
"UserNameAttributeField": "user",
"GroupAttributeField": "group",
}
}
],
UserContextPolicy='USER_TOKEN'
)
```
------