將 OIDC 權杖映射至結構描述

您可能會發現想要將身分來源新增至政策存放區，並將提供者宣告或字符映射到您的政策存放區結構描述。您可以使用引導式設定來建立具有身分來源的政策存放區，或在建立政策存放區之後手動更新結構描述，以自動化此程序。將權杖映射到結構描述後，您可以建立參考權杖的政策。

使用者指南的本節包含下列資訊：

何時可以自動將屬性填入政策存放區結構描述
如何手動建置身分來源的結構描述

透過引導式設定建立的具有身分來源的 API 連結政策存放區和政策存放區，不需要手動將身分 (ID) 字符屬性映射至結構描述。您可以為 Verified Permissions 提供使用者集區中的屬性，並建立填入使用者屬性的結構描述。在 ID 字符授權中，Verified Permissions 會將宣告對應至委託人實體的屬性。

若要在 Verified Permissions 政策存放區中使用 OIDC 身分提供者 (IdP) 做為身分來源，您必須在結構描述中具有提供者屬性。結構描述是固定的，且必須與提供者權杖在 IsAuthorizedWithToken 或 BatchIsAuthorizedWithToken API 請求中建立的實體對應。如果您以從 ID 字符中的提供者資訊自動填入結構描述的方式建立政策存放區，您就可以撰寫政策。如果您建立的政策存放區沒有身分來源的結構描述，則必須將提供者屬性新增至與使用 API 請求建立的實體相符的結構描述。然後，您可以使用提供者字符中的屬性來撰寫政策。

將 ID 字符映射至結構描述

Verified Permissions 會將 ID 字符宣告視為使用者的屬性：其名稱和標題、群組成員資格、其聯絡資訊。ID 字符在屬性型存取控制 (ABAC) 授權模型中最有用。當您希望 Verified Permissions 根據提出請求的人員分析對資源的存取時，請選擇身分來源的 ID 字符。

從 OIDC 供應商使用 ID 字符與使用 Amazon Cognito ID 字符大致相同。差別在於宣告。您的 IdP 可能會顯示標準 OIDC 屬性，或具有自訂結構描述。在 Verified Permissions 主控台中建立新的政策存放區時，您可以使用範例 ID 字符新增 OIDC 身分來源，也可以手動將字符宣告對應至使用者屬性。由於 Verified Permissions 不知道 IdP 的屬性結構描述，因此您必須提供此資訊。

如需詳細資訊，請參閱建立已驗證許可政策存放區。

以下是具有 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 字符屬性。

映射存取權杖

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 結構描述中存取字符範例的屬性。如需編輯結構描述的詳細資訊，請參閱編輯政策存放區結構描述。


{
   "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 存取權杖屬性。

結構描述映射的須知事項

屬性映射在字符類型之間有所不同

在存取權杖授權中，已驗證許可會將宣告對應至內容。在 ID 字符授權中，已驗證許可會將宣告對應至主體屬性。對於您在 Verified Permissions 主控台中建立的政策存放區，只有空白和範例政策存放區會讓您沒有身分來源，並要求您將 ID 字符授權的使用者集區屬性填入您的結構描述。存取權杖授權是以具有群組成員宣告的角色型存取控制 (RBAC) 為基礎，不會自動將其他宣告映射至政策存放區結構描述。

不需要身分來源屬性

當您在 Verified Permissions 主控台中建立身分來源時，不會將任何屬性標記為必要。這可防止遺失宣告導致授權請求中的驗證錯誤。您可以視需要將屬性設定為必要，但這些屬性必須存在於所有授權請求中。

RBAC 不需要結構描述中的屬性

身分來源的結構描述取決於您在新增身分來源時建立的實體關聯。身分來源會將一個宣告對應至使用者實體類型，並將一個宣告對應至群組實體類型。這些實體映射是身分來源組態的核心。透過此最低資訊，您可以在角色型存取控制 (RBAC) 模型中撰寫政策，為使用者可能所屬的特定使用者和特定群組執行授權動作。在結構描述中新增權杖宣告可延長政策存放區的授權範圍。來自 ID 字符的使用者屬性具有有關使用者的資訊，這些使用者可以提供屬性型存取控制 (ABAC) 授權。存取字符的內容屬性具有 OAuth 2.0 範圍等資訊，可以提供來自提供者的其他存取控制資訊，但需要額外的結構描述修改。

Verified Permissions 主控台中的使用 API Gateway 和身分提供者設定和引導設定選項會將 ID 字符宣告指派給結構描述。存取字符宣告的情況並非如此。若要將非群組存取字符宣告新增至結構描述，您必須在 JSON 模式中編輯結構描述，並新增 commonTypes 屬性。如需詳細資訊，請參閱映射存取權杖。

OIDC 群組宣告支援多種格式

當您新增 OIDC 提供者時，您可以選擇 ID 中的群組宣告名稱，或您要映射到政策存放區中使用者群組成員資格的存取權杖。已驗證許可會以下列格式辨識群組宣告：

不含空格的字串： "groups": "MyGroup"
以空格分隔的清單："groups": "MyGroup1 MyGroup2 MyGroup3"。每個字串都是一個群組。
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"
      ]
   }
}

如需將對此結構描述進行驗證的範例政策，請參閱使用括號表示法來參考字符屬性。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

編輯身分來源

用戶端和對象驗證