翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
スコープ、M2M 、およびリソースサーバーによる API 認証
ユーザープールのドメインを設定すると、Amazon Cognito は OAuth 2.0 認可サーバーおよびホストされたウェブ UI を自動的にプロビジョニングします。このウェブ UI により、アプリケーションはユーザーにサインアップページとサインインページを表示できます。詳細については、ホストされた UI でアプリクライアントを追加するを参照してください。認証サーバーによってアクセストークンに追加するスコープを選択できます。スコープはリソースサーバーとユーザーデータへのアクセスを許可します。
リソースサーバーとは、OAuth 2.0 API サーバーscope
クレームにあります。Amazon Cognito アクセストークンのクレームの詳細については、「アクセストークンの使用」を参照してください。
Amazon Cognito を使用すると、アクセストークンのスコープは、外部 APIs またはユーザー属性へのアクセスを許可できます。ローカルユーザー、フェデレーティッドユーザー、またはマシン ID にアクセストークンを発行できます。
M achine-to-machine (M2M) 認証
Amazon Cognito は、マシン ID を使用して API データにアクセスするアプリケーションをサポートします。ユーザープール内のマシン ID は、アプリケーションサーバー上で実行され、リモート API に接続する機密クライアントです。 APIs オペレーションは、スケジュールされたタスク、データストリーム、アセットの更新など、ユーザーとのやり取りなしに行われます。これらのクライアントは、アクセストークンを使用してリクエストを承認すると、マシン間 、または M2M 認証を実行します。M2M 認証では、共有シークレットがアクセスコントロールのユーザー認証情報を置き換えます。
M2M 認証で API にアクセスするアプリケーションには、クライアント ID とクライアントシークレットが必要です。ユーザープールでは、クライアント認証情報の付与をサポートするアプリケーションクライアントを構築する必要があります。クライアント認証情報をサポートするには、アプリケーションクライアントにクライアントシークレットが必要であり、ユーザープールドメインが必要です。このフローでは、マシン ID は から直接アクセストークンをリクエストしますトークンエンドポイント。クライアント認証情報の付与には、アクセストークン内のリソースサーバーからのカスタムスコープのみを許可できます。アプリケーションクライアントの設定の詳細については、「」を参照してくださいユーザープールアプリクライアント。
クライアント認証情報付与からのアクセストークンは、マシン ID が API からリクエストすることを許可するオペレーションの検証可能なステートメントです。アクセストークンが API リクエストを承認する方法の詳細については、「」を参照してください。アプリケーションの例については、Amazon Cognito および API Gateway ベースのマシン間認証 CDK を使用した AWS マシン間認証
M2M 認証には、毎月のアクティブユーザー (MAUs請求する方法とは異なる請求モデルがあります。ユーザー認証にアクティブなユーザーあたりのコストがかかる場合、M2M 請求にはアクティブなクライアント認証情報アプリケーションクライアントとトークンリクエストの合計ボリュームが反映されます。詳細については、「Amazon Cognito の料金
AWS 請求書にコストを追加する Amazon Cognito オペレーションの最適化については、「」を参照してください のコスト管理。
スコープについて
スコープはアプリがリソースにリクエストできるアクセスのレベルです。Amazon Cognito アクセストークンのスコープは、ユーザープールで設定した信頼 (既知のデジタル署名を持つアクセストークンの信頼できる発行者) によってバックアップされます。ユーザープールが生成できるアクセストークンのスコープでは、顧客が自分のユーザープロファイルの一部または全部の管理や、バックエンド API からのデータの取得を許可されていることを証明します。Amazon Cognito ユーザープールが発行するアクセストークンのスコープには、ユーザープールのリザーブド API スコープ、カスタムスコープ、および標準スコープがあります。
ユーザープールのリザーブド API スコープ
aws.cognito.signin.user.admin
スコープは Amazon Cognito ユーザープール API を承認します。これにより、アクセストークンのベアラーが、 および UpdateUserAttributes API オペレーションなどを使用して、ユーザープールユーザーに関するすべての情報をクエリGetUserおよび更新することを許可されます。Amazon Cognito ユーザープール API でユーザーを認証する場合は、このスコープだけをアクセストークンで受け取ります。また、アプリケーションクライアントにユーザー属性の読み取りと書き込みを許可している場合、このユーザー属性の読み取りと書き込みに必要な唯一のスコープでもあります。このスコープは、認可エンドポイント へのリクエストでリクエストすることもできます。このスコープだけでは、UserInfo エンドポイント にユーザー属性をリクエストするには不十分です。ユーザープール API とユーザーへの userInfo
リクエストの両方を承認するアクセストークンについては、/oauth2/authorize
リクエストで openid
スコープと aws.cognito.signin.user.admin
スコープの両方をリクエストする必要があります。
カスタムスコープ
カスタムスコープは、リソースサーバーで保護する外部 API へのリクエストを承認します。カスタムスコープを他の種類のスコープと一緒にリクエストできます。カスタムスコープの詳細については、このページ全体を通じて説明しています。
標準スコープ
ユーザープール OAuth 2.0 認証サーバー (ホストされた UI を含む) でユーザーを認証する場合は、スコープをリクエストする必要があります。ユーザープールのローカルユーザーとサードパーティのフェデレーションユーザーは、Amazon Cognito 認証サーバーで認証できます。標準 OAuth 2.0 スコープは、ユーザープールの UserInfo エンドポイント からユーザー情報を読み取ることをアプリケーションに許可します。userInfo
エンドポイントからユーザー属性をクエリする OAuth モデルでは、ユーザー属性に対する大量のリクエストに合わせてアプリケーションを最適化できます。userInfo
エンドポイントは、アクセストークンのスコープによって決まるアクセス許可レベルで属性を返します。以下の標準 OAuth 2.0 スコープでアクセストークンを発行することをアプリクライアントに許可できます。
- openid
-
OpenID Connect (OIDC) クエリの最小スコープ。ID トークン、一意の識別子のクレーム
sub
、および他のスコープをリクエストする機能を承認します。注記
openid
スコープをリクエストし、それ以外をリクエストしない場合、ユーザープール ID トークンとuserInfo
レスポンスには、アプリケーションクライアントが読み取ることができるすべてのユーザー属性のクレームが含まれます。openid
や他の標準スコープ (profile
、email
、phone
など) をリクエストすると、ID トークンと userInfo レスポンスの内容は追加のスコープの制約に制限されます。例えば、認可エンドポイント へのリクエストでパラメータ
scope=openid+email
を使用すると、sub
、email
、email_verified
を含む ID トークンが返されます。このリクエストのアクセストークンは、UserInfo エンドポイント から同じ属性を返します。リクエストでパラメータscope=openid
を使用すると、ID トークンとuserInfo
内のクライアントが読み取り可能なすべての属性が返されます。 - profile
-
アプリクライアントが読み取ることができるすべてのユーザー属性を承認します。
-
ユーザー属性
email
およびemail_verified
を承認します。Amazon Cognito は、値が明示的に設定されている場合、email_verified
を返します。 - phone
-
ユーザー属性
phone_number
およびphone_number_verified
を承認します。
リソースサーバーについて
リソースサーバー 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
リクエストを許可できます。これらはカスタムスコープです。
注記
リソースサーバーはトークン内のクレームを処理する前に、アクセストークンの署名と有効期限を検証する必要があります。トークンの検証の詳細については、「JSON Web トークンの検証」を参照してください。Amazon API Gateway でユーザープールのトークンを検証および使用する方法の詳細については、ブログ「Amazon Cognito ユーザープールと API Gateway の統合
概要
Amazon Cognito を使用すると、OAuth2.0 リソースサーバーを作成し、これらにカスタムスコープを関連付けることができます。アクセストークンのカスタムスコープは、API の特定のアクションを許可します。ユーザープール内のどのアプリケーションクライアントに対しても、任意のリソースサーバーからカスタムスコープを発行することを許可できます。カスタムスコープをアプリケーションクライアントに関連付け、これらのスコープを トークンエンドポイント から OAuth2.0 認証コード付与、暗黙的な付与、クライアント認証情報付与でリクエストできます。Amazon Cognito は、アクセストークンの scope
クレームにカスタムスコープを追加します。クライアントはサーバーリソースに対してアクセストークンを使用して、トークンに存在するスコープに基づいて承認を判断できます。アクセストークンスコープの詳細については、「ユーザープールのトークンの使用」を参照してください。
カスタムスコープでアクセストークンを取得するには、アプリは認証コードを引き換えるか、クライアント認証情報の付与をリクエストするために、トークンエンドポイント にリクエストを行う必要があります。ホストされた UI では、暗黙的付与からアクセストークンのカスタムスコープをリクエストすることもできます。
注記
これらは IdP としてユーザープールとのヒューマンインタラクティブ認証用に設計されているため、 InitiateAuthAdminInitiateAuthリクエストは単一の値 を持つアクセストークンにのみscope
クレームを生成しますaws.cognito.signin.user.admin
。
リソースサーバーおよびカスタムスコープの管理
リソースを作成するときに、リソースサーバー名とリソースサーバー識別子を指定する必要があります。リソースサーバーに作成したスコープごとに、スコープ名と説明を指定する必要があります。
-
リソースサーバー名: リソースサーバーのわかりやすい名前 (
Solar system object tracker
やPhoto API
など)。 -
リソースサーバーの識別子: リソースサーバーの一意の識別子。識別子は、API に関連付ける任意の名前 (
solar-system-data
など) です。API URI パスへの直接参照のように長い識別子 (https://solar-system-data-api.example.com
など) を設定できますが、文字列が長くなるとアクセストークンのサイズが大きくなります。 -
スコープ名:
scope
クレームに必要な値。例えばsunproximity.read
です。 -
説明: スコープのわかりやすい説明。例えば
Check current proximity to sun
です。
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 、ユーザープールのリソースサーバーを定義できます。
リソースサーバーを定義する
-
Amazon Cognito コンソール
にサインインします。 -
ナビゲーションペインで [User Pools] (ユーザープール) を選択してから、編集するユーザープールを選択します。
-
[App integration] (アプリケーションの統合) タブを開き、検索する [Resource servers] (リソースサーバー) を検索します。
-
[Create a resource server] (リソースサーバーの作成) を選択します。
-
[Resource server name] (リソースサーバー名) を入力します。例えば
Photo Server
です。 -
[Resource server identifier] (リソースサーバー識別子) を入力します。例えば
com.example.photos
です。 -
リソースの [Custom scopes] (カスタムスコープ) (例:
read
およびwrite
) を入力します。 -
[Scope name] (スコープ名) ごとに [Description] (説明) (例:
view your photos
およびupdate your photos
) を入力します。 -
[作成] を選択します。
カスタムスコープは、[Custom scopes] (カスタムスコープ) 列にある、[Resource servers] (リソースサーバー) の [App integration] (アプリケーションの統合) タブで確認できます。カスタムスコープは、アプリケーションクライアントに対して [App integration] (アプリケーションクライアント) タブの下にある [App integration] (アプリケーションの統合) で有効にできます。アプリケーションクライアントを選択し、[Hosted UI settings] (ホストされた UI の設定) を検索して [Edit] (編集) を選択します。[Custom scopes] (カスタムスコープ) を追加し、[Save changes] (変更の保存) を選択します。
ユーザープール (AWS CLI および AWS API) のリソースサーバーの定義
次のコマンドを使用して、ユーザープールのリソースサーバー設定を指定します。
リソースサーバーを作成する
-
AWS CLI:
aws cognito-idp create-resource-server
-
AWS API: CreateResourceServer
リソースサーバーの設定に関する情報を取得する
-
AWS CLI:
aws cognito-idp describe-resource-server
-
AWS API: DescribeResourceServer
ユーザープールのすべてのリソースサーバーに関する情報を一覧表示する
-
AWS CLI:
aws cognito-idp list-resource-servers
-
AWS API: ListResourceServers
リソースサーバーを削除する
-
AWS CLI:
aws cognito-idp delete-resource-server
-
AWS API: DeleteResourceServer
リソースサーバーの設定を更新する
-
AWS CLI:
aws cognito-idp update-resource-server
-
AWS API: UpdateResourceServer