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

スキーマとポリシーでの ID ソースの使用

ID ソースをポリシーストアに追加し、プロバイダーのクレームをポリシーストアスキーマにマッピングしたい場合があります。このプロセスを自動化することも、スキーマを手動で更新することもできます。ユーザーガイドのこのセクションには、次の情報が含まれています。

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

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

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

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

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

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

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

アクセストークン認証では、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 は、スペース区切りのグループクレームの各文字列を個別のグループとして解釈します。グループ名をスペース文字で 1 つのグループとして解釈するには、クレーム内のスペースを置き換えるか、削除します。例えば、という名前のグループを My GroupとしてフォーマットしますMyGroup。

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

ポリシーストアが ID ソースと連携する方法は、ID トークンとアクセストークンのどちらを処理するかという ID ソース設定の重要な決定によって異なります。Amazon Cognito ID プロバイダーでは、API リンクポリシーストアを作成するときにトークンタイプを選択できます。API にリンクされたポリシーストアを作成するときは、ID トークンまたはアクセストークンの認証を設定するかどうかを選択する必要があります。この情報は、Verified Permissions がポリシーストアに適用するスキーマ属性と、API Gateway API の Lambda オーソライザーの構文に影響します。OIDC プロバイダーでは、ID ソースを追加するときにトークンタイプを選択する必要があります。ID トークンまたはアクセストークンを選択できます。また、ポリシーストアで処理されないトークンタイプは除外されます。特に、Verified Permissions コンソールの属性への ID トークンクレームの自動マッピングのメリットを享受したい場合は、ID ソースを作成する前に、処理するトークンタイプを早期に決定してください。トークンタイプを変更するには、ポリシーとスキーマをリファクタリングするために多大な労力が必要です。以下のトピックでは、ポリシーストアでの ID トークンとアクセストークンの使用について説明します。

Cedar パーサーには一部の文字に角括弧が必要です

ポリシーは通常、のような形式でスキーマ属性を参照しますprincipal.username。トークンクレーム名に表示される/可能性がある :、、 .などの英数字以外の文字がほとんどの場合、Verified Permissions は principal.cognito:groupsやなどの条件値を解析できません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"
      ]
   }
}

このスキーマに対して検証する属性のポリシーの例は、次のようになります。


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 トークンをスキーマにマッピングする

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 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 属性を反映するようにスキーマを更新したら、その属性を参照するポリシーを作成できます。


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 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 プロバイダー内のグループのメンバーに適用されます。


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*"
};

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

Verified Permissions は、グループクレーム以外のアクセストークンクレームをアクションの属性、またはコンテキスト属性 として処理します。グループメンバーシップに加えて、IdP からのアクセストークンには API アクセスに関する情報が含まれている場合があります。アクセストークンは、ロールベースのアクセスコントロール (RBAC) を使用する認可モデルで役立ちます。グループメンバーシップ以外のアクセストークンクレームに依存する認証モデルでは、スキーマ設定にさらに労力が必要です。

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

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 スキーマに反映する方法を示しています。スキーマの編集の詳細については、「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 アクセストークンは、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"
         }
      }
   }
}

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 のコロン区切りクレームの代替表記

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

Amazon Cognito ID ソースの手動で構築されたスキーマとポリシーでは、引き続きドット表記を使用できます。他のタイプの 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 が無効になっているか、使用できません。

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

ドキュメントの表記規則

ID ソースの編集

承認モデルの設計