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

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

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

Resource Owner Password (ROP) フローではアプリケーションがユーザーのパスワードを扱うため、サードパーティのクライアントでは使用しないでください。

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

​

前提条件

このチュートリアルを始める前に:

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

  • アプリケーションの種類 として Regular Web Apps を選択します。
  • Allowed Callback URL に {https://yourApp/callback} を追加します。このフィールドは空欄にできません。空欄のままだとエラーメッセージが返されます。
  • アプリケーションの グラントタイプ に パスワード が含まれていることを確認します。設定方法については、グラントタイプを更新する を参照してください。
  • アプリケーションでリフレッシュトークンを使用できるようにするには、アプリケーションの グラントタイプ に リフレッシュトークン が含まれていることを確認します。設定方法については、グラントタイプを更新する を参照してください。リフレッシュトークンの詳細については、リフレッシュトークン を参照してください。

• Auth0 に API を登録する

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

• 接続を設定する

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

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

​

手順

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	ユーザーが入力したユーザー名。
password	ユーザーが入力したパスワード。
client_id	アプリケーションの Client ID。値は アプリケーション設定 で確認できます。
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。Client Secret がアプリケーションの認証方法である場合に必要です。アプリケーション設定 が Post または Basic の場合に使用します。アプリケーションの信頼性が高くない場合 (たとえば SPA) には、このパラメータを設定しないでください。
audience	トークンの audience、つまり API を指定します。これは API の設定タブ の Identifier フィールドで確認できます。
scope	認可をリクエストする scopes を指定します。これにより、返されるクレーム (またはユーザー属性) が決まります。各値はスペースで区切る必要があります。profile や email などのユーザーに関する 標準 OpenID Connect (OIDC) scopes、namespaced format に準拠した custom claims、または対象 API がサポートする任意の scopes (例: read:contacts) をリクエストできます。リフレッシュトークン を取得するには 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 フローと標準スコープ

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

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

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

​

API を呼び出す

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

​

リフレッシュトークン

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

• APIでオフラインアクセスの許可を有効にした
• authorize endpointを通じてAuthentication Requestを開始する際に、offline_accessスコープを含めた

新しいアクセストークンを取得するには、リフレッシュトークンを使用できます。通常、ユーザーが新しいアクセストークンを必要とするのは、前のトークンの有効期限が切れた後か、新しいリソースに初めてアクセスするときだけです。APIを呼び出すたびに新しいアクセストークンを取得するためにエンドポイントを毎回呼び出すのは望ましくありません。さらに、Auth0ではrate limitsが設けられており、同じIPから同じトークンを使用してそのエンドポイントに送信できるリクエスト数は制限されます。

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

​

トークン URL に POST する例

パラメーター

パラメーター名	説明
grant_type	refresh_token に設定します。
client_id	アプリケーションの Client ID です。この値は アプリケーション設定 で確認できます。
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 Token にクレームを追加したりできます。 (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) specification で定義されている構造化クレーム形式でプロファイル情報を返します。つまり、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 プロトコル
• トークン