Resource Owner Password Flow を使用して独自の API を呼び出す

Resource Owner Password Flow を使用して、高い信頼性が求められるアプリケーションから独自の API を呼び出す方法を学びます。

このチュートリアルでは、Resource Owner Password Flow を使用して独自の API を呼び出す方法を説明します。このフローの仕組みや、これを使用すべき理由について詳しくは、Resource Owner Password Flowを参照してください。

Resource Owner Password (ROP) Flow ではアプリケーションがユーザーのパスワードを扱うため、サードパーティのクライアントで使用してはなりません。

Auth0 を使うと、Authentication API を使用して、アプリケーションに リソースオーナー Password Flow (Resource Owner Password Grant または ROPG とも呼ばれます) を簡単に実装できます。以降では、API を直接呼び出す方法を説明します。

​

前提条件

このチュートリアルを始める前に、以下を確認してください。

• Auth0 にアプリケーションを登録する。

  • Application Type で Regular Web Apps を選択します。
  • Allowed Callback URL に {https://yourApp/callback} を追加します。このフィールドを未設定のままにすると、エラーメッセージが返されます。
  • アプリケーションの Grant Types に Password が含まれていることを確認します。手順については、Grant Types を更新する を参照してください。
  • アプリケーションでリフレッシュトークンを使用できるようにするには、アプリケーションの Grant Types に Refresh Token が含まれていることを確認します。手順については、Grant Types を更新する を参照してください。リフレッシュトークンの詳細については、Refresh Tokens を参照してください。

• Auth0 に API を登録する

  • API が以前のトークンの有効期限が切れたときに新しいトークンを取得できるよう、API でリフレッシュトークンを受け取れるようにする場合は、Allow Offline Access を有効にします。

• 接続を設定する

  • 接続が username とパスワードでユーザーを認証できることを確認します (たとえば、データベース接続、または AD/LDAP、ADFS、Azure Active Directory の エンタープライズ接続) 。

• Rules を更新または無効にして、特定の接続にのみ影響するようにします。Password Owner Resource Grant のテスト中に access_denied エラーが発生する場合は、アクセス制御の Rule が原因である可能性があります。

​

手順

1. テナントを設定:テナントのデフォルト接続を設定します。
2. トークンを取得: 認可コードをトークンに交換します。
3. APIを呼び出す: 取得したアクセストークンを使用してAPIを呼び出します。
4. トークンを更新: 既存のトークンの有効期限が切れたら、リフレッシュトークンを使用して新しいトークンをリクエストします。

任意: サンプルのユースケースを確認

任意: レルムサポートを設定

任意: MFAを設定

任意: アタックプロテクションを設定

​

テナントを設定する

Resource Owner Password Flow は、ユーザー名とパスワードでユーザーを認証できる接続に依存するため、テナントのデフォルト接続を設定する必要があります。

1. Auth0 Dashboard > Tenant Settings に移動し、下にスクロールして Default Directory 設定を探します。
2. 使用する接続の名前を入力します。その接続が、ユーザー名とパスワードによるユーザー認証に対応していることを確認してください。

​

トークンをリクエストする

API を呼び出すには、まずユーザーの認証情報を取得する必要があります。通常は、インタラクティブなフォームを使用して取得します。アプリケーションが認証情報を取得したら、それをトークンに交換する必要があります。そのためには、トークンURL に POST リクエストを送信します。

​

トークンURLへのPOSTリクエストの例

パラメーター

パラメーター名	説明
grant_type	password に設定します。
username	ユーザーが入力した username。
password	ユーザーが入力したパスワード。
client_id	アプリケーションのクライアントIDです。この値は Application Settings で確認できます。
client_assertion	アプリケーションの認証情報で署名したアサーションを含む JWT です。アプリケーションの認証方法が Private Key JWT の場合に必要です。
client_assertion_type	値は urn:ietf:params:oauth:client-assertion-type:jwt-bearer です。アプリケーションの認証方法が Private Key JWT の場合に必要です。
client_secret	アプリケーションのクライアントシークレットです。アプリケーションの認証方法が Client Secret の場合に必要です。Application Settings でアプリケーション認証方法が Post または Basic に設定されている場合に使用します。アプリケーションの信頼性が高くない場合 (たとえば SPA など) は、このパラメーターを設定しないでください。
audience	トークンのオーディエンスです。これは API を指定します。この値は API’s settings tab の Identifier フィールドで確認できます。
scope	認可をリクエストする スコープ を指定します。これにより、返されるクレーム (またはユーザー属性) が決まります。各値はスペースで区切る必要があります。profile や email など、ユーザーに関する 標準の OpenID Connect (OIDC) スコープ、namespaced format に準拠した カスタムクレーム、または対象 API がサポートする任意のスコープ (例: read:contacts) をリクエストできます。Refresh Token を取得するには offline_access を含めます (Application Settings で Allow Offline Access フィールドが有効になっていることを確認してください) 。

​

レスポンス

正常に処理されると、access_token、refresh_token、id_token、token_type、expires_in の各値を含むペイロードを伴う HTTP 200 レスポンスが返されます。

{
  "access_token": "eyJz93a...k4laUWw",
  "refresh_token": "GEbRxBN...edjnXbL",
  "id_token": "eyJ0XAi...4faeEoQ",
  "token_type": "Bearer",
  "expires_in": 36000
}

保存する前に、トークンを検証してください。方法については、IDトークンの検証およびアクセストークンの検証を参照してください。

リフレッシュトークンを使うと、ユーザーは実質的に無期限に認証済みの状態を維持できるため、厳重に保管する必要があります。

Resource Owner Password Flow と標準スコープ

パスワードを提供すると完全なアクセス権が与えられるため、パスワードベースのやり取りではすべてのスコープへのアクセスが許可されます。たとえば、リクエストに APIスコープ を含めない場合、すべての API スコープがアクセストークンに含まれます。同様に、リクエストに openid スコープのみを含めた場合は、openid の標準 OpenID Connect スコープ がすべて返されます。これらのケースでは、レスポンスに scope パラメーターが含まれ、発行されたスコープの一覧が返されます。

IDトークンなしでユーザー情報を取得する

ユーザー情報が必要な場合は、リクエストに openid スコープを含めてください。API が 署名アルゴリズム として RS256 を使用している場合、アクセストークンには有効なオーディエンスとして /userinfo が含まれます。つまり、そのアクセストークンを使って /userinfo エンドポイント を呼び出し、ユーザーのクレームを取得できます。

​

API を呼び出す

API を呼び出すには、アプリケーションで取得した アクセストークン を、HTTP リクエストの Authorization ヘッダーで Bearer トークンとして渡す必要があります。

​

リフレッシュトークン

このチュートリアルをここまで進め、次の項目を完了していれば、すでにリフレッシュトークンを受け取っています。

• オフラインアクセスを許可するように API を設定した
• authorize エンドポイントを通じて認証リクエストを開始する際に、offline_access スコープを含めた

リフレッシュトークンを使用すると、新しいアクセストークンを取得できます。通常、ユーザーが新しいアクセストークンを必要とするのは、以前のトークンの有効期限が切れた場合、または新しいリソースへのアクセスを初めて取得する場合のみです。API を呼び出すたびに新しいアクセストークンを取得するためにエンドポイントを呼び出すのは、望ましい実装ではありません。また、Auth0 ではレート制限が設けられているため、同じ IP から同じトークンを使用してそのエンドポイントに実行できるリクエスト数はスロットリングされます。

トークンを更新するには、grant_type=refresh_token を使用して、Authentication API の /oauth/token エンドポイントに POST リクエストを送信します。

​

トークンURLへのPOSTの例

パラメーター

パラメーター名	説明
grant_type	refresh_token に設定します。
client_id	アプリケーションのクライアントIDです。この値は Application Settings で確認できます。
refresh_token	使用するリフレッシュトークンです。
scope	(任意) 要求するスコープをスペース区切りで指定します。指定しない場合は元のスコープが使用されます。指定した場合は、元のスコープより少ない範囲を要求できます。なお、URL エンコードが必要です。

​

レスポンス

正常に処理されると、新しい access_token、その有効期間 (秒単位の expires_in) 、付与された scope の値、および token_type を含むペイロードとともに、HTTP 200 レスポンスが返されます。

{
  "access_token": "eyJ...MoQ",
  "expires_in": 86400,
  "scope": "openid offline_access",
  "token_type": "Bearer"
}

保存する前に、トークンを検証してください。方法については、IDトークンの検証 および アクセストークンの検証 を参照してください。

​

使用例

​

トークンをカスタマイズする

Actions を使用すると、発行されるアクセストークンのスコープを変更したり、アクセストークンや IDトークン にクレームを追加したりできます。 (Actions の詳細については、Auth0 Actions を参照してください。) これを行うには、ユーザーの認証後に実行される次の Action を追加します。

exports.onExecutePostLogin = async (event, api) => {
  // アクセストークンとIDトークンにカスタムクレームを追加する
  api.accessToken.setCustomClaim('https://foo/bar', 'value');
  api.idToken.setCustomClaim('https://fiz/baz', 'some other value');

  // アクセストークンのスコープを変更する
  api.accessToken.addScope('foo');
  api.accessToken.addScope('bar');
};

スコープは、Action の実行後にトークンで使用できるようになります。

Auth0 は、OpenID Connect (OIDC) 仕様で定義された構造化クレーム形式でユーザープロファイル情報を返します。つまり、IDトークンまたはアクセストークンに追加するカスタムクレームは、競合の可能性を避けるために、ガイドラインと制限事項に準拠している必要があります。

​

レルムのサポートを設定する

Auth0 では、リソースオーナー パスワードグラントと同様の機能を提供する拡張グラントを利用できます。この拡張グラントを使うと、個別のユーザーディレクトリ (それぞれ個別の接続に対応) を維持したまま、フロー中にどれを使用するかを指定できます。

このバリエーションを使用するには、次の操作が必要です。

• grant_type リクエストパラメーターを http://auth0.com/oauth/grant-type/password-realm に設定します。
• realm という追加のリクエストパラメーターを送信し、ユーザーが属するレルムの名前を指定します。たとえば、employees という名前の社内従業員向けデータベース接続を設定しており、そのユーザーがその接続に属している場合は、realm を employees に設定します。

レルムとしての接続

アクティブな認証をサポートする接続であれば、データベース接続、パスワードレス接続、AD/LDAP、ADFS、Azure Active Directory のエンタープライズ接続など、レルムとして設定できます。

​

MFA を設定する

Resource Owner Password Flow を使用する必要があり、より強固な認証が必要な場合は、多要素認証 (MFA) を追加できます。詳しくは、MFA を使用して Resource Owner Password Flow で認証する を参照してください。

​

アタックプロテクションを設定する

ブルートフォース対策を使用して Resource Owner Password Flow を利用する場合、一部のアタックプロテクション機能が正しく動作しないことがあります。ただし、よくある問題の一部は回避できます。詳しくは、Resource Owner Password Flow とアタックプロテクションでよくある問題を回避するを参照してください。

​

関連情報

• OAuth 2.0 認可フレームワーク
• OpenID Connect プロトコル
• トークン