【オプション】画面遷移せずにログイン(Hybridフロー)
概要
Game Server を利用して、画面遷移の極力発生しないアプリケーションに適した ID 連携を行うのが Hybrid フロー です。
Hybrid フローでは、ゲーム画面からログイン認証画面に画面遷移するのではなく、ゲーム画面とは別の新しい Window としてログイン認証画面を開きます。
ユーザーがログイン認証画面(新しい Window )での入力を終えて認可を受けると、ログイン認証画面の Window が閉じることで、ユーザーは元のゲーム画面に戻ります。
ここでは、Hybrid フロー により Mobage Connect へログインする機能を開発していきます。
作成するファイル一覧
このチュートリアルで作成するファイルは下記になります。
| ファイル名 | 概要 |
|---|---|
| config.php | 各種設定値をまとめます |
| login_hybrid.php | Login Session を確認して state 値を発行します |
| main.js | Mobage Connect へのログイン状態を確認/ログインする処理を実施します |
| login_cb_post.php | Game Server でのログイン処理を実施します |
チュートリアルをはじめる前に
このチュートリアルは、以下のチュートリアルを終わらせている前提で進めます。
以下のチュートリアルを完了していない場合は、先にそちらを完了させましょう。
また、以下のライブラリを利用するので、ダウンロードしておきます。
Hybrid フローの概要
Hybrid フローは以下のような流れでログイン完了となります。各番号における概要を以下で説明していきます。

A. Login Sessionを確認して state 値を発行する
- ログイン状態でないとアクセスできないコンテンツへのリクエスト
- ログインセッションが無い場合、state の発行と保存リクエストを Session DB に向けて行います。
- state の発行が行われ、保存レスポンスが返ります。
- state 値を返却します。
B. Mobage Connect へのログイン状態とゲームのインストール状態を確認する
101. mobage.oauth.getConnectedStatus() を呼び出し、ログイン状態を確認します。
102.【プラットフォーム側の処理】Mobage JSSDK が Mobage Connect のログインセッションを持っているか、既にゲームをインストールしているかどうかを確認します。
103.【プラットフォーム側の処理】Mobage Platform がログインセッションとゲームのインストール状態を返します。
104. mobage.oauth.getConnectedStatus() のコールバックを呼び出されます。引数は、code, state, session_state の 3 つです。(ログインかつインストール状態の際には getConnectedStatus() は、暗黙的なAuthorization Requestを行います。)
C. ログイン/インストールボタンを表示し実行する
105. ゲームをまだ始めていない場合(connected で無い場合)、mboage.oauth.connect() を呼び出し、Mobage のログイン画面を呼び出します。
106.【プラットフォーム側の処理】Mobage JSSDK が認証処理をリクエストします。この段階でユーザーの状態に応じて、ログイン画面や NBPF 認可画面が表示されます。
107.【プラットフォーム側の処理】認可完了後にレスポンスを JSSDK に返します。
108. mobage.oauth.connect のコールバックが呼び出されます。引数は、code, state, session_state の 3 つです。
mobage.oauth.connect() を非同期処理のコールバックなどで呼び出すようにすると、ブラウザのポップアップブロック機能でログイン画面がブロックされて表示されませんのでご注意ください
D. Game Server でログイン処理を実施する
201. Game Server の Redirect Endpoint へリクエストします。
202. Game Server のセッションから state 値を取得するためのリクエストを行います。
203. state 値を返却します。
204. Client から送信された state 値と Game Server の state 値が一致するか確認します。
205. state 値が一致した場合、Token Endpoint に Token Request を送信します。
206. Token Response が返却されます。(access_token, refresh_token, user_id, session_state, expires_in, scope, token_type が返ります)
207. 返却された id_token を JWT で検証します。
208. access_token, refresh_token, user_id, session_state を保存をリクエストします。
209. access_token, refresh_token, user_id, session_state の保存レスポンスが返ります。
210. ログインセッションを発行します。
211. ログインセッションを発行したレスポンスを返します。
212. ログイン状態でないとアクセスできないコンテンツへのリクエスト
213. レスポンスが返ります。
表中に登場する各種 Endpoint の説明です。
Endpoint | 説明 |
Authorization Endpoint | Client アプリケーションがユーザーの認可を得る為のエンドポイントです。 |
Token Endpoint | API を利用する際に用いる Access Token を得る為のエンドポイントです。 |
Protected Endpoint | ゲームのログインセッションを持った UserAgent でなければ閲覧出来ないエンドポイントです。 |
Redirect Endpoint | Authoirization Response を受け取り、ログイン処理を行う前の検証を行った上 で妥当であればログインセッションを発行し、Protected Endpoint にリダイレ クトするエンドポイントです。 |
開発のステップ
Hybrid フローを実現するために、大きく以下の4ステップで進めます。
-
A. Login Sessionを確認して state 値を発行する
ログイン状態で無いとアクセスが出来ないコンテンツにて、ログインセッションを確認します。
ログインセッションが無い場合、state 値を発行し、新規に発行したセッションと関連づけます。
上記の処理のシーケンス図は以下になります。
ログインセッションが無い場合、state 値を発行する
Mobage Connect へログインしていないとアクセス出来ないコンテンツにユーザーがアクセスした際に、 Game Server で管理しているユーザーのログインセッションを確認します。
ログインセッションが無い場合、"state"値(8文字以上256文字以内の文字列)を生成し、セッション上に保存します。
この state 値は後ほど Mobage JS SDK のメソッドを実行する際に利用するので、JavaScript から読み込めるように HTML Document 上に書き出しておきます。
この state 値は 認可手続きを始めた User Agent と、 認可情報をもたらした User Agent が同一であることを確認するための値です。CSRF 攻撃を防止するために用いられます。
B. Mobage Connect へのログイン状態とゲームのインストール状態を確認する
Mobage JS SDK の mobage.oauth.getConnectedStatus メソッドを使って、Mobage Connect へのログイン状態 と、ゲームのインストール状態 を確認します。
この処理のシーケンス図が下記になります。
Mobage JS SDK の読み込み
Mobage JS SDK を読み込みつつ、
ログイン処理ロジックが書かれた JavaScript のプログラムを読み込みます。
mobage-jssdk-sample-login/hybrid_flow/login_hybrid.php
<script type='text/javascript'>
(function() {
var script = document.createElement('script');
script.type = 'text/javascript';
script.async = true;
script.src = "<?php echo JSSDK_PATH ?>";
document.getElementsByTagName('script')[0].parentNode.appendChild(script);
})();
</script>
<script type='text/javascript' src="../main.js?time=<?php echo time() ?>"></script>
mobageReady イベントの呼び出し
非同期に実行される JavsScript SDK の読み込みが完了すると、"mobageReady" イベントが呼び出されます。
mobage-jssdk-sample-login/main.js
document.addEventListener('mobageReady', function() {
mobage.init() の呼び出し
Mobage Developers Japan(デベロッパーサイト) での設定値を利用して mobage.init() メソッドを呼び出し、 Mobage JS SDK の初期化を行います。
このメソッドは Mobage JS SDK の機能を使うために必ず呼び出す必要があります。
mobage-jssdk-sample-login/main.js
mobage.init({ clientId: clientData.clientId, redirectUri: clientData.redirectUri });
mobage.oauth.getConnectedStatus() メソッドの呼び出し
ログイン状態やインストール状態を確認するために mobage.oauth.getConnectedStatus メソッドを実行します。
mobage-jssdk-sample-login/main.js
mobage.oauth.getConnectedStatus(params, function(err, result) {
if (result) {
console.log('getConnectedStatus is OK');
sendToRedirectURI(result);
getMyInformation();
} else {
console.log('getConnectedStatus failed');
mobageLoginButton.style.cssText = 'visibility:visible';
mobageLogoutButton.style.cssText = 'visibility:hidden';
}
});
このメソッドを実行した際に新たな window が表示されることはありません。
ユーザが Mobage Connect にログインしていない場合には、即座にエラーレスポンスが callback に渡されます。
ユーザが Client アプリをインストールしていない場合にも、即座にエラーレスポンスが callback に渡されます。
mobage.oauth.getConnectedStatus() メソッドのレスポンス
mobage.oauth.getConnectedStatus() メソッドのレスポンスは、ユーザーの状態によって下記のように変化します。
| \ | Mobage Connect へログインしている | Mobage Connect へログインしていない |
| ゲームをインストールしている | result レスポンスが返る, "login":true, "connected":true が返る | ー |
| ゲームをインストールしていない | error レスポンスが返る, "login":true, "connected":false が返る | error レスポンスが返る, "login":false, "connected":false が返る |
-
Mobage Connect へログインしている / ゲームをインストールしている
{"login":true,"connected":true,"response":{"code" : "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX","state" : "mobage-connect_XXXXXXXXXXXXXXXXXXXXXXX","session_state" : "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" } -
Mobage Connect へログインしている / ゲームをインストールしていない
{"login":true,"connected":false,"response":{"error":"consent_required","error_description":"This+action+requires+user's+consent"}} -
Mobage Connect へログインしていない / ゲームをインストールしていない
{"login":false,"connected":false,"response":{"error":"login_required","error_description":"This+action+requires+user's+login"}}上記のように状態の変化に応じて、ログイン画面を出し分けるなどすることが可能です。
result レスポンスが返って来た場合
Mobage Connect にログインしていて、なおかつゲームをインストールしている場合、以下のような result レスポンスが返ります。
{"code" : "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX","state" : "mobage-connect_XXXXXXXXXXXXXXXXXXXXXXX","session_state" : "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"}key value code Token リクエストの際に Server Side 向けの access token を得るために必要な文字列です state Authorization リクエスト時に指定した state 値です session_state Mobage Connect が User Agent に発行しているログインセッションの状態を透過的に表す文字列です。Single Logout 連携時に、この session _state 値に変更があれば、 Game Server のセッションを無効にしてログアウト処理を進める必要があります この場合には、Redirect Endpoint に対して code, state, session_state を送信します。
また、その後の mobage.oauth.connect メソッドを呼び出さないように、ログインボタンを非表示にします。
(ログインかつインストール状態の際には getConnectedStatus() は、暗黙的なAuthorization Requestを行います。)
error レスポンスが返って来た場合
ログインとインストールの両方がまだの場合、以下のような error レスポンスが返ります。
{"login":false,"connected":false,"response":{"error":"login_required","error_description":"This+action+requires+user's+login"}}
この場合は、その後の mobage.oauth.connect メソッドを呼び出せるようにログインボタンを表示します。
TOC
C. ログイン/インストールボタンを表示し実行する
「Mobage Connect にログインしていない」、もしくは「ゲームをインストールしていない」のどちらかに当たる場合に、mobage.oauth.connect()メソッドを呼び出します。mobage.oauth.connect() メソッドを呼び出すと、ユーザーにログインフォーム、もしくはゲームインストールの同意画面が表示されます。ユーザーが必要な情報を入力して、Callback関数が実行されたら、Redirect Endpointに対してcode, state, session_stateを送信しします。
以上の処理のシーケンス図が下記になります。
ログイン/インストールボタンを設定
ユーザをログイン状態かつインストール状態にするために、インストールボタンを設定します。
mobageログインボタンを定義し、ボタンの'click'イベントによって mobage.oauth.connect メソッドが実行されるようにします。
mobage.oauth.connect メソッドが成功した場合、Redirect Endpoint に対して code, state, session_state を送信します。
mobage-jssdk-sample-login/main.js
mobageLoginButton.addEventListener('click', function() {
mobage.oauth.connect({ state: clientData.state }, function(err, result) {
if (err) {
console.log('login failed: error = ', err);
} else {
// console.log('result:', result);
console.log('mobage.oauth.connect is OK(login success)');
sendToRedirectURI(result);
getMyInformation();
}
});
});
この connect() メソッドの呼び出しはクリックイベントなどのブラウザによって開始されたイベントハンドラの中で呼び出すようにします。
ユーザーアクションを伴わずスクリプトによって呼び出すと(非同期処理等)、ブラウザのポップアップブロック機能によって window が開かない場合があります。
Redirect Endpointへcode, state, session_state を送信する
Mobage Connect へのログインとゲームのインストールが実行されると、以下のような result レスポンスが返ります。
{
"code" : "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"state" : "mobage-connect_XXXXXXXXXXXXXXXXXXXXXXX",
"session_state" : "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}
Redirect Endpoint へこれらの code, state, session_state を送信します。
ここでは下記のようなコードで実現します。
mobage-jssdk-sample-login/main.js
function sendToRedirectURI(result) {
mobageLoginButton.style.cssText = 'visibility:hidden';
mobageLogoutButton.style.cssText = 'visibility:visible';
var response = result.response;
var payload = {
code : response.code,
state : response.state,
session_state : response.session_state
};
var req = new XMLHttpRequest();
req.open('POST', clientData.redirectUri);
req.setRequestHeader('Content-Type', 'application/json;charset=UTF-8');
req.addEventListener('load', function() {
// ログイン処理後のハンドリング
} , false);
req.send(JSON.stringify(payload));
}
Redirect Endpointはapplication/json 形式のリクエストを受け付ける形になっていますが、
code, state, session_state を受け取れるのであればどのような形式でも構いません。
D. Game Server でログイン処理を実施する
先ほど Redirect Endpoint に送信した code, state, session_state を受け取って Game Server でのログイン処理を実装します。
Game Server でのログイン処理では、下記を実行します。
- state 値の検証
- Token リクエストの送信と Token レスポンスの受け取り
- id_token の検証
- ログインセッションの発行
上記処理のシーケンス図は以下になります。
state 値の検証
Client からリクエストを受け取り、リクエスト内の state 値を検証します。
Game Server の state 値 と一致するか確認
Game Server のセッションから state 値を取得し、Client から送信された state 値と一致するか確認します。
state 値が一致しない場合は、不正なリクエストとみなし、エラーレスポンスを返して処理を終了してください。
mobage-jssdk-sample-login/hybrid_flow/login_cb_post.php
// validate state
if ($request_params['state'] !== $_SESSION['state']) {
render_error_json();
}
この state 値は 認可手続きを始めた User Agent と、 認可情報をもたらした User Agent が同一であることを確認するための値です。 CSRF 攻撃を防止するために用いられます。
Token リクエストの送信と Token レスポンスの受け取り
Token リクエストのパラメタ設定
state 値が一致した場合、Token Endpoint に Token Request を送信します。
Token Request で指定するパラメタを以下のように設定します。
mobage-jssdk-sample-login/hybrid_flow/login_cb_post.php
// token endpoint request
$token_endpoint_request_params = [
'client_id' => CLIENT_ID,
'redirect_uri' => REDIRECT_POST_ENDPOINT,
'code' => $request_params['code'],
'grant_type' => 'authorization_code'
];
なお、それぞれのパラメタには以下の値を指定してください。
| key | value |
| client_id | Mobage Developers Japan で発行された Client ID 値 |
| redirect_uri | Hybrid フローで指定した Redirect URI 値 |
| code | mobage.oauth.connect メソッドの response で受け取った code 値 |
| grant_type | authorization_code を指定します |
Token リクエストのヘッダー設定
Token Request で Client 認証として client_secret_basic を用いる場合は、
下記のように記載してください。
mobage-jssdk-sample-login/hybrid_flow/login_cb_post.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_basic | Client 認証に Basic 認証を用います。 |
| client_secret_post | Client 認証パラメータを application/x-www-form-urlencoded パラメータに含める方式です。 |
Token Request の送信
パラメタ、ヘッダーをまとめて以下のように Token Request を送信します。
mobage-jssdk-sample-login/hybrid_flow/login_cb_post.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 |
| sandbox | https://sb-connect.mobage.jp/connect/1.0/api/token |
| service | https://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"
}
| key | value |
|---|---|
| access_token | Game Server から API を実行するための access_token が返されます。 |
| id_token | JSON Web Token というフォーマットで提供された値です。このid_token を検証することによってログイン処理を完了させます。 |
| token_type | Bearer |
| expires_in | 900 |
| refresh_token | grant_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/F21/jwt
JWT のデコード
Token Response で得られた id_token は Platform 側の秘密鍵で署名がつけられているため、 X.509 形式の公開鍵を利用して、署名の妥当性を検証します。(署名の検証で利用する公開鍵)
mobage-jssdk-sample-login/hybrid_flow/login_cb_post.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, '/var/log/php/error.log');
render_error_json();
}
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の値 |
|---|---|
| sandbox | https://sb-connect.mobage.jp |
| service | https://connect.mobage.jp |
ログインセッションの発行
id_token が妥当な場合、JWT Claims Set の sub 値が Mobage のユーザー ID となるので、このユーザー向けのログインセッションを発行します。
TOC
動作確認
では、開発したプログラムを Game Server に配置します。
上記のように配置できたら、http://localhost/mobage-jssdk-sample-login/hybrid_flow/login_hybrid.php にアクセスしてください。
以下のようにログインボタンが表示されます。

ログインボタンを押すと、以下のようにログインフォームが新しい Window にて表示されます。
(もしくは、ゲームへのインストール同意確認画面がオーバーレイで表示されます。)

必要事項を入力して Mobage Connect へのログインが成功すると、People API で取得した Mobage ユーザーニックネームが表示されます

Mobage Connect へログインして、Mobage ユーザーニックネームを表示できていることを確認できました。
開発したコード
このチュートリアルで開発したコードは Github から clone できます。
$ git clone https://github.com/DeNADev/mobage-jssdk-sample-login.git
利用したライブラリは下記になります。
更新履歴
- 2017/01/30
- getConnectedStatus のレスポンスについて追記
- 2016/04/11
- JWT の詳細説明リンクを追加