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

This page is not available in English.
Please select another language.

概要

Game Server を利用して、画面遷移の極力発生しないアプリケーションに適した ID 連携を行うのが Hybrid フロー です。
 
Hybrid フローでは、ゲーム画面からログイン認証画面に画面遷移するのではなく、ゲーム画面とは別の新しい Window としてログイン認証画面を開きます。
ユーザーがログイン認証画面(新しい Window )での入力を終えて認可を受けたあと、ログイン認証画面の Window を閉じることで、ユーザーは元のゲーム画面に戻ります。
Mobage では OAuth 2.0 / OpenID Connect 1.0 ベースの 認可システムを提供しており、これらの仕様に紐づいた用語を用います。 不明な用語があれば、用語についての補足をご確認ください。

Hybrid フローは現在 Mobage JavaScript SDK を用いて実装する v2 を提供しており、v1 の新規利用開始は出来ません。 本ページでは、v2 についての説明となります。
また、 本フローを実装する際は、 Mobage Javascript SDK v3.9.1 以降でご利用いただけます。
本フローは 2020/12/1 以降に登録されたアプリケーションのみ利用可能です。

ログインフローの全体像

このページではログインフローの全体像と、推奨するログインフローについて説明します。
 
Hybrid フローのログインシーケンスは下記のようになります。

 

 

以下ではシーケンスに合わせて4つのフェーズに分けて説明します

  • state値の発行
  • Mobage へのログイン/アプリケーション認可状態の確認
  • ゲーム開始ボタンの表示・実行
  • 開発者サーバーでのログイン処理
     

    state値の発行

まずは後の各ステップで利用する state 値を発行します。 state 値は8文字以上256文字以内の文字列を指定してください。
発行した state は Developer Server で管理しているユーザーのログインセッションに紐づけて保存し、ゲームクライアントへ返却します。

Mobage へのログイン/アプリケーション認可状態の確認

Mobage へのログイン状態および認可状態を確認するために Mobage JavaScript SDK(JSSDK)mobage.oauth.getConnectedStatus() を呼び出します。 Mobage オープンプラットフォーム上で Mobage のログイン状態と認可状態の確認処理が完了すると、 mobage.oauth.getConnectedStatus() のコールバックを呼び出され、その際パラメータとして login / connect が返却されます。

返却された login / connect パラメータの値から以下のようにユーザ状態を判別します。

login

connected

状態

false

false

未ログイン

true

false

未認可

true

true

ゲーム開始可能

ゲーム開始ボタンの表示・実行

未ログイン・未認可の場合は各種規約文言と共にゲーム開始ボタンの表示を行う必要があります。
ゲーム開始ボタンはユーザ状態に応じ、未ログインの場合はモバゲーログインボタン・かんたん会員登録ボタンの二つを、未認可時はインストールボタンを表示します。

状態

ボタン

文言

未ログイン

かんたん会員登録

新規かんたん会員で始める

未ログイン

モバゲーログイン

モバゲーIDで始める

未認可

インストール

ゲームを始める

各ボタン押下時には以下のようにmobage.oauth.connect() を呼び出し、結果に応じて Redirect Endpoint にセッション情報を送信します。

かんたん会員登録

モバゲーログイン / インストール

規約の表示について

各種ゲーム開始ボタンの表示に合わせ、以下のように規約リンクを表示して頂く必要があります。

  • 規約文言は各種ボタンの真上に表示してください
  • かんたん会員向けの規約文言「会員規約等(必読)に同意して」、それ以外は「同意事項等(必読)に同意して」としてください。
 

リンク押下時には以下のように JavaScript SDK の規約表示用 API mobage.ui.show を呼び出します。

同意事項等(必読)

会員規約等(必読)

Redirect Endpointへセッション情報を送信

mobage.oauth.connect() を呼び出すと、以下のような result レスポンスが返ります。
resultには code, state, session_state のセッション情報が含まれます。

Redirect Endpoint へこれらの code, state, session_state を送信します。
ここでは application/json 形式のリクエストを以下のように実現します。
code, state, session_state を受け取れるのであればどのような形式でも構いません。

開発者サーバーでのログイン処理

開発者サーバーでのログイン処理に必要な実装は下記となります

  • state の検証
  • Token Request の送信
  • ID Token の検証
  • ログインセッションの発行

state の検証

セッションに紐づけた state と リクエストパラメータから取得した state が一致するかを確認します。 state が一致しない場合は、不正なリクエストとみなし、エラーレスポンスを返して処理を終了してください。

Token Request の送信

ID Token などの各種 Token 取得のためのリクエストを下記の要領で送信します。

URI

各環境での 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

パラメータ

application/x-www-form-urlencoded 形式で下記のパラメータを付与し、POSTメソッドで送信します。

key

value

client_id

Developer Site で発行された Client ID

redirect_uri

Developer Site に登録した Redirect URI

code

Authorization Response で受け取った code

grant_type

`authorization_code` を指定します

Client 認証

Hyblid フローにおける Token Request では、 Client 認証を行う必要があります。
Client 認証を行うには Client ID と Client Secret を Basic 認証ヘッダーとして、あるいはフォームパラメータ client_id および client_secret として渡します。
Client ID と Client Secret は Developer Site 上でアプリケーション登録を行うことで発行される値です。

ID Token の検証

Access Token の取得が成功した場合、レスポンスに含まれる ID Token の署名検証と JWT Claims Set の検証を行います。 ID Token は JSON Web Token(JWT)形式でエンコードされているため、サードパーティの JWT ライブラリ を利用して公開鍵を利用した JWT の検証を実装してください。

ここでは JWT の検証として以下のサードパーティライブラリを利用し、phpによる実装を行います。
https://github.com/F21/jwt

JWT のデコード

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

mobage-jssdk-sample-login/hybrid_flow/login_cb_post.php

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

JWT Claims Setの検証

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

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

key

検証項目

iss

JWT を発行したサーバの識別子が妥当か

aud

アプリケーションのClient IDと一致しているか

iat

現在時刻よりも過去の日時を表すUNIXタイムスタンプ値となっているか

exp

現在時刻よりも未来の日時を表すUNIXタイムスタンプ値となっているか

sub

ログインユーザの所持するMobageユーザーIDと一致するか

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

環境

issの値

sandbox

https://sb-connect.mobage.jp

service

https://connect.mobage.jp

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

セッションに紐づけた state と リクエストパラメータから取得した state が一致するかを確認します。 state が一致しない場合は、不正なリクエストとみなし、エラーレスポンスを返して処理を終了してください。

ID Token が妥当な場合、JWT Claims Set の sub 値が Mobage のユーザー ID となるので、このユーザー向けのログインセッションを発行します。 その際、Authorization Response で受け取った session_state パラメータをログインセッションと紐づけて保持してください。 保存した session_state パラメータは シングルログアウト連携に利用するパラメータです。

詳細は シングルログアウト連携 を参照してください。

API

用語についての補足

用語

説明

Authorization Code

Access Tokenを取得するために利用します。 [`code`](

https://tools.ietf.org/html/rfc6749#section-4.1.3

) パラメータを指します。

Authorization Request

Authorization Code を取得するためのリクエスト

Authorization Endpoint

Authorization Request を送信する先のURI

Redirection Endpoint

Authorization Request に対するレスポンスを返すURI

Access Token

API を実行するために利用する Token。[`access_token`](

https://tools.ietf.org/html/rfc6749#section-4.2.2

) パラメータを指します。

Refresh Token

Access Token を再発行する際に必要な token です。 [`refresh_token`](

https://tools.ietf.org/html/rfc6749#section-6

) パラメータを指します。Mobage Connect では90日間有効です。

ID Token

JSON Web Token (JWT) 形式でエンコードされた、ユーザー認証情報を含む署名付きトークン。

Token Request

Access Token や ID Token 等の各種 Token を取得するためのリクエスト

Token Endpoint

Token Requestを送信する先のURI

 

PREVIOUS

Summary

NEXT

【オプション】画面遷移せずにログイン(Hybridフロー)