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

アクセス認可用_オンライン接続条件①

① セゾンコネクト：OAuth認可関連

1. プロトコル

HTTP1.1 over SSL/TLS (HTTPS)
パラメータの引き渡しは、「オンラインIF一覧」に記述のメソッドを用いる。
全てのリクエストでHTTPSを使用する。

2. メッセージ構造

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

3. OAuth

3.1 バージョン

  • OAuthのバージョンはOAuth 2.0 (RFC 6749) を用いる。
  • OAuthプロトコルフローは Authorization Codeを用いる。

3.2 パラメータ

  • GETパラメータ
    指定のパラメータを[W3C.REC-html401-19991224(2)]で定義された application/x-www-form-urlencoded フォーマットで追加して、リクエストURIを構築する。
  • POSTパラメータ
    パラメータは以下の条件を満たす形式で設定する。
    • エンティティボディーがシングルパートであること。
    • エンティティボディーが[W3C.REC-html401-19991224(2)]で定義されるapplication/x-www-form-urlencodedを満たすこと。
      エンコードはUTF-8とする。
    • HTTPリクエストエンティティヘッダーがContent-Typeヘッダーフィールドを含み、その値がapplication/x-www-form-urlencodedであること。
    • OAuth以外のリクエスト固有のパラメータが含まれる場合、OAuthプロトコルパラメータはリクエスト固有パラメータの後ろに付与され、適切に & で分割されること。
例)
POST /na/token HTTP/1.1
Host: <セゾンコネクトホスト>
Content-Type: application/x-www-form-urlencoded

param1=valu%2Fe1&valu_flg=1

3.3 レスポンス

  • 共通事項
    • 重度のシステム障害や予期できない内部エラーが発生した場合、HTTPステータスコード500番台のレスポンスを返却する。
    • json返却時、返却値が無いフィールドは、フィールド自体が存在しないか、"フィールド名":null　と表記される。
  • 認可コードレスポンス
    • 指定のリダイレクトURIのクエリ部に、[W3C.REC-html401-19991224(2)]で定義されるapplication/x-www-form-urlencodedフォーマットでパラメータを付加する。
    • リクエスト時にパラメータstateを含んでいた場合、クライアントから受け取った値をそのまま付加する。
例)
HTTP/1.1 302 Found
Location: https://client.example.com/cb?code=absdFXBe890F&state=sample_state
  • 認可コードエラーレスポンス
    • 指定のリダイレクトURIのクエリ部に、[W3C.REC-html401-19991224(2)]で定義されるapplication/x-www-form-urlencodedフォーマットでパラメータを付加する。
    • パラメータ「error」をレスポンスボディに付加する。パラメータ「error」の詳細は各シートを参照のこと。
    • リクエスト時にパラメータstateを含んでいた場合、クライアントから受け取った値をそのまま付加する。
例)
HTTP/1.1 302 Found
Location: https://client.example.com/cb?error=access_denied&state=sample_state
  • アクセストークン取得 正常レスポンス
    • HTTPステータスコード200(OK)をHTTPヘッダに付加し、共にパラメータをHTTPレスポンスボディに付加する。
    • パラメータは[RFC4627(3)]で定義されているメディアタイプ application/json 形式で、HTTPレスポンスボディに含まれる。
    • JSONへのシリアライゼーションは、各パラメータをJSONオブジェクトの最上位要素とする形式で行う。
      パラメータ名と文字列値はJSON文字列、数値はJSON数値となる。
    • レスポンスのHTTPヘッダー「Cache-Control」は必ず「no-store」と設定される。
    • レスポンスのHTTPヘッダー「Pragma」は必ず「no-cache」と設定される。
例)
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
     {
       "access_token":"2YotnFZFEjr1zCsicMWpAA",
       "token_type":"example",
       "expires_in":3600,
       "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
       "example_parameter":"example_value"
     }
  • アクセストークン取得 エラーレスポンス
    • HTTPステータスコード400(Bad Request)をHTTPヘッダに付加し、共にパラメータをHTTPレスポンスボディに付加する。
    • パラメータ「error」をレスポンスボディに付加する。パラメータ「error」の詳細はシートTEA004を参照のこと。
    • パラメータは[RFC4627(3)]で定義されているメディアタイプ application/json 形式で、HTTPレスポンスボディに含まれる。
    • JSONへのシリアライゼーションは、各パラメータをJSONオブジェクトの最上位要素とする形式で行う。
      パラメータ名と文字列値はJSON文字列、数値はJSON数値となる。
    • レスポンスのHTTPヘッダー「Cache-Control」は必ず「no-store」と設定される。
    • レスポンスのHTTPヘッダー「Pragma」は必ず「no-cache」と設定される。
例)
HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store

{
    "error":"invalid_request"
}

3.4 トークン有効期限

  • 各種トークンの有効期限はデフォルトでは下記のように定義されており、クライアントごとに個別設定を可能とする。
    「ユーザに対するTokenを保持管理する／しない」クライアントによってデフォルトの有効期限は異なる。
トークン有効期限備考
認可コード60秒※TEA002応答後、TEA004を受け付ける間のタイムアウト値
※デフォルト値60秒となります。SE作業により、変更することが可能です。
アクセストークン※セゾンコネクトクライアント管理システムより、変更することが可能です。
リフレッシュトークン※セゾンコネクトクライアント管理システムより、変更することが可能です。

3.5 クライアント情報

  • 当システムにおいて、下記のクライアント情報をあらかじめ認可サーバに登録しておく必要がある。諸情報を事前に決定し、クレディセゾン側運用にて登録を行う。
登録情報名文字種別桁数/値範囲詳細
クライアント名称全角/半角英数字-クライアントの名称。
クライアント略称半角英数記2文字クライアントの略称。
リダイレクトURI半角英数記128文字認可コード発行/認可要求エラー時にエンドユーザをリダイレクトさせるURI。

4. その他

その他詳細なOAuth仕様については[The OAuth 2.0 Authorization Framework(1)]を参照のこと。
画面遷移を伴うものについては、ブラウザがその応答を受け取り、処理すること。

5. 参考

(1) http://tools.ietf.org/html/rfc6749
(2) http://www.w3.org/TR/1999/REC-html401-19991224/
(3) http://tools.ietf.org/html/rfc4634