Binding
Concrete Specification
Prerequisites（前提条件）
本プロトコルは HTTPS（TLS 1.2以上） を使用し、 REST形式のHTTPリクエスト/レスポンス により通信を行う。
エンドポイント：指定されたURIに対してHTTPメソッド（GET, POST, PUT, DELETE）を使用
データ形式：リクエストおよびレスポンスの本文はJSON形式
認証・認可：認証・認可方式には OAuth 2.0 および OpenID Connect を使用する。
自然人主体の認証には OpenID Connect（Authorization Code Flow）を、 システム主体のアクセス制御には OAuth 2.0（Client Credentials Flow）を用いる。
また、ポリシーベースでの認可制御を提供する。
セキュリティ要件：TLS 1.2以上必須、暗号化通信を保証
Field Definitions（フィールド定義）
本プロトコルで使用される各フィールドの定義を記す。 なお、各APIの詳細な項目定義は別途公開している「API仕様書」を参照すること。
各フィールドについて、以下の情報を記す。
フィールド名：プロトコル内で使用される名称
型：データ型（例：整数、文字列）
必須性：フィールドの利用条件
R = Required（必須）
C = Conditional（条件付き必須）
O = Optional（任意）
Request：リクエストにおいて使用される
Response：レスポンスにおいて使用される
説明：フィールドの意味や利用方法
Headerフィールド定義
API-Key
String
R
✔
クライアントアプリごとに払い出されたAPIKeyを指定する。ODS独自項目
Authorization
String
C
✔
アクセストークンを指定する。例：Bearer < token > 認証フロー関連のAPI（パスワード変更を除く）では不要。
Content-Type
String
R
✔
✔
リクエスト形式を指定する。
User-Agent
String
O
✔
クライアントのユーザーエージェントを指定する。
Accept-Language
String
O
✔
クライアントの受け入れる希望言語を指定する。
X-TrackingID
String
O
✔
✔
リクエストのトレーシングを行う一意なIDを指定する。ODS独自項目
Content-Security-Policy
String
O
✔
コンテンツの読み込み・実行ポリシーを指定し、スクリプトやリソースの許可元を制御する。
X-Content-Type-Options
String
O
✔
ブラウザのMIMEタイプ推測を禁止し、指定されたContent-Typeを強制する。
Strict-Transport-Security
String
O
✔
指定期間、HTTPS接続を強制し、HTTPへのダウングレードを防止する。
Access-Control-Allow-Origin
String
O
✔
CORSに関する項目。 レスポンスを許可するオリジンを指定し、クロスオリジンアクセスを制御する。
Access-Control-Allow-Methods
String
O
✔
CORSに関する項目。 クロスオリジンリクエストで許可するHTTPメソッドを指定する。
Access-Control-Allow-Headers
String
O
✔
CORSに関する項目。 クロスオリジンリクエストで許可するリクエストヘッダーを指定する。
Access-Control-Allow-Credentials
String
O
✔
CORSに関する項目。 クロスオリジンリクエストで認証情報の送信を許可するかを指定する。
Payloadフィールド定義
type
String
R
✔
実行結果の種類を識別するURIを設定する。
title
String
R
✔
実行結果を説明する内容を設定する。
status
Integer
R
✔
HTTPステータスコードを設定する。
detail
String
R
✔
ODS運営事業者が調査を行うのにあたり必要な情報（例：エラー発生時の発生日時）を設定する。
data
String
C
✔
正常時の実行結果に対する業務データオブジェクト。 異常時では不要。
Functional Description（機能詳細）
Request・Response・Example・Error一覧・API固有のフィールド定義などの具体実装はAPI仕様書の記載を参照すること。
認証
ユーザ当人認証
OIDCの認可フローに基づきユーザの認証を行う。
認証
クライアントシステム認証
クライアントIDとクライアントシークレットを使用して、クライアントクレデンシャルフローにてクライアントの認証を行う。
トークン検証・更新
トークンイントロスペクション
アクセストークンを検証し、トークンの有効性や関連情報を取得する。
トークン検証・更新
アクセストークン更新
リフレッシュトークンを使用してアクセストークンを再取得する。
パスワード変更
パスワード変更
リクエストに含まれるIDに対応するユーザのパスワードを変更する。
APIKey検証
APIKey検証
リクエストボディに含めたAPIKeyの有効性を検証する。
認可
認可モデル登録・取得
認可に利用するモデルの登録・取得を行う。登録についてはアクセス制限を設け、許可したユーザのみ登録可能となるようにする。
認可
認可タプル登録・取得
認可に利用するタプルの登録・取得を行う。登録についてはアクセス制限を設け、許可したユーザのみ登録可能となるようにする。
認可
認可判定
認可の判定を行う。API定義についてはAuthZENのevaluationエンドポイントの仕様に準拠する。
ユーザ・クライアント登録
ユーザ登録
ユーザの新規作成を行う。
ユーザ・クライアント登録
クライアント登録
クライアントの登録およびクライアントシークレットの発行を行う。
事業者情報管理
事業者情報登録・取得・更新
事業者情報に関する操作を行う。
事業所情報管理
事業所情報登録・取得・更新
事業者に紐づく付帯情報である事業所情報に関する操作を行う。
認証
本プロトコルの認証機能では以下の 2 種類の認証フローを提供する。
Authorization Code Flow（認可コードフロー）
ユーザを伴う認証シナリオで使用する。クライアントはユーザを介してIdentity & Trust（L3）の認証画面へリダイレクトし、認証後に発行される認可コードを用いてアクセストークンを取得する。
Client Credentials Flow（クライアントクレデンシャルフロー）
ユーザを伴わない非対話認証シナリオに使用する。クライアントはclient_idおよびclient_secretを用いてIdentity & Trust（L3）のクライアントシステム認証エンドポイントへアクセスし、アクセストークンを取得する。
認証情報・識別子
認証情報
本機能で用いる主な認証情報を以下に示す。
login_user_id
認可コードフロー
ユーザ認証を伴う認可コードフローにおいて、ユーザがログイン画面で入力する識別子。
password
認可コードフロー
ログインユーザ ID に対応する秘密情報。
client_id
認可コードフロー/クライアントクレデンシャルフロー
本プロトコル上のクライアント（アプリケーション）を識別する ID。
client_secret
認可コードフロー/クライアントクレデンシャルフロー
クライアントが Identity & Trust（L3）に対し自身を認証するために使用する秘密情報。
識別子
本プロトコルでは発行するアクセストークンに対し、業務上の識別に必要な以下2種類のカスタムクレームを付与する。
operator_id（事業者識別子）
ユーザまたはクライアントが所属する 事業者（operator） を識別するための情報である。 本クレームは以下のフローにおいてアクセストークンへ付与される。
- Authorization Code Flow（認可コードフロー） → ユーザ払い出し時に指定された事業者を付与。
- Client Credentials Flow（クライアントクレデンシャルフロー） → クライアント（client_id）払い出し時に指定された事業者を付与。
open_system_id（システム識別子）
クライアントが属するシステムを識別するための情報である。 本クレームは以下のフローにおいてのみアクセストークンへ付与される。
- Client Credentials Flow（クライアントクレデンシャルフロー）
Authorization Code Flow（ユーザを伴うフロー）では付与されない。
Sequence Diagram（シーケンス図）
認可コードフロー
プロトコルフローを参照すること
クライアントクレデンシャルフロー
トークン検証
トークン更新
パスワード変更
APIKey検証
モデル登録
タプル登録
認可判断
ユーザ・クライアント登録
事業者情報管理
事業所情報管理
最終更新