# Bir bağlantının OIDC yapılandırmasını oluştur veya değiştir

`PUT /v1/connections/{connection_id}/oidc` · izin `connections:write`

Kurumsal bir OIDC bağlantısının güven taraflı (relying party) yapılandırmasını oluşturur veya tamamen değiştirir.

- **İlk yazma:** `If-Match` üstbilgisi göndermeyin ve `sp_host` (bu ortamın etkin bir ana makinesi) verin. `https://<sp_host>/sso/<connection_id>/callback` geri çağırma adresi bundan sonra sabittir. Yanıt `201 Created` olur. Yapılandırma yokken `If-Match` göndermek `412` ile başarısız olur.
- **Güncelleme:** `If-Match` zorunludur. Olmadan istek `428` ile başarısız olur ve hiçbir şey yazılmaz; bu nedenle üstbilgisiz bir istek mevcut yapılandırmanın üzerine asla yazamaz. Yapılandırma, okuduğunuzdan beri değiştiyse (veya değer eşleşmiyorsa) istek `412` ile başarısız olur. `*` mevcut yapılandırmayla eşleşir. `sp_host` boş olmalı veya kaydedilmiş ana makine olmalıdır.

İstemci gizli anahtarı yalnızca yazılabilir: asla döndürülmez, günlüğe kaydedilmez veya denetim günlüğüne yazılmaz. `client_secret` olmadan güncellediğinizde kaydedilmiş gizli anahtar korunur; `private_key_jwt` bunu kaldırır (ortamın imzalama anahtarı istemci onayını imzalar). Değişen bir `issuer` kaydedilmiş keşif belgesini temizler; değişen bir `issuer` veya `client_id` son geçen bağlantı testini geçersiz kılar. Aynı yapılandırmayı göndermek hiçbir şey yazmaz. Yazmalar `connection.protocol_config_created` veya `connection.oidc_config_updated` olarak denetlenir (yalnızca değişen alanlar; gizli anahtar yalnızca `client_secret_set` olarak görünür).

**Etkin** bir bağlantıda, `issuer` veya `client_id` değiştiren bir güncelleme uygulanmaz. Tüm istek (yeni gizli anahtar dahil) bir [taslak revizyon](../connections/revisions.md) olur: yanıt, değişmemiş canlı yapılandırma, değişmemiş `ETag` ve bir `revision` alanıyla `200 OK` olur. Taslağı `revision_id` ile [Bağlantıyı test et](../connections/test.md) bölümünde test edin, ardından [yayınlayın](../connections/publish-revision.md). Diğer güncellemeler doğrudan uygulanır.

## İstek

| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
| `connection_id` | yol | evet | Kurumsal OIDC bağlantı kimliği (`conn_…`). |
| `If-Match` | üstbilgi | güncellemede | Son okuma veya yazmadaki `ETag`. Güncellemede eksikse: `428`; eskiyse: `412`. İlk yazmada gönderilmez. |
| `sp_host` | dize | ilk yazmada | Bu ortamın etkin ana makinesi (küçük harf). Güncellemede boş veya kaydedilmiş ana makine. |
| `issuer` | dize | evet | Sorgu veya parça içermeyen, en fazla 512 bayt mutlak `https` URL'si. |
| `client_id` | dize | evet | 1–255 bayt, denetim karakteri yok. |
| `client_auth_method` | dize | evet | `private_key_jwt` (önerilir; gizli anahtar saklanmaz), `client_secret_basic` veya `client_secret_post`. |
| `client_secret` | dize | hayır | Yalnızca yazılabilir, en fazla 1024 bayt. Güncellemede atlanırsa korunur. `private_key_jwt` ile kullanılamaz. |
| `client_secret_expires_at` | dize \| null | hayır | Kimlik sağlayıcının gizli anahtarı ne zaman süresi dolduracağı (RFC 3339). Yalnızca `client_secret` ile birlikte. |
| `provider_profile` | dize | hayır | `entra`, `okta`, `google`, `keycloak`, `ping`, `onelogin`, `jumpcloud` veya `generic` (varsayılan). |
| `entra_tenant_id` | dize | `entra` için | Microsoft Entra kiracı kimliği (UUID); yalnızca `entra` profili için. |

## Yanıt

İlk yazmada `201 Created`, güncellemede `200 OK`; yapılandırma ([OIDC yapılandırmasını al](get.md) bölümüne bakın) ve yeni `ETag` ile birlikte. İstemci gizli anahtarı yanıtta yer almaz. Güncelleme bir taslak revizyona dönüştüğünde gövdede ayrıca `revision` (taslak) bulunur ve yapılandırma ile `ETag` canlı olanlardır.

## 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 OIDC bağlantısı değil, `sp_host` kaydedilmiş ana makineden farklı veya bir gizli anahtar yöntemi için kaydedilmiş ya da verilmiş bir gizli anahtar yok. |
| 412 | `precondition_failed` | `If-Match` geçerli sürümle eşleşmiyor, yapılandırma eşzamanlı olarak değişti veya `If-Match` ilk yazmadan önce gönderildi. |
| 422 | `validation_failed` | Bir alan yukarıdaki kuralları ihlal ediyor; `errors[]` alanı belirtir (`/issuer`, `/client_id`, `/client_auth_method`, `/client_secret`, `/client_secret_expires_at`, `/provider_profile`, `/entra_tenant_id`, `/sp_host`). |
| 428 | `precondition_required` | Yapılandırma mevcut ve `If-Match` üstbilgisi eksik. |
| 400 | `unknown_field` | Gövdede bilinmeyen bir alan var. |
| 401 | `unauthenticated` | Kimlik bilgisi eksik, geçersiz veya iptal edilmiş. |
| 403 | `insufficient_permissions` | Kimlik bilgisinde gerekli izin 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

Gizli anahtarı komut satırında değil, bir dosyada tutun (`oidc.json`):

```json
{"sp_host":"acme.eu1.keenauth.app","issuer":"https://idp.example.com","client_id":"keenauth-acme","client_auth_method":"client_secret_basic","client_secret":"<secret from the identity provider>"}
```

```bash
curl -X PUT "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b/oidc" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d @oidc.json
```

```bash
keenauth connections oidc put conn_01j9xp6q0r1s5t7v9w1x3y5z7b --data @oidc.json
keenauth connections oidc put conn_01j9xp6q0r1s5t7v9w1x3y5z7b --data @oidc-update.json --if-match '"6f1c…"'
```