翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# API リンクポリシーストア
一般的なユースケースは、Amazon Verified Permissions を使用してAmazon API Gateway でホストされている APIs へのユーザーアクセスを許可することです。 AWS コンソールのウィザードを使用して、[Amazon Cognito](https://aws.amazon.com/cognito) または任意の OIDC ID プロバイダー (IdP) で管理されているユーザーのロールベースのアクセスポリシーを作成し、Verified Permissions を呼び出してこれらのポリシーを評価するオー AWS Lambda ソライザーをデプロイできます。
ウィザードを完了するには、[新しいポリシーストアを作成する](policy-stores-create.md)ときに ** API Gateway と ID プロバイダーでセットアップ**を選択し、ステップに従います。
API リンクポリシーストアが作成され、認可リクエスト用に認可モデルとリソースがプロビジョニングされます。ポリシーストアには、Verified Permissions API Gateway に接続する ID ソースと Lambda オーソライザーがあります。ポリシーストアが作成されたら、ユーザーのグループメンバーシップに基づいて API リクエストを承認できます。例えば、Verified Permissions は、`Directors`グループのメンバーであるユーザーにのみアクセス権を付与できます。
アプリケーションが大きくなるにつれて、[Cedar ポリシー言語](https://docs.cedarpolicy.com/)を使用して、ユーザー属性と OAuth 2.0 スコープによるきめ細かな認可を実装できます。例えば、Verified Permissions は、ドメイン に `email` 属性を持つユーザーにのみアクセス権を付与できます`mycompany.co.uk`。
API の認可モデルを設定した後、残りの責任は、ユーザーを認証し、アプリケーションで API リクエストを生成し、ポリシーストアを維持することです。
デモを確認するには、*Amazon Web Services YouTube チャンネル*の[「Amazon Verified Permissions - Quick Start Overview and Demo](https://www.youtube.com/watch?v=OBrSrzfuWhQ)」を参照してください。
**Topics**
+ [Verified Permissions が API リクエストを承認する方法](#policy-stores-api-userpool-how-it-works)
+ [API リンクポリシーストアに関する考慮事項](#policy-stores-api-userpool-considerations)
+ [属性ベースのアクセスコントロール (ABAC) の追加](#policy-stores-api-userpool-abac)
+ [を使用した本番稼働への移行 AWS CloudFormation](policy-stores-api-userpool-considerations-production.md)
+ [API リンクポリシーストアのトラブルシューティング](policy-stores-api-userpool-considerations-troubleshooting.md)
**重要**
Verified Permissions コンソールの **Set up with API Gateway と ID ソース**オプションを使用して作成したポリシーストアは、本番環境への即時デプロイを意図していません。最初のポリシーストアで、認可モデルを確定し、ポリシーストアリソースを CloudFormation にエクスポートします。を使用して、プログラムで Verified Permissions を本番環境にデプロイします[AWS Cloud Development Kit (AWS CDK)](https://aws.amazon.com/cdk)。詳細については、「[を使用した本番稼働への移行 AWS CloudFormation](policy-stores-api-userpool-considerations-production.md)」を参照してください。
API と ID ソースにリンクされたポリシーストアでは、アプリケーションは API にリクエストを行うときに、認可ヘッダーにユーザープールトークンを表示します。ポリシーストアの ID ソースは、Verified Permissions のトークン検証を提供します。トークンは、[IsAuthorizedWithToken](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_IsAuthorizedWithToken.html) API を使用して認可リクエスト`principal`で を形成します。Verified Permissions は、アイデンティティ (ID) のグループクレームや、ユーザープールなどのアクセストークンに表示されるように、`cognito:groups`ユーザーのグループメンバーシップに関するポリシーを構築します。API は Lambda オーソライザーでアプリケーションからトークンを処理し、認可決定のために Verified Permissions に送信します。API が Lambda オーソライザーから認可決定を受け取ると、リクエストをデータソースに渡すか、リクエストを拒否します。
**Verified Permissions を使用した ID ソースと API Gateway 認可のコンポーネント**
+ [Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools.html) ユーザーを認証してグループ化するユーザープールまたは OIDC IdP。ユーザーのトークンは、ポリシーストアで Verified Permissions が評価するグループメンバーシップとプリンシパルまたはコンテキストを入力します。
+ [API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-rest-api.html) REST API。Verified Permissions は、 などの API パスと API メソッドからのアクションを定義します`MyAPI::Action::get /photo`。
+ API の Lambda 関数と [Lambda オーソライザー](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html)。Lambda 関数は、ユーザープールからベアラートークンを取得し、Verified Permissions に認可をリクエストして、決定を返します API Gateway。** API Gateway と ID ソースワークフローでセットアップすると、**この Lambda オーソライザーが自動的に作成されます。
+ Verified Permissions ポリシーストア。ポリシーストア ID ソースは、 Amazon Cognito ユーザープールまたは OIDC プロバイダーグループです。ポリシーストアスキーマは API の設定を反映し、ポリシーはユーザーグループを許可された API アクションにリンクします。
+ IdP でユーザーを認証し、API リクエストにトークンを追加するアプリケーション。
## Verified Permissions が API リクエストを承認する方法
新しいポリシーストアを作成し、**Set up with API Gateway and an identity source** オプションを選択すると、Verified Permissions はポリシーストアスキーマとポリシーを作成します。スキーマとポリシーには、API アクションと、アクションを実行することを許可するユーザーグループが反映されます。Verified Permissions は、Lambda 関数と[オーソライザー](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html)も作成します。
1. ユーザーは、 Amazon Cognito または別の OIDC IdP を使用してアプリケーションにサインインします。IdP は、ID トークンとアクセストークンをユーザー情報で発行します。
1. アプリケーションは JWTsを保存します。詳細については、[「 デベロッパーガイド」の「ユーザープールでのトークンの使用](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html)」を参照してください。 *Amazon Cognito *
1. ユーザーは、アプリケーションが外部 API から取得する必要があるデータをリクエストします。
1. アプリケーションは、 の REST API からデータをリクエストします API Gateway。ID またはアクセストークンをリクエストヘッダーとして追加します。
1. API に認可決定のキャッシュがある場合、前のレスポンスが返されます。キャッシュが無効になっている場合、または API に現在のキャッシュがない場合、 API Gateway はリクエストパラメータを[トークンベースの Lambda オーソライザー](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html)に渡します。
1. Lambda 関数は、[IsAuthorizedWithToken](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_IsAuthorizedWithToken.html) API を使用して Verified Permissions ポリシーストアに認可リクエストを送信します。Lambda 関数は、認可決定の要素を渡します。
1. プリンシパルとしてのユーザーのトークン。
1. アクションとして、 API メソッドを API パス、たとえば `GetPhoto`と組み合わせて使用します。
1. リソース`Application`という用語。
1. Verified Permissions はトークンを検証します。 Amazon Cognito トークンの検証方法の詳細については、「 *Amazon Cognito デベロッパーガイド*」の[「Amazon Verified Permissions による認可](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-authorization-with-avp.html)」を参照してください。
1. Verified Permissions は、ポリシーストア内のポリシーに対して認可リクエストを評価し、認可決定を返します。
1. Lambda オーソライザーは `Allow`または `Deny`レスポンスを返します API Gateway。
1. API は、アプリケーションにデータまたは`ACCESS_DENIED`レスポンスを返します。アプリケーションは API リクエストの結果を処理して表示します。
## 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 の名前からポリシーストアの名前[空間](https://docs.cedarpolicy.com/schema/schema.html#schema-namespace)を取得します。
**Lambda 関数に VPC 設定がない**
Verified Permissions が API オーソライザー用に作成する Lambda 関数は、デフォルトの VPC で起動されます。デフォルトでは です。プライベート VPCs に制限されたネットワークアクセスを持つ APIs は、Verified Permissions でアクセスリクエストを許可する Lambda 関数と通信できません。
**Verified Permissions が CloudFormation にオーソライザーリソースをデプロイする**
API リンクポリシーストアを作成するには、権限の高いプリンシパルを Verified AWS Permissions コンソールにサインインする必要があります。このユーザーは、複数の にまたがってリソースを作成する CloudFormation スタックをデプロイします AWS のサービス。このプリンシパルには、Verified Permissions、 IAM、Lambda、および でリソースを追加および変更するアクセス許可が必要です API Gateway。ベストプラクティスとして、これらの認証情報を組織内の他の管理者と共有しないでください。
Verified Permissions が作成するリソースの概要[を使用した本番稼働への移行 AWS CloudFormation](policy-stores-api-userpool-considerations-production.md)については、「」を参照してください。
## 属性ベースのアクセスコントロール (ABAC) の追加
IdP を使用した一般的な認証セッションは、ID トークンとアクセストークンを返します。これらのトークンタイプのいずれかを、API へのアプリケーションリクエストでベアラートークンとして渡すことができます。ポリシーストアの作成時に選択した内容に応じて、Verified Permissions は 2 種類のトークンのいずれかを想定しています。どちらのタイプも、ユーザーのグループメンバーシップに関する情報を保持します。のトークンタイプの詳細については Amazon Cognito、[「 デベロッパーガイド」の「ユーザープールでのトークンの使用](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html)」を参照してください。 *Amazon Cognito *
ポリシーストアを作成したら、ポリシーを追加および拡張できます。たとえば、新しいグループをユーザープールに追加するときに、ポリシーに追加できます。ポリシーストアは、ユーザープールがトークンでグループを表示する方法をすでに認識しているため、新しいポリシーを持つ新しいグループに対して一連のアクションを許可できます。
また、ポリシー評価のグループベースのモデルを、ユーザープロパティに基づいてより正確なモデルに拡張することもできます。ユーザープールトークンには、認可の決定に役立つ追加のユーザー情報が含まれています。
**ID トークン**
ID トークンはユーザーの属性を表し、高レベルのきめ細かなアクセスコントロールを備えています。E メールアドレス、電話番号、部門やマネージャーなどのカスタム属性を評価するには、ID トークンを評価します。
**アクセストークン**
アクセストークンは、OAuth 2.0 スコープを使用したユーザーのアクセス許可を表します。認可レイヤーを追加したり、追加のリソースのリクエストをセットアップしたりするには、アクセストークンを評価します。たとえば、ユーザーが適切なグループに属*しており、* API へのアクセスを一般的に許可`PetStore.read`する のようなスコープを保持していることを検証できます。ユーザープールは、実行時に[リソースサーバー](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-define-resource-servers.html)とトークンのカスタマイズを使用して、カスタムスコープをトークンに追加できます。 [https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-pre-token-generation.html#user-pool-lambda-pre-token-generation-accesstoken](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-pre-token-generation.html#user-pool-lambda-pre-token-generation-accesstoken)
ID [Amazon Cognito トークンとアクセストークンでクレームを処理するポリシーの例については、「スキーマ](cognito-map-token-to-schema.md)へのトークンの[マッピング」と「スキーマへの OIDC](oidc-map-token-to-schema.md) トークンのマッピング」を参照してください。