# Tek Oturum Açma

> OIDC üzerinden federe oturum açma — etkinleştirme, otomatik hesap oluşturma, kendi hesabınızı bağlama ile bağlantısını kesme ve root'u yalnız yerel tutan korumalar.

- Güncelleme: 2026-10-30
- Kaynak: https://contextator.com/tr/docs/sso/
- Dil: tr-TR
- Yazar: Muhammet Şafak

---
OIDC üzerinden federe oturum açma, parola formunun yanında ikinci bir kapı olarak — hiçbir zaman onun
yerine geçmez.

## Etkinleştirmek

`OIDC_ISSUER_URL`'i ayarlamak açma/kapama anahtarıdır. Boş bırakıldığında hiçbir discovery isteği
yapılmaz ve `/login`'de hiçbir düğme render edilmez, gerçi SSO route'ları kayıtlı kalır
(`GET /api/auth/oidc/login` `404` yanıtlar, ve callback `/login?oidc_error=not_configured`'a yönlendirir).
Ayarlandığında, discovery ilk oturum açma denemesinde bir kez getirilir ve önbelleğe alınır.

| Değişken | Varsayılan | Notlar |
|----------|---------|-------|
| `OIDC_ISSUER_URL` | – | Sağlayıcının issuer URL'i. Tüm özellik için açma/kapama anahtarı |
| `OIDC_CLIENT_ID` / `OIDC_CLIENT_SECRET` | – | Sağlayıcı tarafından verilir. `OIDC_CLIENT_SECRET`, `ADMIN_TOKEN` gibi bir süreç sırrıdır — ortamdan okunur, veritabanına hiçbir zaman yazılmaz, bu yüzden hiçbir yedek ya da dump onu taşımaz |
| `OIDC_REDIRECT_URI` | hesaplanır | Opsiyonel. Sağlayıcıya kayıtlı callback URL'i, örn. `https://docs.example.com/api/auth/oidc/callback`. Ayarlanmazsa `<base>/api/auth/oidc/callback` olur; `<base>`, `PUBLIC_BASE_URL`'dir, o yoksa isteğin kendi şeması ve host'u. Sağlayıcı, isteğin host'unun güvenilir biçimde üretemeyeceği tam bir eşleşme gerektiriyorsa ayarlayın |
| `OIDC_SCOPES` | `openid profile email` | Sağlayıcıdan istenen, boşlukla ayrılmış scope'lar |
| `OIDC_BUTTON_LABEL` | `Single sign-on` | `/login` SSO düğmesindeki metin |
| `OIDC_AUTO_PROVISION` | `0` | `1`, ilk başarılı sağlayıcı oturum açmasının burada kendiliğinden bir hesap oluşturmasına izin verir. Varsayılan olarak kapalıdır: eşlenmemiş bir sağlayıcı kimliğine sessizce bir hesap açılmak yerine reddedilir |
| `OIDC_DEFAULT_ROLE` | `member` | Oluşturulan bir hesabın alacağı rol. Yalnızca `admin` ya da `member` — hiçbir zaman `root` |

Sağlayıcının kendisi için dashboard'dan yapılandırılacak hiçbir şey yoktur; bu değişkenler örneğin
ortamında operatör tarafından ayarlanır. Ayarların nasıl uygulandığı için
[Yapılandırma](/tr/docs/configuration/)'ya bakın.

## Oturum açmak

Federe bir oturum açma her zaman sağlayıcının `sub` claim'iyle bir hesaba eşleştirilir, hiçbir zaman
e-posta claim'iyle değil — bir e-posta, yanlış yapılandırılmış ya da ele geçirilmiş bir sağlayıcının farklı
bir yerel hesaba ulaşmak için tam da sahteleyebileceği şeydir. Sağlayıcıdaki e-postanızı değiştirmek
bağlantınızı kesmez ve sizi kazara başka birinin hesabına bağlayamaz.

Bu yolla yeni bir hesabın hiç oluşturulup oluşturulamayacağı operatörün seçimidir (`OIDC_AUTO_PROVISION`),
varsayılan olarak kapalı. O kapalıyken, sağlayıcı üzerinden oturum açmak, sağlayıcı kimliği zaten bir
hesaba bağlı değilse reddedilir. Bir admin'in oluşturduğu hesap kullanıcı adı ya da e-postayla eşleşmez:
sahibi parolayla bir kez oturum açar ve kimliği kendisi bağlar (aşağıda). Onu açın ve ilk başarılı oturum açma
`OIDC_DEFAULT_ROLE` ile bir hesap üretir.

Bir kez oturum açıldığında, federe bir hesap diğer her hesapla aynı [rol tablosuna](/tr/docs/accounts-and-permissions/)
tabidir — nereye ulaşabileceğiniz nasıl oturum açtığınıza bağlı değildir — ve bir sağlayıcı kesintisi
hiçbir zaman yerel parolayla oturum açmayı engellemez. İki kapı birbirine bağımlı değildir.

## Kendi hesabınızı bağlamak ya da bağlantısını kesmek

Bir kez oturum açıldığında — parolayla ya da sağlayıcı üzerinden — root olmayan her hesap kendi federe
kimliğini **API tokens** sayfasında (`#/~tokens`), **Single sign-on** başlığı altında bağlayabilir ya da ayırabilir. Bağlamak,
giriş düğmesinin kullandığı aynı sağlayıcı yönlendirmesini başlatır, ama döndüğü kimliği zaten onu
sahiplenen hesaba oturum açmak yerine *mevcut* oturuma bağlar. Zaten farklı bir hesaba bağlı olan bir
sağlayıcı kimliğini bağlamak reddedilir, birleştirilmez — her kimlik tam olarak bir hesaba aittir.

**Bağlantıyı kesmek kendi kendine yapılan bir işlemdir ve aynı istekte hesabın geçerli kimlik
bilgilerini iptal eder:** kimlik kaldırıldığı anda o hesabın sahip olduğu her oturum ve her API token'ı
geçersiz kılınır — isteği yapan oturum da dahil — çünkü bağlantıyı kesmek aynı zamanda sonraki bir
root'a yükseltmenin önünü açan şeydir, ve hesap hâlâ kanıtlanabilir şekilde bir dış kimlik sağlayıcısına
bağlıyken açılan hiçbir şey o bağlantıdan daha uzun ömürlü olmamalıdır. Aynı işlem hesabın **MCP OAuth
kimlik bilgilerini** de iptal eder — `/mcp/<project>` için verilmiş her erişim ve yenileme token'ı — bu
yüzden o hesap olarak oturum açmış bir MCP client'ı bir sonraki isteğinde `401` alır ve yeniden
yetkilendirmek zorunda kalır; diğer hesapların kimlik bilgileri dokunulmadan kalır. Bağlantı kesmenin
audit olayı kaç tanesinin iptal edildiğini `detail.revokedMcpCredentials` olarak kaydeder. Bağlantı
gittiği için, çalışan bir oturum elde etmek üzere yerel olarak tekrar oturum açın.

Hesabın yerel bir parolası yoksa ve bu bağlantı oturum açmanın tek yoluysa, bağlantıyı kesmek
reddedilir (`409 last_sign_in_method`) — hiçbir şey kaldırılmaz, hiçbir şey iptal edilmez — ta ki bir
admin önce `POST /api/users/:id/password` ile onun için bir parola ayarlayana kadar.

## root her zaman yerel kalır

`root` en baştan bir sağlayıcı kimliği bağlayamaz — kontrol dashboard'da onun için hiç görünmez, ve API
girişimi doğrudan reddeder (`403 root_local_only`). Ters yön de korunur: hâlâ bağlı bir kimliği olan bir
hesaba `root` vermek reddedilir (`409 root_requires_unlink`), hem Kullanıcılar sayfasında hem de API'de,
yazma işleminden önce kontrol edilir — böylece bağlantı var olduğu sürece hesabın rolü hiçbir zaman
gerçekten `root` olmaz. İkinci bir savunma hattı olarak, bir oturumun rolü ve oturum açma yöntemi her
istekte yeniden okunur; bir hesap bir şekilde hâlâ bağlıyken `root`'a ulaşmış olsaydı, onun için SSO
üzerinden açılmış bir oturum root olarak davranmasına izin verilmek yerine bir sonraki isteğinde oturumdan
atılırdı. Yalnızca bağlantı kesildikten sonra başka bir root hesabı `root` rolünü verebilir.

Bu ürünün bir sağlayıcı claim'inden yeniden oluşturamayacağı tek hesabın — `root` — hiçbir zaman SSO
üzerinden oturum açmamasının nedeni budur.

## Gruplar proje üyeliği verir

`OIDC_GROUPS_CLAIM`, bir kişinin gruplarını listeleyen **ID token**'ın üst düzey claim'ine ayarlandığında (örneğin
`groups`), bu gruplar proje üyeliği verebilir. Bir yönetici, bir grup adını bir projeye ve bir role (`viewer` ya da
`editor`) **Users → SSO group mappings** altında ya da `GET`/`POST /api/oidc/group-mappings` ve
`DELETE /api/oidc/group-mappings/:id` ile eşler. Grup adları büyük harfler dahil birebir eşleşir ve bir grup hiçbir
zaman instance rolünü değiştirmez: hiç kimse bir grup yüzünden `admin` ya da `root` olmaz. Ayarlanmamışsa burada hiçbir
şey çalışmaz ve oturum açma değişmez. Claim yalnızca ID token'dan okunur, iç içe bir claim yolu desteklenmez. Claim'i
üretmek için bir scope isteyen sağlayıcı bunu `OIDC_SCOPES` ile alır.

Bir `member` hesabının her SSO oturum açışında:

- Hesabın gruptan gelen üyelikleri, gruplarının eşlendiği projelerin tam kendisi olur; iki grup aynı projeyi eşliyorsa
  daha yüksek rol geçerlidir.
- Aynı proje için elle eklenmiş bir üyelik kazanır ve bir grup tarafından asla değiştirilmez ya da kaldırılmaz.
- Bir gruptan ayrılan kişi üyeliği **bir sonraki oturum açışında** kaybeder, öncesinde değil. Erişimi hemen kesmek için
  hesabı devre dışı bırakın.
- `admin` ve `root` hesaplar atlanır: zaten her projeye ulaşırlar.

Ayar açıkken üyelik API'si, gruptan gelen bir satır için `409 membership_managed_by_group` yanıtı verir, çünkü bir
sonraki oturum açış onu geri koyardı. Gruptan gelen bir üyelik ayrıca eşlemesi silindiğinde, hesabı SSO bağlantısını
kestiğinde ve bağlı bir hesap parolayla oturum açtığında da kaldırılır. Ayarı kapatmak hiçbir şeyi kaldırmaz.

Eksik, `null`, `[]` ya da `{}` bir claim grup yok demektir ve oturum açma sürer. Okunamayan bir claim — Microsoft
Entra'nın overage işareti (`_claim_names.groups`), bir dize listesi olmayan her şey, 1 000'den fazla girdi ya da 256
karakteri aşan bir ad — bir `member`'in oturum açışını `groups_unavailable` ile durdurur ve hiçbir şeyi değiştirmez. Bir
oturum açışın değiştirdiği her üyelik tek bir audit olayıdır. Helm chart'ında ayar `config.oidcGroupsClaim`'dir.

## Admin API

Bağlamak ve bağlantı kesmek aynı zamanda iki sıradan endpoint'tir, oturum açmış bir çağıranın kendi
oturumundan bir betik tarafından çağrılabilir — bkz. [Admin API](/tr/docs/admin-api/#tek-oturum-açma).
