メインコンテンツまでスキップ

【オプション】画面遷移してログイン(Authorization Code Grantフロー)

概要​

Game Server を利用して、旧来通りの画面遷移型アプリケーションに適した ID 連携を行うのが Authorization Code Grant フロー です。

Authorization Code Grant フローでは、ゲーム画面からログイン認証画面に画面遷移し、ユーザーがログイン認証画面での入力を終えて認可を受けると、ゲーム画面に遷移することでゲームに戻ります。

ここでは、Authorization Code Grant フロー により Mobage Connect へログインする機能を開発していきます。

警告

Authorization Code Grant フローをご利用いただく場合、今後提供予定の Shell App SDK をご利用いただけません。
Shell App SDK をご利用いただく場合は、Hybrid フローをご利用ください。

作成するファイル一覧​

このチュートリアルで作成するファイルは下記になります。

ファイル名概要
config.php各種設定値をまとめます
login_auth.phpLogin Session を確認します
authorize.phpstate 値を発行し、Authorization Endpoint へリダイレクトします
login_cb_get.phpGame Server でのログイン処理を実施します

チュートリアルをはじめる前に​

このチュートリアルは、以下のチュートリアルを終わらせている前提で進めます。
以下のチュートリアルを完了していない場合は、先にそちらを完了させましょう。

また、以下のライブラリを利用するので、ダウンロードしておきます。

開発のステップ​

Authorization Code Grant フローを実現するために、大きく以下の4ステップで進めます。

ログイン状態で無いとアクセスが出来ないコンテンツにて、ログインセッションを確認します。
ログインセッションが無い場合、Game Server はユーザーを Session Start Endpoint へリダイレクトします。
リダイレクト先では state 値を発行し、新規に発行したセッションを Game Server 上に保存します。
 
上記の処理のシーケンス図は以下になります。

表中に登場する各種 Endpoint の説明です。

Endpoint

説明

Authorization Endpoint 

Client アプリケーションがユーザーの認可を得る為のエンドポイントです。 

Token Endpoint 

API を利用する際に用いる Access Token を得る為のエンドポイントです。 

Protected Endpoint

ゲームのログインセッションを持った UserAgent でなければ閲覧出来ないエン ドポイントです。

Session Start Endpoint

Authorization Request を送る前に Protected Endpoint の URI を保存し、state 値を生成した上でセッションを開始しセッションデータに紐づける為のエンドポ イントです。

Redirect Endpoint

Authoirization Response を受け取り、ログイン処理を行う前の検証を行った上 で妥当であればログインセッションを発行し、Protected Endpoint にリダイレ クトするエンドポイントです。

ログインセッションが存在するか確認する​

Mobage Connect へログインしていないとアクセス出来ないコンテンツにUser Agentがアクセスした際に、 Game Server で管理しているUser Agentのログインセッションを確認します。
ログインセッションが無い場合、Game Server はUser Agentを Session Start Endpoint へリダイレクトします。
このチュートリアルでは、 login_auth.php でログインセッションを確認し、ログインセッションが無ければ authorize.php にリダイレクトします。
リダイレクト先で state 値(8文字以上256文字以内の文字列)を生成し、セッション上に保存します。

備考

この state 値は 認可手続きを始めた User Agent と、 認可情報をもたらした User Agent が同一であることを確認するための値です。 CSRF 攻撃を防止するために用いられます。

TOC

Authorization Endpoint へ Authorization Request を送るためのパラメータを準備し、Authorization Request を送信します。
 
この処理のシーケンス図が下記になります。

Authorization Request の送信​

Authorization Endpoint に Authorization Request として送信したいパラメータをまとめます。
まとめたパラメタを用いて Authorization Endpoint へリダイレクトすることで Authorization Request を実行します。

mobage-jssdk-sample-login/authorization_code_grant_flow/authorize.php

$authorize_endpoint_request_params = [
'client_id' => CLIENT_ID,
'redirect_uri' => REDIRECT_GET_ENDPOINT,
'response_type' => 'code',
'scope' => 'openid common_api',
'state' => $state,
];
$query = http_build_query($authorize_endpoint_request_params);
header('Location: ' . AUTHORIZE_ENDPOINT_URL . '?' . $query);
exit;

なお、Authorization Endpoint としては以下を指定します。

環境URI
sandboxhttps://sb-connect.mobage.jp/connect/1.0/services/authorize
servicehttps://connect.mobage.jp/connect/1.0/services/authorize

Authorization Response の受信​

User Agent が Authorization Endpoint にアクセス (Authorization Request) した際、ユーザーの状態によって以下のような挙動になります。

Mobage Connect へのログインに成功した時​

成功時には以下のようなパラメータが Redirect Endpoint へのクエリパラメータとして渡されます。

keyvalue
codeサーバーサイド向けの access token を得る為に Token Endpoint に grant_type=authorization_code でアクセスする際に必要な文字列です。
stateAuthorization Request 時に指定した state 値です。
session_stateMobage Connect が User Agent に発行しているログインセッションの状態を透過的に表す文字列です。原則として、ゲームサーバーが User Agent に発行するセッションデータに紐付け、 Single Logout 連携時に、この session_state 値に変更があれば、ゲームサーバー側のセッションを無効にしてログアウト処理を進める必要があります。
Mobage Connect へのログインに失敗した時​

失敗時には以下のようなパラメータが Redirect Endpoint へのクエリパラメータとして渡されます。

keyvalue
errorOAuth 2.0/OpenID Connect 1.0 で定義されるエラーコードが指定されます。
error_descriptionerror 内容を説明する文章が指定されます。
stateAuthorization Request 時に指定したstate 値です。

TOC

Game Server でログイン処理を実施する​

先ほど Authorization Response で受信した code, state, session_state を受け取って Game Server でのログイン処理を実装します。
Game Server でのログイン処理では、下記を実行します。

上記処理のシーケンス図は以下になります。

state 値の検証​

Authorization Response で受信したstate 値を検証します。

Game Server の state 値 と一致するか確認​

Game Server のセッションから state 値を取得し、Client から送信された state 値と一致するか確認します。
state 値が一致しない場合は、不正なリクエストとみなし、エラーレスポンスを返して処理を終了してください。

mobage-jssdk-sample-login/authorization_code_grant_flow/login_cb_get.php

// validate state
if (isset($_SESSION['state']) &&
$_GET['state'] !== $_SESSION['state']) {
header('Location: ' . CLIENT_URI);
exit;
}
備考

この state 値は 認可手続きを始めた User Agent と、 認可情報をもたらした User Agent が同一であることを確認するための値です。CSRF 攻撃を防止するために用いられます。

Token リクエストの送信と Token レスポンスの受け取り​

Token リクエストのパラメタ設定​

state値が一致した場合、Token Endpoint に Token Request を送信します。
Token Request で指定するパラメタを以下のように設定します。

mobage-jssdk-sample-login/authorization_code_grant_flow/login_cb_get.php

// token endpoint request
$token_endpoint_request_params = [
'client_id' => CLIENT_ID,
'redirect_uri' => REDIRECT_GET_ENDPOINT,
'code' => $_GET['code'],
'grant_type' => 'authorization_code'
];

なお、それぞれのパラメタには以下の値を指定してください。

keyvalue
client_idMobage Developers Japan で発行された Client ID 値
redirect_uriAuthorization Code Grant フローで指定した Redirect URI 値
codeAuthorization Response で受け取った code 値
grant_typeauthorization_code を指定します
Token リクエストのヘッダー設定​

Token Request で Client 認証として client_secret_basic を用いる場合は、
下記のように記載してください。

mobage-jssdk-sample-login/authorization_code_grant_flow/login_cb_get.php

$headers = [
'Content-Type: application/x-www-form-urlencoded',
'Connection: close',
'Authorization: ' . sprintf("Basic %s", base64_encode(CLIENT_ID . ":" . CLIENT_SECRET)),
];

なお、Token Request では Client 認証として下記をサポートしています。

種別説明
client_secret_basicClient 認証に Basic 認証を用います。
client_secret_postClient 認証パラメータを application/x-www-form-urlencoded パラメータに含める方式です。
Token Request の送信​

パラメタ、ヘッダーをまとめて以下のように Token Request を送信します。

mobage-jssdk-sample-login/authorization_code_grant_flow/login_cb_get.php

$options = [
'http' => [
'method' => 'POST',
'content' => http_build_query($token_endpoint_request_params),
'header' => implode("\r\n", $headers),
]
];

$contents = file_get_contents(TOKEN_ENDPOINT_URL, false, stream_context_create($options));

なお、各環境での Token Endpoint の URI は以下のようになります。

環境URI
sandboxhttps://sb-connect.mobage.jp/connect/1.0/api/token
servicehttps://connect.mobage.jp/connect/1.0/api/token

また、Token Response の例を以下に示します。

{
"refresh_token":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"id_token":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"expires_in":900,
"scope":"openid common_api",
"token_type":"Bearer",
"access_token":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}
keyvalue
access_tokenGame Server から API を実行するための access_token が返されます。
id_tokenJSON Web Token というフォーマットで提供された値です。このid_token を検証することによってログイン処理を完了させます。
token_typeBearer
expires_in900
refresh_tokengrant_type=refresh_token による Token Request で改めて access token を得る為に必要なトークンです。発行時から90日間有効です。
scope現在、クライアント向けに認可されているユーザーに関する権限を全て示すスペース区切りの文字列です。

id_token の検証​

Token Request が成功の場合、得られた id_token の値を検証します。
id_token はJSON Web Token(JWT)というフォーマットで提供されており、この JWT は署名アルゴリズムが RS256 となっています。
ここでは JWT の検証として以下のライブラリを利用します。
https://github.com/firebase/php-jwt

JWT のデコード​

Token Response で得られた id_token は Platform 側の秘密鍵で署名がつけられているため、 X.509 形式の公開鍵を利用して、署名の妥当性を検証します。(署名の検証で利用する公開鍵)

mobage-jssdk-sample-login/authorization_code_grant_flow/login_cb_get.php

if ($contents) {
$json_body = json_decode($contents, true);

try {
$jwt_claims = JWT::decode($json_body['id_token'], PUBLIC_KEY, array('RS256'));
} catch (Exception $e) {
error_log('jwt_decode failed because ' . $e . "\n", 3, ERROR_LOG_PATH);
header('Location: ' . CLIENT_URI);
exit;
}

JWT の payload(JWT Claims Set) は以下のようなデータ構造をしています。

{
"jti" : "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"exp" : 1412577402,
"a_hash" : "XXXXXXXXXXXXXXXXXXXXXX",
"sub" : 123456,
"aud" : !12000129-4!,
"iss" : "`https://sb-connect.mobage.jp",`
"iat" : "1412576502",
"typ" : "id_token"
}
JWT Claims Setの検証​

Token Response で得られた id_token が妥当であるかどうかを確認するため、JWT 中の本文である JWT Claims Set を検証する処理を実装します。 Game Server で検証する項目は以下になります。

備考

JSON Web Token と JSON Web Token の検証についての詳細は、以下 URL をご確認ください。 https://docs.mobage.com/display/JPJSSDK/JSON_Web_Token

  • iss (Issuer Claim, この JWT を発行したサーバの識別子)が妥当か
  • aud (Audience Claim, この JWT の公開範囲として指定された Client ID)がアプリケーションのClient IDと一致しているか
  • iat (Issued At Claim) が現在時刻よりも過去の日時を表すUNIXタイムスタンプ値となっているか
  • exp (Expiration Time Claim)が現在時刻よりも未来の日時を表すUNIXタイムスタンプ値となっているか
  • sub (Subject Claim)がログインユーザの所持するMobageユーザーIDと一致するか

なお、iss 値は sandbox/service で以下のように異なる値となっています。

環境issの値
sandboxhttps://sb-connect.mobage.jp
servicehttps://connect.mobage.jp

ログインセッションの発行​

id_token が妥当な場合、JWT Claims Set の sub 値が Mobage のユーザー ID となるので、このユーザー向けのログインセッションを発行します。

TOC

動作確認​

では、開発したプログラムを Game Server に配置します。

ファイル名URL
config.phphttp://localhost/mobage-jssdk-sample-login/config.php
login_hybrid.phphttp://localhost/mobage-jssdk-sample-login/authorization_code_grant_flow/login_auth.php
authorize.phphttp://localhost/mobage-jssdk-sample-login/authorization_code_grant_flow/authorize.php
login_cb_get.phphttp://localhost/mobage-jssdk-sample-login/authorization_code_grant_flow/login_cb_get.php

上記のように配置できたら、http://localhost/mobage-jssdk-sample-login/authorization_code_grant_flow/login_auth.php にアクセスしてください。

ユーザーが Mobage Connect へログインしていない場合は、以下のようにログインフォーム画面に遷移します。
(ログインはしているがゲームをインストールしていない場合は、ゲームへのインストール同意確認画面に遷移します。)

 
必要事項を入力してMobage Connect へのログインが成功すると、Game Server にてログインセッションが生成されます。
ログインセッションが生成された後に、ログイン状態を確認すると、下記のようにPeople API で取得した Mobage ユーザーニックネームが表示されます

Mobage Connect へログインして、Mobage ユーザーニックネームを表示できていることを確認できました。

開発したコード​

このチュートリアルで開発したコードは Github から clone できます。

$ git clone https://github.com/DeNADev/mobage-jssdk-sample-login.git

利用したライブラリは下記になります。

更新履歴​

  • 2016/04/11
    • JWT の詳細説明リンクを追加
  • 概要
  • 作成するファイル一覧
  • チュートリアルをはじめる前に
  • 開発のステップ
    • Game Server でログイン処理を実施する
  • 動作確認
  • 開発したコード
  • 更新履歴