# SAML 接続の IdP 起点サインインを設定

`PUT /v1/connections/{connection_id}/idp-initiated` · 権限 `connections:write`

エンタープライズ SAML 接続に対して、IdP 起点のサインイン（ID プロバイダのアプリポータルから送られる、要求のない SAML レスポンス）を許可またはオフにし、ユーザーが遷移できるアプリケーションを設定します。既定ではオフです。

- **全置換:** すべてのリクエストで 3 つのフィールドすべてが書き込まれます。省略された `idp_initiated_default_application_id` と空の `idp_initiated_allowed_application_ids` は消去されます。
- **対象:** 各アプリケーションはこの環境に存在し、ブラウザ経由でサインインさせるものである必要があります（マシン間通信、管理用、またはクライアント ID メタデータドキュメントのクライアントは不可）。また `initiate_login_uri` を持つ必要があります。サインイン後、ブラウザは `iss` を付けてそのアドレスへ送られ、アプリケーションは `state` と PKCE を使って独自の認可リクエストを開始します。
- **RelayState:** ID プロバイダが RelayState を送る場合、それがアプリケーションの `client_id` とバイト単位で完全に一致し、かつそのアプリケーションが既定のもの、または許可リストに含まれている場合にのみ、そのアプリケーションが選択されます。RelayState を URL として扱うことはありません。
- **セキュリティ:** この設定は、ユーザーが開始していないレスポンスを受け入れるため、ダッシュボードのユーザーには直近のステップアップ認証と `owner` または `admin` ロールが必要です。Admin Portal では変更できません。

## リクエスト

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `connection_id` | path | はい | エンタープライズ SAML 接続 ID（`conn_…`）。 |
| `If-Match` | header | いいえ | 接続の `ETag`。古い値の場合は `412` になります。 |
| `allow_idp_initiated` | boolean | はい | 要求のない SAML レスポンスを受け入れます。`true` の場合は `idp_initiated_default_application_id` が必要です。 |
| `idp_initiated_default_application_id` | string \| null | 有効時 | RelayState が空のときに使用されるアプリケーション（`app_…`）。 |
| `idp_initiated_allowed_application_ids` | array | いいえ | RelayState が選択できるアプリケーション（`app_…`）。一意で、最大 20 件。 |

## レスポンス

`200 OK` とともに接続（[接続を取得](../connections/get.md)を参照）と新しい `ETag` が返されます。接続には、`allow_idp_initiated`、`idp_initiated_default_application_id`、`idp_initiated_allowed_application_ids` に保存された値が表示されます。

## エラー

| HTTP | code | 発生条件 |
|---|---|---|
| 404 | `not_found` | この環境に接続が存在しません。 |
| 412 | `precondition_failed` | `If-Match` が現在のバージョンと一致しません。 |
| 422 | `validation_failed` | 接続がエンタープライズ SAML 接続ではない、有効時に既定のアプリケーションがない、またはアプリケーションが対象のルールを満たしていません。問題のフィールドは `errors[]` で示されます。 |
| 400 | `unknown_field` | リクエストボディに不明なフィールドがあります。 |
| 401 | `unauthenticated` | 認証情報が未指定、無効、または取り消されています。 |
| 403 | `insufficient_permissions` | 認証情報に必要な権限がありません。 |
| 403 | `step_up_required` | ダッシュボードのユーザーが直近のステップアップ認証を完了していません。 |
| 429 | `rate_limited` | レート制限を超えました。`Retry-After` の期間を待ってから再試行してください。 |
| 503 | `service_unavailable` | 依存サービスが一時的に利用できません。`Retry-After` の期間を待ってから再試行してください。 |

## 例

```bash
curl -X PUT "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b/idp-initiated" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allow_idp_initiated":true,"idp_initiated_default_application_id":"app_01j9xp6q0r1s5t7v9w1x3y5z7c","idp_initiated_allowed_application_ids":["app_01j9xp6q0r1s5t7v9w1x3y5z7c"]}'
```

```bash
keenauth connections idp-initiated put conn_01j9xp6q0r1s5t7v9w1x3y5z7b --data '{"allow_idp_initiated":false}'
```