# ログインフローの概要

このページではログインフローの全体像と、推奨するログインフローについて説明します。
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 処理
});

WARNING

mobage.oauth.connect() を非同期処理のコールバックなどで呼び出すようにすると、ブラウザのポップアップブロック機能でログイン画面がブロックされて表示されませんのでご注意ください

# 規約の表示について

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

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

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.