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’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 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.
adminveroothesaplar 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.