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

ID プロバイダートークンをスキーマにマッピングする

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

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

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

ガイド付きセットアップで作成された ID ソースを持つ APIにリンクされたポリシーストアとポリシーストアでは、ID (ID) トークン属性をスキーマに手動でマッピングする必要はありません。Verified Permissions にユーザープール内の属性を指定し、ユーザー属性が入力されたスキーマを作成できます。ID トークン認証では、Verified Permissions はクレームをプリンシパルエンティティの属性にマッピングします。Amazon Cognito トークンをスキーマに手動でマッピングする必要がある場合があります。

サンプルから空のポリシーストアまたはポリシーストアを作成しました。
アクセストークンの使用をロールベースのアクセスコントロール () を超えて拡張したいと考えていますRBAC。
Verified Permissions REST API、、 AWS SDKまたはを使用してポリシーストアを作成します AWS CDK。

Verified Permissions ポリシーストアで Amazon Cognito または OIDC ID プロバイダー (IdP ) を ID ソースとして使用するには、スキーマにプロバイダー属性が必要です。スキーマは固定されており、プロバイダートークンが IsAuthorizedWithTokenまたは BatchIsAuthorizedWithTokenAPIリクエストで作成するエンティティに対応する必要があります。ID トークンのプロバイダー情報からスキーマを自動的に入力する方法でポリシーストアを作成した場合は、ポリシーを記述する準備が整います。ID ソースのスキーマなしでポリシーストアを作成する場合は、APIリクエストを使用して作成されたエンティティに一致するプロバイダー属性をスキーマに追加する必要があります。その後、プロバイダートークンの属性を使用してポリシーを記述できます。

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

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

Verified Permissions は、ID トークンクレームをユーザーの名前とタイトル、グループメンバーシップ、連絡先情報などの属性として処理します。ID トークンは、属性ベースのアクセスコントロール (ABAC) 承認モデルで最も役立ちます。Verified Permissions でリクエスト者に基づいてリソースへのアクセスを分析する場合は、ID ソースの ID トークンを選択します。

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

OIDC ID トークン

OIDC プロバイダーの ID トークンの操作は、Amazon Cognito ID トークンの操作とほぼ同じです。違いはクレームにあります。IdP には、標準OIDC属性が表示されるか、カスタムスキーマがある場合があります。Verified Permissions コンソールで新しいポリシーストアを作成するときに、ID トークンの例を使用して OIDC ID ソースを追加するか、トークンクレームをユーザー属性に手動でマッピングできます。Verified Permissions は IdP の属性スキーマを認識していないため、この情報を指定する必要があります。

詳細については、「Verified Permissions ポリシーストアの作成」を参照してください。

OIDC ID ソースを持つポリシーストアのスキーマの例を次に示します。


"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。グループメンバーシップ以外のアクセストークンクレームに依存する認証モデルでは、スキーマ設定にさらなる労力が必要です。

Amazon Cognito アクセストークンのマッピング

Amazon Cognito アクセストークンには、認可に使用できるクレームがあります。

Amazon Cognito アクセストークンでの便利なクレーム

client_id: OIDC 依存する相手のクライアントアプリケーションの ID。クライアント ID を使用すると、Verified Permissions は、承認リクエストがポリシーストアの許可されたクライアントからのものであることを確認できます。(M2M) machine-to-machine認証では、リクエストするシステムはクライアントシークレットを使用してリクエストを承認し、クライアント 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 スキーマに反映する方法を示しています。スキーマの編集の詳細については、「ポリシーストアスキーマを 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 アクセストークン属性を反映。

OIDC アクセストークンのマッピング

外部OIDCプロバイダーからのほとんどのアクセストークンは、Amazon Cognito アクセストークンと密接に連携しています。OIDC アクセストークンは、Verified Permissions に渡されるとコンテキストオブジェクトにマッピングされます。アクセストークンの属性は 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"
}


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

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

Verified Permissions の起動時に、Amazon Cognito トークンの推奨スキーマは、これらのコロン区切り文字列をのように要求cognito:groupsし、階層区切り文字として.文字を使用するようにcustom:store変換しました。この形式はドット表記 と呼ばれます。例えば、への参照がポリシーprincipal.cognito.groupsで cognito:groups になりました。この形式は引き続き使用できますが、ブラケット表記を使用してスキーマとポリシーを構築することをお勧めします。この形式では、への参照cognito:groupsがポリシーprincipal["cognito:groups"]に含まれます。Verified Permissions コンソールからユーザープール ID トークンの自動生成されたスキーマは、括弧表記を使用します。

Amazon Cognito ID ソースの手動で構築されたスキーマとポリシーでは、引き続きドット表記を使用できます。他のタイプの OIDCIdP のスキーマ:またはポリシーでは、または他の英数字以外の文字でドット表記を使用することはできません。

ドット表記のスキーマは、次の例に示すように、:文字の各インスタンスを 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属性を追加する必要があります。詳細については、「アクセストークンをマッピングする」を参照してください。

OIDC グループクレームが複数の形式をサポート

OIDC プロバイダーを追加するときは、ポリシーストアのユーザーのグループメンバーシップにマッピングする ID トークンまたはアクセストークンのグループクレームの名前を選択できます。検証済みアクセス許可は、次の形式でグループのクレームを認識します。

スペースのない文字列: "groups": "MyGroup"
スペース区切りリスト: "groups": "MyGroup1 MyGroup2 MyGroup3"。各文字列はグループです。
JSON (カンマ区切り) リスト: "groups": ["MyGroup1", "MyGroup2", "MyGroup3"]

注記

Verified Permissions は、スペース区切りグループの各文字列を個別のグループとして解釈します。スペース文字を含むグループ名を単一のグループとして解釈するには、クレーム内のスペースを置き換えるか、削除します。例えば、 My Group という名前のグループをフォーマットしますMyGroup。

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

ポリシーストアが ID ソースと連携する方法は、ID トークンを処理するかアクセストークンを処理するかという ID ソース設定の重要な決定によって異なります。Amazon Cognito ID プロバイダーでは、APIリンクされたポリシーストアを作成するときにトークンタイプを選択できます。リンクAPIされたポリシーストアを作成するときは、ID トークンまたはアクセストークンの認証を設定するかどうかを選択する必要があります。この情報は、Verified Permissions がポリシーストアに適用するスキーマ属性と、APIゲートウェイの Lambda オーソライザーの構文に影響しますAPI。OIDC プロバイダーでは、ID ソースを追加するときにトークンタイプを選択する必要があります。ID またはアクセストークンを選択できます。また、ポリシーストアで処理されないトークンタイプは除外されます。特に、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 ソースの編集

リクエストを承認する