Server-Side 実装について

• Access Token と Refresh Token の管理
• RESTful API の利用

Access Token と Refresh Token の管理

Access Token / Refresh Token とは

Access Token 及び Refresh Token の定義を以下にまとめます。

Game Server は通常、Authorization Code Grantフローや Hybrid フローで得た code 値を得た上で、 Token Endpoint に渡す事によって Access Token 及び Refresh Token を得ます。
Access Token が失効した場合は、 Refresh Token を利用して Token Request を行うことで、 新たに Access Token を発行します。
 

Access Token / Refresh Token は、必ず UserAgent 毎に管理してください。 UserId ごとに管理した場合は、SPWeb の処理が Shell App SDK API として動作するなどの問題が発生する可能性がございます。

Access Token / Refresh Token の文字列長について

Access Token 及び Refresh Token の文字列長は既存の物に対してかなり長い為、例えば MySQL であれば text 型等のデータ型を採用した上で保存して下さい。
 

Token Endpoint と Client 認証

各環境における Token Endpoint の URI は以下に示した通りです。

また利用可能な Client 認証は以下に示した通りです。

Refresh Token の利用

Access Token が失効した場合に、 Refresh Token を利用して Access Token を再発行します。
 

Access Token が失効しているか確認する

Access Token が失効しているかどうかは、下記の手順で確認します。
Access Token が失効していた場合は、Refresh Token を利用して Access Token を再発行します。
 

expires_in で Token の有効期限が切れているか確認

Access Token の有効期限は、Access Token と共に発行される expires_in 値を利用して確認します。

有効期限 = Game Server で Access Token を受け取った時刻 ＋ expires_in 値

この有効期限を過ぎている場合は、 Access Token が失効していると判断できます。
 

実際に利用して失効しているか確認

有効期限内だが失効している Access Token を実際に利用した場合、 RESTful API からは以下のレスポンスが返って来ます。

• HTTP status code : 401 Unauthorized
• error_description : "The access token expired"
  これらのレスポンスが返って来た場合は、 Access Token が失効していると判断できます。
   

  Refresh Token を利用して Access Token を再発行する

  Refresh Token を利用する際には Token Endpoint に対して Token Request を送る必要があります。
  この際の Token Request で指定する application/x-www-form-urlencoded 形式の key, value を以下に示します。

  key	value
  grant_type	refresh_token を指定します
  refresh_token	Refresh Token 値

  例として Client 認証に client_secret_post を利用した例を以下に示します。
  この際、 Access Token だけでなく Refresh Token も新しい値が返って来る場合があります。その場合は古い RefreshToken は利用出来なくなりますのでご注意下さい。
   
  なお、 Token Response の例を以下に示します。

  key	value
  access_token	Game Server から API を実行するための access_token が返されます。
  token_type	Bearer
  expires_in	900
  refresh_token	grant_type=refresh_token による Token Request で改めて access token を得る為に必要なトークンです。発行時から90日間有効です。
  scope	現在、クライアント向けに認可されているユーザーに関する権限を全て示すスペース区切りの文字列です。

Client Credentials Grant 

Client Credentials Grant とは

Client Credentials Grant とは、Client 認証のみで Client 向けの API 実行権限である Access Token を得る為のフローで、 OAuth 2.0 で規定されています。
旧来の Proxy Server モデルでは Trusted モデルと呼ばれていた Using OAuth for Consumer Request に対応する概念です。
Client Credentials Grant では特にユーザーに紐づく権限を得る訳ではないので、Client 向けの secret があれば Token Endpoint にアクセスするだけで Access Token を得る事が出来ます。
サポートしている Client 認証手段に関しては以下表を参照して下さい。
 

key	value
grant_type	client_credentialsを指定します

 
Client 認証で client_secret_post を用いる場合は以下のようなリクエストになります。

 
Token Request が成功の場合は Token Response として以下のフィールドがJSONとして返って来ます。
 

key	value
access_token	Game Server から API を実行する為の access token が返されます。
token_type	Bearer
expires_in	900

Client Credentials Grant では、refresh_token は発行されません。

 
得られた Access Token は Authorization Code Grant で得られた物と違って、特定のユーザーに紐づく物ではなく Client のみに紐づく権限なので、一緒に管理はしないようにして下さい。
Token Request が失敗した場合は Token Error Response として、以下に示すパラメータが JSON として返って来ます。

key	value
error	OAuth 2.0/OpenID Connect 1.0 で定義されるエラーコードが指定されます。
error_description	error 内容を説明する文章が指定されます。

 

RESTful API の利用

ここでは JavaScript SDK または Mobage Connect を利用した場合の RESTful API について説明します。
 

利用可能な RESTful API とエンドポイント

各環境の RESTful API のベースエンドポイントを以下に示します。

また利用可能な Authorization Code Grant で得た Access Token と、Client Credentials Grant で得た Access Token とで異なります。詳細は以下を参照して下さい。
各 API のインターフェースについてはそれぞれのドキュメントを参照して下さい。

Client Credentials Grant を使用すれば、Mobage 非会員の状態でもテキストデータの作成・更新・削除が行えますが、Mobage 非会員の状態ではテキストデータの取得以外は行わないでください。

Authorization

RESTful APIに対しては現状以下のAuthorizationが許可されています。

• Authorization Code Grant または Hybrid によって得られた code を用いて得られた Access Token
  Refresh Token を利用して得られた Access Token
• ゲームサーバーから API  サーバーへのリクエスト - Mobage Developers の Trusted モデル

Access Token は既存のモデルの Proxy モデルの代わりに利用する事が出来ます。

取得した Access Token は以下のように Authorization ヘッダ中に Auth Schema を Bearer とした上で指定して下さい