Mobage HTML5 Game Quick Guide

# ログインフローの概要

このページではログインフローの全体像と、推奨するログインフローについて説明します。
Mobage では OAuth 2.0 / OpenID Connect 1.0 ベースの 認可システムを提供しており、これらの仕様に紐づいた用語を用います。 不明な用語があれば、用語についての補足をご確認ください。

# ログインフローの選択

Mobageでは3種類のログインフローをサポートしており、Hybrid フローを推奨しています。 ここでは Hybrid フローについて説明します。

TIP

Hybrid フローは現在 Mobage JavaScript SDK を用いて実装する v2 を提供しており、v1 の新規利用開始は出来ません。 本ページでは、v2 についての説明となります。

# ログインフローの全体像

Hybrid フローのログインシーケンスは下記のようになります。 Authentication Overview

以下ではシーケンスに合わせて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() を呼び出します。

かんたん会員登録

mobage.oauth.connect({
    state: state,
    requestType: "window", // "window" を指定すると、Hybrid フローで認可リクエストが送信されます
    easyRegistration: true   // true を指定すると、認可リクエストと同時にかんたん会員の発行が行われます
}, function(err, result) {
    // callback 処理
});

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

mobage.oauth.connect({
    state: state,
    requestType: "window"
}, function(err, result) {
    // callback 処理
});

# 規約の表示について

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

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

Agreement Sample

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

同意事項等（必読）

mobage.ui.show( "client_agreement_menu");

会員規約等（必読）

mobage.ui.show( "client_agreement_menu",{ "isEasyRegistration": true});

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

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

{
    connected: true,
    login: true,
    response: {
        code : "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        state : "mobage-connect_XXXXXXXXXXXXXXXXXXXXXXX",
        session_state : "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    }
}

Redirect Endpoint へこれらの code, state, session_state を送信します。

詳細については画面遷移せずにログインの Redirect Endpointへセッション情報を送信 をご確認ください。

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

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

  • 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 認証

Hybird フローにおける 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 は JWT 形式でエンコードされているため、サードパーティの JWT ライブラリ を利用して公開鍵を利用した JWT の検証を実装してください。

サンプルアプリケーションを実行する から配布している Java サンプルコードでは Java JWT: JSON Web Token for Java and Android を利用しています。

ID Token の検証の詳細については画面遷移せずにログインの ID Tokenの検証 をご確認ください。

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

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

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

# API

# 用語についての補足

用語 説明
Authorization Code Access Tokenを取得するために利用します。 code パラメータを指します。
Authorization Request Authorization Code を取得するためのリクエスト
Authorization Endpoint Authorization Request を送信する先のURI
Redirection Endpoint redirect_uri パラメータで指定する、Authorization Request に対するレスポンスを返すURI
Access Token API を実行するために利用する Token。access_token パラメータを指します。
Refresh Token Access Token を再発行する際に必要な token です。 refresh_token パラメータを指します。Mobage Connect では90日間有効です。
ID Token JSON Web Token (JWT) 形式でエンコードされた、ユーザー認証情報を含む署名付きトークン。
Token Request Access Token や ID Token 等の各種 Token を取得するためのリクエスト
Token Endpoint Token Requestを送信する先のURI

← アイテム購入フローの概要 →

MIT Licensed | Copyright © 2020-present DeNA.Co., Ltd. All rights reserved.