翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# Amazon Cognito トークンをスキーマにマッピングする
ID ソースをポリシーストアに追加し、プロバイダークレーム、またはトークンをポリシーストアスキーマにマッピングする場合があります。このプロセスを自動化するには、[ガイド付きセットアップ](policy-stores-create.md)を使用して ID ソースでポリシーストアを作成するか、ポリシーストアの作成後にスキーマを手動で更新します。トークンをスキーマにマッピングしたら、それらを参照するポリシーを作成できます。
ユーザーガイドのこのセクションには、次の情報が含まれています。
+ ポリシーストアスキーマに属性を自動的に入力できる場合
+ Verified Permissions ポリシーで Amazon Cognito トークンクレームを使用する方法
+ ID ソースのスキーマを手動で構築する方法
[API リンクポリシーストア](policy-stores-api-userpool.md)と[ガイド付きセットアップ](policy-stores-create.md)で作成された ID ソースを持つポリシーストアでは、ID (ID) トークン属性をスキーマに手動でマッピングする必要はありません。Verified Permissions にユーザープールの属性を指定し、ユーザー属性が入力されたスキーマを作成できます。ID トークン認可では、Verified Permissions はクレームをプリンシパルエンティティの属性にマッピングします。次の条件で Amazon Cognito 、トークンをスキーマに手動でマッピングする必要がある場合があります。
+ サンプルから空のポリシーストアまたはポリシーストアを作成しました。
+ アクセストークンの使用をロールベースのアクセスコントロール (RBAC) を超えて拡張したい。
+ Verified Permissions REST API、 AWS SDK、または を使用してポリシーストアを作成します AWS CDK。
Verified Permissions ポリシーストアで ID ソース Amazon Cognito として を使用するには、スキーマにプロバイダー属性が必要です。スキーマは固定されており、プロバイダートークンが [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 トークンのプロバイダー情報からスキーマを自動的に入力する方法でポリシーストアを作成した場合は、ポリシーを作成する準備が整います。ID ソースのスキーマなしでポリシーストアを作成する場合は、API リクエストを使用して作成されたエンティティに一致するプロバイダー属性をスキーマに追加する必要があります。その後、プロバイダートークンの属性を使用してポリシーを記述できます。
Verified Permissions で認証されたユーザーに Amazon Cognito ID とアクセストークンを使用する方法の詳細については、「Amazon *Amazon Cognitoデベロッパーガイド*」の「Amazon [Verified Permissions による認可](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-authorization-with-avp.html)」を参照してください。
**Topics**
+ [ID トークンをスキーマにマッピングする](#cognito-map-id-token)
+ [アクセストークンをマッピングする](#cognito-map-access-token)
+ [Amazon Cognito コロン区切りクレームの代替表記](#cognito-colon-claims)
+ [スキーママッピングについて知っておくべきこと](#cognito-map-token-to-schema-things-to-know)
## ID トークンをスキーマにマッピングする
Verified Permissions は、ID トークンクレームをユーザーの名前とタイトル、グループメンバーシップ、連絡先情報などの属性として処理します。ID トークンは、*属性ベースのアクセスコントロール* (ABAC) 認可モデルで最も役立ちます。Verified Permissions でリクエストを行っているユーザーに基づいてリソースへのアクセスを分析する場合は、ID ソースの ID トークンを選択します。
Amazon Cognito ID トークンは、ほとんどの [OIDC 依存パーティライブラリで機能します](https://openid.net/developers/certified-openid-connect-implementations/)。追加のクレームで OIDC の機能を拡張します。アプリケーションは、Amazon Cognito ユーザープール認証 API オペレーション、またはユーザープールがホストする UI を使用してユーザーを認証できます。詳細については、「 *Amazon Cognito デベロッパーガイド*[」の「API とエンドポイント](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pools-API-operations.html)の使用」を参照してください。Amazon Cognito ID トークンでの便利なクレーム
*`cognito:username` および `preferred_username`*
ユーザーのユーザー名のバリエーション。
*`sub`*
ユーザーの一意のユーザー識別子 (UUID)
*`custom:` プレフィックスが付いたクレーム*
などのカスタムユーザープール属性のプレフィックス`custom:employmentStoreCode`。
*標準のクレーム*
`email` や などの標準 OIDC クレーム`phone_number`。詳細については、「エラーセット 2 を組み込んだ OpenID Connect Core 1.0 の[標準クレーム](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims)」を参照してください。 *OpenID *
*`cognito:groups`*
ユーザーのグループメンバーシップ。ロールベースのアクセスコントロール (RBAC) に基づく認可モデルでは、このクレームはポリシーで評価できるロールを示しています。
*一時的なクレーム*
ユーザーのプロパティではないが、実行時にユーザープールの[トークン生成前 Lambda トリガー](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-pre-token-generation.html)によって追加されるクレーム。一時的なクレームは標準クレームに似ていますが、 `tenant`や など、標準外です`department`。
`:` 区切り文字を持つ Amazon Cognito 属性を参照するポリシーでは、 形式の属性を参照します`principal["cognito:username"]`。ロールクレーム`cognito:groups`はこのルールの例外です。Verified Permissions は、このクレームの内容をユーザーエンティティの親エンティティにマッピングします。
Amazon Cognito ユーザープールからの ID トークンの構造の詳細については、「 *Amazon Cognito デベロッパーガイド*」の[「ID トークン](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-the-id-token.html)の使用」を参照してください。
次の ID トークンの例には、4 種類の属性があります。これには、 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 ユーザープールで ID ソースを作成するときは、Verified Permissions が で認可リクエストで生成するプリンシパルエンティティのタイプを指定します`IsAuthorizedWithToken`。その後、ポリシーはそのリクエストを評価する一環として、そのプリンシパルの属性をテストできます。スキーマは ID ソースのプリンシパルタイプと属性を定義し、Cedar ポリシーで参照できます。
ID トークングループクレームから派生するグループエンティティのタイプも指定します。認可リクエストでは、Verified Permissions はグループクレームの各メンバーをそのグループエンティティタイプにマッピングします。ポリシーでは、そのグループエンティティをプリンシパルとして参照できます。
以下の例は、サンプルの ID トークンの属性をVerified Permissions スキーマに反映する方法を示しています。スキーマの編集の詳細については、「[ポリシーストアスキーマの編集](schema-edit.md)」を参照してください。ID ソース構成でプリンシパルタイプ `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 ID トークン属性を反映](policies-examples.md#policies-examples-cognito-id)。
## アクセストークンをマッピングする
Verified Permissions は、グループクレーム以外のアクセストークンクレームをアクションの属性または*コンテキスト属性*として処理します。グループメンバーシップに加えて、IdP からのアクセストークンには API アクセスに関する情報が含まれる場合があります。アクセストークンは、ロールベースのアクセスコントロール (RBAC) を使用する認可モデルに役立ちます。グループメンバーシップ以外のアクセストークンクレームに依存する認可モデルでは、スキーマ設定に追加の労力が必要です。
Amazon Cognito アクセストークンには、認可に使用できるクレームがあります。Amazon Cognito アクセストークンでの便利なクレーム
*`client_id`*
OIDC 証明書利用者のクライアントアプリケーションの ID。クライアント ID を使用すると、Verified Permissions は、承認リクエストがポリシーストアの許可されたクライアントからのものであることを確認できます。machine-to-machine (M2M) 認可では、リクエスト元のシステムはクライアントシークレットを使用してリクエストを承認し、認可の証拠としてクライアント ID とスコープを提供します。
*`scope`*
トークンのベアラーのアクセス許可を表す [OAuth 2.0 スコープ](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3)。
*`cognito:groups`*
ユーザーのグループメンバーシップ。ロールベースのアクセスコントロール (RBAC) に基づく認可モデルでは、このクレームはポリシーで評価できるロールを示しています。
*一時的なクレーム*
アクセス許可ではないが、実行時にユーザープールの[トークン生成前 Lambda トリガー](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-pre-token-generation.html)によって追加されるクレーム。一時的なクレームは標準クレームに似ていますが、 `tenant`や など、標準外です`department`。アクセストークンをカスタマイズすると、 AWS 請求書にコストがかかります。
Amazon Cognito ユーザープールからのアクセストークンの構造の詳細については、「 *Amazon Cognito デベロッパーガイド*」の[「アクセストークンの使用](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-the-access-token.html)」を参照してください。
Amazon Cognito アクセストークンは、Verified Permissions に渡されるとコンテキストオブジェクトにマッピングされます。アクセストークンの属性は `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"
}
```
次の例は、サンプルアクセストークンの属性を 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"
}
}
}
}
```
このスキーマに対して検証するポリシーの例については、「」を参照してください[Amazon Cognito アクセストークン属性を反映](policies-examples.md#policies-examples-cognito-access)。
## Amazon Cognito コロン区切りクレームの代替表記
Verified Permissions の起動時に、 `cognito:groups` や などの Amazon Cognito トークンクレームに推奨されるスキーマは、これらのコロン区切り文字列を階層区切り文字`.`として使用するように`custom:store`変換しました。この形式は*ドット表記*と呼ばれます。たとえば、ポリシー`principal.cognito.groups`で への参照`cognito:groups`が になりました。この形式は引き続き使用できますが、[ブラケット表記](#cognito-map-token-to-schema-things-to-know)を使用してスキーマとポリシーを構築することをお勧めします。この形式では、ポリシー`principal["cognito:groups"]`で への参照`cognito:groups`が になります。Verified Permissions コンソールからユーザープール ID トークンの自動生成されたスキーマは、角括弧表記を使用します。
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
}
}
}
}
```
このスキーマに対して検証し、ドット表記を使用するポリシーの例については、「」を参照してください[ドット表記を使用して属性を参照します](policies-examples.md#policies-examples-dot)。
## スキーママッピングについて知っておくべきこと
**属性マッピングはトークンタイプによって異なります**
アクセストークン認可では、Verified Permissions はクレームを[コンテキスト](context.md)にマッピングします。ID トークン認可では、Verified Permissions はクレームをプリンシパル属性にマッピングします。Verified Permissions コンソールで作成したポリシーストアの場合、**空の**ポリシーストアと**サンプル**ポリシーストアのみが ID ソースを持たず、ID トークン認可のためにユーザープール属性をスキーマに入力する必要があります。アクセストークン認可は、グループメンバークレームを含むロールベースのアクセスコントロール (RBAC) に基づいており、他のクレームをポリシーストアスキーマに自動的にマッピングしません。
**ID ソース属性は必要ありません**
Verified Permissions コンソールで ID ソースを作成すると、必須としてマークされた属性はありません。これにより、クレームの欠落が認可リクエストで検証エラーを引き起こすのを防ぐことができます。必要に応じて属性を に設定できますが、すべての認可リクエストに存在する必要があります。
**RBAC はスキーマに属性を必要としません**
ID ソースのスキーマは、ID ソースを追加するときに行うエンティティの関連付けによって異なります。ID ソースは、1 つのクレームをユーザーエンティティタイプにマッピングし、1 つのクレームをグループエンティティタイプにマッピングします。これらのエンティティマッピングは、アイデンティティソース設定の中核です。この最小限の情報を使用して、ロールベースのアクセスコントロール (RBAC) モデルで、特定のユーザーおよびユーザーが属する可能性のある特定のグループに対して認可アクションを実行するポリシーを作成できます。スキーマにトークンクレームを追加すると、ポリシーストアの認可範囲が拡張されます。ID トークンのユーザー属性には、属性ベースのアクセスコントロール (ABAC) 認可に貢献できるユーザーに関する情報があります。アクセストークンのコンテキスト属性には、OAuth 2.0 スコープなどの情報があり、プロバイダーからの追加のアクセスコントロール情報を提供できますが、追加のスキーマ変更が必要です。
Verified Permissions コンソール**の API Gateway と ID プロバイダーのセットアップ**と**ガイド付きセットアップ**オプションは、ID トークンクレームをスキーマに割り当てます。アクセストークンクレームの場合はこの限りではありません。非グループアクセストークンクレームをスキーマに追加するには、JSON モードでスキーマを編集し、 [commonTypes](https://docs.cedarpolicy.com/schema/json-schema.html#schema-commonTypes) 属性を追加する必要があります。詳細については、「[アクセストークンをマッピングする](#cognito-map-access-token)」を参照してください。
**トークンタイプを選択する**
ポリシーストアが ID ソースと連携する方法は、ID トークンを処理するかアクセストークンを処理するかという ID ソース設定の重要な決定によって異なります。 Amazon Cognito ID プロバイダーでは、API リンクポリシーストアを作成するときにトークンタイプを選択できます。[API リンクポリシーストア](policy-stores-api-userpool.md)を作成するときは、ID トークンまたはアクセストークンの認可を設定するかどうかを選択する必要があります。この情報は、Verified Permissions がポリシーストアに適用するスキーマ属性と、 API Gateway API の Lambda オーソライザーの構文に影響します。特に、Verified Permissions コンソールの属性への ID トークンクレームの自動マッピングを活用する場合は、ID ソースを作成する前に、処理するトークンタイプを早期に決定します。トークンタイプを変更するには、ポリシーとスキーマをリファクタリングするための多大な労力が必要です。以下のトピックでは、ポリシーストアでの 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)。