リソースサーバーを使用したスコープ、M2M、および API

ユーザープールのドメインを設定すると、Amazon Cognito は OAuth 2.0 認可サーバーおよびホストされたウェブ UI を自動的にプロビジョニングします。このウェブ UI により、アプリケーションはユーザーにサインアップページとサインインページを表示できます。詳細については、「ホストされた UI を使用してアプリケーションクライアントを追加する」を参照してください。認可サーバーによってアクセストークンに追加するスコープを選択できます。スコープはリソースサーバーとユーザーデータへのアクセスを許可します。

リソースサーバーとは、OAuth 2.0 API サーバーのことです。リソースサーバーは、アクセスが保護されたリソースを保護するために、保護対象の API でリクエストされたメソッドとパスを承認するスコープが、ユーザープールのアクセストークンに含まれていることを検証します。トークンの署名に基づく発行者の検証、トークンの有効期限に基づく有効性の検証、トークンクレームのスコープに基づくアクセスレベルの検証を行います。ユーザープールスコープは、アクセストークンの scope クレームにあります。Amazon Cognito アクセストークンのクレームの詳細については、「アクセストークンの理解」を参照してください。

Amazon Cognito を使用すると、アクセストークンのスコープは、外部 API またはユーザー属性へのアクセスを認可できます。アクセストークンは、ローカルユーザー、フェデレーションユーザー、またはマシン ID に発行できます。

API 認可

以下は、Amazon Cognito トークンを使用して API へのリクエストを認可する方法の一部です。

Machine to machine (M2M) 認可

Amazon Cognito は、マシン ID を使用して API データにアクセスするアプリケーションをサポートしています。ユーザープール内のマシン ID は、アプリケーションサーバー上で実行され、リモート API に接続する機密クライアントです。オペレーションは、スケジュールされたタスク、データストリーム、アセットの更新など、ユーザーとのインタラクションなしで行われます。これらのクライアントは、アクセストークンを使用してリクエストを認可すると、Machine to Machine (M2M) 認可を実行します。M2M 認可では、共有シークレットがアクセスコントロールのユーザー認証情報を置き換えます。

M2M 認可で API にアクセスするアプリケーションには、クライアント ID とクライアントシークレットが必要です。ユーザープールでは、クライアント認証情報の付与をサポートするアプリケーションクライアントを構築する必要があります。クライアント認証情報をサポートするには、アプリケーションクライアントにクライアントシークレットが必要であり、ユーザープールドメインがなくてはなりません。このフローでは、マシン ID は トークンエンドポイント から直接アクセストークンをリクエストします。クライアント認証情報の付与には、アクセストークン内のリソースサーバーからのカスタムスコープのみを認可できます。アプリケーションクライアントのセットアップの詳細については、「アプリケーションクライアントによるアプリケーション固有の設定」を参照してください。

クライアント認証情報の付与からのアクセストークンは、マシン ID が API にリクエストすることを許可するオペレーションの検証可能なステートメントです。アクセストークンが API リクエストを認可する方法の詳細については、引き続きお読みください。アプリケーションの例については、「Amazon Cognito and API Gateway based machine to machine authorization using AWS CDK」を参照してください。

M2M 認可には、月間アクティブユーザー (MAU) に請求する方法とは異なる請求モデルがあります。ユーザー認証にアクティブなユーザーあたりのコストがかかる場合、M2M 請求にはアクティブなクライアント認証情報アプリケーションクライアントと、トークンリクエストの合計ボリュームが反映されます。詳細については、「Amazon Cognito の料金」を参照してください。M2M 認可のコストを制御するには、アクセストークンの期間と、アプリケーションが行うトークンリクエストの数を最適化します。API Gateway キャッシングを使用して M2M 認可の新しいトークンのリクエストを減らす方法については、「ユーザープールトークンの有効期限とキャッシュの管理」を参照してください。

AWS 請求のコスト増となる Amazon Cognito オペレーションの最適化については、「 のコスト管理」を参照してください。

スコープについて

スコープはアプリがリソースにリクエストできるアクセスのレベルです。Amazon Cognito アクセストークンのスコープは、ユーザープールで設定した信頼 (既知のデジタル署名を持つアクセストークンの信頼できる発行者) によってバックアップされます。ユーザープールが生成できるアクセストークンのスコープでは、顧客が自分のユーザープロファイルの一部または全部の管理や、バックエンド API からのデータの取得を許可されていることを証明します。Amazon Cognito ユーザープールが発行するアクセストークンのスコープには、ユーザープールのリザーブド API スコープ、カスタムスコープ、および OpenID Connect (OIDC) スコープがあります。

ユーザープールのリザーブド API スコープ

aws.cognito.signin.user.admin スコープは、Amazon Cognito ユーザープール API の現在のユーザーのセルフサービスオペレーションを認可します。アクセストークンのベアラーに対して、当該ベアラーに関するすべての情報を、GetUser や UpdateUserAttributes などの API オペレーションを使用してクエリおよび更新することを認可します。Amazon Cognito ユーザープール API でユーザーを認証する場合は、このスコープだけをアクセストークンで受け取ります。また、アプリケーションクライアントにユーザー属性の読み取りと書き込みを許可している場合、このユーザー属性の読み取りと書き込みに必要な唯一のスコープでもあります。このスコープは、認可エンドポイント へのリクエストでリクエストすることもできます。このスコープだけでは、userInfo エンドポイント にユーザー属性をリクエストするには不十分です。ユーザープール API とユーザーへの userInfo リクエストの両方を承認するアクセストークンについては、/oauth2/authorize リクエストで openid スコープと aws.cognito.signin.user.admin スコープの両方をリクエストする必要があります。

カスタムスコープ

カスタムスコープは、リソースサーバーで保護する外部 API へのリクエストを承認します。カスタムスコープを他の種類のスコープと一緒にリクエストできます。カスタムスコープの詳細については、このページ全体を通じて説明しています。

OpenID Connect (OIDC) のスコープ

ユーザープール認可サーバー (ホストされた UI を含む) でユーザーを認証する場合は、スコープをリクエストする必要があります。ユーザープールのローカルユーザーとサードパーティのフェデレーションユーザーは、Amazon Cognito 認可サーバーで認証できます。OIDC スコープは、ユーザープールの userInfo エンドポイント からユーザー情報を読み取ることをアプリケーションに認可します。userInfo エンドポイントからユーザー属性をクエリする OAuth モデルでは、ユーザー属性に対する大量のリクエストに合わせてアプリケーションを最適化できます。userInfo エンドポイントは、アクセストークンのスコープによって決まるアクセス許可レベルで属性を返します。以下の OIDC スコープでアクセストークンを発行することをアプリケーションクライアントに認可できます。

リソースサーバーについて

リソースサーバー API は、データベース内の情報へのアクセスを許可したり、IT リソースを制御したりすることができます。Amazon Cognito のアクセストークンは、OAuth 2.0 をサポートする API へのアクセスを許可できます。Amazon API Gateway REST API には、Amazon Cognito のアクセストークンによる認可の組み込みサポートがあります。アプリは、API コール内でアクセストークンをリソースサーバーに渡します。リソースサーバーはアクセストークンを検査し、アクセスを付与するかどうかを決定します。

Amazon Cognito は、ユーザープールのアクセストークンのスキーマを将来更新する可能性があります。アプリケーションがアクセストークンを API に渡す前に、アクセストークンの内容を分析する場合は、スキーマの更新を受け入れるようにコードを設計する必要があります。

カスタムスコープはユーザーが定義するスコープであり、ユーザープールの承認機能を拡張して、ユーザーとユーザー属性のクエリや変更とは関係のない目的にも対応できるようにします。例えば、写真用のサーバーリソースがある場合、2 つのスコープを定義することが考えられます。写真への読み取りアクセス用の photos.read と、書き込み/削除アクセス用の photos.write です。アクセストークンを承認して許可するように API を設定し、scope クレームでの photos.read によるアクセストークンへの HTTP GET リクエスト、および photos.write によるトークンへの HTTP POSTリクエストを許可できます。これらはカスタムスコープです。

概要

Amazon Cognito を使用すると、OAuth2.0 リソースサーバーを作成し、これらにカスタムスコープを関連付けることができます。アクセストークンのカスタムスコープは、API の特定のアクションを許可します。ユーザープール内のどのアプリケーションクライアントに対しても、任意のリソースサーバーからカスタムスコープを発行することを許可できます。カスタムスコープをアプリケーションクライアントに関連付け、これらのスコープを トークンエンドポイントから OAuth2.0 認可コード付与、暗黙的な付与、クライアント認証情報付与でリクエストできます。Amazon Cognito は、アクセストークンの scope クレームにカスタムスコープを追加します。クライアントはサーバーリソースに対してアクセストークンを使用して、トークンに存在するスコープに基づいて承認を判断できます。アクセストークンスコープの詳細については、「ユーザープールのトークンの使用」を参照してください。

カスタムスコープでアクセストークンを取得するには、アプリケーションは認可コードを引き換えるか、クライアント認証情報の付与をリクエストするために、トークンエンドポイント にリクエストを行う必要があります。ホストされた UI では、暗黙的付与からアクセストークンのカスタムスコープをリクエストすることもできます。

リソースサーバーおよびカスタムスコープの管理

リソースを作成するときに、リソースサーバー名とリソースサーバー識別子を指定する必要があります。リソースサーバーに作成したスコープごとに、スコープ名と説明を指定する必要があります。

Amazon Cognito では、ユーザープールのローカルユーザーであるか、サードパーティ ID プロバイダーのフェデレーションユーザーであるかに関係なく、すべてのユーザーのアクセストークンにカスタムスコープを含めることができます。ホストされた UI を含む OAuth 2.0 認可サーバーでは、認証フロー中にユーザーのアクセストークンのスコープを選択できます。ユーザーの認証は、リクエストパラメータの 1 つとして scope を使用して 認可エンドポイント で開始する必要があります。リソースサーバーには次の形式が推奨されます。識別子として、API のわかりやすい名前を使用します。カスタムスコープには、リソースサーバーが許可するアクションを使用します。

resourceServerIdentifier/scopeName

例えば、カイパーベルトで新しい小惑星を発見し、それを solar-system-data API を通じて登録するとします。小惑星のデータベースへの書き込み操作を許可するスコープは asteroids.add です。発見の登録を許可するアクセストークンをリクエストするときは、scope HTTPS リクエストパラメータを scope=solar-system-data/asteroids.add としてフォーマットします。

スコープをリソースサーバーから削除しても、すべのクライアントとの関連付けは削除されません。代わりに、スコープが inactive とマークされます。Amazon Cognito はアクセストークンに非アクティブなスコープを追加しませんが、それ以外はアプリからのスコープのリクエストを通常どおりに処理します。後でスコープをリソースサーバーに再度追加すると、Amazon Cognito はそのスコープを再度アクセストークンに書き込みます。アプリケーションクライアントに関連付けていないスコープをリクエストすると、ユーザープールのリソースサーバーからスコープを削除したかどうかに関係なく、認証は失敗します。

AWS Management Console、API、または CLI を使用して、ユーザープールのリソースサーバーとスコープを定義できます。

ユーザープールのリソースサーバーを定義する (AWS Management Console)

AWS Management Consoleを使用して、ユーザープールのリソースサーバーを定義できます。

カスタムスコープは、[Custom scopes] (カスタムスコープ) 列にある、[Resource servers] (リソースサーバー) の [App integration] (アプリケーションの統合) タブで確認できます。カスタムスコープは、アプリケーションクライアントに対して [App integration] (アプリケーションクライアント) タブの下にある [App integration] (アプリケーションの統合) で有効にできます。アプリケーションクライアントを選択し、[Hosted UI settings] (ホストされた UI の設定) を検索して [Edit] (編集) を選択します。[Custom scopes] (カスタムスコープ) を追加し、[Save changes] (変更の保存) を選択します。

ユーザープールのリソースサーバーを定義する (AWS CLI および AWS API)

次のコマンドを使用して、ユーザープールのリソースサーバー設定を指定します。