メインコンテンツまでスキップ
API docs by Redocly

認証・認可画面用API (1.0.0)

Download OpenAPI specification:Download

認証画面・認可画面からの処理を行うためのAPI群。

認証インタラクションAPI

このAPIを使用することで、以下の認証インタラクションを実行できます：

  • パスワード認証
  • SMS認証（チャレンジ・認証）
  • メール認証（チャレンジ・認証）
  • FIDO-UAF認証（チャレンジ・認証・登録・登録解除）
  • WebAuthn認証（チャレンジ・認証・登録・登録解除）
  • 初期ユーザー登録
  • 認証キャンセル
  • 認証デバイス通知

認可画面データAPI

認可画面で表示するためのクライアント情報、スコープ情報などを取得できます。

各インタラクションタイプに応じたリクエストボディとレスポンス形式を提供します。

認証インタラクション

認証画面からの各種認証処理。

認証フローは以下の通りです：

  1. 認可エンドポイントから認証トランザクションIDを取得
  2. 認証インタラクションAPIで認証処理を実行
  3. 認証完了後、認可コードまたはエラーレスポンスを受信

認証インタラクション実行

指定された認可リクエストIDと認証インタラクションタイプに基づいて認証処理を実行します。

サポートされている認証インタラクションタイプ

パスワード認証

  • password-authentication - パスワードによる認証

SMS認証

  • sms-authentication-challenge - SMS認証チャレンジ（認証コード送信）
  • sms-authentication - SMS認証（認証コード検証）

メール認証

  • email-authentication-challenge - メール認証チャレンジ（認証コード送信）
  • email-authentication - メール認証（認証コード検証）

FIDO-UAF認証

  • fido-uaf-registration-challenge - FIDO-UAF登録チャレンジ
  • fido-uaf-registration - FIDO-UAF登録
  • fido-uaf-authentication-challenge - FIDO-UAF認証チャレンジ
  • fido-uaf-authentication - FIDO-UAF認証
  • fido-uaf-deregistration - FIDO-UAF登録解除
  • fido-uaf-cancel - FIDO-UAF処理キャンセル

WebAuthn認証

  • webauthn-registration-challenge - WebAuthn登録チャレンジ
  • webauthn-registration - WebAuthn登録
  • webauthn-authentication-challenge - WebAuthn認証チャレンジ
  • webauthn-authentication - WebAuthn認証
  • webauthn-deregistration - WebAuthn登録解除

その他

  • initial-registration - 初期ユーザー登録
  • authentication-cancel - 認証キャンセル
  • authentication-device-notification - 認証デバイス通知
  • authentication-device-deny - 認証デバイス拒否
  • authentication-device-binding-message - 認証デバイスバインディングメッセージ検証

ナンバーマッチング（認可コードフロー + デバイス認証）

  • authentication-device-number-matching-challenge - ナンバーマッチングコード発行
  • authentication-device-number-matching - ナンバーマッチングコード検証

属性照合

  • attribute-verification - 確定した利用者の確認（アカウントの状態の条件、入力値と登録済みの属性の照合）

バインディングメッセージ検証について

authentication-device-binding-messageは、CIBAフローにおいて消費デバイスと認証デバイス間の トランザクション一致を確認するための検証インタラクションです。

用途:

  • フィッシング対策: ユーザーが正しいトランザクションを承認しているか確認
  • トランザクション確認: 金融取引等での取引内容確認
  • セッション連動: 複数デバイス間でのセッション一致確認

OIDC CIBA仕様: Section 7.1

ナンバーマッチングについて

認可コードフローで認証デバイス（FIDO-UAF等）へステップアップする際の、プッシュ疲労（push fatigue）対策です。

コードは認証デバイスに送信されません。 サインイン画面に表示されたコードを、ユーザーが認証デバイスへ転記します。 承認者が元の画面を見ないと承認できないため、届いた通知を反射的に承認する攻撃が成立しなくなります。

インタラクション 呼び出し元 動作
authentication-device-number-matching-challenge サインイン画面 コードを生成してサーバー側に保存し、レスポンス number_matching_code で画面に返す
authentication-device-number-matching 認証デバイス 転記されたコードをリクエストボディ number_matching_code で、自身の識別子を device_id で送る。コードは保存値と、device_id は認証トランザクションに紐づく認証デバイスと照合される

コードは数字のみで、桁数は認証設定 authentication-device-number-matching の execution.details.length で指定します（既定 4 桁）。

コード発行はプッシュ配信とは分離されています。プッシュ（FCM）は CIBA と共通の authentication-device-notification 側にあり、ナンバーマッチングの利用にプッシュは必須ではありません。

検証エラーは以下のとおりです。

状況 error error_description
認証デバイス未紐付け invalid_request authentication device is not bound to this transaction
device_id 不一致 invalid_request device_id does not match the authentication device
チャレンジ未実行 invalid_request number_matching_code has not been issued
コード不一致 invalid_request number_matching_code does not match

device_id は必須です。認証トランザクションに認証デバイスが紐づいていない場合、 このインタラクションは成立しません（Issue #1869）。

認証デバイス側が番号入力画面の要否を判定するためのフラグは、認証トランザクション取得API （GET /{tenant-id}/v1/authentication-devices/{device-id}/authentications）の number_matching_required です。

属性照合について

前の段で利用者が確定したあとに行う追加の確認です（Issue #1907）。 認証要素には数えず（amr に入らない）、単独では認証を完了させません。

認証設定 attribute-verification に名前付きのインタラクションを並べ、リクエストボディの interaction で どれを実行するかを指定します。1 つのインタラクションは次のどちらか一方です。

  • アカウントの状態の条件（execution.details.conditions）：身元確認済みかなどを、認証ポリシーと同じ条件式で その場で確認します。入力は不要です。満たさないときは、設定の error（例：identity_verification_required）を返します
  • 入力の照合（execution.details.fields）：リクエストボディの値を登録済みの属性と照合します。 応答は一致・不一致だけで、どの項目が違ったかは返しません

結果はインタラクションの名前ごとに $.attribute-verification.interactions.<名前>.* として記録されます。

状況 HTTP error
成功 200 -
前の段で利用者が確定していない 400 invalid_request
interaction が無い、または設定に無い名前 400 invalid_request
入力が文字列でない 400 invalid_request（試行回数に数えない）
条件を満たさない 400 設定の error（既定 attribute_condition_not_satisfied）
一致しない（属性が未登録の場合を含む） 400 attribute_mismatch
試行回数の上限に達した 400 too_many_attempts
設定が無い・読めない 500 server_error
path Parameters
tenant-id
required
string <uuid>
Example: 67e7eae6-62b0-4500-9eff-87459f63fc66

テナントID

id
required
string
Example: authz_req_67890

認可リクエストID

interaction-type
required
string
Enum: "password-authentication" "sms-authentication-challenge" "sms-authentication" "email-authentication-challenge" "email-authentication" "fido-uaf-registration-challenge" "fido-uaf-registration" "fido-uaf-authentication-challenge" "fido-uaf-authentication" "fido-uaf-deregistration" "fido-uaf-cancel" "webauthn-registration-challenge" "webauthn-registration" "webauthn-authentication-challenge" "webauthn-authentication" "webauthn-deregistration" "initial-registration" "authentication-cancel" "authentication-device-notification" "authentication-device-deny" "authentication-device-binding-message" "authentication-device-number-matching-challenge" "authentication-device-number-matching" "attribute-verification"
Example: password-authentication

認証インタラクションタイプ

header Parameters
x-view-binding
string

別サイト認可画面モード（ui_config.cross_site / クライアントの cross_site_authorization_view）でのみ必須。 認可リクエストの応答で、認可画面の URL の fragment（#view_binding=<値>）に渡された値。 認可画面からの呼び出しが、認可リクエストを始めたブラウザからのものかを確かめるために使う （同一サイト構成で IDP_AUTH_SESSION Cookie が担う照合の代わり）。 値が無い・違う場合は 401。認可リクエストを訪れるたびに作り直され、最後のものだけが有効。

Request Body schema: application/json

認証インタラクションタイプに応じたリクエストボディ。 各インタラクションタイプで必要なパラメータが異なります。

One of
username
required
string

ユーザー名またはメールアドレス

password
required
string <password>

パスワード

Responses

Request samples

Content type
application/json
Example
{
  • "username": "user@example.com",
  • "password": "securePassword123"
}

Response samples

Content type
application/json
{
  • "user": {
    }
}

認証状態確認

指定された認可リクエストIDに紐づく認証トランザクションの全体状態を取得します。

SPAが「認証フローのどの段階にいるか」（進行中 / 成功 / 失敗 / ロック）を知るための 読み取り専用エンドポイントです。認証インタラクションAPI（/password 等）は ハンドラ固有のレスポンスしか返さないため、フロー全体の状態確認にはこのAPIを使用します。

  • 認証不要: view-data APIと同様、認可リクエストIDが推測困難なトークンとして機能し、 加えて AUTH_SESSION cookie を検証します。
  • 副作用なし: 読み取り専用でDBは更新しません。

ステータス値

status 意味
in_progress 認証フロー進行中（未完了）
success 認証成功（認証ポリシーの success_conditions 充足）
failure 認証失敗（failure_conditions 充足）
locked ロック状態（lock_conditions 充足）
path Parameters
tenant-id
required
string <uuid>
Example: 67e7eae6-62b0-4500-9eff-87459f63fc66

テナントID

id
required
string
Example: authz_req_67890

認可リクエストID

header Parameters
x-view-binding
string

別サイト認可画面モード（ui_config.cross_site / クライアントの cross_site_authorization_view）でのみ必須。 認可リクエストの応答で、認可画面の URL の fragment（#view_binding=<値>）に渡された値。 認可画面からの呼び出しが、認可リクエストを始めたブラウザからのものかを確かめるために使う （同一サイト構成で IDP_AUTH_SESSION Cookie が担う照合の代わり）。 値が無い・違う場合は 401。認可リクエストを訪れるたびに作り直され、最後のものだけが有効。

Responses

Response samples

Content type
application/json
Example
{
  • "status": "in_progress",
  • "interaction_results": { },
  • "authentication_methods": [ ]
}

認可画面データ

認可画面で表示するためのデータ取得API。

認可画面データ取得フローは以下の通りです：

  1. 認可リクエストから認可リクエストIDを取得
  2. View Data APIでクライアント情報、スコープ情報を取得
  3. 認可画面にデータを表示

認可画面データ取得

指定された認可リクエストIDに基づいて、認可画面で表示するためのデータを取得します。

レスポンスデータ

  • クライアント情報: クライアント名、ロゴURI、利用規約URIなど
  • スコープ情報: 要求されているスコープの一覧
  • クレーム情報: 要求されているクレームの一覧（id_token / userinfo / verified_claims）。クレーム単位の同意表示に使用します
  • セッション情報: セッション有効化フラグ
  • フェデレーション情報: 利用可能な外部IdP連携情報
  • カスタムパラメータ: クライアント固有のカスタムパラメータ

このAPIは認可画面のレンダリング時に使用され、ユーザーに表示する情報を提供します。

path Parameters
tenant-id
required
string <uuid>
Example: 67e7eae6-62b0-4500-9eff-87459f63fc66

テナントID

id
required
string
Example: authz_req_67890

認可リクエストID

header Parameters
x-view-binding
string

別サイト認可画面モード（ui_config.cross_site / クライアントの cross_site_authorization_view）でのみ必須。 認可リクエストの応答で、認可画面の URL の fragment（#view_binding=<値>）に渡された値。 認可画面からの呼び出しが、認可リクエストを始めたブラウザからのものかを確かめるために使う （同一サイト構成で IDP_AUTH_SESSION Cookie が担う照合の代わり）。 値が無い・違う場合は 401。認可リクエストを訪れるたびに作り直され、最後のものだけが有効。

Responses

Response samples

Content type
application/json
Example
{
  • "client_id": "client123",
  • "client_name": "サンプルアプリケーション",
  • "client_uri": "https://client.example.com",
  • "logo_uri": "https://client.example.com/logo.png",
  • "contacts": "support@client.example.com",
  • "tos_uri": "https://client.example.com/terms",
  • "policy_uri": "https://client.example.com/privacy",
  • "scopes": [
    ],
  • "claims": {
    },
  • "claim_values": {
    },
  • "session_enabled": true,
  • "custom_params": {
    }
}

認可リクエスト

OAuth 2.0/OpenID Connect認可リクエスト関連API。

  • 標準的な認可リクエスト処理
  • 認可承認・拒否処理

認可承認

ユーザーが認証完了後、認可画面で「許可」を選択した際に呼び出すAPI。

認可承認により認可コードが発行され、クライアントのredirect_uriに リダイレクトされます。

path Parameters
tenant-id
required
string <uuid>
Example: 67e7eae6-62b0-4500-9eff-87459f63fc66

テナントID

id
required
string
Example: authz_req_67890

認可リクエストID

header Parameters
x-view-binding
string

別サイト認可画面モード（ui_config.cross_site / クライアントの cross_site_authorization_view）でのみ必須。 認可リクエストの応答で、認可画面の URL の fragment（#view_binding=<値>）に渡された値。 認可画面からの呼び出しが、認可リクエストを始めたブラウザからのものかを確かめるために使う （同一サイト構成で IDP_AUTH_SESSION Cookie が担う照合の代わり）。 値が無い・違う場合は 401。認可リクエストを訪れるたびに作り直され、最後のものだけが有効。

Request Body schema: application/json
optional

任意。consent画面でユーザーが共有を拒否した scope / クレーム（view-data の scopes / claims から選択）。

  • denied_scopes: 拒否された scope。付与スコープから除外され、その scope 由来のクレームも 発行されません（認証ポリシー(LoA)由来の拒否スコープにマージされます）。
  • denied_claims: 拒否されたクレーム名。付与時に id_token / userinfo / verified_claims から 除外されます（OIDC4IDA §5.7.3、claim単位の同意）。
  • granted_claim_values: 配列クレームのうち共有を許可した要素（view-data の claim_values から選択）。クレーム丸ごとではなく要素単位の同意です。

ボディ無し（従来どおり）の場合は全要求 scope / クレームを許可します。

  • auth_proof: 別サイト認可画面モードで、認証ステップの応答で受け取った値。ブラウザで本人しか 通せないステップを経た認可では必須です（無い・使用済み・別の認可リクエスト向け・別の利用者向けの 場合は 400）。デバイスだけで認証した認可（login_hint ＋ プッシュ承認など）では不要です。
auth_proof
string

認証ステップの応答で受け取った auth_proof（別サイト認可画面モードのみ）

denied_scopes
Array of strings

共有を拒否した scope の一覧

denied_claims
Array of strings

共有を拒否したクレーム名の一覧

object

配列クレームのうち共有を許可した要素。クレーム名をキーとし、値は許可した要素の配列です。

絞る方向にしか働きません。 ユーザーが実際に保有する値との積集合だけが残るため、 ここに保有していない値を書いてもクレームには入りません。

許可リストとして解釈されます。 列挙した要素はそのグラントに固定され、以降の トークン発行・UserInfo でも同じリストで絞られます。同意後にユーザーの保有が 増えても、列挙されていない要素は解放されません（新しい要素を解放するには 再同意が必要です）。制限しないつもりであればキー自体を送らないでください。 全要素を列挙することは「制限しない」ではなく「いま保有している要素に限定する」 という意思表示になります。

  • 指定しなかったクレームは従来どおり全要素を共有します
  • 空配列を指定するとそのクレームは省略されます（null や空配列ではなくキーごと消えます。 クレームを丸ごと拒否した場合と同じ結果、OIDC Core §5.3.2）
  • 一致は要素まるごとです。オブジェクト要素はフィールドの集合で比較するため順序は 問いませんが、識別子フィールドだけの部分指定では選択できません
  • 配列でないクレームや、ユーザーが持たないクレームを指定した場合は無視されます

verified_claims のクレームは、トークン上の位置と同じ verified_claims.claims.{クレーム名} に指定します（view-data の claim_values.verified_claims.claims から選択）。同じ名前の custom_properties の クレームとは別の選択で、それぞれ自分の値とだけ突き合わせます。 verified_claims.verification は選択の対象外です。

選択は同意の決定としてグラントに保存され、アクセストークン / ID Token / UserInfo の すべてに適用されます。

Responses

Request samples

Content type
application/json
Example
{
  • "denied_scopes": [
    ]
}

Response samples

Content type
application/json
Example

既存の OP セッションで認可承認

ブラウザに有効な OP セッションがあり、view-data の session_enabled が true のときに、 再認証せずに認可を承認するAPI。ユーザーと認証情報は OP セッションから取ります。

別サイト認可画面モードでは、OP セッションは認可リクエスト（トップレベル遷移）の時点で 認可リクエストに紐づけられ、この呼び出しはそれを使います（XHR には Cookie が届かないため）。 応答は authorize と同じく auth_proof になり、認可画面は /complete へ遷移します。

path Parameters
tenant-id
required
string <uuid>
Example: 67e7eae6-62b0-4500-9eff-87459f63fc66

テナントID

id
required
string
Example: authz_req_67890

認可リクエストID

header Parameters
x-view-binding
string

別サイト認可画面モード（ui_config.cross_site / クライアントの cross_site_authorization_view）でのみ必須。 認可リクエストの応答で、認可画面の URL の fragment（#view_binding=<値>）に渡された値。 認可画面からの呼び出しが、認可リクエストを始めたブラウザからのものかを確かめるために使う （同一サイト構成で IDP_AUTH_SESSION Cookie が担う照合の代わり）。 値が無い・違う場合は 401。認可リクエストを訪れるたびに作り直され、最後のものだけが有効。

Responses

Response samples

Content type
application/json
{}

別サイト認可画面モードの完了（トップレベル遷移）

別サイト認可画面モードで、認可フローの最後にブラウザをトップレベル遷移させるエンドポイント。 authorize（または authorize-with-session）の応答で受け取った auth_proof を付けて開きます。 fetch / XHR では呼ばないでください（Cookie が保存されません）。

次の 2 つを照合し、OP セッションの Cookie を保存してクライアントの redirect_uri へ 302 します。

  • auth_proof：認証したブラウザか
  • IDP_AUTH_SESSION Cookie：認可リクエストを始めたブラウザか

遷移先は auth_proof の中にあり、URL で指定できるものはありません。

path Parameters
tenant-id
required
string <uuid>
Example: 67e7eae6-62b0-4500-9eff-87459f63fc66

テナントID

id
required
string
Example: authz_req_67890

認可リクエストID

query Parameters
auth_proof
required
string

authorize の応答で受け取った auth_proof

Responses

認可拒否

ユーザーが認可画面で「拒否」を選択した際に呼び出すAPI。

認可拒否によりaccess_deniedエラーがクライアントのredirect_uriに 返却されます。

path Parameters
tenant-id
required
string <uuid>
Example: 67e7eae6-62b0-4500-9eff-87459f63fc66

テナントID

id
required
string
Example: authz_req_67890

認可リクエストID

header Parameters
x-view-binding
string

別サイト認可画面モード（ui_config.cross_site / クライアントの cross_site_authorization_view）でのみ必須。 認可リクエストの応答で、認可画面の URL の fragment（#view_binding=<値>）に渡された値。 認可画面からの呼び出しが、認可リクエストを始めたブラウザからのものかを確かめるために使う （同一サイト構成で IDP_AUTH_SESSION Cookie が担う照合の代わり）。 値が無い・違う場合は 401。認可リクエストを訪れるたびに作り直され、最後のものだけが有効。

Responses

Response samples

Content type
application/json
{}

フェデレーション

外部IdPとの連携認証API。

OIDC、SAMLなどの外部アイデンティティプロバイダーとの フェデレーション認証を行うためのAPI群。

フェデレーション認証開始

外部IdPとのフェデレーション認証を開始します。

指定されたSSOプロバイダーに対してリダイレクト先URLを生成し、 外部IdPの認証画面に遷移させます。

サポートされるフェデレーションタイプ

  • oidc - OpenID Connect
  • saml - SAML 2.0

一般的なSSOプロバイダー

  • Google (OIDC)
  • Azure AD (OIDC/SAML)
  • Okta (OIDC/SAML)
  • Auth0 (OIDC)
path Parameters
tenant-id
required
string <uuid>
Example: 67e7eae6-62b0-4500-9eff-87459f63fc66

テナントID

id
required
string
Example: authz_req_67890

認可リクエストID

federation-type
required
string
Enum: "oidc" "saml"
Example: oidc

フェデレーションタイプ

sso-provider-name
required
string
Example: google

SSOプロバイダー名

header Parameters
x-view-binding
string

別サイト認可画面モード（ui_config.cross_site / クライアントの cross_site_authorization_view）でのみ必須。 認可リクエストの応答で、認可画面の URL の fragment（#view_binding=<値>）に渡された値。 認可画面からの呼び出しが、認可リクエストを始めたブラウザからのものかを確かめるために使う （同一サイト構成で IDP_AUTH_SESSION Cookie が担う照合の代わり）。 値が無い・違う場合は 401。認可リクエストを訪れるたびに作り直され、最後のものだけが有効。

Responses

Response samples

Content type
application/json
Example

フェデレーション認証コールバック

外部IdPからのコールバックを処理します。

外部IdPでの認証完了後、認可コードやSAMLレスポンスを受信し、 ユーザー情報を取得して認証を完了させます。

処理フロー

  1. 外部IdPからのコールバック受信
  2. 認可コードまたはSAMLレスポンスの検証
  3. ユーザー情報取得
  4. 内部ユーザーとのマッピング
  5. 認証完了またはユーザー登録画面へリダイレクト
path Parameters
tenant-id
required
string <uuid>
Example: 67e7eae6-62b0-4500-9eff-87459f63fc66

テナントID

federation-type
required
string
Enum: "oidc" "saml"
Example: oidc

フェデレーションタイプ

header Parameters
x-view-binding
string

別サイト認可画面モード（ui_config.cross_site / クライアントの cross_site_authorization_view）でのみ必須。 認可リクエストの応答で、認可画面の URL の fragment（#view_binding=<値>）に渡された値。 認可画面からの呼び出しが、認可リクエストを始めたブラウザからのものかを確かめるために使う （同一サイト構成で IDP_AUTH_SESSION Cookie が担う照合の代わり）。 値が無い・違う場合は 401。認可リクエストを訪れるたびに作り直され、最後のものだけが有効。

Request Body schema: application/x-www-form-urlencoded
required

外部IdPからのコールバックパラメータ。 フェデレーションタイプによって形式が異なります。

code
string

OIDC認可コード

state
string

状態パラメータ

SAMLResponse
string

SAMLレスポンス

RelayState
string

SAMLリレー状態

error
string

エラーコード

error_description
string

エラー詳細

Responses

Request samples

Content type
application/x-www-form-urlencoded
Example
code=abc123&state=xyz456

Response samples

Content type
application/json
{
  • "id": "4b0e1b4a-6a39-4b5b-9d5e-2f1f2c8c6a11",
  • "tenant_id": "67e7eae6-62b0-4500-9eff-87459f63fc66"
}