画面遷移せずにログイン(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 値を発行する
1. ログイン状態でないとアクセスできないコンテンツへのリクエスト
2. ログインセッションが無い場合、state の発行と保存リクエストを Session DB に向けて行います。
3. state の発行が行われ、保存レスポンスが返ります。
4. 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ステップで進めます。

ログインセッションが無い場合、state 値を発行する

Mobage Connect へログインしていないとアクセス出来ないコンテンツにユーザーがアクセスした際に、 Game Server で管理しているユーザーのログインセッションを確認します。
ログインセッションが無い場合、"state"値(8文字以上256文字以内の文字列)を生成し、セッション上に保存します。
この state 値は後ほど Mobage JS SDK のメソッドを実行する際に利用するので、JavaScript から読み込めるように HTML Document 上に書き出しておきます。

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

 
TOC
 

 

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

mobageReady イベントの呼び出し

非同期に実行される JavsScript SDK の読み込みが完了すると、"mobageReady" イベントが呼び出されます。

mobage-jssdk-sample-login/main.js

 

mobage.init() の呼び出し

Mobage Developers Japan(デベロッパーサイト) での設定値を利用して mobage.init() メソッドを呼び出し、 Mobage JS SDK の初期化を行います。
このメソッドは Mobage JS SDK の機能を使うために必ず呼び出す必要があります。

mobage-jssdk-sample-login/main.js

mobage.oauth.getConnectedStatus() メソッドの呼び出し

ログイン状態やインストール状態を確認するために mobage.oauth.getConnectedStatus メソッドを実行します。

mobage-jssdk-sample-login/main.js
このメソッドを実行した際に新たな 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 へログインしている / ゲームをインストールしている
  • Mobage Connect へログインしている / ゲームをインストールしていない
  • Mobage Connect へログインしていない / ゲームをインストールしていない
     
    上記のように状態の変化に応じて、ログイン画面を出し分けるなどすることが可能です。
     
    result レスポンスが返って来た場合
    Mobage Connect にログインしていて、なおかつゲームをインストールしている場合、以下のような result レスポンスが返ります。

    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 レスポンスが返ります。

この場合は、その後の 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
この connect() メソッドの呼び出しはクリックイベントなどのブラウザによって開始されたイベントハンドラの中で呼び出すようにします。
ユーザーアクションを伴わずスクリプトによって呼び出すと(非同期処理等)、ブラウザのポップアップブロック機能によって window が開かない場合があります。

Redirect Endpointへcode, state, session_state を送信する

Mobage Connect へのログインとゲームのインストールが実行されると、以下のような result レスポンスが返ります。

Redirect Endpoint へこれらの code, state, session_state を送信します。
ここでは下記のようなコードで実現します。

mobage-jssdk-sample-login/main.js
Redirect Endpointはapplication/json 形式のリクエストを受け付ける形になっていますが、
code, state, session_state を受け取れるのであればどのような形式でも構いません。

 
TOC

 

 

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

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

 

 

state 値の検証

Client からリクエストを受け取り、リクエスト内の state 値を検証します。

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

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

mobage-jssdk-sample-login/hybrid_flow/login_cb_post.php
この 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

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

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

なお、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

なお、各環境での 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 の例を以下に示します。

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

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

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 に配置します。
 

ファイル名

 URL

config.php

http://localhost/mobage-jssdk-sample-login/config.php

login_hybrid.php

http://localhost/mobage-jssdk-sample-login/hybrid_flow/login_hybrid.php

main.js

http://localhost/mobage-jssdk-sample-login/main.js

login_cb_post.php

http://localhost/mobage-jssdk-sample-login/hybrid_flow/login_cb_post.php

 
上記のように配置できたら、http://localhost/mobage-jssdk-sample-login/hybrid_flow/login_hybrid.php にアクセスしてください。
以下のようにログインボタンが表示されます。
 

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

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

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

開発したコード

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

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

更新履歴

  • 2017/01/30
    • getConnectedStatus のレスポンスについて追記
  • 2016/04/11
    • JWT の詳細説明リンクを追加

PREVIOUS

概要

NEXT

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