Bağlantıya SAML IdP meta verilerini içe aktarın

POST /v1/connections/{connection_id}:import-metadata · izin connections:write

Kimlik sağlayıcıdan yüklenen bir SAML 2.0 meta veri belgesini kurumsal bir SAML bağlantısına uygular.

Bağlantının kimlik sağlayıcı tarafı (varlık kimliği, HTTP-Redirect tek oturum açma URL'si, tek oturum kapatma URL'si) belgedeki değerlerle değiştirilir.
Belgedeki, süresi henüz dolmamış ve henüz kaydedilmemiş imzalama sertifikaları eklenir (source değeri manual olur). Bağlantıda zaten bulunan sertifikalar etkin kalır; bunları Sertifikayı silin ile silebilirsiniz.
Bağlantı artık yüklenen belgeyi izler: kayıtlı meta veri URL'si ve sertifika sabitlemesi temizlenir.
Bu değişiklik, son başarılı bağlantı testini geçersiz kılar; bağlantıyı etkinleştirmek için yeni bir testin başarıyla tamamlanması gerekir.

Etkin bir bağlantıda, kimlik sağlayıcının varlık kimliğini veya SSO URL'sini değiştiren ya da bir imzalama sabitlemesini kaldıran bir belge uygulanmaz. Tüm içe aktarma bir taslak revizyon olur: yanıt, değişmemiş canlı kimlik sağlayıcı tarafını gösterir, added_certificate_fingerprints boş olur ve revision ayarlanır. Taslağı, revision_id ile Bağlantıyı test edin adımında test edin, ardından yayımlayın. Diğer içe aktarmalar (yeni sertifikalar, SLO URL'si, MFA değerleri) doğrudan uygulanır.

Belge katı sınırlarla ayrıştırılır (en fazla 1 MiB, DOCTYPE yok). Belge geçersizse yanıt nedenini belirtmez; nedeni de belge içeriğini de günlüğe yazılmaz. Birden çok EntityDescriptor öğesi içeren bir belge entity_id gerektirir. SAML materyali bir sürüme sahip olmadığı için istek If-Match üstbilgisi almaz. Yazma işlemleri connection.idp_metadata_imported olarak denetlenir; her yeni sertifika için ayrıca connection.idp_certificate_added kaydedilir.

İstek

Alan	Tür	Zorunlu	Açıklama
`connection_id`	yol	evet	Kurumsal SAML bağlantı kimliği (`conn_…`).
`metadata_xml`	string	evet	Meta veri belgesi (`EntityDescriptor` veya `EntitiesDescriptor`), en fazla 1 MiB.
`entity_id`	string	birden çok varlık için	Birden çok varlık içeren bir belgeden alınacak kimlik sağlayıcının varlık kimliği. Tek varlık varsa eşleşmesi gerekir.
`mfa_authn_context_values`	array \| null	hayır	Kimlik sağlayıcı tarafından çok faktörlü kimlik doğrulama sayılan SAML `AuthnContextClassRef` değerleri (en fazla 10). Verildiğinde (boş liste dahil) kaydedilir; atlandığında veya `null` olduğunda kayıtlı değerler korunur.

Yanıt

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…"]
}

Alan	Açıklama
`idp_entity_id`, `idp_sso_url`, `idp_slo_url`	İçe aktarmadan sonraki kimlik sağlayıcı tarafı; belgede tek oturum kapatma hizmeti yoksa `idp_slo_url` `null` olur.
`certificates`	Bağlantının etkin imzalama sertifikaları (bkz. Sertifikaları listeleyin).
`added_certificate_fingerprints`	Bu içe aktarmanın eklediği sertifikaların SHA-256 parmak izleri; zaten kayıtlı sertifikalar listelenmez.
`revision`	Yalnızca içe aktarma bir taslak revizyona dönüştüğünde: taslak (bkz. Revizyonları listeleyin).

Hatalar

HTTP	code	Ne zaman
404	`not_found`	Bağlantı bu ortamda yok veya kurumsal bir bağlantı değil.
409	`conflict`	Bağlantı bir SAML bağlantısı değil, henüz bir SAML yapılandırması yok veya içe aktarma 3 etkin sertifika sınırını aşar (hiçbir şey değişmez).
422	`validation_failed`	Belge veya bir alan geçersiz; `errors[]` ilgili alanı gösterir (`/metadata_xml`, `/entity_id`, `/mfa_authn_context_values`). Staging ve production ortamlarında test kimlik sağlayıcısı da `/metadata_xml` alanında reddedilir: ayrılmış `.invalid` alan adı altındaki bir varlık kimliği veya yerel mock sunucusunun genel test anahtarı.
413	`payload_too_large`	İstek gövdesi 4 MiB'tan büyük.
400	`unknown_field`	Gövdede bilinmeyen bir alan var.
401	`unauthenticated`	Kimlik bilgisi eksik, geçersiz veya iptal edilmiş.
403	`insufficient_permissions`	Kimlik bilgisinin gerekli izni yok.
429	`rate_limited`	Hız sınırı aşıldı; `Retry-After` süresinden sonra yeniden deneyin.
503	`service_unavailable`	Bir bağımlılık geçici olarak kullanılamıyor; `Retry-After` süresinden sonra yeniden deneyin.

Örnek

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