本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用字符控制使用者對文件的存取
**注意**
功能支援會因索引類型和正在使用的搜尋 API 而有所不同。若要查看您正在使用的索引類型和搜尋 API 是否支援此功能，請參閱[索引類型](https://docs.aws.amazon.com/kendra/latest/dg/hiw-index-types.html)。
**重要**
Amazon Kendra GenAI Enterprise Edition 索引不支援字符型使用者存取控制。
您可以控制哪些使用者或群組可以存取索引中的特定文件，或在搜尋結果中查看特定文件。這稱為使用者內容篩選。這是一種個人化搜尋，具有控制文件存取的優點。例如，並非所有搜尋公司入口網站資訊的團隊都應該存取最機密的公司文件，這些文件也與所有使用者無關。只有獲得最高機密文件存取權的特定使用者或團隊群組，才能在其搜尋結果中查看這些文件。
Amazon Kendra 企業和開發人員索引支援使用下列字符類型的字符型使用者存取控制：
+ 開啟 ID
+ 具有共用秘密的 JWT
+ 具有公有金鑰的 JWT
+ JSON
Amazon Kendra 可用於為您的擷取和搜尋應用程式提供安全的企業搜尋。在查詢和擷取期間， 會根據請求中`UserContext`提供的 `AttributeFilters` 和 Amazon Kendra 篩選搜尋結果。 會 Amazon Kendra 讀取其連接器在網路爬取和擷取期間收集的文件存取控制清單 (ACLs)。擷取和搜尋結果會傳回指向原始文件儲存庫加上簡短摘錄URLs。原始儲存庫仍會強制執行完整文件的存取。
**Topics**
+ [使用 OpenID](create-index-access-control-tokens-openid.md)
+ [將 JSON Web Token (JWT) 與共用秘密搭配使用](create-index-access-control-tokens-jwtshared.md)
+ [搭配公有金鑰使用 JSON Web Token (JWT)](create-index-access-control-tokens-jwtpublic.md)
+ [使用 JSON](create-index-access-control-tokens-json.md)
# 使用 OpenID
若要設定 Amazon Kendra 索引以使用 OpenID 字符進行存取控制，您需要 OpenID 供應商的 OpenID(JSON Web 金鑰集） URL。在大多數情況下，JWKS URL 的格式如下 （如果遵循 openId 探索）`https://domain-name/.well_known/jwks.json`。
下列範例示範如何在建立索引時使用 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 (s)**。您必須指定符合 JWT 中對象的規則表達式。
1. 在**佈建詳細資訊**頁面中，選擇**開發人員版本**。
1. 選擇**建立**以建立您的索引。
1. 等待您的索引建立。 Amazon Kendra 佈建索引的硬體。此操作可能需要一些時間。
------
#### [ CLI ]
若要 AWS CLI 使用 JSON 輸入檔案使用 建立索引，請先使用所需的參數建立 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`為「使用者」。的預設值`GroupAttributeField`為「群組」。
接著，`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 Token (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 (s)**。您必須指定符合 JWT 中對象的規則表達式。
1. 在**佈建詳細資訊**頁面中，選擇**開發人員版本**。
1. 選擇**建立**以建立您的索引。
1. 等待您的索引建立。為您的索引 Amazon Kendra 佈建硬體。此操作可能需要一些時間。
------
#### [ CLI ]
您可以在 中使用 JWT 字符搭配共用秘密 AWS Secrets Manager。秘密必須是 base64 URL 編碼的秘密。您需要 Secrets Manager ARN，而且您的 Amazon Kendra 角色必須能夠存取 Secrets Manager 資源`GetSecretValue`上的 。如果您使用 加密 Secrets Manager 資源 AWS KMS，該角色也必須具有解密動作的存取權。
若要 AWS CLI 使用 JSON 輸入檔案使用 建立索引，請先使用所需的參數建立 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`為「使用者」。的預設值`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 的詳細資訊，請參閱 https：//[jwt.io](http://jwt.io)。
------
#### [ Python ]
您可以在 中使用 JWT 字符搭配共用秘密 AWS Secrets Manager。秘密必須是 base64 URL 編碼的秘密。您需要 Secrets Manager ARN，而且您的 Amazon Kendra 角色必須能夠存取 Secrets Manager 資源`GetSecretValue`上的 。如果您使用 加密 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 Token (JWT)
下列範例示範如何在建立索引時將 JSON Web Token (JWT) 與公有金鑰搭配使用，以進行使用者存取控制。如需 JWT 的詳細資訊，請參閱 https：//[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 公有金鑰的指數值。它以 Base64urlUInt 編碼值表示。
1. 指定**模數**。這是 RSA 公有金鑰的指數值。它以 Base64urlUInt 編碼值表示。
1. 選取**儲存金鑰**以儲存新金鑰。
1. 在**進階組態**下*選用*：
1. 指定要在 ACL 檢查中使用的**使用者名稱**。
1. 指定要在 ACL 檢查中使用的一或多個**群組**。
1. 指定將驗證字符發行**者的發行**者。
1. 指定**用戶端 ID (s)**。您必須指定符合 JWT 中對象的規則表達式。
1. 在**佈建詳細資訊**頁面中，選擇**開發人員版本**。
1. 選擇**建立**以建立您的索引。
1. 等待您的索引建立。為您的索引 Amazon Kendra 佈建硬體。此操作可能需要一些時間。
------
#### [ CLI ]
您可以使用 JWT 搭配 內的公有金鑰 AWS Secrets Manager。您需要 Secrets Manager ARN，而且您的 Amazon Kendra 角色必須能夠存取 Secrets Manager 資源`GetSecretValue`上的 。如果您使用 加密 Secrets Manager 資源 AWS KMS，該角色也必須具有解密動作的存取權。
若要 AWS CLI 使用 JSON 輸入檔案使用 建立索引，請先使用所需的參數建立 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`為「使用者」。的預設值`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 的詳細資訊，請參閱 https：//[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 ]
若要 AWS CLI 使用 JSON 輸入檔案使用 建立索引，請先使用所需的參數建立 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
```
如果您不是針對 使用 Open ID AWS IAM Identity Center，則可以將 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'
)
```
------