konot edited this page Jun 29, 2018 · 6 revisions

Marvelous Connect Lite について、構築手順や運用マニュアルなどを記載しています。

構築手順

Marvelous Connect Lite の構築手順を説明します。

ソース編

Marvelous Connect Lite は Zend Framework 1 を利用した Zend Framework 1(以下 ZF1)アプリケーションです。
Marvelous Connect Lite は下記ディレクトリ構成となっています。(以降の説明便宜のために一部省略し、2階層目まで表示しています)

.
├── application
│   ├── Bootstrap.php
│   ├── cache                      ← Zend Framework がメタ情報キャッシュを作成できるようにパーミッションを「777」に変更してください。
│   ├── common
│   ├── configs
│   ├── controllers
│   ├── logics
│   ├── misp
│   ├── models
│   ├── modules
│   ├── plugins
│   ├── validate
│   └── views
├── database
│   ├── data
│   ├── common_ng_word.sql
│   ├── MISP_Event.sql
│   ├── MISP_Session.sql
│   ├── MISP_Trigger.sql
│   └── MISPLite.sql
├── docs
├── features
├── jmeter
├── language
├── library
├── nbproject
├── providers
├── public
│   ├── index.php                  ← Zend Framework のフロントファイルです。Web リクエストを受け付けるために public ディレクトリをドキュメントルートとしてください。
│   └── marvelous_resource
├── tests
└── vendor

ソースの配置場所に指定はありません。ご利用の環境に応じて任意の場所に配置できます。
ただし、Web リクエストを受け付けるために、ZF1 アプリケーションのフロントファイル「index.php」が含まれる public ディレクトリをドキュメントルートにする必要があります。
ご利用の httpd に応じて設定を行ってください。

ソース配置後、ZF1 がメタ情報キャッシュを作成できるように「application/cache」ディレクトリのパーミッションを「777」に変更してください。

動作環境の識別と、設定ファイル(application.ini)の関係について

ZF1 の設定ファイル(application.ini)には、動作環境別に設定群を記述することができます。
ZF1 は、その動作環境の識別のために環境変数 APPLICATION_ENV の値を利用します。

環境変数 APPLICATION_ENV の設定記述は、いくつか方法があります。

  1. httpd の設定ファイル(httpd.conf など)に記述する
  2. index.php と同じ階層に .htaccess を配置し、そこに記述する(Marvelous Connect Lite は左記の方法をとっています)

Marvelous Connect Lite では、下記の APPLICATION_ENV の値を利用しています。

APPLICATION_ENV 用途
production 本番・商用環境
staging 本番・商用環境未満の試験環境
testing 単体テスト
development 開発環境

ZF1 アプリケーションは、上記 APPLICATION_ENV の値と設定ファイル(application.ini)に記述された環境ディレクティブを照合し、動作環境に応じて適切な設定群を利用します。

環境ディレクティブは設定ファイル(application.ini)の上から順に解釈されていくため、差分設定を他ディレクティブに記述します。
同じ設定項目が見つかった場合は値を上書き します。

Marvelous Connect Lite の環境ディレクティブや用途は下記表になります。(表中、ボールド体とした文字列部分が、APPLICATION_ENV の値と一致している必要があります)
(production ディレクティブは必ず読み込まれるデフォルト設定です。)

環境ディレクティブ 用途
[production] 本番・商用環境
[staging : production] 本番・商用環境未満の試験環境
[testing: production] 単体テストモードディレクティブ
[development : production] 開発環境

ログ設定

Marvelous Connect Lite は Fluentd を利用したログ出力があります。

ソース配置後は、Fluentd のログ出力先ディレクトリの作成と、その設定記述が必要です。

対象ファイル:application/configs/application.ini

設定項目名:log.access.file
           log.external.file
           log.internal.file
           log.exception.file 

Marvelous Connect Lite の application.ini は、設定ディレクティブ「[production],[development : production] など」で環境別設定を行っていますので、記述場所を取り違えないようご注意ください。

application.ini(部分抜粋)
log.access.file = "作成した Fluentd のログディレクトリ/access.log"
log.external.file = "作成した Fluentd のログディレクトリ/external.log"
log.internal.file = "作成した Fluentd のログディレクトリ/internal.log"
log.exception.file = "作成した Fluentd のログディレクトリ/exception.log"

ソース編は以上です。

DB編

Marvelous Connect Lite を動作させるための DB 構築について説明します。
なお、本手順は MySQL の SOURCE コマンドで DDL, DML を投入しますので、
あらかじめサーバ上に DDL, DML ファイルを配置しておくこと、および MySQL にログインしてコマンド実行できることが前提となります。

DB 構築のための SQL

Marvelous Connect Lite には下記の DDL と DML が同梱されており、これを投入することで DB を構築します。

ファイル名 種類 用途
database/MISPLite.sql DDL Marvelous Connect Lite のコアテーブルを作成するための DDL です。
database/MISP_Event.sql DDL Marvelous Connect Lite の運用に必要な MySQL Event Scheduler です。
database/MISP_Session.sql DDL ID 連携時の情報をセッションテーブルに保存するための DDL です。
database/MISP_Trigger.sql DDL PK がオートインクリメント、かつ、物理削除を行うテーブルにて、mysqld 再起動時も支障がないようにするためのトリガーです。
database/common_ng_word.sql DDL NG ワード API が利用する NG ワードデータテーブルのための DDL です。
database/data/master.sql DML Marvelous Connect Lite のマスタデータを投入する DML です。アプリケーション情報や ID 連携プラットフォーム情報などが含まれています。
database/data/test.sql DML テストデータを投入する DML です。商用環境に適用しないよう注意してください。

DB 構築

以下の順番で構築します。

  1. Marvelous Connect Lite 用のDB作成

  2. DDL 実行

    1. MISPLite.sql
    2. MISP_Trigger.sql
    3. MISP_Session.sql
    4. MISP_Event.sql
    5. common_ng_word.sql
  3. DML 実行

    1. master.sql
    2. test.sql(開発環境用)
  4. 確認

  5. Marvelous Connect Lite の DB 接続設定

Marvelous Connect Lite 用のDB作成

  1. MySQL にログインする

    $ mysql -u xxxxx -h xxxx -P xxxxxx -p
    mysql>
    
  2. Marvelous Connect Lite 用のDBを作成する

    mysql> CREATE DATABASE misp_lite;
    

DDL 実行

  1. DDL の配置場所に change directory する

    $ cd ....
    
  2. MySQL にログインする

    $ mysql -u xxxxx -h xxxx -P xxxxxx -p
    mysql>
    
  3. 作成した DB に use する

    mysql> USE misp_lite;
    
  4. DDL 実行

    1. MISPLite.sql

      mysql> SOURCE MISPLite.sql
      
    2. MISP_Trigger.sql

      mysql> SOURCE MISP_Trigger.sql
      
    3. MISP_Session.sql

      mysql> SOURCE MISP_Session.sql
      
    4. MISP_Event.sql

      mysql> SOURCE MISP_Event.sql
      
    5. common_ng_word.sql

      mysql> SOURCE common_ng_word.sql
      

DML 実行

  1. DML の配置場所に change directory する

    $ cd ....
    
  2. MySQL にログインする

    $ mysql -u xxxxx -h xxxx -P xxxxxx -p
    mysql>
    
  3. 作成した DB に use する

    mysql> USE misp_lite;
    
  4. DML 実行

    1. master.sql

      mysql> SOURCE master.sql
      
    2. test.sql(開発環境用)

      mysql> SOURCE test.sql
      

確認

MySQL の SHOW TABLES コマンドを実行し、下記のテーブル状態であることを確認してください。

mysql> SHOW TABLES;
+-----------------------------------------------+
| Tables_in_misp_lite                           |
+-----------------------------------------------+
| application                                   |
| application_redirect_uri                      |
| application_user                              |
| application_user_currency                     |
| application_user_currency_payment_item        |
| application_user_payment                      |
| application_user_payment_cancel_log           |
| application_user_payment_id                   |
| application_user_payment_item                 |
| application_user_payment_item_id              |
| application_user_platform_relation            |
| application_user_target_currency_payment_item |
| application_user_target_product_payment_item  |
| common_ng_word                                |
| developer                                     |
| payment_device                                |
| payment_platform                              |
| payment_rating                                |
| platform                                      |
| platform_product                              |
| platform_product_item                         |
| platform_user                                 |
| session                                       |
| user                                          |
| user_platform_application_relation            |
+-----------------------------------------------+
25 rows in set (0.00 sec)

Marvelous Connect Lite の DB 接続設定

DB 情報に応じて Marvelous Connect Lite の DB 接続設定を行います。

対象ファイル:application/configs/application.ini

設定項目名:db.mainDb
           db.subDb

Marvelous Connect Lite の application.ini は、設定ディレクティブ「[production],[development : production] など」で環境別設定を行っていますので、記述場所を取り違えないようご注意ください。

application.ini(部分抜粋) 備考
; DB接続情報(複数DB用に"mainDb"など中カテゴリを用意) -
db.mainDb.adapterNamespace = "Common_Db_Adapter" -
db.mainDb.type = "pdo_mysql" -
db.mainDb.dbname = "misp_lite" 作成した DB 名を記述してください
db.mainDb.host = "127.0.0.1" DB 環境に応じた MySQL のホストを記述してください
db.mainDb.port = "3306" DB 環境に応じた MySQL の接続ポート番号を記述してください
db.mainDb.charset = "UTF8" -
db.subDb.adapterNamespace = "Common_Db_Adapter" -
db.subDb.type = "pdo_mysql" -
db.subDb.dbname = "misp_lite" サブDB、いわゆるスレーブDBの設定です。スレーブDBが存在しない場合はメインDBの設定を記述してください。
db.subDb.host = "127.0.0.1" -
db.subDb.port = "3306" -
db.subDb.charset = "UTF8" -

DB 編は以上です。

データリセット手順

データリセットは次の順番で行ってください。(application_id は適宜読み替えてください)

  1. アプリケーションユーザプラットフォーム関連テーブル

    
    

SELECT * FROM application_user_platform_relation WHERE application_id = 'xxxxx' AND application_world_id <> 'pre'; DELETE FROM application_user_platform_relation WHERE application_id = 'xxxxx' AND application_world_id <> 'pre'; SELECT * FROM application_user_platform_relation WHERE application_id = 'xxxxx' AND application_world_id <> 'pre';

  1. アプリケーションユーザテーブル

    
    

SELECT * FROM application_user WHERE application_id = 'xxxxx' AND application_world_id <> 'pre'; DELETE FROM application_user WHERE application_id = 'xxxxx' AND application_world_id <> 'pre'; SELECT * FROM application_user WHERE application_id = 'xxxxx' AND application_world_id <> 'pre';

シーケンス図

ユーザ登録・認証

使用するAPIメソッド概要

対象API HTTPメソッド 内容 備考
/app/people POST ゲーム内ユーザをマーベラスコネクト内に登録する パスワードを未設定でユーザ登録を行った場合、マーベラスコネクト側で一意のパスワードを自動発行する
/app/token POST ユーザIDとパスワードで認証を行う 認証に成功した際、トークンが発行される

実装手順

①ゲーム内ユーザの登録

  1. クライアント側でゲーム内ユーザの作成を開始し、サーバ側にもユーザ情報を登録(図-1~2)

  2. 作成されたユーザの情報を/app/peopleのPOSTリクエストでマーベラスコネクトへ登録(図-3)

    • 登録の際、マーベラスコネクト側でパスワードを自動発行する

    • パスワードはゲーム側で発行したいという場合

      • POSTリクエスト時にパスワードの情報も一緒に送ればマーベラスコネクト側で送られてきたパスワードでユーザ登録されます(図-3)
  3. レスポンスにユーザ情報とともにパスワードが返ってくるのでクライアントに保存しておく(図-6)

②ゲーム内ユーザの認証

  1. クライアントに保存されているユーザIDとパスワードを使用し、/app/tokenのPOSTリクエスト(ユーザ認証API)を行う(図-1~2)
  2. 認証が成功した場合、レスポンスからトークンが取得できるのでサーバ側で検証を行う(図-4)
  3. 認証が通ったら、クライアント側にトークンを保存(図-5~6)

③パスワード取得失敗時など、再度アプリケーションユーザをマーベラスコネクトから取得する手順

④認証後

  • クライアントとサーバのデータのやり取り時にトークンを渡すようにする

    • 有効期限内は認証処理を省略可能
    • 期限切れなどで検証エラーになった際は再度「②ゲーム内ユーザの認証」を行う
  • トークンは端末ごとに異なる

    • 別端末でアクセスしていることなどが分かります

引き継ぎ機能

アプリケーションユーザとマーベラスコネクトに登録されたユーザを連携させ
アプリケーション側で引き継ぎ機能を実装することで実現できます。
下記二つの手順をご覧ください。

また、文中に出てくる**「Authorization Request」「Authorization Response」につきましては
後述の
「Authorization RequestとAuthorization Response」**をご覧ください。

アプリケーションユーザとマーベラスコネクトに登録されたユーザを連携させる手順

① ユーザとマーベラスコネクトの認証を行い、トークンを取得する

  1. クライアント側でnonceを生成してください
  2. ブラウザを呼び出してください
  3. ブラウザから Authorization Request をリクエストしてください
  4. Authorization Request にアクセストークン・IDトークンが **ない** 場合は初回ログイン画面が表示されます
    Authorization Request にアクセストークン・IDトークンが **ある** 場合は一覧画面が表示されます
  5. ブラウザに Authorization Response が返却されます
    • アクセストークン・IDトークンなど

② トークンを使用し、アプリケーションユーザとマーベラスコネクトユーザを連携させる

  1. クライアントから送られてきたアクセストークン・IDトークン・nonceを使用してIDトークンの検証を行う
  2. クライアントから送られてきた、アプリケーションユーザIDとアプリケーションユーザのパスワードが正しいことを確認してください

引き継ぎ機能を実装する手順

① ユーザーとマーベラスコネクトの認証を行い、トークンを取得する

手順は上記「アプリケーションユーザとマーベラスコネクトに登録されたユーザを連携させる手順」の
「アプリケーションユーザとマーベラスコネクトに登録されたユーザを連携させる手順 ①」 と同様。

② トークンを使用し、アプリケーションユーザを取得する

  1. クライアント側に、レスポンスから取得したアプリケーションユーザIDやパスワードを保存して 引き継いだ状態からゲームが始められるようにしてください

Authorization RequestとAuthorization Response

Authorization Request

アプリケーションとマーベラスコネクトのID連携を行う際、ブラウザを介して Authorization Request を行う必要があります。

リクエスト先

<Marvelous Connect Lite API のURL>/marvelous/authorization

パラメータ
パラメータ セットされる情報
response_type
レスポンス内容要求 “id_token%20token” 固定
これはアクセストークンとIDトークンの両方が
レスポンスのURLフラグメントとして返されることを要求する
scope 対象範囲 “openid” 固定
client_id アプリケーションID
state アプリケーション側で指定する値
redirect_uri Authorization Response(後述)が返ってくるURIを指定する
nonce
アプリケーション側でリクエストごとに指定する一意の値
(リプレイ攻撃防止用のランダムな文字列)
access_token アクセストークン(クライアントに保存されている場合のみ使用)
id_token IDトークン(クライアントに保存されている場合のみ使用)
max_age(任意)
トークンの有効期限を秒単位で指定
指定しない場合の有効期限は2時間(7200)になります
参考例
https://marvelous-connect.com/marvelous/authorization?
 response_type=id_token%20token
 &scope=openid
 &client_id=00000
 &state=af0ifjshoge
 &redirect_uri=http://maql-games.jp/test/index/callback
 &nonce=awawa2014happynewyear
 &max_age=7200

Authorization Response

レスポンス先

Authorization Request の redirect_uri パラメータ

パラメータ
パラメータ セットされる情報
access_token マーベラスコネクトユーザのアクセストークン文字列
token_type Access Token の種類 “bearer” 固定
id_token マーベラスコネクトユーザのIDトークン文字列
expires_in アクセストークンが失効するまでの時間(秒)
state Authorization Request で設定したstateパラメータ
platform_id 連携したプラットフォームID
参考例
<Authorization Requestのredirect_uriパラメータ>?
 access_token=SlAV32hkKG
 &token_type=bearer
 &id_token=eyJ0 ... ZXso
 &expires_in=3600
 &state=af0ifjsldkj
 &platform_id=00001

仮想通貨機能

使用するAPIメソッド概要

対象API HTTPメソッド 内容 備考
/app/payment GET 残高情報を取得する。存在する場合、決済処理中の情報も取得する このAPIはいつコールしても問題ない
/app/payment POST 決済処理の開始処理 同時に行える仮想通貨処理は一つだけ
/app/payment PUT 開始されている決済処理を実施する 前提として、POSTリクエストのあとに実施する
/app/payment DELETE 決済情報を削除する 通常は、決済処理が完了してから実施する。決済処理が完了していない場合でもその決済処理を削除することができる

実装手順

①共通処理

前提
  • 共通処理は、仮想通貨残高をクライアントで表示する前に行われることが期待される
    • 共通処理を行う前は、処理中の決済が中断されて残っている可能性があるため、 正しい残高を表示できない場合がある
  • 共通処理は、無償通貨獲得処理・消費処理の前に行われる
    • 共通処理を行う前に各処理を開始すると、基本的には前回の決済処理が残っているため 409エラーとなる
手順

②無償通貨獲得処理

前提
  • 無償通貨獲得処理の前に共通処理が行われていること
手順

③消費処理

前提
  • 消費処理の前に共通処理が行われていること
手順

運用マニュアル

リダイレクト先の追加

Authorization Request の結果を返却するURLを追加する場合、DBにリダイレクトURLを追加する必要があります。

追加は以下のように行う。

    • 新規アプリケーション(application_id=00000)に、リダイレクトURL「http://misp.jp/test/callback」を追加する場合

      • 対象DB:misp_lite

          INSERT INTO application_redirect_uri (application_id, redirect_uri, created_date, updated_date, deleted_date) VALUES ('00000', 'http://misp.jp/test/callback', now(), now(), null);
          

NGワードの追加

NGワードAPIを使用する場合、禁止としたい単語をDBに追加する必要があります。

追加は以下のように行う。

    • 「marvelous」という単語をNGワードにする場合(投入単語は全角大文字にする必要があります。例:「marvelous」→「MARVELOUS)

      • 対象DB:misp_lite

          INSERT INTO common_ng_word (`ng_word`, `created_date`, `updated_date`) values ( 'MARVELOUS', now(), now() );
          
    • 「marvelous」という単語を特定のアプリケーション(application_id=00000)でのみNGワードにする場合(投入単語は全角大文字にする必要があります。例:「marvelous」→「MARVELOUS)

      • 対象DB:misp_lite

          INSERT INTO common_ng_word (`application_id`, `ng_word`, `created_date`, `updated_date`) values ('00000', 'MARVELOUS', now(), now() );
          

Marvelous系OPの追加

Marvelous Connect Lite で使用するOpenIDプロバイダを追加する場合、以下の様な手順が必要となります。

    • MarvelousIDを追加する場合

      • レコード追加

        • 対象DB:misp_lite

            INSERT INTO platform (platform_id, platform_name, platform_domain, platform_type, sort_order, created_date, updated_date, deleted_date) VALUES ('MarvelousMembers', 'MarvelousID', 'marv-m.jp', '0', '10', now(), now(), null);
            
      • ソースファイル追加

        • application/misp/hybridauth/Hybrid/Providers/MarvelousMembers.php

            class Hybrid_Providers_MarvelousMembers extends Hybrid_Provider_Model_OpenID
            {
                /**
                 * adapter initializer 
                 */
                function initialize()
                {
                    parent::initialize();
                    $this->openidIdentifier = 'https://www.marv-m.jp/openid';
                }
            }
            
      • 設定追加

        • application/configs/hybridauth.yml

            providers:
                  MarvelousMembers:
                    enabled: TRUE
            
      • 画像リソースの追加

        • 画像リソースとはマーベラスコネクトのログイン画面に表示されるOPを示す画像です
        • 画像リソースの有無でOPの表示/非表示を制御しています
        • 画像リソースはレコード追加の際に platform_name カラムで使用した名称にしてください
          • 拡張子は取り除いておく必要があります
            例: MarvelousID.jpg →名前の変更→ MarvelousID
            * 以下のディレクトリに画像リソースを配置します * /public/marvelous_resource/img/login * ログイン画面に表示されるOPを示す画像 * /public/marvelous_resource/img/login/en * ログイン画面に表示されるOPを示す画像(/public/marvelous_resource/img/login のものと同一で構いません) * /public/marvelous_resource/img/index * ID連携後画面に表示されるOPを示す画像

ローカライズ対応

ローカライズは、デフォルトは「en」になっています。
別のローカライズに対応するには以下の様な手順が必要となります。

    • ja を追加する場合

      • /application/configs/application.ini に以下の設定を追加

          misp.supported.languages[] = "ja"
          
    • 画像リソースの追加

      • ディレクトリの追加

          /public/marvelous_resource/img/login/ja
          
      • 表示したいOPの画像を追加

        • /public/marvelous_resource/img/login/ja

          • ログイン画面に表示されるOPを示す画像
          • 必要であれば「/public/marvelous_resource/img/login」、「/public/marvelous_resource/img/index」にも画像を追加
    • 翻訳ファイルの追加

      • ディレクトリの追加

        language/ja
      • 既存の翻訳ファイルをもとに作成、追加

        • language/ja

          • poEditなどを使用して、「language/en」内の翻訳ファイルをもとに作成してください

            • lang_ja.mo
            • lang_ja.po
      • 新たに翻訳ファイルを作成する場合

        • 例:アプリケ-ション名の翻訳ファイルを作成する場合
          • /language/en
            • 新規でアプリケーション名の翻訳ファイルを作成
              • applicationname_lang_en.po
                • デフォルト設定のため、ソーステキストと翻訳の内容は同じとなる
              • applicationname_lang_en.mo
          • /language/jp
            • 新規でアプリケーション名の翻訳ファイルを作成
              • applicationname_lang_jp.po
                • ソーステキストは英語(applicationname_lang_en.poと同様)、翻訳の部分に日本語を記載
              • applicationname_lang_jp.mo

依存ライブラリ

Marvelous Connect Lite が依存している外部ライブラリについて記載します。

# ライブラリ名 ベンダー ライセンス Marvelous Connect Lite 内のソースパス 用途 リンク
1 MZCL Marvelous Inc. MIT application/common application/models ZF1 の拡張・共通機能ライブラリ -
2 HybridAuth Mohamed Mrassi MIT + GPLv3 application/misp/hybridauth ID連携ライブラリ https://hybridauth.github.io/hybridauth/
3 PHP Akita Ryo Ito MIT application/misp/Akita application/misp/OpenIDConnect OpenID Connect IDトークンの生成や検証など https://github.com/ritou/php-Akita_OpenIDConnect
4 OAuth.php 記載なし Apache License 2.0 application/misp/OAuth OAuthシグネチャ作成・検証など https://code.google.com/archive/p/oauth/source/default/source
5 Composer Nils Adermann Jordi Boggiano MIT vendor/autoload.php vendor/composer JSON Schema for PHP のautoload https://getcomposer.org/
6 JSON Schema for PHP Justin Rainbow MIT vendor/justinrainbow/json-schema JSONスキーマ検証 https://github.com/justinrainbow/json-schema
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.