PKCE を使用した Authorization Code フローで API を呼び出す

PKCE を使用した Authorization Code フローを使って、ネイティブ、モバイル、またはシングルページ アプリケーションから API を呼び出す方法を学びます。

このチュートリアルでは、PKCE を使用した Authorization Code フローを使って、ネイティブアプリ、モバイルアプリ、またはシングルページアプリから独自の API を呼び出す方法を説明します。このフローの仕組みと、これを使用すべき理由については、Authorization Code Flow with Proof Key for Code Exchange (PKCE) を参照してください。ネイティブアプリ、モバイルアプリ、またはシングルページアプリにログインを追加する方法については、Add Login Using Authorization Code Flow with PKCE を参照してください。

Auth0 では、次の方法でアプリに Authorization Code Flow with Proof Key for Code Exchange (PKCE) を簡単に実装できます。

• Auth0 Mobile SDKs と Auth0 Single-Page App SDK: フローを実装する最も簡単な方法で、多くの複雑な処理を代わりに行ってくれます。Mobile Quickstarts と Single-Page App Quickstarts では、手順を順を追って説明しています。
• Authentication API: 独自のソリューションを構築したい場合は、このまま読み進めて API を直接呼び出す方法を確認してください。

​

前提条件

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

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

  • アプリケーションの種類に応じて、Application Type で Native または Single-Page App を選択します。
  • Allowed Callback URL に {yourCallbackUrl} を追加します。コールバック URL の形式は、アプリケーションの種類とプラットフォームによって異なります。アプリケーションの種類とプラットフォームごとの形式について詳しくは、Native/Mobile Quickstarts および Single-Page App Quickstarts を参照してください。
  • アプリケーションの Grant Types に 認可コード が含まれていることを確認してください。設定方法については、Grant Types を更新する を参照してください。
  • アプリケーションでリフレッシュトークンを使用できるようにする場合は、アプリケーションの Grant Types に Refresh Token が含まれていることを確認してください。設定方法については、Grant Types を更新する を参照してください。リフレッシュトークンの詳細については、Refresh Tokens を参照してください。

• Auth0 で API を登録する

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

​

手順

1. コードベリファイアを作成する: Auth0 に送信してトークンをリクエストするための code_verifier を生成します。
2. コードチャレンジを作成する: code_verifier から code_challenge を生成し、これを Auth0 に送信して authorization_code をリクエストします。
3. ユーザーを認可する: ユーザーの認可をリクエストし、authorization_code とともにアプリへリダイレクトします。
4. トークンをリクエストする: authorization_code と code_verifier をトークンと引き換えます。
5. API を呼び出す: 取得したアクセストークンを使って API を呼び出します。
6. リフレッシュトークンを使用する: 既存のトークンの有効期限が切れたときに、新しいトークンをリクエストするためにリフレッシュトークンを使用します。

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

​

code verifier を作成する

code_verifier を作成します。これは、最終的にトークンをリクエストするために Auth0 に送信される、暗号学的にランダムな Base64 エンコード済みのキーです。

​

Javascript のサンプル

// 依存関係: Node.js cryptoモジュール
// https://nodejs.org/api/crypto.html#crypto_crypto
function base64URLEncode(str) {
    return str.toString('base64')
        .replace(/\+/g, '-')
        .replace(/\//g, '_')
        .replace(/=/g, '');
}
var verifier = base64URLEncode(crypto.randomBytes(32));

​

Java の例

// 依存関係: Apache Commons Codec
// https://commons.apache.org/proper/commons-codec/
// Base64クラスをインポートします。
// import org.apache.commons.codec.binary.Base64;
SecureRandom sr = new SecureRandom();
byte[] code = new byte[32];
sr.nextBytes(code);
String verifier = Base64.getUrlEncoder().withoutPadding().encodeToString(code);

​

Android サンプル

// See https://developer.android.com/reference/android/util/Base64
// Base64クラスをインポートする
// import android.util.Base64;
SecureRandom sr = new SecureRandom();
byte[] code = new byte[32];
sr.nextBytes(code);
String verifier = Base64.encodeToString(code, Base64.URL_SAFE | Base64.NO_WRAP | Base64.NO_PADDING);

​

Swift 5のサンプル

var buffer = [UInt8](repeating: 0, count: 32)
_ = SecRandomCopyBytes(kSecRandomDefault, buffer.count, &buffer)
let verifier = Data(buffer).base64EncodedString()
    .replacingOccurrences(of: "+", with: "-")
    .replacingOccurrences(of: "/", with: "_")
    .replacingOccurrences(of: "=", with: "")

​

Objective-C のサンプル

NSMutableData *data = [NSMutableData dataWithLength:32];
int result __attribute__((unused)) = SecRandomCopyBytes(kSecRandomDefault, 32, data.mutableBytes);
NSString *verifier = [[[[data base64EncodedStringWithOptions:0]
                        stringByReplacingOccurrencesOfString:@"+" withString:@"-"]
                        stringByReplacingOccurrencesOfString:@"/" withString:@"_"]
                        stringByTrimmingCharactersInSet:[NSCharacterSet characterSetWithCharactersInString:@"="]];

​

code challenge を作成する

authorization_code をリクエストするために Auth0 に送信する code_challenge を、code_verifier から生成します。

​

Javascript の例

// 依存関係: Node.js cryptoモジュール
// https://nodejs.org/api/crypto.html#crypto_crypto
function sha256(buffer) {
    return crypto.createHash('sha256').update(buffer).digest();
}
var challenge = base64URLEncode(sha256(verifier));

​

Java のサンプル

// 依存関係: Apache Commons Codec
// https://commons.apache.org/proper/commons-codec/
// Base64クラスをインポートします。
// import org.apache.commons.codec.binary.Base64;
byte[] bytes = verifier.getBytes("US-ASCII");
MessageDigest md = MessageDigest.getInstance("SHA-256");
md.update(bytes, 0, bytes.length);
byte[] digest = md.digest();
String challenge = Base64.encodeBase64URLSafeString(digest);

​

Swift 5のサンプル

import CommonCrypto

// ...

guard let data = verifier.data(using: .utf8) else { return nil }
var buffer = [UInt8](repeating: 0, count: Int(CC_SHA256_DIGEST_LENGTH))
_ = data.withUnsafeBytes {
    CC_SHA256($0.baseAddress, CC_LONG(data.count), &buffer)
}
let hash = Data(buffer)
let challenge = hash.base64EncodedString()
    .replacingOccurrences(of: "+", with: "-")
    .replacingOccurrences(of: "/", with: "_")
    .replacingOccurrences(of: "=", with: "")

​

Objective-Cのサンプル

// 依存関係: Apple Common Cryptoライブラリ
// http://opensource.apple.com//source/CommonCrypto
u_int8_t buffer[CC_SHA256_DIGEST_LENGTH * sizeof(u_int8_t)];
memset(buffer, 0x0, CC_SHA256_DIGEST_LENGTH);
NSData *data = [verifier dataUsingEncoding:NSUTF8StringEncoding];
CC_SHA256([data bytes], (CC_LONG)[data length], buffer);
NSData *hash = [NSData dataWithBytes:buffer length:CC_SHA256_DIGEST_LENGTH];
NSString *challenge = [[[[hash base64EncodedStringWithOptions:0]
                         stringByReplacingOccurrencesOfString:@"+" withString:@"-"]
                         stringByReplacingOccurrencesOfString:@"/" withString:@"_"]
                         stringByTrimmingCharactersInSet:[NSCharacterSet characterSetWithCharactersInString:@"="]];

​

ユーザーを認可する

code_verifier と code_challenge を作成したら、ユーザーの認可を得る必要があります。これは技術的には 認可フロー の始まりにあたり、このステップには次のプロセスの 1 つ以上が含まれることがあります。

• ユーザーを認証する。
• 認証を行うため、ユーザーを IDプロバイダー にリダイレクトする。
• 有効な シングルサインオン (SSO) セッションがあるか確認する。
• 以前に同意が与えられていない場合は、要求された権限レベルについてユーザーの同意を得る。

ユーザーを認可するには、アプリからユーザーを 認可 URL に送る必要があります。その際、前のステップで生成した code_challenge と、code_challenge の生成に使用したメソッドを含めます。

​

認可 URL の例

パラメータ

カスタム API の呼び出し時にユーザーを認可する場合は、次の点に注意してください。

• audience パラメータを含める必要があります
• 対象の API でサポートされている追加のスコープを含めることもできます

パラメータ名	説明
response_type	Auth0 が返す認証情報の種類 (code または token) を示します。このフローでは、値は code である必要があります。
code_challenge	code_verifier から生成されたチャレンジです。
code_challenge_method	チャレンジの生成に使用する方法です (例: S256) 。PKCE 仕様では S256 と plain の 2 つの方法が定義されています。この例では前者を使用しており、後者は非推奨であるため、Auth0 がサポートしているのは 前者のみ です。
client_id	アプリケーションの Client ID です。この値は Application Settings で確認できます。
redirect_uri	ユーザーが認可を許可した後に、Auth0 がブラウザーをリダイレクトする URL です。認可コードは URL パラメータ code で取得できます。この URL は Application Settings で有効なコールバック URL として指定する必要があります。 警告: OAuth 2.0 Specification に従い、Auth0 はハッシュ以降の内容をすべて削除し、フラグメントは一切考慮しません。
scope	認可をリクエストする scopes です。各 scope はスペースで区切る必要があります。profile や email など、ユーザーに関する任意の standard OpenID Connect (OIDC) scopes、namespaced format に準拠した custom claims、または対象 API がサポートする任意のスコープ (例: read:contacts) をリクエストできます。リフレッシュトークン を取得するには offline_access を含めてください (Application Settings で オフラインアクセスの許可 フィールドが有効になっていることを確認してください) 。
audience	モバイルアプリがアクセスする API の一意の識別子です。このチュートリアルの前提条件の一部として作成した API の Settings タブにある Identifier の値を使用します。
state	(推奨) アプリが最初のリクエストに追加し、Auth0 がアプリケーションにリダイレクトするときに含める、不透明な任意の英数字の文字列です。この値を使ってクロスサイトリクエストフォージェリ (CSRF) 攻撃を防ぐ方法については、Mitigate CSRF Attacks With State Parameters を参照してください。
organization	(任意) ユーザーの認証時に使用する organization の ID です。指定しない場合、アプリケーションで Display Organization Prompt が設定されていれば、ユーザーは認証時に organization 名を入力できます。
invitation	(任意) organization 招待の ticket ID です。メンバーを Organizations に招待する 場合、ユーザーが招待を承諾したときに、アプリケーションは invitation と organization のキーと値のペアを引き渡して、招待の承諾を処理する必要があります。

例として、API の呼び出し時に使用する認可 URL の HTML スニペットは次のようになります。

​

レスポンス

問題なく進めば、HTTP 302 レスポンスが返されます。認可コードは URL の末尾に含まれます。

HTTP/1.1 302 Found
Location: {yourCallbackUrl}?code={authorizationCode}&state=xyzABC123

​

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

認可コードを取得したら、次はそれをトークンと交換する必要があります。前のステップで取得した認可コード (code) を使い、code_verifier を添えて トークン URL に POST リクエストを送信する必要があります。

​

トークンURLへのPOST例

パラメーター

パラメーター名	説明
grant_type	これを "authorization_code" に設定します。
code_verifier	このチュートリアルの最初のステップで生成した、暗号学的にランダムなキーです。
code	このチュートリアルの前のステップで取得した authorization_code です。
client_id	ご利用のアプリケーションの Client ID です。この値は Application Settings で確認できます。
redirect_uri	Application Settings で設定した有効なコールバック URL です。これは、このチュートリアルの前のステップで認可 URL に渡した redirect_uri と完全に一致している必要があります。なお、URL エンコードが必要です。

​

レスポンス

問題なく処理されると、access_token、refresh_token、id_token、token_type の各値を含むペイロードとともに、HTTP 200 レスポンスが返されます。

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

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

ID トークンには、デコードして取り出す必要があるユーザー情報が含まれています。

アクセストークンは、Auth0 Authentication API の /userinfo エンドポイントまたは別の API を呼び出すために使用されます。独自の API を呼び出す場合、最初に必要になるのは、アクセストークンを検証することです。

リフレッシュトークンは、前の アクセストークン または ID トークン の有効期限が切れた後に、新しいものを取得するために使用されます。refresh_token は、offline_access scope を含め、Auth0 Dashboard で API の オフラインアクセスの許可 を有効にした場合にのみ、レスポンスに含まれます。

リフレッシュトークンは、ユーザーが実質的に永続して認証済みの状態を保てるようにするため、厳重に保管する必要があります。

​

API を呼び出す

ネイティブ／モバイル アプリケーションから API を呼び出すには、取得したアクセストークンを HTTP request の Authorization ヘッダーで Bearer トークンとして渡す必要があります。

​

リフレッシュトークン

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

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

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

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

​

トークン URL への POST の例

パラメーター

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

​

レスポンス

問題なく進めば、新しい access_token、その有効期間 (秒単位の expires_in) 、付与された scope 値、および token_type を含むペイロードとともに、HTTP 200 レスポンスが返されます。最初のトークンのスコープに openid が含まれている場合、レスポンスには新しい id_token も含まれます。

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

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

​

使用例

​

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

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

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

  // Access Token のスコープを変更する
  api.accessToken.addScope('foo');
  api.accessToken.addScope('bar');
};

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

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

​

サンプルアプリケーションを見る: モバイルアプリ + API

実装例については、Mobile + API アーキテクチャシナリオを参照してください。このチュートリアルシリーズには、GitHub で参照できるコードサンプル も用意されています。

​

詳しくはこちら

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