API リンクポリシーストア

Amazon Verified Permissions コンソールで新しいポリシーストアを作成するときは、 API Gateway と ID ソースでセットアップ オプションを選択できます。このオプションでは、API リンクポリシーストア を構築します。これは、Amazon Cognito ユーザープールまたは OIDC ID プロバイダー (IdP) で認証し、Amazon API Gateway APIs。開始するには、接続された API と ID プロバイダーを使用してポリシーストアを作成するを参照してください。

トピック

Verified Permissions が API リクエストを承認する方法
属性ベースのアクセスコントロール (ABAC) の追加
API にリンクされたポリシーストアに関する考慮事項
API リンクポリシーストアのトラブルシューティング

重要

Verified Permissions コンソールの API Gateway でセットアップし、ID ソースオプションを使用して作成したポリシーストアは、本番環境への即時デプロイを目的としていません。最初のポリシーストアで、承認モデルを確定し、ポリシーストアリソースをにエクスポートします CloudFormation。AWS Cloud Development Kit (CDK) を使用して、プログラムで Verified Permissions を本番環境にデプロイします。詳細については、「を使用した本番環境への移行 AWS CloudFormation」を参照してください。

API と ID ソースにリンクされたポリシーストアでは、アプリケーションは API にリクエストを行うときに、承認ヘッダーにユーザープールトークンを表示します。ポリシーストアの ID ソースは、Verified Permissions のトークン検証を提供します。トークンは API を使用して認証リクエストprincipalでを形成しますIsAuthorizedWithToken。Verified Permissions は、アイデンティティ (ID) とアクセストークンのグループクレーム、例えばcognito:groupsユーザープールのグループメンバーシップに関するポリシーを構築します。API は Lambda オーソライザーでアプリケーションからトークンを処理し、認証決定のために Verified Permissions に送信します。API が Lambda オーソライザーから承認決定を受け取ると、リクエストをデータソースに渡すか、リクエストを拒否します。

Verified Permissions による ID ソースと API Gateway 認証のコンポーネント

ユーザーを認証してグループ化する Amazon Cognito ユーザープールまたは OIDC IdP。ユーザーのトークンは、ポリシーストアで Verified Permissions が評価するグループメンバーシップとプリンシパルまたはコンテキストを入力します。
API Gateway REST API。Verified Permissions は、などの API パスと API メソッドからのアクションを定義しますMyAPI::Action::get /photo。
API の Lambda 関数と Lambda オーソライザー。Lambda 関数は、ユーザープールからベアラートークンを受け取り、Verified Permissions から認証をリクエストし、API Gateway に決定を返します。Cognito と API Gateway のセットアップワークフローでは、この Lambda オーソライザーが自動的に作成されます。
Verified Permissions ポリシーストア。ポリシーストア ID ソースはユーザープールです。ポリシーストアスキーマは API の設定を反映し、ポリシーはユーザーグループを許可された API アクションにリンクします。
IdP でユーザーを認証し、API リクエストにトークンを追加するアプリケーション。

Verified Permissions が API リクエストを承認する方法

新しいポリシーストアを作成し、Cognito と API Gateway でセットアップ オプションを選択すると、Verified Permissions はポリシーストアスキーマとポリシーを作成します。スキーマとポリシーには、API アクションと、アクションを実行することを許可するユーザープールグループが反映されます。Verified Permissions は、Lambda 関数とオーソライザーも作成します。API のメソッドで新しいオーソライザーを設定する必要があります。

Amazon API Gateway 、Amazon Cognito 、および Amazon Verified Permissions を使用した認証リクエストのフローを示す図。 Amazon Cognito

ユーザーは、Amazon Cognito または別の OIDC IdP を使用してアプリケーションにサインインします。IdP は、ID トークンとアクセストークンをユーザー情報とともに発行します。
アプリケーションは JWTsを保存します。詳細については、「Amazon Cognito デベロッパーガイド」の「ユーザープールでのトークンの使用」を参照してください。 Amazon Cognito
ユーザーは、アプリケーションが外部 API から取得する必要があるデータをリクエストします。
アプリケーションは API Gateway の REST API からデータをリクエストします。ID またはアクセストークンをリクエストヘッダーとして追加します。
API に承認決定のキャッシュがある場合、前のレスポンスが返されます。キャッシュが無効になっている場合、または API に現在のキャッシュがない場合、API Gateway はリクエストパラメータをトークンベースの Lambda オーソライザーに渡します。
Lambda 関数は、 IsAuthorizedWithToken API を使用して Verified Permissions ポリシーストアに認証リクエストを送信します。Lambda 関数は、承認決定の要素を渡します。
1. プリンシパルとしてのユーザーのトークン。
2. API メソッドは、アクションGetPhotoとしてなどの API パスと組み合わせます。
3. リソースApplicationという用語。
Verified Permissions はトークンを検証します。Amazon Cognito トークンの検証方法の詳細については、「Amazon Amazon Cognitoデベロッパーガイド」の「Amazon Verified Permissions による認可」を参照してください。
Verified Permissions は、ポリシーストア内のポリシーと照らし合わせて認証リクエストを評価し、承認決定を返します。
Lambda オーソライザーは API Gateway に Allowまたは Denyレスポンスを返します。
API は、アプリケーションにデータまたはACCESS_DENIEDレスポンスを返します。アプリケーションは API リクエストの結果を処理して表示します。

属性ベースのアクセスコントロール (ABAC) の追加

IdP を使用した一般的な認証セッションは、ID トークンとアクセストークンを返します。これらのトークンタイプのいずれかを、アプリケーションリクエストのベアラートークンとして API に渡すことができます。ポリシーストアの作成時に選択した内容に応じて、Verified Permissions は 2 種類のトークンのいずれかを想定しています。どちらのタイプにも、ユーザーのグループメンバーシップに関する情報が格納されます。Amazon Cognito のトークンタイプの詳細については、「Amazon Cognito デベロッパーガイド」の「ユーザープールでのトークンの使用」を参照してください。 Amazon Cognito

ポリシーストアを作成したら、ポリシーを追加および拡張できます。例えば、ユーザープールに追加するときに、ポリシーに新しいグループを追加できます。ポリシーストアは、ユーザープールがグループをトークンで提示する方法をすでに認識しているため、新しいポリシーを持つ新しいグループに対して一連のアクションを許可できます。

また、ポリシー評価のグループベースのモデルを、ユーザーのプロパティに基づいてより正確なモデルに拡張することもできます。ユーザープールトークンには、承認の決定に役立つ追加のユーザー情報が含まれています。

ID トークン: ID トークンはユーザーの属性を表し、最高レベルのきめ細かなアクセスコントロールを備えています。E メールアドレス、電話番号、部門やマネージャーなどのカスタム属性を評価するには、ID トークンを評価します。
アクセストークン: アクセストークンは、OAuth 2.0 スコープを使用したユーザーのアクセス許可を表します。認証レイヤーを追加したり、追加のリソースのリクエストを設定したりするには、アクセストークンを評価します。例えば、ユーザーが適切なグループに属しており、API へのアクセスを一般的に許可PetStore.readするのようなスコープを保持していることを検証できます。ユーザープールは、リソースサーバーと実行時のトークンカスタマイズを使用して、カスタムスコープをトークンに追加できます。

ID トークンとアクセストークンでクレームを処理するポリシーの例スキーマとポリシーでの ID ソースの使用については、「」を参照してください。

API にリンクされたポリシーストアに関する考慮事項

Verified Permissions コンソールで API にリンクされたポリシーストアを構築すると、最終的な本番デプロイのテストが作成されます。本番環境に移行する前に、API とユーザープールの固定設定を確立します。以下の要素を考慮してください。

API Gateway がレスポンスをキャッシュする

API リンクポリシーストアでは、Verified Permissions は認証キャッシュ TTL が 120 秒の Lambda オーソライザーを作成します。この値は調整することも、オーソライザーのキャッシュをオフにすることもできます。キャッシュが有効になっているオーソライザーでは、TTL の有効期限が切れるまで、オーソライザーは毎回同じレスポンスを返します。これにより、リクエストされたステージのキャッシュ TTL と等しい期間だけ、ユーザープールトークンの有効期間を延長できます。

Amazon Cognito グループは再利用できます

Amazon Verified Permissions は、ユーザーの ID またはアクセストークンの cognito:groupsクレームからユーザープールユーザーのグループメンバーシップを決定します。このクレームの値は、ユーザーが属するユーザープールグループのフレンドリ名の配列です。ユーザープールグループを一意の識別子に関連付けることはできません。

ポリシーストアに同じグループとして存在する同じ名前で削除および再作成するユーザープールグループ。ユーザープールからグループを削除するときは、ポリシーストアからグループへのすべての参照を削除します。

API から派生した名前空間とスキーマは point-in-time

Verified Permissions は、特定の時点で API をキャプチャします。ポリシーストアを作成するときにのみ API をクエリします。API のスキーマまたは名前が変更された場合は、ポリシーストアと Lambda オーソライザーを更新するか、新しい API リンクポリシーストアを作成する必要があります。Verified Permissions は、API の名前からポリシーストアの名前空間を取得します。

Lambda 関数に VPC 設定がない

Verified Permissions が API オーソライザー用に作成する Lambda 関数は VPC に接続されていません。デフォルトでは、プライベート VPCs に制限されたネットワークアクセスを持つ APIs は、Verified Permissions でアクセスリクエストを許可する Lambda 関数と通信できません。

Verified Permissions がにオーソライザーリソースをデプロイする CloudFormation

API リンクポリシーストアを作成するには、権限の高いプリンシパルを Verified AWS Permissions コンソールにサインインする必要があります。このユーザーは、複数のにリソースを作成する AWS CloudFormation スタックをデプロイします AWS のサービス。このプリンシパルには、Verified Permissions、、Lambda IAM、および API Gateway でリソースを追加および変更するアクセス許可が必要です。ベストプラクティスとして、これらの認証情報を組織内の他の管理者と共有しないでください。

Verified Permissions が作成するリソースの概要を使用した本番環境への移行 AWS CloudFormationについては、「」を参照してください。

を使用した本番環境への移行 AWS CloudFormation

API リンクポリシーストアは、API Gateway API の認証モデルをすばやく構築する方法です。アプリケーションの認証コンポーネントのテスト環境として機能するように設計されています。テストポリシーストアを作成したら、ポリシー、スキーマ、および Lambda オーソライザーの改良に時間をかけます。

API のアーキテクチャを調整し、ポリシーストアのスキーマとポリシーに同等の調整が必要になる場合があります。API リンクポリシーストアは、API アーキテクチャからスキーマを自動的に更新しません。検証済みアクセス許可は、ポリシーストアの作成時にのみ API をポーリングします。API が十分に変化する場合は、新しいポリシーストアでプロセスを繰り返す必要がある場合があります。

アプリケーションと認可モデルを本番環境にデプロイする準備ができたら、開発した API リンクポリシーストアをオートメーションプロセスと統合します。ベストプラクティスとして、ポリシーストアのスキーマとポリシーを、他の AWS アカウントとにデプロイできる AWS CloudFormation テンプレートにエクスポートすることをお勧めします AWS リージョン。

API にリンクされたポリシーストアプロセスの結果は、最初のポリシーストアと Lambda オーソライザーです。Lambda オーソライザーには、いくつかの依存リソースがあります。Verified Permissions は、自動的に生成された CloudFormation スタックにこれらのリソースをデプロイします。本番環境にデプロイするには、ポリシーストアと Lambda オーソライザーリソースをテンプレートに収集する必要があります。API にリンクされたポリシーストアは、次のリソースで構成されます。

AWS::VerifiedPermissions::PolicyStore: スキーマを SchemaDefinition オブジェクトにコピーします。エスケープ"文字はです\"。
AWS::VerifiedPermissions::IdentitySource: テストポリシーストアからの出力GetIdentitySource から値をコピーし、必要に応じて変更します。
の 1 つ以上AWS::VerifiedPermissions::Policy: ポリシーステートメントを Definition オブジェクトにコピーします。エスケープ"文字はです\"。
AWS::Lambda::Function 、AWS：IAM::Role 、AWS::IAM::Policy 、AWS::ApiGateway::Authorizer 、AWS::Lambda::Permission: ポリシーストアの作成時に Verified Permissions がデプロイしたスタックのテンプレートタブからテンプレートをコピーします。

次のテンプレートは、ポリシーストアの例です。既存のスタックからこのテンプレートに Lambda オーソライザーリソースを追加できます。


{
    "AWSTemplateFormatVersion": "2010-09-09",
    "Resources": {
        "MyExamplePolicyStore": {
            "Type": "AWS::VerifiedPermissions::PolicyStore",
            "Properties": {
                "ValidationSettings": {
                    "Mode": "STRICT"
                },
                "Description": "ApiGateway: PetStore/test",
                "Schema": {
                    "CedarJson": "{\"PetStore\":{\"actions\":{\"get /pets\":{\"appliesTo\":{\"principalTypes\":[\"User\"],\"resourceTypes\":[\"Application\"],\"context\":{\"type\":\"Record\",\"attributes\":{}}}},\"get /\":{\"appliesTo\":{\"principalTypes\":[\"User\"],\"resourceTypes\":[\"Application\"],\"context\":{\"type\":\"Record\",\"attributes\":{}}}},\"get /pets/{petId}\":{\"appliesTo\":{\"context\":{\"type\":\"Record\",\"attributes\":{}},\"resourceTypes\":[\"Application\"],\"principalTypes\":[\"User\"]}},\"post /pets\":{\"appliesTo\":{\"principalTypes\":[\"User\"],\"resourceTypes\":[\"Application\"],\"context\":{\"type\":\"Record\",\"attributes\":{}}}}},\"entityTypes\":{\"Application\":{\"shape\":{\"type\":\"Record\",\"attributes\":{}}},\"User\":{\"memberOfTypes\":[\"UserGroup\"],\"shape\":{\"attributes\":{},\"type\":\"Record\"}},\"UserGroup\":{\"shape\":{\"type\":\"Record\",\"attributes\":{}}}}}}"
                }
            }
        },
        "MyExamplePolicy": {
            "Type": "AWS::VerifiedPermissions::Policy",
            "Properties": {
                "Definition": {
                    "Static": {
                        "Description": "Policy defining permissions for testgroup cognito group",
                        "Statement": "permit(\nprincipal in PetStore::UserGroup::\"us-east-1_EXAMPLE|testgroup\",\naction in [\n  PetStore::Action::\"get /\",\n  PetStore::Action::\"post /pets\",\n  PetStore::Action::\"get /pets\",\n  PetStore::Action::\"get /pets/{petId}\"\n],\nresource);"
                    }
                },
                "PolicyStoreId": {
                    "Ref": "MyExamplePolicyStore"
                }
            },
            "DependsOn": [
                "MyExamplePolicyStore"
            ]
        },
        "MyExampleIdentitySource": {
            "Type": "AWS::VerifiedPermissions::IdentitySource",
            "Properties": {
                "Configuration": {
                    "CognitoUserPoolConfiguration": {
                        "ClientIds": [
                            "1example23456789"
                        ],
                        "GroupConfiguration": {
                            "GroupEntityType": "PetStore::UserGroup"
                        },
                        "UserPoolArn": "arn:aws:cognito-idp:us-east-1:123456789012:userpool/us-east-1_EXAMPLE"
                    }
                },
                "PolicyStoreId": {
                    "Ref": "MyExamplePolicyStore"
                },
                "PrincipalEntityType": "PetStore::User"
            },
            "DependsOn": [
                "MyExamplePolicyStore"
            ]
        }
    }
}

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

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

ドキュメントの表記規則

ポリシーストアの作成

トラブルシューティング