ゲームサーバーから API サーバーへのリクエスト
リクエスト形式
API へのリクエストの仕方には Proxy モデルと Trusted モデルの二つがあります。
Proxy モデル
Gadgets Server により発行された opensocial_viewer_id に対応する access token を必要としたリクエスト
Trusted モデル
各アプリケーションごとにアクセス可能なリクエスト
これらのアクセス手段のサポート状況は各 API によって異なります。詳しくは API 各々のリファレンスをご参照下さい。
いずれのアクセス手段でも、API の Authorization には OAuth を用います。OAuth のリクエスト時に含める xoauth_requestor_id の値ですがモデル別に異なります。
| モデル | xoauth_requestor_id |
|---|---|
| Proxy | Gadgets Server から渡された opensocial_viewer_id の値 |
| Trusted | アプリケーションID |
OAuth の署名生成については次のトピック「OAuth Signature の生成」をご参照下さい。
OAuth Signature の生成
ゲームサーバーから API サーバのリクエストでは、Authorization ヘッダにゲームサーバーが生成した OAuth Signature を含めます。この値をAPI サーバが検証する事で改ざん等の悪意あるリクエストを防ぎ、ゲームサーバーからの正当なリクエストである事を確認します。
Base String の生成
生成は以下の手順で行います。
1.Base String 生成に必要な値を準備します。
| 項目 | 説明 |
|---|---|
| リクエストメソッド | API サーバーに対してリクエストするHTTPメソッド |
| API URL | API サーバーへのリクエストURL(クエリパラメータは含まない) |
| クエリパラメータ | API サーバーへのリクエストクエリパラメータ |
| パラメータ | 下記のパラメータを参照 |
| パラメータ | 説明 | 参照元 |
|---|---|---|
| oauth_consumer_key | アプリケーション毎のキー | アプリケーション登録時に発行 |
| oauth_nonce | リクエスト毎にユニークな値 | ゲームサーバーで生成 |
| oauth_timestamp | UNIXタイムスタンプ | ゲームサーバーで生成 |
| oauth_token | アクセストークン | Gadget サーバーからの Authorization リクエストヘッダの oauth_token の値 |
| oauth_signature_method | 署名方式 | HMAC-SHA1固定 |
| oauth_version | OAuthのバージョン | 1.0固定 |
| xoauth_requestor_id | アプリケーションを実行しているユーザID | Gadget サーバーからのクエリパラメータ opensocial_viewer_id の値 |
- Trusted モデル (OAuth Consumer Request) の場合は oauth_token をパラメータに含めません。
- oauth_token が無い場合、OAuth Service Provider はそのリクエストを Consumer Request として解釈します
- OAuth Consumer Request に関しての詳細な仕様は、OAuth Consumer Request 1.0 Draft 1 を参照して下さい。
- Trusted モデルの際の xoauth_requestor_id はアプリケーション ID を指定します
2.クエリパラメータとパラメータはキーと値を "=" で連結した上で、キーでアルファベット昇順でソートしたものを "&" で連結します。
3.これらを URI エスケープして "&" で連結します。
Base String の生成例
| パラメータ | 値 |
|---|---|
| リクエストメソッド | GET |
| API URL | http://app.example.com?foo=bar |
| oauth_consumer_key | abcdefghij1234567890 |
| oauth_nonce | abcdefghij1234567890 |
| oauth_timestamp | 1234567890 |
| oauth_token | abcdefghij1234567890 |
| oauth_signature_method | HMAC-SHA1 |
| oauth_version | 1.0 |
| xoauth_requestor_id | 12345 |
GET&http%3A%2F%2Fapi.example.com&
foo%3Dbar%26
oauth_consumer_key%3Dabcdefghij1234567890%26
oauth_nonce%3Dabcdefghij1234567890%26
oauth_signature_method%3DHMAC-SHA1%26
oauth_timestamp%3D1234567890%26
oauth_token%3Dabcdefghij1234567890%26
oauth_version%3D1.0%26
xoauth_requestor_id%3D12345
Signature の生成
ベース文字列をアプリケーション時に発行された Consumer Secret と Authorization ヘッダの oauth_token_secret を "&" で連結した値をキーとして Authorization ヘッダの oauth_signature_method のアルゴリズム (現在はHMAC-SHA1固定です) でダイジェスト値を生成します。この値をさらに BASE64 エンコードすることによって Signature を生成することができます。
Authorization ヘッダの生成
Authorizationヘッダに必要なパラメータは以下の通りです。
| パラメータ |
|---|
| oauth_consumer_key |
| oauth_nonce |
| oauth_signature |
| oauth_signature_method |
| oauth_timestamp |
| oauth_token |
| oauth_version |
| xoauth_requestor_id |
1. パラメータのキーと値をURIエンコーディング。
2. パラメータの値をダブルクォーテーション (") でくくる。
3. パラメータのキーと値を "=" で連結。
4. パラメータそれぞれをカンマ (,) で連結。
5. オプションの realm パラメータを付加。
Authorization ヘッダの生成例
OAuth realm="",
oauth_consumer_key="abcdefghij1234567890",
oauth_nonce="abcdefghij1234567890",
oauth_signature="X9KBpVUD0W17gNznsd568M9QPUI%3D",
oauth_signature_method="HMAC-SHA1",
oauth_timestamp="1234567890",
oauth_token="abcdefghij1234567890",
oauth_version="1.0",
xoauth_requestor_id="12345"
OAuth Request Body Hash (Optional)
API サーバーへ POST/PUT リクエストを行う場合、Request Body に対して hash 値を計算し、その値を OAuth の署名計算に必要なキーとして加える事が出来ます。詳細な仕様に関しては OAuth Request Body Hash 1.0 Draft 4 を参照して下さい。
Request Body を検証に含める場合、Request Body 値の HASH 値を OAuth Signature の生成時と同じアルゴリズムで求め、その値をさらに base64 エンコードした値を oauth_body_hash パラメータに含めます。
参考資料
The OAuth Core 1.0 Protocol draft-hammer-oauth-10
OAuth Core 1.0 Revision A
OAuth Request Body Hash 1.0 Draft 4
OAuth Consumer Request 1.0 Draft 1
RESTful Protocol Specification v0.9
更新履歴
- 2013/03/15
- ドキュメント移行