翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# Amazon Cognito ID ソースの使用
Verified Permissions は Amazon Cognito ユーザープールと密接に連携します。 Amazon Cognito JWTsは予測可能な構造です。Verified Permissions はこの構造を認識し、含まれている情報から最大限のメリットを得ます。たとえば、ID トークンまたはアクセストークンを使用して、ロールベースのアクセスコントロール (RBAC) 認可モデルを実装できます。
新しい Amazon Cognito ユーザープール ID ソースには、次の情報が必要です。
+ AWS リージョン。
+ ユーザープール ID。
+ ID ソースに関連付けるプリンシパルエンティティタイプ。例: `MyCorp::User`。
+ ID ソースに関連付けるプリンシパルグループエンティティタイプ。例: `MyCorp::UserGroup`。
+ ポリシーストアへのリクエストを許可するユーザープールのクライアント IDs。
Verified Permissions は同じ 内の Amazon Cognito ユーザープールでのみ機能するため AWS アカウント、別のアカウントで ID ソースを指定することはできません。Verified Permissions は、ユーザープールプリンシパルを操作するポリシーで参照する必要がある ID ソース識別子である*エンティティプレフィックス*を、 などのユーザープールの ID に設定します`us-west-2_EXAMPLE`。この場合、ID を持つユーザープール内のユーザーを `a1b2c3d4-5678-90ab-cdef-EXAMPLE22222` として参照します。 `us-west-2_EXAMPLE|a1b2c3d4-5678-90ab-cdef-EXAMPLE22222`
ユーザープールトークン*クレーム*には、属性、スコープ、グループ、クライアント IDs、カスタムデータを含めることができます。[Amazon Cognito JWTs](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) には、Verified Permissions の承認決定に役立つさまざまな情報を含める機能があります。具体的には次のとおりです。
1. `cognito:` プレフィックス付きのユーザー名およびグループクレーム
1. を使用した[カスタムユーザー属性](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-attributes.html#user-pool-settings-custom-attributes) `custom: prefix`
1. 実行時に追加されたカスタムクレーム
1. `sub` や などの OIDC 標準クレーム `email`
これらのクレームの詳細と、 の Verified Permissions ポリシーでそれらを管理する方法について説明します[Amazon Cognito トークンをスキーマにマッピングする](cognito-map-token-to-schema.md)。
**重要**
Amazon Cognito トークンは有効期限が切れる前に取り消すことができますが、JWTsは署名と有効性を備えたステートレスリソースと見なされます。[JSON ウェブトークン RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519) に準拠するサービスは、トークンをリモートで検証することが想定されており、発行者による検証は必須ではありません。つまり、Verified Permissions は、後で削除されたユーザーに対して取り消されたトークンまたは発行されたトークンに基づいてアクセスを許可できます。このリスクを軽減するために、有効期間をできるだけ短くしてトークンを作成し、ユーザーのセッションを継続する権限を削除したい場合は更新トークンを取り消すことをお勧めします。詳細については、[「トークン失効によるユーザーセッションの終了](https://docs.aws.amazon.com/cognito/latest/developerguide/token-revocation.html)」を参照してください。
次の例は、プリンシパルに関連付けられた Amazon Cognito ユーザープールクレームの一部を参照するポリシーを作成する方法を示しています。
```
permit(
principal,
action,
resource == ExampleCo::Photo::"VacationPhoto94.jpg"
)
when {
principal["cognito:username"]) == "alice" &&
principal["custom:department"]) == "Finance"
};
```
次の例は、Cognito ユーザープール内のユーザーであるプリンシパルを参照するポリシーを作成する方法を示しています。プリンシパル ID は の形式であることに注意してください`"|"`。
```
permit(
principal == ExampleCo::User::"us-east-1_example|a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
action,
resource == ExampleCo::Photo::"VacationPhoto94.jpg"
);
```
Verified Permissions のユーザープール ID ソースの Cedar ポリシーは、英数字とアンダースコア () 以外の文字を含むクレーム名に特別な構文を使用します`_`。これには、 `cognito:username`や などの`:`文字を含むユーザープールプレフィックスクレームが含まれます`custom:department`。`cognito:username` または `custom:department`クレームを参照するポリシー条件を記述するには、`principal["custom:department"]`それぞれ `principal["cognito:username"]`および として記述します。
**注記**
トークンに `cognito:`または `custom:`プレフィックスを持つクレームと、リテラル値 `cognito`または を持つクレーム名が含まれている場合`custom`、[IsAuthorizedWithToken](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_IsAuthorizedWithToken.html) を使用した認可リクエストは で失敗します`ValidationException`。
クレームのマッピングの詳細については、「」を参照してください[Amazon Cognito トークンをスキーマにマッピングする](cognito-map-token-to-schema.md)。 Amazon Cognito ユーザーの認可の詳細については、[「Amazon Cognito デベロッパーガイド」の「Amazon Verified Permissions を使用した認可](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-authorization-with-avp.html)」を参照してください。 *Amazon Cognito *
**Topics**
+ [Amazon Verified Permissions Amazon Cognito ID ソースの作成](cognito-create.md)
+ [Amazon Verified Permissions Amazon Cognito ID ソースの編集](cognito-edit.md)
+ [Amazon Cognito トークンをスキーマにマッピングする](cognito-map-token-to-schema.md)
+ [のクライアントとオーディエンスの検証 Amazon Cognito](cognito-validation.md)
# Amazon Verified Permissions Amazon Cognito ID ソースの作成
次の手順では、ID ソースを既存のポリシーストアに追加します。
Verified Permissions コンソールで[新しいポリシーストアを作成する](policy-stores-create.md)ときに、ID ソースを作成することもできます。このプロセスでは、ID ソーストークンのクレームをエンティティ属性に自動的にインポートできます。**ガイド付きセットアップ**を選択するか、 ** API Gateway と ID プロバイダーオプションを使用してセットアップ**します。これらのオプションでは、初期ポリシーも作成されます。
**注記**
**ID ソース** は、ポリシーストアを作成するまでは左側のナビゲーションペインには表示されません。作成する ID ソースは、現在のポリシーストアに関連付けられます。
Verified Permissions API の [create-identity-source](https://docs.aws.amazon.com/cli/latest/reference/verifiedpermissions/create-identity-source.html) AWS CLI または [CreateIdentitySource](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_CreateIdentitySource.html) を使用して ID ソースを作成するときに、プリンシパルエンティティタイプを除外できます。ただし、空のエンティティタイプは、エンティティタイプが の ID ソースを作成します`AWS::Cognito`。このエンティティ名は、ポリシーストアスキーマと互換性がありません。 Amazon Cognito ID をポリシーストアスキーマと統合するには、プリンシパルエンティティタイプをサポートされているポリシーストアエンティティに設定する必要があります。
------
#### [ AWS マネジメントコンソール ]
**Amazon Cognito ユーザープール ID ソースを作成するには**
1. [Verified Permissions コンソール](https://console.aws.amazon.com/verifiedpermissions/)を開きます。ポリシーストアを選択します。
1. 左側にあるナビゲーションペインで、**[ID ソース]** を選択します。
1. **[ID ソースを作成]**を選択します。
1. **Cognito ユーザープールの詳細**で、 を選択し、ID ソースの**ユーザープール ID** AWS リージョン を入力します。
1. **プリンシパル設定**の**プリンシパルタイプ**で、このソースからプリンシパルのエンティティタイプを選択します。接続された Amazon Cognito ユーザープールの ID は、選択したプリンシパルタイプにマッピングされます。
1. **グループ設定**で、ユーザープール`cognito:groups`クレームをマッピングする場合は **Cognito グループ**を使用するを選択します。プリンシパルタイプの親であるエンティティタイプを選択します。
1. **クライアントアプリケーションの検証**で、クライアントアプリケーション IDsを検証するかどうかを選択します。
+ クライアントアプリケーション ID を検証するには、「**クライアントアプリケーション ID が一致するトークンのみを受け入れる**」を選択します。検証するクライアントアプリケーション ID ごとに [**新しいクライアントアプリケーション ID を追加**] を選択します。追加したクライアントアプリケーション ID を削除するには、クライアントアプリケーション ID の横にある [**削除**] を選択します。
+ クライアントアプリケーション ID を検証したくない場合は、**[クライアントアプリケーション ID を検証しない]**を選択します。
1. **[ID ソースを作成]**を選択します。
1. (オプション) ポリシーストアにスキーマがある場合、Cedar ポリシーのアイデンティティトークンまたはアクセストークンから抽出した属性を参照する前に、スキーマを更新して、ID ソースが作成するプリンシパルのタイプを Cedar に認識させる必要があります。スキーマへの追加には、Cedar ポリシーで参照したい属性を含める必要があります。 Amazon Cognito トークン属性を Cedar プリンシパル属性にマッピングする方法の詳細については、「」を参照してください[Amazon Cognito トークンをスキーマにマッピングする](cognito-map-token-to-schema.md)。
**注記**
[API リンクポリシーストア](policy-stores-api-userpool.md)を作成するか、ポリシーストアの作成時に ** API Gateway と ID プロバイダーのセットアップ**を使用するとき、Verified Permissions はユーザープールにユーザー属性をクエリし、プリンシパルタイプにユーザープール属性が入力されるスキーマを作成します。
1. トークンからの情報を使用して認可を決定するポリシーを作成します。詳細については、「[Amazon Verified Permissions 静的ポリシーの作成](policies-create.md)」を参照してください。
ID ソースの作成、スキーマの更新、ポリシーの作成が完了したら、 を使用して Verified Permissions `IsAuthorizedWithToken`に認可の決定を依頼します。詳細については、*Amazon Verified Permissions API リファレンスガイド*の[IsAuthorizedWithToken](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_IsAuthorizedWithToken.html)」を参照してください。
------
#### [ AWS CLI ]
**Amazon Cognito ユーザープール ID ソースを作成するには**
[CreateIdentitySource](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_CreateIdentitySource.html) オペレーションを使用して ID ソースを作成できます。次の の例では、 Amazon Cognito ユーザープールから認証された ID にアクセスできる ID ソースを作成します。
1. `create-identity-source` コマンドの `--configuration`パラメータで使用する Amazon Cognito ユーザープールの以下の詳細を含む`config.txt`ファイルを作成します。
```
{
"cognitoUserPoolConfiguration": {
"userPoolArn": "arn:aws:cognito-idp:us-west-2:123456789012:userpool/us-west-2_1a2b3c4d5",
"clientIds":["a1b2c3d4e5f6g7h8i9j0kalbmc"],
"groupConfiguration": {
"groupEntityType": "MyCorp::UserGroup"
}
}
}
```
1. 次のコマンドを実行して ID Amazon Cognito ソースを作成します。
```
$ aws verifiedpermissions create-identity-source \
--configuration file://config.txt \
--principal-entity-type "User" \
--policy-store-id 123456789012
{
"createdDate": "2023-05-19T20:30:28.214829+00:00",
"identitySourceId": "ISEXAMPLEabcdefg111111",
"lastUpdatedDate": "2023-05-19T20:30:28.214829+00:00",
"policyStoreId": "PSEXAMPLEabcdefg111111"
}
```
1. (オプション) ポリシーストアにスキーマがある場合、Cedar ポリシーのアイデンティティトークンまたはアクセストークンから抽出した属性を参照する前に、スキーマを更新して、ID ソースが作成するプリンシパルのタイプを Cedar に認識させる必要があります。スキーマへの追加には、Cedar ポリシーで参照したい属性を含める必要があります。 Amazon Cognito トークン属性を Cedar プリンシパル属性にマッピングする方法の詳細については、「」を参照してください[Amazon Cognito トークンをスキーマにマッピングする](cognito-map-token-to-schema.md)。
**注記**
[API リンクポリシーストア](policy-stores-api-userpool.md)を作成するか、ポリシーストアの作成時に ** API Gateway と ID プロバイダーでセットアップ**を使用するとき、Verified Permissions はユーザープールにユーザー属性をクエリし、プリンシパルタイプにユーザープール属性が入力されるスキーマを作成します。
1. トークンからの情報を使用して認可を決定するポリシーを作成します。詳細については、「[Amazon Verified Permissions 静的ポリシーの作成](policies-create.md)」を参照してください。
ID ソースの作成、スキーマの更新、ポリシーの作成が完了したら、 を使用して Verified Permissions `IsAuthorizedWithToken`に認可の決定を依頼します。詳細については、*「Amazon Verified Permissions API リファレンスガイド*」の「[IsAuthorizedWithToken](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_IsAuthorizedWithToken.html)」を参照してください。
------
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)」を参照してください。
# Amazon Verified Permissions Amazon Cognito ID ソースの編集
ID ソースの一部のパラメータは、作成後に編集できます。ID ソースのタイプを変更することはできません。ID ソースを削除し、OIDC または OIDC Amazon Cognito に切り替える新しい ID ソースを作成する必要があります Amazon Cognito。ポリシーストアスキーマが ID ソース属性と一致する場合は、ID ソースに加えた変更を反映するようにスキーマを個別に更新する必要があることに注意してください。
------
#### [ AWS マネジメントコンソール ]
**Amazon Cognito ID ソースを更新するには**
1. [Verified Permissions コンソール](https://console.aws.amazon.com/verifiedpermissions/)を開きます。ポリシーストアを選択します。
1. 左側にあるナビゲーションペインで、[**ID ソース**] を選択します。
1. 編集する ID ソースの ID を選択します。
1. **[編集]** を選択します。
1. **Cognito ユーザープールの詳細**で、 を選択し AWS リージョン 、ID ソースの**ユーザープール ID** を入力します。
1. **プリンシパルの詳細**で、ID ソースの**プリンシパルタイプ**を更新できます。接続された Amazon Cognito ユーザープールの ID は、選択したプリンシパルタイプにマッピングされます。
1. **グループ設定**で、ユーザープール`cognito:groups`クレームをマッピングする場合は **Cognito グループ**を使用するを選択します。プリンシパルタイプの親であるエンティティタイプを選択します。
1. **クライアントアプリケーションの検証**で、クライアントアプリケーション IDsを検証するかどうかを選択します。
+ クライアントアプリケーション ID を検証するには、「**クライアントアプリケーション ID が一致するトークンのみを受け入れる**」を選択します。検証するクライアントアプリケーション ID ごとに [**新しいクライアントアプリケーション ID を追加**] を選択します。追加したクライアントアプリケーション ID を削除するには、クライアントアプリケーション ID の横にある [**削除**] を選択します。
+ クライアントアプリケーション ID を検証したくない場合は、「**クライアントアプリケーション ID を検証しない**」を選択します。
1. **[変更を保存]** をクリックします。
1. ID ソースのプリンシパルタイプを変更した場合は、更新されたプリンシパルタイプが正しく反映されるようにスキーマを更新する必要があります。
ID ソースを削除するには、ID ソースの横にあるラジオボタンを選択し、次に [**ID ソースを削除**] を選択します。テキストボックスに`delete`を入力し、[**ID ソースを削除**] を選択して ID ソースの削除を確定します。
------
#### [ AWS CLI ]
**Amazon Cognito ID ソースを更新するには**
[UpdateIdentitySource](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_UpdateIdentitySource.html) オペレーションを使用して ID ソースを更新できます。次の の例では、指定された ID ソースを更新して、別の Amazon Cognito ユーザープールを使用します。
1. `update-identity-source` コマンドの `--configuration`パラメータで使用する Amazon Cognito ユーザープールの以下の詳細を含む`config.txt`ファイルを作成します。
```
{
"cognitoUserPoolConfiguration": {
"userPoolArn": "arn:aws:cognito-idp:us-west-2:123456789012:userpool/us-west-2_1a2b3c4d5",
"clientIds":["a1b2c3d4e5f6g7h8i9j0kalbmc"],
"groupConfiguration": {
"groupEntityType": "MyCorp::UserGroup"
}
}
}
```
1. 次のコマンドを実行して、 Amazon Cognito ID ソースを更新します。
```
$ aws verifiedpermissions update-identity-source \
--update-configuration file://config.txt \
--policy-store-id 123456789012
{
"createdDate": "2023-05-19T20:30:28.214829+00:00",
"identitySourceId": "ISEXAMPLEabcdefg111111",
"lastUpdatedDate": "2023-05-19T20:30:28.214829+00:00",
"policyStoreId": "PSEXAMPLEabcdefg111111"
}
```
**注記**
ID ソースのプリンシパルタイプを変更する場合、更新されたプリンシパルタイプを正しく反映するようにスキーマを更新する必要があります。
------
# 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)。
# のクライアントとオーディエンスの検証 Amazon Cognito
ID ソースをポリシーストアに追加すると、Verified Permissions には、ID トークンとアクセストークンが意図したとおりに使用されていることを確認する設定オプションがあります。この検証は、 `IsAuthorizedWithToken`および `BatchIsAuthorizedWithToken` API リクエストの処理で行われます。この動作は、ID トークンとアクセストークン、および Amazon Cognito と OIDC ID ソースによって異なります。Amazon Cognito ユーザープールプロバイダーを使用すると、Verified Permissions は ID トークンとアクセストークンの両方でクライアント ID を検証できます。OIDC プロバイダーを使用すると、Verified Permissions は ID トークンのクライアント ID とアクセストークンの対象者を検証できます。
*クライアント ID* は、アプリケーションが使用する ID プロバイダーインスタンスに関連付けられた識別子です`1example23456789`。例: 。*対象者*は、 など、アクセストークンの目的の*証明書利用者*または送信先に関連付けられた URL パスです`https://mytoken.example.com`。アクセストークンを使用する場合、`aud`クレームは常に対象者に関連付けられます。
Amazon Cognito ID トークンには、[アプリケーションクライアント](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-client-apps.html) ID を含む `aud`クレームがあります。アクセストークンには、アプリケーションクライアント ID も含まれる`client_id`クレームがあります。
ID ソースに**クライアントアプリケーション検証**に 1 つ以上の値を入力すると、Verified Permissions はこのアプリケーションクライアント IDs のリストを ID トークン`aud`クレームまたはアクセストークン`client_id`クレームと比較します。Verified Permissions は、 Amazon Cognito ID ソースの証明書利用者 URL を検証しません。
## JWTs のクライアント側の認可
アプリケーションで JSON ウェブトークンを処理し、ポリシーストア ID ソースを使用せずにそのクレームを Verified Permissions に渡すことができます。JSON Web Token (JWT) からエンティティ属性を抽出し、Verified Permissions に解析できます。
この例では、JWT.1 を使用してアプリケーションから Verified Permissions を呼び出す方法を示します。
```
async function authorizeUsingJwtToken(jwtToken) {
const payload = await verifier.verify(jwtToken);
let principalEntity = {
entityType: "PhotoFlash::User", // the application needs to fill in the relevant user type
entityId: payload["sub"], // the application need to use the claim that represents the user-id
};
let resourceEntity = {
entityType: "PhotoFlash::Photo", //the application needs to fill in the relevant resource type
entityId: "jane_photo_123.jpg", // the application needs to fill in the relevant resource id
};
let action = {
actionType: "PhotoFlash::Action", //the application needs to fill in the relevant action id
actionId: "GetPhoto", //the application needs to fill in the relevant action type
};
let entities = {
entityList: [],
};
entities.entityList.push(...getUserEntitiesFromToken(payload));
let policyStoreId = "PSEXAMPLEabcdefg111111"; // set your own policy store id
const authResult = await client
.isAuthorized({
policyStoreId: policyStoreId,
principal: principalEntity,
resource: resourceEntity,
action: action,
entities,
})
.promise();
return authResult;
}
function getUserEntitiesFromToken(payload) {
let attributes = {};
let claimsNotPassedInEntities = ['aud', 'sub', 'exp', 'jti', 'iss'];
Object.entries(payload).forEach(([key, value]) => {
if (claimsNotPassedInEntities.includes(key)) {
return;
}
if (Array.isArray(value)) {
var attibuteItem = [];
value.forEach((item) => {
attibuteItem.push({
string: item,
});
});
attributes[key] = {
set: attibuteItem,
};
} else if (typeof value === 'string') {
attributes[key] = {
string: value,
}
} else if (typeof value === 'bigint' || typeof value ==='number') {
attributes[key] = {
long: value,
}
} else if (typeof value === 'boolean') {
attributes[key] = {
boolean: value,
}
}
});
let entityItem = {
attributes: attributes,
identifier: {
entityType: "PhotoFlash::User",
entityId: payload["sub"], // the application needs to use the claim that represents the user-id
}
};
return [entityItem];
}
```
¹ このコード例では、[aws-jwt-verify](https://github.com/awslabs/aws-jwt-verify) ライブラリを使用して OIDC 互換 IdPs によって署名された JWT を検証しています。