ID トークンのマッピングアクセストークンをマッピングする Amazon Cognito コロン区切りクレームの代替表記スキーママッピングについて知っておくべきこと

Amazon Cognito トークンをスキーマにマッピングする

ID ソースをポリシーストアに追加し、プロバイダークレーム、またはトークンをポリシーストアスキーマにマッピングする場合があります。このプロセスを自動化するには、ガイド付きセットアップを使用して ID ソースでポリシーストアを作成するか、ポリシーストアの作成後にスキーマを手動で更新します。トークンをスキーマにマッピングしたら、それらを参照するポリシーを作成できます。

ユーザーガイドのこのセクションには、次の情報が含まれています。

ポリシーストアスキーマに属性を自動的に入力できる場合
Verified Permissions ポリシーで Amazon Cognito トークンクレームを使用する方法
ID ソースのスキーマを手動で構築する方法

API リンクポリシーストアとガイド付きセットアップで作成された 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 または BatchIsAuthorizedWithToken API リクエストで作成するエンティティに対応している必要があります。ID トークンのプロバイダー情報からスキーマを自動的に入力する方法でポリシーストアを作成した場合は、ポリシーを作成する準備が整います。ID ソースのスキーマなしでポリシーストアを作成する場合は、API リクエストを使用して作成されたエンティティに一致するプロバイダー属性をスキーマに追加する必要があります。その後、プロバイダートークンの属性を使用してポリシーを記述できます。

Verified Permissions で認証されたユーザーに Amazon Cognito ID とアクセストークンを使用する方法の詳細については、「Amazon Amazon Cognitoデベロッパーガイド」の「Amazon Verified Permissions による認可」を参照してください。

ID トークンをスキーマにマッピングする

Verified Permissions は、ID トークンクレームをユーザーの名前とタイトル、グループメンバーシップ、連絡先情報などの属性として処理します。ID トークンは、属性ベースのアクセスコントロール (ABAC) 認可モデルで最も役立ちます。Verified Permissions でリクエストを行っているユーザーに基づいてリソースへのアクセスを分析する場合は、ID ソースの 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。
標準のクレーム: email やなどの標準 OIDC クレームphone_number。詳細については、「エラーセット 2 を組み込んだ OpenID Connect Core 1.0 の標準クレーム」を参照してください。 OpenID
cognito:groups: ユーザーのグループメンバーシップ。ロールベースのアクセスコントロール (RBAC) に基づく認可モデルでは、このクレームはポリシーで評価できるロールを示しています。
一時的なクレーム: ユーザーのプロパティではないが、実行時にユーザープールのトークン生成前 Lambda トリガーによって追加されるクレーム。一時的なクレームは標準クレームに似ていますが、 tenantやなど、標準外ですdepartment。

: 区切り文字を持つ Amazon Cognito 属性を参照するポリシーでは、形式の属性を参照しますprincipal["cognito:username"]。ロールクレームcognito:groupsはこのルールの例外です。Verified Permissions は、このクレームの内容をユーザーエンティティの親エンティティにマッピングします。

Amazon Cognito ユーザープールからの ID トークンの構造の詳細については、「 Amazon Cognito デベロッパーガイド」の「ID トークンの使用」を参照してください。

次の 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 スキーマに反映する方法を示しています。スキーマの編集の詳細については、「ポリシーストアスキーマの編集」を参照してください。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 トークン属性を反映。

アクセストークンをマッピングする

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 スコープ。
cognito:groups: ユーザーのグループメンバーシップ。ロールベースのアクセスコントロール (RBAC) に基づく認可モデルでは、このクレームはポリシーで評価できるロールを示しています。
一時的なクレーム: アクセス許可ではないが、実行時にユーザープールのトークン生成前 Lambda トリガーによって追加されるクレーム。一時的なクレームは標準クレームに似ていますが、 tenantやなど、標準外ですdepartment。アクセストークンをカスタマイズすると、 AWS 請求書にコストがかかります。

Amazon Cognito ユーザープールからのアクセストークンの構造の詳細については、「 Amazon Cognito デベロッパーガイド」の「アクセストークンの使用」を参照してください。

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 スキーマに反映する方法を示しています。スキーマの編集の詳細については、「ポリシーストアスキーマの編集」を参照してください。


{
   "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 アクセストークン属性を反映。

Amazon Cognito コロン区切りクレームの代替表記

Verified Permissions の起動時に、 cognito:groups やなどの Amazon Cognito トークンクレームに推奨されるスキーマは、これらのコロン区切り文字列を階層区切り文字.として使用するようにcustom:store変換しました。この形式はドット表記と呼ばれます。たとえば、ポリシーprincipal.cognito.groupsでへの参照cognito:groupsがになりました。この形式は引き続き使用できますが、ブラケット表記を使用してスキーマとポリシーを構築することをお勧めします。この形式では、ポリシー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
         }
      }
   }
}

このスキーマに対して検証し、ドット表記を使用するポリシーの例については、「」を参照してくださいドット表記を使用して属性を参照します。

スキーママッピングについて知っておくべきこと

属性マッピングはトークンタイプによって異なります

アクセストークン認可では、Verified Permissions はクレームをコンテキストにマッピングします。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 属性を追加する必要があります。詳細については、「アクセストークンをマッピングする」を参照してください。

トークンタイプを選択する

ポリシーストアが ID ソースと連携する方法は、ID トークンを処理するかアクセストークンを処理するかという ID ソース設定の重要な決定によって異なります。 Amazon Cognito ID プロバイダーでは、API リンクポリシーストアを作成するときにトークンタイプを選択できます。API リンクポリシーストアを作成するときは、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"
      ]
   }
}

このスキーマに対して検証するポリシーの例については、「」を参照してください角括弧表記を使用してトークン属性を参照します。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

ID ソースの編集

クライアントとオーディエンスの検証