# SAML IdP メタデータを接続にインポート

`POST /v1/connections/{connection_id}:import-metadata` · 権限 `connections:write`

ID プロバイダからアップロードされた SAML 2.0 メタデータドキュメントを、エンタープライズ SAML 接続に適用します。

- 接続の ID プロバイダ側（エンティティ ID、HTTP-Redirect シングルサインオン URL、シングルログアウト URL）は、ドキュメントの値で置き換えられます。
- ドキュメント内の署名証明書のうち、有効期限が切れておらず、まだ登録されていないものが追加されます（`source` は `manual`）。接続に既に登録されている証明書は有効のまま残ります。削除するには [証明書を削除](../connection-certificates/delete.md) を参照してください。
- 接続はアップロードされたドキュメントに従うようになります。保存されているメタデータ URL と証明書のピン留めは解除されます。
- この変更により、直前に成功した[接続テスト](test.md)は無効になります。接続を有効化するには、新たにテストに成功する必要があります。

**有効**な接続では、ID プロバイダのエンティティ ID または SSO URL を変更するドキュメント、または署名のピン留めを削除するドキュメントは適用されません。インポート全体が[下書きリビジョン](revisions.md)になり、レスポンスには変更されていない稼働中の ID プロバイダ側が表示され、`added_certificate_fingerprints` は空になり、`revision` が設定されます。`revision_id` を指定して [接続をテスト](test.md) で下書きをテストし、そのうえで [公開](publish-revision.md) してください。それ以外のインポート（新しい証明書、SLO URL、MFA の値）は直接適用されます。

ドキュメントは厳格な制限（最大 1 MiB、`DOCTYPE` なし）のもとで解析されます。ドキュメントが無効な場合、レスポンスは理由を示さず、理由もドキュメントの内容もログに記録されません。複数の `EntityDescriptor` 要素を含むドキュメントには `entity_id` が必要です。SAML のデータにはバージョンがないため、このリクエストは `If-Match` ヘッダーを受け付けません。書き込みは `connection.idp_metadata_imported` として監査され、新しい証明書ごとに `connection.idp_certificate_added` も記録されます。

## リクエスト

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `connection_id` | path | はい | エンタープライズ SAML 接続 ID（`conn_…`）。 |
| `metadata_xml` | string | はい | メタデータドキュメント（`EntityDescriptor` または `EntitiesDescriptor`）。最大 1 MiB。 |
| `entity_id` | string | 複数のエンティティがある場合 | 複数のエンティティを含むドキュメントから取得する ID プロバイダのエンティティ ID。エンティティが 1 つの場合は一致している必要があります。 |
| `mfa_authn_context_values` | array \| null | いいえ | ID プロバイダによって多要素認証とみなされる SAML `AuthnContextClassRef` の値（最大 10 個）。指定された場合（空のリストも含む）は保存されます。省略された場合または `null` の場合は、保存済みの値が維持されます。 |

## レスポンス

`200 OK`：

```json
{
  "idp_entity_id": "https://idp.example.com/entity",
  "idp_sso_url": "https://idp.example.com/sso/redirect",
  "idp_slo_url": null,
  "certificates": [
    {"id": "conncert_01j9xq2m4n6p8r0s2t4v6w8y0a", "sha256_fingerprint": "3b0c…", "not_before": "2026-01-01T00:00:00Z", "not_after": "2028-01-01T00:00:00Z", "source": "manual"}
  ],
  "added_certificate_fingerprints": ["3b0c…"]
}
```

| フィールド | 説明 |
|---|---|
| `idp_entity_id`, `idp_sso_url`, `idp_slo_url` | インポート後の ID プロバイダ側。ドキュメントにシングルログアウトサービスがない場合、`idp_slo_url` は `null` になります。 |
| `certificates` | 接続の有効な署名証明書（[証明書一覧](../connection-certificates/list.md) を参照）。 |
| `added_certificate_fingerprints` | このインポートで追加された証明書の SHA-256 フィンガープリント。既に登録済みの証明書は一覧に含まれません。 |
| `revision` | インポートが下書きリビジョンになった場合のみ：その下書き（[リビジョン一覧](revisions.md) を参照）。 |

## エラー

| HTTP | code | 発生条件 |
|---|---|---|
| 404 | `not_found` | 接続がこの環境に存在しない、またはエンタープライズ接続ではありません。 |
| 409 | `conflict` | 接続が SAML 接続ではない、まだ SAML 設定がない、またはインポートにより有効な証明書が 3 つを超える場合（何も変更されません）。 |
| 422 | `validation_failed` | ドキュメントまたはフィールドが無効です。`errors[]` がフィールドを指します（`/metadata_xml`、`/entity_id`、`/mfa_authn_context_values`）。ステージングおよび本番環境では、テスト用 ID プロバイダも `/metadata_xml` で拒否されます。予約済みの `.invalid` ドメイン配下のエンティティ ID、または[ローカルモックサーバー](/docs/cli/mock-server)の公開テスト鍵が該当します。 |
| 413 | `payload_too_large` | リクエストボディが 4 MiB を超えています。 |
| 400 | `unknown_field` | ボディに未知のフィールドが含まれています。 |
| 401 | `unauthenticated` | 認証情報がない、無効、または取り消されています。 |
| 403 | `insufficient_permissions` | 認証情報に必要な権限がありません。 |
| 429 | `rate_limited` | レート制限を超えました。`Retry-After` の期間を待ってから再試行してください。 |
| 503 | `service_unavailable` | 依存先が一時的に利用できません。`Retry-After` の期間を待ってから再試行してください。 |

## 例

```bash
jq -Rs '{metadata_xml: .}' idp-metadata.xml > import.json
curl -X POST "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b:import-metadata" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d @import.json
```

```bash
keenauth connections import-metadata conn_01j9xp6q0r1s5t7v9w1x3y5z7b --metadata-file idp-metadata.xml
```