このチュートリアルでは、ハイブリッドフローを使用して独自のAPIをを呼び出します。フローの仕組みやメリットについては、「ハイブリッドフロー」を参照してください。
- Authentication API：独自のソリューションを構築したい場合は、このまま読み続けて、APIを直接呼び出す方法を学習してください。
前提条件
このチュートリアルを始める前に：-
Auth0にアプリケーションを登録します。
- 適切な ［Application Type（アプリケーションタイプ）］ を選択します。
{https://yourApp/callback}の ［Allowed Callback URL（許可されているコールバックURL）］ を追加します。- アプリケーションの ［Grant Types（付与タイプ）］ に ［Implicit（暗黙的）］ と ［Authorization Code（認可コード）］ が必ず含まれていることを確認してください。詳細については、「付与タイプを更新する」をお読みください。
- アプリケーションでリフレッシュトークンを使用できるようにするには、アプリケーションの ［Grant Types（付与タイプ）］ に ［Refresh Token（リフレッシュトークン）］ が含まれていることを確認してください。詳細については、「付与タイプを更新する」をお読みください。リフレッシュトークンの詳細については、「リフレッシュトークン」をお読みください。
-
APIをAuth0に登録する
- APIがリフレッシュトークンを受信して、以前のトークンの有効期限が切れたときに新しいトークンを取得できるようにする場合は、［Allow Offline Access（オフラインアクセスの許可）］ を有効にします。
ステップ
- ユーザーを認可する： ユーザーの認可を要求し、認可コードと一緒にアプリにリダイレクトします。
- トークンを要求する： 認可コードをトークンと交換します。
- APIを呼び出す： 取得したアクセストークンを使ってAPIを呼び出します。
- リフレッシュトークン： 既存のトークンが期限切れになったら、リフレッシュトークンを使用して新しいトークンを要求します。
ユーザーを認可する
この手順には、以下のようなプロセスが含まれます。- ユーザーを認証する
- 認証を行うために、ユーザーをIDプロバイダーへリダイレクトする
- 有効なシングルサインオン（）セッションを確認する
- 以前に同意を得ていない場合は、要求された権限レベルについてユーザーの同意を得る
認可URLの例
パラメーター
ユーザーを認可するためにカスタムのAPIを呼び出すときは、- オーディエンスパラメーターを含めなければなりません。
- ターゲットAPIでサポートされている追加のスコープを含めることができます。
| パラメーター名 | 説明 |
|---|---|
response_type | Auth0が返す資格情報の種類を示します（コードまたはトークン）。このフローでは、値はcodeを含む必要がありますが、id_token、token、id_token tokenを含むこともできます。特に、id_tokenはIDトークンを返し、tokenはアクセストークンを返します。 |
response_mode | 応答パラメーターが返される方法を指定します。安全保護のため、値はform_postにする必要があります。このモードでは、応答パラメーターは、HTTP POSTメソッドを介して送信され、application/x-www-form-urlencodedフォーマットを使用して本文でエンコードされるHTMLフォーム値としてエンコードされます。 |
client_id | アプリケーションのクライアントID。これは、アプリケーション設定で見つけることができます。 |
redirect_uri | 認可がユーザーにより付与された後にAuth0がブラウザーをリダイレクトするURL。認可コードは、code URLパラメーターで利用できます。アプリケーション設定で有効なコールバックURLとしてこのURLを指定する必要があります。 警告： OAuth 2.0の仕様に従って、Auth0はハッシュの後、すべてを削除し、フラグメントを受け付けません。 |
scope | 返したいクレーム（またはユーザー属性）を決定する、認可を要求したいスコープを指定します。スペースで区切る必要があります。profileまたはemailなどのユーザーに関する標準OpenID Connect（OIDC)スコープ、名前空間形式に従ったカスタムクレーム、ターゲットAPIがサポートするスコープ（例、read:contacts）を要求できます。offline_accessを含めてを取得できます（Allow Offline Access（オフラインアクセスの許可）フィールドがアプリケーション設定で有効になっていることを確認してください）。 |
audience | WebアプリケーションがアクセスするAPIの一意の識別子。このチュートリアルの前提条件の一環として作成したAPIのSettings（設定）のIdentifier（識別子） 値を使用します。 |
state | （推奨）Auth0がリダイレクトしてアプリケーションに戻る際に含まれ、アプリが初期要求に追加する不透明な任意の英数字の文字列。クロスサイトリクエストフォージェリ（CSRF）攻撃を防止するためにこの値を使用する方法については、状態パラメーターを使ってCSRF攻撃を軽減するをご覧ください。 |
nonce | トークンリプレイ攻撃を防ぐために使用される、アプリが初期要求に追加し、Auth0がIDトークンに含める暗号的にランダムな文字列。 |
organization | （任意）ユーザーを認証する時に使用する組織のID。提供されない場合、アプリケーションはDisplay Organization Prompt（組織のプロンプトを表示） に設定され、ユーザーは、認証時に組織名を入力できます。 |
invitation | （任意）組織の招待のチケットID。Organizationにメンバーを招待する場合、ユーザーが招待を受け入れたとき、アプリケーションは、invitationおよびorganizationのキー/値ペアを転送することで、招待の受け入れを処理する必要があります。 |
応答
すべてが成功すると、HTTP 302応答を受け取ります。要求された資格情報は本文にエンコードされます。
response_typeとして何を要求したかによって異なります。
| 応答タイプ | コンポーネント |
|---|---|
code | 認可コード |
id_token | IDトークン |
token | アクセストークン（およびexpires_inとtoken_type値） |
id_token token | IDトークン、アクセストークン（およびexpires_inとtoken_type値） |
このトランザクションで受信するアクセストークンは、最初に受け取るアクセストークンだけです。これをAPIの呼び出しに使用することはお勧めしません。
トークンは、検証してから保存します。操作方法については、「IDトークンの検証」および「アクセストークンを検証する」を参照してください。
c_hashという追加のクレームが含まれていることがわかります。これにはcodeのハッシュが含まれています。このクレームは、IDトークンがcodeと同時に発行される場合に必須であり、検証する必要があります。
- IDトークンのヘッダー内の
algクレームで指定されたハッシュアルゴリズムを使用して、codeのASCII表現のオクテットをハッシュ化します。 - ハッシュの左半分をBase64urlエンコードします。
- 結果が
c_hashの値と一致することを確認します。
トークンを要求する
取得した認可コードは、トークンと交換する必要があります。前の手順で抽出した認可コード（code）を使用して、トークンURLにPOSTする必要があります。
このステップで受け取るアクセス トークンは、APIを呼び出す際に使用します。このトークンは、チュートリアルの前のステップで受け取ったアクセストークンとは別に保管するようにしてください。
トークンURLへのPOSTの例
パラメーター
| パラメーター名 | 説明 |
|---|---|
grant_type | authorization_codeに設定します。 |
code | このチュートリアルの前の手順で取得したauthorization_codeです。 |
client_id | アプリケーションのクライアントIDです。この値は［Application Settings（アプリケーションの設定）］で見つけることができます。 |
client_secret | アプリケーションのクライアントシークレットです。この値は［Application Settings（アプリケーションの設定）］で見つけることができます。アプリケーションの認証方法については、「アプリケーションの資格情報」をお読みください。 |
redirect_uri | アプリケーションの設定で指定されている有効なコールバックURLです。このチュートリアルの前の手順で認可URLに渡されたredirect_uriと完全に一致しなければなりません。これは、URLエンコードする必要があります。 |
応答
すべてが成功すると、access_token、fresh_token、id_token、およびtoken_typeの値を含むペイロードとともにHTTP 200応答を受信します。
トークンは、検証してから保存します。操作方法については、「IDトークンの検証」および「アクセストークンを検証する」を参照してください。
refresh_tokenは、offline_accessスコープを含め、DashboardでAPIの**［Allow Offline Access（オフラインアクセスの許可）］** を有効にした場合にのみ、応答内に表示されます。
リフレッシュトークンは、ユーザーが実質的に永久に認証された状態を維持できるようにするため、安全に保管しなければなりません。
APIを呼び出す
通常のWebアプリケーション（または同様のケースで、アプリケーションの資格情報を安全に保存できる場合）からAPIを呼び出すには、アプリケーションは、取得したアクセストークンをベアラートークンとしてHTTP要求の認可ヘッダーで渡さなければなりません。リフレッシュトークン
このチュートリアルに従って次の作業を完了している場合、あなたはすでにリフレッシュ トークンを受け取っています。- オフラインアクセスを許可するように、APIを構成する。
- 認可エンドポイントを通じて認証要求を開始するときに、
offline_accessスコープを含める。
grant_type=refresh_tokenを使用して、認証APIの/oauth/tokenエンドポイントに対してPOST要求を送信します。
トークンURLへのPOSTの例
パラメーター
| パラメーター名 | 説明 |
|---|---|
grant_type | これをrefresh_tokenに設定します。 |
client_id | アプリケーションのクライアントID。この値はアプリケーション設定で確認できます。 |
refresh_token | 使用するリフレッシュトークン。 |
scope | （任意）要求されたスコープの権限をスペースで区切ったリスト。送信されない場合は、元のスコープが使用されます。送信する場合は、スコープを減らして要求することができます。これはURLでエンコードされている必要があります。 |
応答
すべてが成功すると、新しいaccess_token、秒単位の有効期間（expires_in）、付与されたscope値、およびtoken_typeを含むペイロードとともにHTTP 200応答を受信します。最初のトークンのスコープにopenidが含まれている場合、応答には新しいid_tokenも含まれます。
トークンは、検証してから保存します。操作方法については、「IDトークンの検証」および「アクセストークンを検証する」を参照してください。
サンプルユースケース
トークンをカスタマイズする
ルールを使用して、アクセストークンで返されたスコープを変更し、クレームをアクセスとIDトークンに追加することができます。（ルールの詳細については、「Auth0ルール」をお読みください。）これを行うには、ユーザーの認証後に実行される次のルールを追加します。Auth0は、プロファイル情報をOpenID Connect（OIDC）仕様で定義されている構造化クレーム形式で返します。つまり、IDトークンまたはアクセストークンに追加するカスタムクレームは、衝突を避けるためにガイドラインと制限に従わなければなりません。