# 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](../connection-certificates/delete.md) 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](test.md) 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](revisions.md) 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](test.md) adımında test edin, ardından [yayımlayın](publish-revision.md). 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`:

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

| 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](../connection-certificates/list.md)). |
| `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](revisions.md)). |

## 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](/docs/cli/mock-server) 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

```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
```