ご利用ガイドAPIリファレンス更新内容Recipes

リソースアクセス用__オンライン接続条件②

② セゾンコネクト：リソースアクセス関連

1. プロトコル

HTTP1.1 over SSL/TLS (HTTPS)
パラメータの引き渡しは、POSTパラメータを用いる。
全てのリクエストでHTTPSを使用する。

2. メッセージ構造

  • HTTPプロトコルでは、HTTPメッセージはリクエストライン/ステータスライン、メッセージヘッダ、空行、メッセージボディの4つから構成される。
  • リクエストライン/ステータスライン、メッセージヘッダ、空行をヘッダ部とし、メッセージボディを業務APが設定/参照する本体（ボディ部）とする。
531

3. リクエストパラメータ

  • POSTパラメータ
    パラメータは以下の条件を満たす形式で設定する。
    • エンティティボディーがシングルパートであること。
    • エンティティボディーが[W3C.REC-html401-19991224(2)]で定義されるapplication/x-www-form-urlencodedを満たすこと。
      エンコードはUTF-8とする。
    • HTTPリクエストエンティティヘッダーがContent-Typeヘッダーフィールドを含み、その値がapplication/x-www-form-urlencodedであること。
例)
POST /resource/1 HTTP/1.1
Host: <セゾンコネクトホスト> 
Authorization: MAC id="h480djs93hd8",
                        ts="1336363200",
                        nonce="dj83hs9s",
                        mac="bhCQXTVyfj5cmA9uKkPFx1zeOXM="
Content-Type: application/x-www-form-urlencoded

param1=value
  • OAuth2.0 MAC Token Usage
    • アクセストークンが必要と記述されているAPIへのアクセスを行う場合、OAuth2.0 MAC Token Usageを用いる。
    • クライアントは、リソースへのアクセスを行うAPIにリクエストする際は、以下のように、必ずリクエスト中にAuthorizationヘッダを付与する。
      Authorizationヘッダには
    • メッセージ認証コード(MAC)の生成には[OAuth2.0 MAC Token Usage draft2(1)]で定義されている方法を用いる。(3. Making Requests)
    • MACアルゴリズムはHMAC(SHA-256)を用いる。
    • HMAC(SHA-256)で生成したバイトコードをBase64に変換したものをメッセージ認証コードとする。
    • MAC Keyにはクライアントシークレットを用いる。
    • MAC Key Identifier(Authorizationヘッダのid)はアクセストークンを設定する。
    • nonceはクライアント側がランダムに生成した値を設定する。値の生成には予想困難な乱数(暗号論的疑似乱数等)を使用することが望ましい。
    • タイムスタンプ(ts)はクライアント側の現在日時(1970年1月1日 00:00:00 GMTからの経過秒数)を用いる。
      タイムスタンプがセゾンコネクトが検証する際の日時から一定時間以上経過している場合は認証エラーとなるため、
      NTP等を用いて正確な現在日時を設定することが必要となる。
リクエスト形式)
 GET　/resource/1 HTTP/1.1
 Host: <セゾンコネクトホスト>
 Authorization: MAC id="<アクセストークン>",
                        ts="<タイムスタンプ>",
                        nonce="<MAC生成に使用するランダムな値>",
                        mac="<MAC>"

例)
 GET　/resource/1 HTTP/1.1
 Host: <セゾンコネクトホスト>
 Authorization: MAC id="h480djs93hd8",
                        ts="1336363200",
                        nonce="dj83hs9s",
                        mac="bhCQXTVyfj5cmA9uKkPFx1zeOXM="

4. レスポンス形式

  • 共通事項
    • HTTPステータスコードをHTTPヘッダに付加し、共にパラメータをHTTPレスポンスボディに付加する。
    • 重度のシステム障害や予期できない内部エラーが発生した場合、HTTPステータスコード500番台のレスポンスを返却する。
    • パラメータは[RFC4627(3)]で定義されているメディアタイプ application/json 形式で、HTTPレスポンスボディに含まれる。
    • JSONへのシリアライゼーションは、各パラメータをJSONオブジェクトの最上位要素とする形式で行う。
      パラメータ名と文字列値はJSON文字列、数値はJSON数値となる。
    • レスポンスのHTTPヘッダー「Cache-Control」は必ず「no-store」と設定される。
    • json返却時、返却値が無いフィールドは、フィールド自体が存在しないか、"フィールド名":null　と表記される。
  • 保護リソースへのリクエストが正常の場合
    • ステータスコード200(OK)と共にパラメータをHTTPレスポンスボディに付加する。
    • パラメータには、処理結果コードと各API固有のパラメータが含まれる。
    • 処理結果コードのコード値とその内容は「処理結果コード」を参照のこと。業務的なエラーの場合はこの処理結果コードで内容を記載する。
    • 各API固有のパラメータは、各APIのIF仕様書を参照のこと。
  • 保護リソースへのリクエストが不正または形式に問題がある場合
    • ステータスコード400系と共にパラメータ「error」をHTTPレスポンスボディに付加する。
    • パラメータ「error」の値によって、ステータスコードの値は異なる。
    • 認証情報を欠いている場合(指定のOAuthプロトコルパラメータが存在しない場合)、
      エラーコードおよびその他エラー情報を含まないレスポンスをHTTPステータスコード401で返却する。
    • アクセストークンのチェックについては、下記「アクセストークンの認証について」も合わせて参照のこと。
    • パラメータ「error」の値はOAuthエラーコードシートを参照のこと。

5. 参考

(1) http://tools.ietf.org/html/draft-ietf-oauth-v2-http-mac-02#section-3