【オプション】画面遷移してログイン(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ステップで進めます。

ログイン状態で無いとアクセスが出来ないコンテンツにて、ログインセッションを確認します。
ログインセッションが無い場合、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

なお、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 値です。

 
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
この 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

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

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

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

なお、各環境での 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/firebase/php-jwt

JWT のデコード

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

mobage-jssdk-sample-login/authorization_code_grant_flow/login_cb_get.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/authorization_code_grant_flow/login_auth.php

authorize.php

http://localhost/mobage-jssdk-sample-login/authorization_code_grant_flow/authorize.php

login_cb_get.php

http://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 できます。

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

更新履歴

  • 2016/04/11
    • JWT の詳細説明リンクを追加

PREVIOUS

画面遷移せずにログイン(Hybridフロー)

NEXT

【オプション】GameServer使わないログイン(Client-Side フロー)