有關綱要對應的注意事項映射 ID 令牌映射訪問令牌 Amazon Cognito 冒號分隔聲明的替代符號

在結構描述和原則中使用身分識別來源

您可能會發現要將身分識別來源新增至原則存放區，並將 Provider 宣告對應至您的原則存放區結構描述。您可以自動執行此程序或手動更新結構描述。使用者指南的這一節包含下列資訊：

何時可以自動將屬性填入策略存放區結構描述
如何在您的已驗證許可政策中使用 Amazon Cognito 和 OIDC 令牌聲明
如何手動建置身分識別來源的結構描述

透過引導式設定具有身分識別來源的 API 連結原則存放區和原則存放區不需要將身分識別 (ID) Token 屬性手動對應至結構描述。您可以為使用者集區或 OIDC Token 中的屬性提供「已驗證的權限」，並建立填入使用者屬性的結構描述。在 ID 令牌授權中，已驗證的權限將聲明映射到主體實體的屬性。在下列情況下，您可能需要手動將 Amazon Cognito 權杖對應至結構描述：

您已從範例建立空白原則存放區或原則存放區。
您希望將訪問令牌的使用擴展到基於角色的訪問控制（RBAC）之外。
您可以使用已驗證的權限 REST API、 AWS SDK 或 AWS CDK.

若要使用 Amazon Cognito 或 OIDC 身分識別提供者 (IdP) 做為已驗證許可政策存放區中的身分來源，您的結構描述中必須具有提供者屬性。如果您建立原則存放區的方式會從 ID Token 中的提供者資訊自動填入結構描述，您就可以編寫政策了。如果您建立沒有身分識別來源結構描述的原則存放區，則必須將 Provider 屬性新增至結構描述。您的模式必須對應於提供程序令牌創建的實體IsAuthorizedWithToken或BatchIsAuthorizedWith令牌 API 請求。然後，您可以使用提供者 Token 中的屬性來撰寫政策。

如需有關針對已驗證的使用者使用 Amazon Cognito ID 和存取權杖的詳細資訊，請參閱 Amazon Cognito 開發人員指南中的使用 Amazon 驗證許可授權。

有關綱要對應的注意事項

標記類型之間的屬性對應不同

在訪問令牌授權中，已驗證的權限將聲明映射到上下文。在 ID 令牌授權中，已驗證的權限將聲明映射到主要屬性。對於您在 [已驗證權限] 主控台中建立的原則存放區，只有空白和範例原則存放區會讓您沒有身分識別來源，並要求您在結構描述中填入 ID Token 授權的使用者集區屬性。存取權杖授權是以具有群組成員資格宣告的角色型存取控制 (RBAC) 為基礎，且不會自動將其他宣告對應至原則儲存架構。

不需要身份識別來源屬性

當您在 [已驗證的權限] 主控台中建立身分識別來源時，不會將任何屬性標記為必要。這樣可以防止缺少聲明導致授權請求中的驗證錯誤。您可以視需要將屬性設定為必要，但所有授權要求中都必須出現這些屬性。

RBAC 不需要架構中的屬性

身分識別來源的結構描述取決於您在新增身分識別來源時所建立的實體關聯。身分識別來源會將一個宣告對應至使用者實體類型，並將一個宣告對應至群組實體類型。這些實體對應是身分識別來源組態的核心。有了這項最低限度資訊，您就可以撰寫原則，在角色型存取控制 (RBAC) 模型中，針對使用者可能是其成員的特定使用者和特定群組執行授權動作。將 Token 聲明添加到模式中擴展了策略存儲區的授權範圍。來自 ID 令牌的用戶屬性具有有關可以促進基於屬性的訪問控制（ABAC）授權的用戶的信息。來自訪問令牌的上下文屬性具有諸如 OAuth 2.0 範圍之類的信息，這些信息可以提供來自提供程序的其他訪問控制信息，但需要進行其他模式

[已驗證權限] 主控台中的 [使用 API Gateway 和身分識別來源設定] 以及 [引導式設定] 選項會將 ID Token 宣告指派給結構描述。訪問令牌聲明並非如此。若要將非群組存取權杖宣告新增至結構描述，您必須在 JSON 模式下編輯結構定義，並新增 CommonType 屬性。如需詳細資訊，請參閱映射訪問令牌。

OIDC 群組聲明支援多種格式

新增 OIDC 提供者時，您可以選擇要對應至原則存放區中使用者群組成員資格的 ID 或存取權杖中的群組宣告名稱。已驗證的權限可識別以下列格式的群組宣告：

字符串不帶空格："groups": "MyGroup"
以空格分隔的清單："groups": "MyGroup1 MyGroup2 MyGroup3"。每個字串都是一個群組。
JSON (逗號分隔) 清單："groups": ["MyGroup1", "MyGroup2", "MyGroup3"]

注意

驗證權限將空格分隔的組聲明中的每個字符串解釋為一個單獨的組。若要將具有空格字元的群組名稱解譯為單一群組，請取代或移除宣告中的空格。例如，格式化名My Group為的群組MyGroup。

選擇權杖類型

您的政策存放區與身分識別來源搭配使用的方式取決於身分識別來源組態中的一項重要決定：您是要處理 ID 還是存取權杖。使用 Amazon Cognito 身分識別供應商時，您可以在建立 API 連結政策存放區時選擇權杖類型。當您建立 API 連結的原則存放區時，您必須選擇是否要設定 ID 或存取權杖的授權。此資訊會影響已驗證權限套用至原則存放區的結構描述屬性，以及 API Gateway API 的 Lambda 授權器語法。使用 OIDC 提供者時，您必須在新增身分識別來源時選擇權杖類型。您可以選擇 ID 或存取權杖，而您的選擇將未選擇的權杖類型排除在您的政策存放區中處理。特別是如果您希望從「已驗證權限」控制台中的 ID 令牌聲明自動映射到屬性中受益，請在創建身份源之前儘早決定要處理的令牌類型。變更 Token 類型需要大量的努力來重構您的政策和結構描述。下列主題說明 ID 和存取權杖搭配原則存放區的使用方式。

Cedar 解析器需要一些字符的括號

策略通常會以類似的格式引用結構描述屬性principal.username。在大多數非字母數字字符（例如 :.，或/）可能出現在令牌聲明名稱中的情況下，「已驗證權限」無法解析principal.cognito:groups或context.ip-address之類的條件值。您必須改為使用格式或格式的括號標記法來格principal["cognito:username"]式context["ip-address"]化這些條件。底線字元_是宣告名稱中的有效字元，也是此需求的唯一非英數字元例外。

此類型主體屬性的部分範例結構描述如下所示：


"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"
      ]
   }
}

將根據此結構描述驗證之屬性的範例原則如下所示：


permit (
    principal in MyCorp::UserGroup::"us-west-2_EXAMPLE|MyUserGroup",
    action,
    resource
) when {
    principal["cognito:username"] == "alice" &&
    principal["custom:employmentStoreCode"] == "petstore-dallas" &&
    principal has email && principal.email == "alice@example.com" &&
    context["ip-address"] like "192.0.2.*"
};

將 ID 令牌映射到模式

驗證權限處理 ID 令牌聲明作為用戶的屬性：他們的姓名和標題，他們的組成員資格，他們的聯繫信息。ID 令牌在基於屬性的訪問控制（ABAC）授權模型中最有用。當您希望「已驗證權限」根據提出請求的人員分析資源存取時，請為身分識別來源選擇 ID Token。

Amazon Cognito ID 令牌

Amazon Cognito ID 令牌適用於大多數 OIDC 重新派對程式庫。他們通過其他索賠擴展了 OIDC 的功能。您的應用程式可以透過 Amazon Cognito 使用者集區身份驗證 API 操作或使用者集區託管的 UI 來驗證使用者。如需詳細資訊，請參閱 Amazon Cognito 開發人員指南中的使用 API 和端點。

Amazon Cognito ID 令牌中有用的聲明

cognito:username 和 preferred_username: 使用者使用者名稱的變體。
sub: 使用者的唯一使用者識別碼 (UUID)
具有custom:前綴的索賠: 自定義用戶池屬性的前綴，例如custom:employmentStoreCode。
標準索償: 標準 OIDC 聲明類似email和。phone_number有關更多信息，請參閱 OpenID Connect 核心 1.0 中的標準聲明，其中包含勘誤集 2。
cognito:groups: 使用者的群組成員資格。在以角色為基礎的存取控制 (RBAC) 為基礎的授權模型中，此宣告會呈現您可以在原則中評估的角色。
短暫索賠: 聲明不是用戶的屬性，但在運行時由用戶池前令牌生成 Lambda 觸發器添加。暫時性聲明類似於標準聲明，但不在標準範圍內，例如tenant或department。

在參考具有:分隔符號之 Amazon Cognito 屬性的政策中，請以格式principal["cognito:username"]參考屬性。角色宣告cognito:groups是此規則的例外狀況。已驗證的權限會將此宣告的內容對應至使用者實體的父項實體。

如需 Amazon Cognito 使用者集區 ID 權杖結構的詳細資訊，請參閱 Amazon Cognito 開發人員指南中的使用 ID 權杖。

以下示例 ID 令牌具有四種屬性類型中的每一種。其中包括 Amazon Cognito 專屬聲明cognito:username、自訂宣告custom:employmentStoreCode、標準聲明和暫時性索賠email。tenant


{
    "sub": "91eb4550-XXX",
    "cognito:groups": [
        "Store-Owner-Role",
        "Customer"
    ],
    "email_verified": true,
    "clearance": "confidential",
    "iss": "https://cognito-idp.us-east-2.amazonaws.com/us-east-2_EXAMPLE",
    "cognito:username": "alice",
    "custom:employmentStoreCode": "petstore-dallas",
    "origin_jti": "5b9f50a3-05da-454a-8b99-b79c2349de77",
    "aud": "1example23456789",
    "event_id": "0ed5ad5c-7182-4ecf-XXX",
    "token_use": "id",
    "auth_time": 1687885407,
    "department": "engineering",
    "exp": 1687889006,
    "iat": 1687885407,
    "tenant": "x11app-tenant-1",
    "jti": "a1b2c3d4-e5f6-a1b2-c3d4-TOKEN1111111",
    "email": "alice@example.com"
}

使用 Amazon Cognito 使用者集區建立身分識別來源時，您可以指定在授權請求中產生的已驗證許可的主體實體類型。IsAuthorizedWithToken然後，您的原則可以測試該主體的屬性，作為評估該請求的一部分。您的結構描述會定義身分識別來源的主體類型和屬性，然後您可以在 Cedar 原則中參照這些屬性。

您也可以指定要從 ID 權杖群組宣告衍生的群組實體類型。在授權要求中，已驗證的權限會將群組宣告的每個成員對應至該群組實體類型。在原則中，您可以將該群組實體參照為主參與者。

下列範例顯示如何反映 [已驗證權限] 結構描述中範例識別 Token 的屬性。如需編輯資料架構的更多資訊，請參閱〈〉在 JSON 模式下編輯結構定義。如果您的身分識別來源組態指定了主參與者類型User，則您可以包含類似下列範例的項目，讓 Cedar 可以使用這些屬性。


"User": {
   "shape": {
      "type": "Record",
      "attributes": {
         "cognito:username": {
            "type": "String",
            "required": false
         },
         "custom:employmentStoreCode": {
            "type": "String",
            "required": false
         },
         "email": {
            "type": "String"
         },
         "tenant": {
            "type": "String",
            "required": true
         }
      }
   }
}

更新結構描述以反映 Amazon Cognito 屬性後，您可以建立參考這些屬性的政策。


permit (
    principal in MyCorp::UserGroup::"us-west-2_EXAMPLE|MyUserGroup",
    action,
    resource
) when {
    principal["cognito:username"] == "alice" &&
    principal["custom:employmentStoreCode"] == "petstore-dallas" &&
    principal.tenant == "x11app-tenant-1" &&
    principal has email && principal.email == "alice@example.com"
};

OIDC 識別碼權杖

使用來自 OIDC 提供者的 ID 權杖與使用 Amazon Cognito ID 權杖大致相同。不同之處在於索賠。您的 IdP 可能會呈現標準 OIDC 屬性，或具有自訂結構描述。當您在 [已驗證權限] 主控台中建立新的原則存放區時，您可以使用範例 ID Token 新增 OIDC 身分識別來源，或者您可以手動將權杖宣告對應至使用者屬性。由於已驗證的權限不知道 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 提供者中的群組成員。


permit (
    principal in MyCorp::UserGroup::"MyOIDCProvider|MyUserGroup",
    action,
    resource
) when {
    principal.email_verified == true && principal.email == "alice@example.com" &&
    principal.phone_number_verified == true && principal.phone_number like "+1206*"
};

映射訪問令牌

已驗證的權限處理除了組聲明作為動作的屬性或上下文屬性以外的訪問令牌聲明。除了群組成員資格外，IdP 中的存取權杖可能包含有關 API 存取的資訊。在使用基於角色的訪問控制（RBAC）的授權模型中，訪問令牌非常有用。依賴群組成員資格以外的存取權杖宣告的授權模型需要額外的工作架構組態。

映射 Amazon Cognito 問令牌

Amazon Cognito 訪問令牌具有可用於授權的聲明：

Amazon Cognito 訪問令牌中的有用聲明

client_id: OIDC 信賴方的用戶端應用程式識別碼。使用用戶端 ID，「已驗證的權限」可以驗證授權要求來自原則存放區的允許用戶端。在 machine-to-machine （M2M）授權中，請求系統使用客戶端密鑰授權請求，並提供客戶端 ID 和範圍作為授權證據。
scope: OAuth 2.0 範圍，表示令牌承載者的訪問權限。
cognito:groups: 使用者的群組成員資格。在以角色為基礎的存取控制 (RBAC) 為基礎的授權模型中，此宣告會呈現您可以在原則中評估的角色。
短暫索賠: 不是存取權限，但是由使用者集區前憑證產生 Lambda 觸發程序在執行階段新增的宣告。暫時性聲明類似於標準聲明，但不在標準範圍內，例如tenant或department。訪問令牌的自定義會為您的 AWS 賬單增加成本。

如需有關 Amazon Cognito 使用者集區存取權杖結構的詳細資訊，請參閱 Amazon Cognito 開發人員指南中的使用存取權杖。

傳遞至已驗證許可時，Amazon Cognito 存取權杖會對應至內容物件。訪問令牌的屬性可以使用引用context.token.attribute_name。以下示例訪問令牌包括client_id和scope聲明。


{
    "sub": "91eb4550-9091-708c-a7a6-9758ef8b6b1e",
    "cognito:groups": [
        "Store-Owner-Role",
        "Customer"
    ],
    "iss": "https://cognito-idp.us-east-2.amazonaws.com/us-east-2_EXAMPLE",
    "client_id": "1example23456789",
    "origin_jti": "a1b2c3d4-e5f6-a1b2-c3d4-TOKEN1111111",
    "event_id": "bda909cb-3e29-4bb8-83e3-ce6808f49011",
    "token_use": "access",
    "scope": "MyAPI/mydata.write",
    "auth_time": 1688092966,
    "exp": 1688096566,
    "iat": 1688092966,
    "jti": "a1b2c3d4-e5f6-a1b2-c3d4-TOKEN2222222",
    "username": "alice"
}

下列範例顯示如何反映 [已驗證權限] 結構描述中範例存取權杖的屬性。如需編輯資料架構的更多資訊，請參閱〈〉在 JSON 模式下編輯結構定義。


{
   "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"
         }
      }
   }
}

更新結構描述以反映 Amazon Cognito 屬性後，您可以建立參考這些屬性的政策。


permit(principal, action in [MyApplication::Action::"Read", MyApplication::Action::"GetStoreInventory"], resource)
when { 
    context.token.client_id == "52n97d5afhfiu1c4di1k5m8f60" &&
    context.token.scope.contains("MyAPI/mydata.write")
};

映射 OIDC 訪問令牌

來自外部 OIDC 提供者的大多數存取權杖都與 Amazon Cognito 存取權杖密切一致。傳遞至已驗證權限時，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"
}

下列範例顯示如何反映 [已驗證權限] 結構描述中範例存取權杖的屬性。如需編輯資料架構的更多資訊，請參閱〈〉在 JSON 模式下編輯結構定義。


{
   "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"
         }
      }
   }
}

更新結構描述以反映 IdP 屬性之後，您可以建立參照屬性的策略。


permit(
    principal, 
    action in [MyApplication::Action::"Read", MyApplication::Action::"GetStoreInventory"],
    resource
)
when { 
    context.token.client_id == "52n97d5afhfiu1c4di1k5m8f60" &&
    context.token.scope.contains("MyAPI-read")
};

Amazon Cognito 冒號分隔聲明的替代符號

啟動驗證許可時，Amazon Cognito 權杖的建議結構描述會宣告cognito:groups並custom:store轉換這些冒號分隔字串，以使用該字.元作為階層分隔符號。這種格式稱為點符號。例如，您的政策principal.cognito.groups中cognito:groups已成為對的引用。雖然您可以繼續使用此格式，但我們建議您使用括號標記來建置結構描述和原則。在這種格式中，您的政策principal["cognito:groups"]中將cognito:groups成為的引用。從「已驗證的權限」主控台為使用者集區 ID 權杖自動產生的結構描述使用括號標記法。

您可以在手動建立的結構描述和 Amazon Cognito 身分識別來源的政策中繼續使用點符號。對於任何其他類型的 OIDC IdP，您不能在綱要或原則中使用點符號或任何其他非英數字元。:

點符號的結構描述會將:字元的每個執行個體嵌套成cognito或custom初始片語的子項，如下列範例所示：


"CognitoUser": {
   "shape": {
      "type": "Record",
      "attributes": {
         "cognito": {
            "type": "Record",
            "required": true,
            "attributes": {
               "username": {
                  "type": "String",
                  "required": true
               }
            }
         },
         "custom": {
            "type": "Record",
            "required": true,
            "attributes": {
               "employmentStoreCode": {
                  "type": "String",
                  "required": true
               }
            }
         },
         "email": {
            "type": "String"
         },
         "tenant": {
            "type": "String",
            "required": true
         }
      }
   }
}

使用此格式的結構描述，您可以建立具有點標記法的原則，如下列範例所示：


permit(principal, action, resource)
when {
    principal.cognito.username == "alice" &&
    principal.custom.employmentStoreCode == "petstore-dallas" &&
    principal.tenant == "x11app-tenant-1" &&
    principal has email && principal.email == "alice@example.com"
};

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

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

文件慣用形式

編輯識別來源

設計授權模型