SAML IdP メタデータを接続にインポート
POST /v1/connections/{connection_id}:import-metadata · 権限 connections:write
ID プロバイダからアップロードされた SAML 2.0 メタデータドキュメントを、エンタープライズ SAML 接続に適用します。
- 接続の ID プロバイダ側（エンティティ ID、HTTP-Redirect シングルサインオン URL、シングルログアウト URL）は、ドキュメントの値で置き換えられます。
- ドキュメント内の署名証明書のうち、有効期限が切れておらず、まだ登録されていないものが追加されます（
sourceはmanual）。接続に既に登録されている証明書は有効のまま残ります。削除するには 証明書を削除 を参照してください。 - 接続はアップロードされたドキュメントに従うようになります。保存されているメタデータ URL と証明書のピン留めは解除されます。
- この変更により、直前に成功した接続テストは無効になります。接続を有効化するには、新たにテストに成功する必要があります。
有効な接続では、ID プロバイダのエンティティ ID または SSO URL を変更するドキュメント、または署名のピン留めを削除するドキュメントは適用されません。インポート全体が下書きリビジョンになり、レスポンスには変更されていない稼働中の ID プロバイダ側が表示され、added_certificate_fingerprints は空になり、revision が設定されます。revision_id を指定して 接続をテスト で下書きをテストし、そのうえで 公開 してください。それ以外のインポート（新しい証明書、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：
{
"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 |
接続の有効な署名証明書（証明書一覧 を参照）。 |
added_certificate_fingerprints |
このインポートで追加された証明書の SHA-256 フィンガープリント。既に登録済みの証明書は一覧に含まれません。 |
revision |
インポートが下書きリビジョンになった場合のみ：その下書き（リビジョン一覧 を参照）。 |
エラー
| 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、またはローカルモックサーバーの公開テスト鍵が該当します。 |
| 413 | payload_too_large |
リクエストボディが 4 MiB を超えています。 |
| 400 | unknown_field |
ボディに未知のフィールドが含まれています。 |
| 401 | unauthenticated |
認証情報がない、無効、または取り消されています。 |
| 403 | insufficient_permissions |
認証情報に必要な権限がありません。 |
| 429 | rate_limited |
レート制限を超えました。Retry-After の期間を待ってから再試行してください。 |
| 503 | service_unavailable |
依存先が一時的に利用できません。Retry-After の期間を待ってから再試行してください。 |
例
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
keenauth connections import-metadata conn_01j9xp6q0r1s5t7v9w1x3y5z7b --metadata-file idp-metadata.xml