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 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 bölümünde test edin, ardından yayınlayın. 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 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):

{"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>"}

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

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