OAuth 2.0 スコープとリソースサーバーでの API 認可 - Amazon Cognito

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

OAuth 2.0 スコープとリソースサーバーでの API 認可

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

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

ユーザーがユーザープールのローカルユーザーかサードパーティかにかかわらず、またホストされた UI と Amazon Cognito ユーザープール API のどちらで認証するかにかかわらず、ユーザープロファイルが生成できるアクセストークンのスコープでは、ユーザー属性の操作をアプリケーションに許可します。

スコープについて

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

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

aws.cognito.signin.user.admin スコープは Amazon Cognito ユーザープール API を承認します。アクセストークンの所有者に対して、ユーザープールユーザーに関するすべての情報を GetUserUpdateUserAttributes などの API オペレーションを使用してクエリおよび更新することを許可します。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 や他の標準スコープ (profileemailphone など) をリクエストすると、ID トークンと userInfo レスポンスの内容は追加のスコープの制約に制限されます。

例えば、認可エンドポイント へのリクエストでパラメータ scope=openid+email を使用すると、subemailemail_verified を含む ID トークンが返されます。このリクエストのアクセストークンは、UserInfo エンドポイント から同じ属性を返します。リクエストでパラメータ scope=openid を使用すると、ID トークンと userInfo 内のクライアントが読み取り可能なすべての属性が返されます。

profile

アプリクライアントが読み取ることができるすべてのユーザー属性を承認します。

email

ユーザー属性 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 の統合」を参照してください。API Gateway は、アクセストークンの検証とリソースの保護に適したオプションです。API Gateway カスタムオーソライザーの詳細については、「API Gateway Lambda オーソライザーを使用する」を参照してください。

概要

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


                リソースサーバーのフローの概要。クライアントはカスタムスコープでの付与をリクエストし、ユーザープールはカスタムスコープでアクセストークンを返し、クライアントはアクセストークンを API に提示します。

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

注記

InitiateAuth リクエストと AdminInitiateAuth リクエストは、ユーザープールを IdP として人間との対話型の認証を行うように設計されているため、アクセストークンの 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を使用して、ユーザープールのリソースサーバーを定義できます。

リソースサーバーを定義する
  1. Amazon Cognito コンソールにサインインします。

  2. ナビゲーションペインで [User Pools] (ユーザープール) を選択してから、編集するユーザープールを選択します。

  3. [App integration] (アプリケーションの統合) タブを開き、検索する [Resource servers] (リソースサーバー) を検索します。

  4. [Create a resource server] (リソースサーバーの作成) を選択します。

  5. [Resource server name] (リソースサーバー名) を入力します。例えば、Photo Server です。

  6. [Resource server identifier] (リソースサーバー識別子) を入力します。例えば、com.example.photos です。

  7. リソースの [Custom scopes] (カスタムスコープ) (例: read および write ) を入力します。

  8. [Scope name] (スコープ名) ごとに [Description] (説明) (例: view your photos および update your photos) を入力します。

  9. [Create] (作成) を選択します。

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

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

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

リソースサーバーを作成する
リソースサーバーの設定に関する情報を取得する
ユーザープールのすべてのリソースサーバーに関する情報を一覧表示する
リソースサーバーを削除する
リソースサーバーの設定を更新する