PKCE を使用した Authorization Code フローでログインを追加する

PKCE を使用した Authorization Code フローを使って、Native、モバイル、またはシングルページ アプリケーションにログインを追加する方法を学びます。

PKCE を使用した Authorization Code フローを使うと、Native、モバイル、またはシングルページアプリにログイン機能を追加できます。このフローの仕組みと、これを使用すべき理由については、Authorization Code Flow with Proof Key for Code Exchange (PKCE) をお読みください。Native、モバイル、またはシングルページアプリから API を呼び出す方法については、Call Your API Using PKCE を使用した Authorization Code フロー をお読みください。

Proof Key for Code Exchange (PKCE) を使用した Authorization Code フローを実装するには、次のリソースを利用できます。

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

ログインに成功すると、アプリケーションはユーザーの ID トークン と アクセストークン を利用できるようになります。ID トークンには基本的なユーザープロファイル情報が含まれ、アクセストークンは Auth0 の /userinfo エンドポイントや独自の保護された API の呼び出しに使用できます。ID トークンの詳細については、ID Tokens をお読みください。アクセストークンの詳細については、Access Tokens をお読みください。

​

前提条件

Auth0 にアプリケーションを登録します。詳しくは、ネイティブアプリケーションを登録する または シングルページ Web アプリケーションを登録する をご覧ください。

• アプリケーションの種類に応じて、Application Type で Native または Single-Page App を選択します。
• Allowed Callback URL に YOUR_CALLBACK_URL を追加します。コールバック URL の形式は、アプリケーションの種類とプラットフォームによって異なります。アプリケーションの種類とプラットフォームごとの形式について詳しくは、Native/Mobile Quickstarts と Single-Page App Quickstarts を参照してください。
• アプリケーションの Grant Types に Authorization Code が含まれていることを確認します。詳しくは、グラントタイプを更新する をご覧ください。

​

code verifier を作成

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

code_verifier を作成するアルゴリズムの詳細については、OAuth Proof Key for Code Exchange 仕様のセクション 4.1 Client Creates a Code Verifier を参照してください。

​

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のサンプル

// 依存関係: 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.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:@"="]];

​

コードチャレンジを作成する

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

code_challenge が code_verifier からどのように導出されるかについて詳しくは、OAuth Proof Key for Code Exchange 仕様の 4.2 Client Creates the Code Challenge を参照してください。

​

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:@"="]];

​

ユーザーの認可を取得する

ユーザーに認可を求め、authorization_code とともにアプリへリダイレクトして戻します。

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

• ユーザーを認証すること;
• 認証を処理するために、ユーザーを IDプロバイダー にリダイレクトすること;
• アクティブな シングルサインオン (SSO) セッションを確認すること;
• 以前に同意が与えられていない場合は、要求された権限レベルに対するユーザーの同意を取得すること。

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

​

認可 URL の例

​

パラメータ

パラメータ名	説明
response_type	Auth0 が返す認証情報の種類 (code または token) を示します。このフローでは、値は code である必要があります。
code_challenge	code_verifier から生成されたチャレンジです。
code_challenge_method	チャレンジの生成に使用するメソッド (例: S256) です。PKCE 仕様では S256 と plain の 2 つのメソッドが定義されています。この例では前者を使用しており、後者は非推奨であるため、Auth0 でサポートされているのは 前者のみ です。
client_id	アプリケーションの Client ID です。この値は アプリケーション設定 で確認できます。
redirect_uri	ユーザーが認可した後、Auth0 がブラウザーをリダイレクトする先の URL です。認可コードは URL パラメータ code で受け取れます。この URL は、アプリケーション設定 で有効なコールバック URL として指定する必要があります。 警告: OAuth 2.0 Specification に従い、Auth0 はハッシュ以降の内容をすべて削除し、フラグメントは 一切 考慮しません。
scope	認可をリクエストする対象の scopes を指定します。これにより、返されるクレーム (またはユーザー属性) が決まります。複数指定する場合はスペースで区切る必要があります。レスポンスで ID トークンを取得するには、少なくとも openid スコープを指定する必要があります。ユーザーの完全なプロファイルを返したい場合は、openid profile をリクエストできます。email など、ユーザーに関する standard OpenID Connect (OIDC) scopes や、namespaced format に準拠した custom claims をリクエストすることもできます。リフレッシュトークン を取得するには offline_access を含めます (アプリケーション設定 で オフラインアクセスの許可 フィールドが有効になっていることを確認してください) 。
state	(推奨) アプリが最初の request に追加する、任意の英数字からなる不透明な文字列です。Auth0 はアプリケーションにリダイレクトするとき、この値をそのまま含めます。この値を使ってクロスサイトリクエストフォージェリ (CSRF) 攻撃を防ぐ方法については、Mitigate CSRF Attacks With State Parameters を参照してください。
connection	(任意) ユーザーが特定の接続でサインインするようにします。たとえば、github を渡すと、ユーザーは GitHub アカウントでログインするために直接 GitHub に移動します。指定しない場合、ユーザーには設定済みのすべての接続を含む Auth0 Lock 画面が表示されます。設定済みの接続の一覧は、アプリケーションの Connections タブで確認できます。
organization	(任意) ユーザー認証時に使用する organization の ID です。指定しない場合でも、アプリケーションで Display Organization Prompt が設定されていれば、ユーザーは認証時に organization名 を入力できます。
invitation	(任意) organization 招待の ticket ID です。Organizations にメンバーを招待する 場合は、ユーザーが招待を承諾した際に、アプリケーションで invitation と organization のキーと値のペアを転送して、招待承諾を処理する必要があります。

例として、アプリに login を追加する際の認可 URL 用 HTML スニペットは次のようになります。

​

レスポンス

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

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

​

トークンを取得する

authorization_code と code_verifier をトークンと交換します。

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

​

Token URL への POST の例

​

パラメータ

パラメータ名	説明
grant_type	"authorization_code" に設定します。
code_verifier	このチュートリアルの最初の手順で生成した、暗号学的にランダムなキーです。
code	このチュートリアルの前の手順で取得した authorization_code です。
client_id	アプリケーションの Client ID です。この値は アプリケーション設定 で確認できます。
redirect_uri	アプリケーション設定で設定した有効なコールバック 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 Token を検証するとアクセストークンを検証するをご覧ください。

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

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

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

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

​

使用例

​

基本的な認証リクエスト

この例では、ステップ1でユーザーを認証する際に送信できる、最も基本的なリクエストを示します。Auth0のログイン画面が表示され、設定済みの任意の接続を使ってユーザーがサインインできます。

では、トークンをリクエストすると、ID トークンには最も基本的なクレームが含まれます。ID トークンをデコードすると、次のようになります。

{
  "iss": "https://auth0pnp.auth0.com/",
  "sub": "auth0|581...",
  "aud": "xvt9...",
  "exp": 1478112929,
  "iat": 1478076929
}

​

ユーザーの名前とプロフィール画像をリクエストする

通常のユーザー認証に加えて、この例では、名前やプロフィール画像といった追加のユーザー情報をリクエストする方法を示します。

ユーザーの名前とプロフィール画像をリクエストするには、ユーザーを認可する際に適切なスコープを追加する必要があります。

これで、トークンをリクエストすると、ID トークンにはリクエストした名前とプロフィール画像のクレームが含まれるようになります。ID トークンをデコードすると、次のようになります。

{
  "name": "auth0user@...",
  "picture": "https://example.com/profile-pic.png",
  "iss": "https://auth0user.auth0.com/",
  "sub": "auth0|581...",
  "aud": "xvt...",
  "exp": 1478113129,
  "iat": 1478077129
}

​

GitHub でユーザーをログインさせるよう要求する

通常のユーザー認証に加えて、この例では、GitHub などのソーシャルアイデンティティプロバイダーへユーザーを直接送る方法を示します。この例を機能させるには、Auth0 Dashboard > Authentication > Social に移動して、適切な接続を設定する必要があります。接続名は 設定 タブで確認してください。

ユーザーを GitHub のログイン画面に直接送るには、ユーザーを認可する際に connection パラメーターを渡し、その値を接続名 (この場合は github) に設定する必要があります。

ここでトークンをリクエストすると、ID トークンには、GitHub から返されたユーザーの一意の ID が sub クレームとして含まれます。ID トークンをデコードすると、次のようになります。

{
  "name": "John Smith",
  "picture": "https://avatars.example.com",
  "email": "jsmith@...",
  "email_verified": true,
  "iss": "https://auth0user.auth0.com/",
  "sub": "github|100...",
  "aud": "xvt...",
  "exp": 1478114742,
  "iat": 1478078742
}

​

詳細情報

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