Bir OpenID Connect sağlayıcısı bağlama

Kimlik sağlayıcınız SAML yerine OpenID Connect konuşuyorsa bu kılavuzu kullanın. OIDC sertifikalı her issuer çalışır — Pocket ID, Keycloak, Auth0, Zitadel, Google Workspace ve benzerlerinin tümü aynı adımları izler; yalnızca sağlayıcınızın değerleri gösterdiği yer farklıdır.

Önkoşullar

• istemci oluşturabileceğiniz bir OIDC sağlayıcısı — client id ve issuer URL değerlerini (.well-known/openid-configuration belgesinin yayımlandığı temel adres) ve istemci gizli türdeyse (herkese açık PKCE istemcilerinde secret bulunmaz) client secret değerini not edin,
• yönettiğiniz bir Control Center sunucusu (sunucu sahibi).

Adımlar

1. Ayarlar → Sunucu → Tek oturum açma bölümünü açın ve OpenID Connect seçeneğine geçin.
2. Issuer URL, Client ID ve sağlayıcı verdiyse Client secret (isteğe bağlı) alanlarını doldurun. Control Center uç noktaları issuer’ın standart discovery belgesinden keşfeder — sağlayıcı başına yapılandırma gerekmez.
3. Sağlayıcıda, bu istemciye https://<your-server>/oidc/callback yönlendirmesini kaydedin.
4. Gruplarınız groups dışında bir claim altında yer alıyorsa Gruplar claim adını ayarlayın; isterseniz grupları rollere eşleyin (SSO sahip rolünü asla veremez).
5. Üyelik politikasını seçin (her çalışma alanına otomatik ekleme ya da çalışma alanı başına davet zorunluluğu), Oturum açmak için OpenID Connect kullan seçeneğini açın ve Bağlantıyı kaydet düğmesine basın.
6. Bağlantıyı dene düğmesine basın — sunucu issuer’ın discovery belgesini getirir ve uç noktalarını doğrular; yani yeşil bir bildirim, tarayıcı gidiş-dönüşü dışındaki her şeyin çalıştığı anlamına gelir. İstemci kaydını da denetlemek için aşağıdaki denetleyiciyi kullanın.
7. Bir oturum açma deneyin: web bağlanma ekranı OpenID Connect ile oturum aç gösterir ya da https://<your-server>/oidc/login adresini doğrudan açabilirsiniz.

Claim’ler (e-posta, ad, gruplar) sunucunuz tarafından issuer’ın token uç noktasından TLS üzerinden okunur — tarayıcı bunları hiçbir zaman sağlamaz, dolayısıyla hiçbir yerel JWT imza doğrulaması devreye girmez. İstemcinin openid profile email kapsamını istemesine izin verilmelidir; Control Center tam olarak bunu ister.

Claim’leri kimlik doğrulayan tek şey bu TLS kanalı olduğundan, issuer URL https olmalıdır — düz metin bir issuer, yoldaki herhangi bir saldırganın toplu olarak kimlik sahtelemesine olanak tanır. http yalnızca yerel geliştirme için loopback issuer’larda (localhost, 127.0.0.1, ::1) kabul edilir.

Herkese açık istemci mi, gizli istemci mi?

Varsayılan — ve önerilen — biçim, PKCE (RFC 7636) ile authorization code akışını kullanan herkese açık istemcidir: sunucunun elinde tuttuğu tek kullanımlık code verifier, secret’ın yerini alır ve token alışverişi, onu başlatan yetkilendirme isteğine bağlanır. Sızabilecek bir secret yoktur ve çalınan bir authorization code, verifier olmadan işe yaramaz. Bazı sağlayıcılar, istemciyi oluştururken bu türe “SPA” ya da “native” istemci türü der.

Sağlayıcınız bunun yerine gizli bir istemci verdiyse ya istemciyi sağlayıcıda herkese açık olarak işaretleyin (PKCE her iki durumda da açık kalır) ya da client secret’ı bağlantının Client secret (isteğe bağlı) alanına yapıştırın. Secret, sunucunun 0600 izinli secrets dosyasında saklanır (asla veritabanında değil), token uç noktasına client_secret_post olarak gönderilir ve RPC üzerinden asla döndürülmez; kaydederken alanı boş bırakmak saklanan secret’ı korur. Bir oturum açma token alışverişinde başarısız olduğunda sunucu günlüğü sağlayıcının kendi hatasını adlandırır (invalid_client neredeyse her zaman secret’ın eksik ya da yanlış olduğu anlamına gelir).

Erişilebilirlik

Oturum açmanın kendisi tarayıcı aracılığıyla gerçekleşir: issuer yalnızca kullanıcının tarayıcısını /oidc/callback adresine geri yönlendirir ve sunucunuz token uç noktasına giden yönde bir HTTPS çağrısı yapar — issuer’dan gelen bir bağlantıya gerek yoktur; bu nedenle NAT arkasındaki bir sunucu, kullanıcıların tarayıcıları ona ulaşabildiği sürece çalışır (LAN, VPN, Tailscale veya bir tünel). SCIM ile sağlama istisnadır: IdP doğrudan sunucunuzu çağırır; bu da bir tünel ya da herkese açık bir URL gerektirir — bkz. SCIM ile kullanıcı sağlama.

Yapılandırmanızı bu sayfadan denetleyin

Aşağıdaki denetleyici tarayıcınızda çalışır. Issuer’ınızın discovery belgesini doğrudan getirir; bu site onu hiçbir zaman görmez ve sunucunun kurallarını uygular: belgeyle eşleşen bir https issuer, uç noktaların issuer’ın kendi origin’inde olması, PKCE S256 ve istemci türünüzün gerektirdiği token kimlik doğrulama yöntemi. Bir client ID ve sunucu adresiyle, istemcinin ve yönlendirme URI’sinin kayıtlı olup olmadığını gösteren bir test oturum açması açabilir. Hiçbir zaman client secret istemez.

Runs in your browserYour browser fetches the discovery document straight from your issuer. Add a server address and it also asks that server which sign-in methods it offers. This site never receives what you type.

Issuer URL

Client ID (optional)

Needed for the test sign-in.

Groups claim (optional)

Client type

Public, PKCE only Confidential, has a client secret

Never paste the secret here. The check only needs to know whether one exists.

Server address (optional)

The address your users open. Adds a reachability check and a test sign-in.

Paste the discovery document instead

Discovery document JSON

For providers that block other sites from reading it.

Check issuer