Contextator
ENTR

Yönetim ve güvenlik

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:

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.
  • 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.

Gezinmek için ok tuşları, açmak için Enter.