本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 將 OIDC 權杖映射至結構描述
您可能會發現想要將身分來源新增至政策存放區，並將提供者宣告或權杖映射到您的政策存放區結構描述。您可以使用[引導式設定](policy-stores-create.md)來建立具有身分來源的政策存放區，或在建立政策存放區後手動更新結構描述，以自動化此程序。將權杖映射到結構描述後，您可以建立參考權杖的政策。
使用者指南的本節包含下列資訊：
+ 何時可以自動將屬性填入政策存放區結構描述
+ 如何手動建置身分來源的結構描述
透過[引導式設定](policy-stores-create.md)建立的具有身分來源的 [API 連結政策存放區](policy-stores-api-userpool.md)和政策存放區，不需要手動將身分 (ID) 字符屬性映射至結構描述。您可以為 Verified Permissions 提供使用者集區中的屬性，並建立填入使用者屬性的結構描述。在 ID 字符授權中，已驗證許可會將宣告對應至委託人實體的屬性。
若要在 Verified Permissions 政策存放區中使用 OIDC 身分提供者 (IdP) 做為身分來源，您必須在結構描述中具有提供者屬性。結構描述是固定的，且必須與提供者權杖在 [IsAuthorizedWithToken](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_IsAuthorizedWithToken.html) 或 [BatchIsAuthorizedWithToken](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_BatchIsAuthorizedWithToken.html) API 請求中建立的實體對應。如果您以從 ID 字符中的提供者資訊自動填入結構描述的方式建立政策存放區，您就可以撰寫政策。如果您建立的政策存放區沒有身分來源的結構描述，則必須將提供者屬性新增至與使用 API 請求建立的實體相符的結構描述。然後，您可以使用提供者字符中的屬性來撰寫政策。
**Topics**
+ [將 ID 字符映射至結構描述](#oidc-map-id-token)
+ [映射存取權杖](#oidc-map-access-token)
+ [結構描述映射的須知事項](#oidc-map-token-to-schema-things-to-know)
## 將 ID 字符映射至結構描述
Verified Permissions 會將 ID 字符宣告視為使用者的屬性：其名稱和標題、群組成員資格、其聯絡資訊。ID 字符在*屬性型存取控制* (ABAC) 授權模型中最有用。當您希望 Verified Permissions 根據提出請求的人員分析對資源的存取時，請選擇身分來源的 ID 字符。
從 OIDC 供應商使用 ID 字符與使用 Amazon Cognito ID 字符大致相同。差異在於宣告。您的 IdP 可能會顯示[標準 OIDC 屬性](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims)，或具有自訂結構描述。在 Verified Permissions 主控台中建立新的政策存放區時，您可以使用範例 ID 字符新增 OIDC 身分來源，也可以手動將字符宣告對應至使用者屬性。由於 Verified Permissions 不知道 IdP 的屬性結構描述，因此您必須提供此資訊。
如需詳細資訊，請參閱[建立已驗證許可政策存放區](policy-stores-create.md)。
以下是具有 OIDC 身分來源之政策存放區的範例結構描述。
```
"User": {
"shape": {
"type": "Record",
"attributes": {
"email": {
"type": "String"
},
"email_verified": {
"type": "Boolean"
},
"name": {
"type": "String",
"required": true
},
"phone_number": {
"type": "String"
},
"phone_number_verified": {
"type": "Boolean"
}
}
}
}
```
如需將對此結構描述進行驗證的範例政策，請參閱 [反映 OIDC ID 字符屬性](policies-examples.md#policies-examples-oidc-id)。
## 映射存取權杖
Verified Permissions 會處理存取金鑰宣告，而不是群組宣告為 動作的屬性或*內容屬性*。除了群組成員資格之外，來自 IdP 的存取權杖可能包含 API 存取的相關資訊。存取權杖適用於使用角色型存取控制 (RBAC) 的授權模型。依賴群組成員資格以外的存取字符宣告的授權模型需要額外的結構描述組態工作。
來自外部 OIDC 提供者的大多數存取字符都與 Amazon Cognito 存取字符緊密一致。當傳遞至 Verified Permissions 時，OIDC 存取權杖會映射至內容物件。您可以使用 參考存取字符的屬性`context.token.attribute_name`。下列範例 OIDC 存取權杖包含範例基本宣告。
```
{
"sub": "91eb4550-9091-708c-a7a6-9758ef8b6b1e",
"groups": [
"Store-Owner-Role",
"Customer"
],
"iss": "https://auth.example.com",
"client_id": "1example23456789",
"aud": "https://myapplication.example.com"
"scope": "MyAPI-Read",
"exp": 1688096566,
"iat": 1688092966,
"jti": "a1b2c3d4-e5f6-a1b2-c3d4-TOKEN2222222",
"username": "alice"
}
```
下列範例顯示如何反映 Verified Permissions 結構描述中存取字符範例的屬性。如需編輯結構描述的詳細資訊，請參閱 [編輯政策存放區結構描述](schema-edit.md)。
```
{
"MyApplication": {
"actions": {
"Read": {
"appliesTo": {
"context": {
"type": "ReusedContext"
},
"resourceTypes": [
"Application"
],
"principalTypes": [
"User"
]
}
}
},
...
...
"commonTypes": {
"ReusedContext": {
"attributes": {
"token": {
"type": "Record",
"attributes": {
"scope": {
"type": "Set",
"element": {
"type": "String"
}
},
"client_id": {
"type": "String"
}
}
}
},
"type": "Record"
}
}
}
}
```
如需將對此結構描述進行驗證的範例政策，請參閱 [反映 OIDC 存取權杖屬性](policies-examples.md#policies-examples-oidc-access)。
## 結構描述映射的須知事項
**屬性映射在字符類型之間有所不同**
在存取權杖授權中，已驗證許可會將宣告對應至[內容](context.md)。在 ID 字符授權中，已驗證許可會將宣告對應至主體屬性。對於您在 Verified Permissions 主控台中建立的政策存放區，只有**空白**和**範例**政策存放區會讓您沒有身分來源，並要求您將 ID 字符授權的使用者集區屬性填入您的結構描述。存取權杖授權是以具有群組成員宣告的角色型存取控制 (RBAC) 為基礎，不會自動將其他宣告映射至政策存放區結構描述。
**不需要身分來源屬性**
當您在 Verified Permissions 主控台中建立身分來源時，不會將任何屬性標記為必要。這可防止遺失宣告導致授權請求中的驗證錯誤。您可以視需要將屬性設定為必要，但這些屬性必須存在於所有授權請求中。
**RBAC 不需要結構描述中的屬性**
身分來源的結構描述取決於您在新增身分來源時建立的實體關聯。身分來源會將一個宣告映射至使用者實體類型，並將一個宣告映射至群組實體類型。這些實體映射是身分來源組態的核心。透過此最低資訊，您可以在角色型存取控制 (RBAC) 模型中撰寫政策，為使用者可能所屬的特定使用者和特定群組執行授權動作。在結構描述中新增權杖宣告可延長政策存放區的授權範圍。來自 ID 權杖的使用者屬性具有可促成屬性型存取控制 (ABAC) 授權的使用者相關資訊。存取字符的內容屬性具有 OAuth 2.0 範圍等資訊，可以提供來自提供者的其他存取控制資訊，但需要額外的結構描述修改。
Verified Permissions 主控台中的**使用 API Gateway 和身分提供者設定**和**引導設定**選項會將 ID 字符宣告指派給結構描述。存取字符宣告的情況並非如此。若要將非群組存取字符宣告新增至您的結構描述，您必須在 JSON 模式中編輯結構描述，並新增 [commonTypes](https://docs.cedarpolicy.com/schema/json-schema.html#schema-commonTypes) 屬性。如需詳細資訊，請參閱[映射存取權杖](#oidc-map-access-token)。
**OIDC 群組宣告支援多種格式**
當您新增 OIDC 提供者時，您可以在 ID 或存取權杖中選擇要映射到政策存放區中使用者群組成員資格的群組宣告名稱。驗證的許可會以下列格式辨識群組宣告：
1. 不含空格的字串： `"groups": "MyGroup"`
1. 以空格分隔的清單：`"groups": "MyGroup1 MyGroup2 MyGroup3"`。每個字串都是一個群組。
1. JSON （逗號分隔） 清單： `"groups": ["MyGroup1", "MyGroup2", "MyGroup3"]`
**注意**
Verified Permissions 會將空格分隔群組中的每個字串宣告解譯為個別群組。若要將具有空格字元的群組名稱解譯為單一群組，請取代或移除宣告中的空格。例如，格式化`My Group`名為 的群組`MyGroup`。
**選擇字符類型**
政策存放區與身分來源搭配使用的方式取決於身分來源組態中的金鑰決策：您是否將處理 ID 或存取權杖。使用 OIDC 供應商時，您必須在新增身分來源時選擇字符類型。您可以選擇 ID 或存取權杖，而且您選擇的權杖類型不會在政策存放區中處理。特別是如果您希望從 ID 字符宣告自動映射到 Verified Permissions 主控台中的屬性中受益，請在建立身分來源之前提早決定要處理的字符類型。變更字符類型需要大量精力來重構您的政策和結構描述。下列主題說明搭配政策存放區使用 ID 和存取權杖。
**Cedar 剖析器需要某些字元的括號**
政策通常會參考 等格式的結構描述屬性`principal.username`。如果大多數出現在字符宣告名稱`/`中的非英數字元，例如 `.`、 `:`或 ，Verified Permissions 無法剖析 `principal.cognito:username`或 等條件值`context.ip-address`。您必須改為使用括號表示法來格式化這些條件`context["ip-address"]`，格式分別為 `principal["cognito:username"]`或 。底線字元`_`是宣告名稱中的有效字元，也是此要求的唯一非英數字元例外狀況。
此類型主體屬性的部分範例結構描述如下所示：
```
"User": {
"shape": {
"type": "Record",
"attributes": {
"cognito:username": {
"type": "String",
"required": true
},
"custom:employmentStoreCode": {
"type": "String",
"required": true,
},
"email": {
"type": "String",
"required": false
}
}
}
}
```
此類型內容屬性的部分範例結構描述如下所示：
```
"GetOrder": {
"memberOf": [],
"appliesTo": {
"resourceTypes": [
"Order"
],
"context": {
"type": "Record",
"attributes": {
"ip-address": {
"required": false,
"type": "String"
}
}
},
"principalTypes": [
"User"
]
}
}
```
如需將對此結構描述進行驗證的範例政策，請參閱 [使用括號表示法來參考字符屬性](policies-examples.md#policies-examples-brackets)。