【オプション】画面遷移してログイン(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.php | Login Session を確認します |
| authorize.php | state 値を発行し、Authorization Endpoint へリダイレクトします |
| login_cb_get.php | Game Server でのログイン処理を実施します |
チュートリアルをはじめる前に
このチュートリアルは、以下のチュートリアルを終わらせている前提で進めます。
以下のチュートリアルを完了していない場合は、先にそちらを完了させましょう。
また、以下のライブラリを利用するので、ダウンロードしておきます。
開発のステップ
Authorization Code Grant フローを実現するために、大きく以下の4ステップで進めます。
- Login Session を確認して state 値を発行する
- Authorization Request を送信し Authorization Response を受信する
- Game Server でログイン処理を実施する
ログイン状態で無いとアクセスが出来ないコンテンツにて、ログインセッションを確認します。
ログインセッションが無い場合、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 攻撃を防止するために用いられます。
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 |
| sandbox | https://sb-connect.mobage.jp/connect/1.0/services/authorize |
| service | https://connect.mobage.jp/connect/1.0/services/authorize |
Authorization Response の受信
User Agent が Authorization Endpoint にアクセス (Authorization Request) した際、ユーザーの状態によって以下のような挙動になります。
Mobage Connect へのログインに成功した時
成功時には以下のようなパラメータが Redirect Endpoint へのクエリパラメータとして渡されます。
| key | value |
|---|---|
| code | サーバーサイド向けの access token を得る為に Token Endpoint に grant_type=authorization_code でアクセスする際に必要な文字列です。 |
| state | Authorization Request 時に指定した state 値です。 |
| session_state | Mobage Connect が User Agent に発行しているログインセッションの状態を透過的に表す文字列です。原則として、ゲームサーバーが User Agent に発行するセッションデータに紐付け、 Single Logout 連携時に、この session_state 値に変更があれば、ゲームサーバー側のセッションを無効にしてログアウト処理を進める必要があります。 |
Mobage Connect へのログインに失敗した時
失敗時には以下のようなパラメータが Redirect Endpoint へのクエリパラメータとして渡されます。
| key | value |
|---|---|
| error | OAuth 2.0/OpenID Connect 1.0 で定義されるエラーコードが指定されます。 |
| error_description | error 内容を説明する文章が指定されます。 |
| state | Authorization Request 時に指定したstate 値です。 |
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'
];
なお、それぞれのパラメタには以下の値を指定してください。
| key | value |
| client_id | Mobage Developers Japan で発行された Client ID 値 |
| redirect_uri | Authorization Code Grant フローで指定した Redirect URI 値 |
| code | Authorization Response で受け取った code 値 |
| grant_type | authorization_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_basic | Client 認証に Basic 認証を用います。 |
| client_secret_post | Client 認証パラメータを 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 |
| 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/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の値 |
|---|---|
| sandbox | https://sb-connect.mobage.jp |
| service | https://connect.mobage.jp |
ログインセッションの発行
id_token が妥当な場合、JWT Claims Set の sub 値が Mobage のユーザー ID となるので、このユーザー向けのログインセッションを発行します。
動作確認
では、開発したプログラムを Game Server に配置します。
上記のように配置できたら、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 の詳細説明リンクを追加