QueryProxy, discovery belgesi yayımlayan her OpenID Connect (OIDC) sağlayıcısı üzerinden kullanıcı girişi yapabilir ve takım rollerini sağlayıcının bildirdiği gruplardan belirleyebilir. Bu sayfa ayarları, her sağlayıcı için bir örneği, rol eşlemesini ve parola girişini kapatmadan önce bilmeniz gereken davranışları anlatır.

Çok adımlı doğrulama (MFA) sağlayıcının işidir. SSO ile giren bir kullanıcı QUERYPROXY_REQUIRE_2FA kapsamının dışındadır: QueryProxy ondan ikinci bir faktör istemez ve sağlayıcının hangisini kullandığını denetleyemez. MFA’yı kimlik sağlayıcıda, QueryProxy için kaydettiğiniz uygulamada zorunlu kılın.

Nasıl çalışır

QueryProxy, PKCE’li authorization code akışını kullanır. state ve nonce değerlerini denetler, ID token imzasını sağlayıcının yayımladığı anahtarlara karşı doğrular. SAML desteklenmez.

QUERYPROXY_OIDC_ISSUER ve QUERYPROXY_OIDC_CLIENT_ID birlikte ayarlanınca giriş sayfasında Log in with SSO düğmesi görünür.
Kullanıcı sağlayıcıda oturum açar ve {APP_URL}/auth/oidc/callback adresine döner.
QueryProxy kullanıcıyı bulur ya da oluşturur, rol eşlemesini uygular ve oturum açar.

Kullanıcı, e-posta adresiyle değil, issuer ve subject (sub) çiftiyle tanınır.

QueryProxy’yi sağlayıcıya kaydedin

Gizli (confidential) bir OIDC istemcisi (“web uygulaması”) oluşturun ve tek bir redirect URI kaydedin:

https://queryproxy.example.com/auth/oidc/callback

Bu adres APP_URL artı /auth/oidc/callback’tir ve birebir eşleşmelidir. APP_URL’yi kullanıcıların yazdığı adrese, yani ters vekilinizin arkasındaki HTTPS adresine ayarlayın.

Ayrıca bir post-logout redirect URI kaydedin: APP_URL artı /login, örneğin https://queryproxy.example.com/login. QueryProxy, çıkışta sağlayıcının oturumunu sonlandırırken bunu gönderir (bkz. Çıkış yapma). Kayıtlı değilse sağlayıcı kullanıcıyı geri göndermek yerine bir hata sayfası gösterebilir.

Sonra istemciyi QueryProxy tarafında tanımlayın:

QUERYPROXY_OIDC_ISSUER=https://idp.example.com/realms/queryproxy
QUERYPROXY_OIDC_CLIENT_ID=queryproxy
QUERYPROXY_OIDC_CLIENT_SECRET=...        # ya da QUERYPROXY_OIDC_CLIENT_SECRET_FILE=/run/secrets/oidc

QUERYPROXY_OIDC_ISSUER, sonuna /.well-known/openid-configuration eklenince sağlayıcıyı tarif eden belgeye ulaşılan temel URL’dir. Değiştirdikten sonra konteynerleri yeniden başlatın.

Değişken	Varsayılan	Anlamı
`QUERYPROXY_OIDC_ISSUER`	yok	Issuer URL’si. Bu ve istemci kimliği birlikte ayarlanınca SSO açılır
`QUERYPROXY_OIDC_CLIENT_ID`	yok	Sağlayıcıda kayıtlı istemci kimliği
`QUERYPROXY_OIDC_CLIENT_SECRET`	yok	İstemci secret’ı. `QUERYPROXY_OIDC_CLIENT_SECRET_FILE` onu dosyadan okur
`QUERYPROXY_OIDC_SCOPES`	`openid email profile`	Sağlayıcıdan istenen kapsamlar, boşlukla ayrılmış. Bazı sağlayıcılar `groups` eklenmesini ister
`QUERYPROXY_OIDC_GROUP_CLAIM`	`groups`	Kullanıcının gruplarını listeleyen claim. Tam bu adda claim yoksa `realm_access.roles` gibi noktalı yol izlenir
`QUERYPROXY_OIDC_ROLE_MAP`	yok	Virgülle ayrılmış `grup:takım:rol` girdileri; bkz. Rol eşlemesi
`QUERYPROXY_LOCAL_LOGIN`	`all`	Parolayla kimin girebileceği: `all`, `admins_only` ya da `none`

ID token’ın taşıması gerekenler

sub, her zaman.
email, bir sağlayıcı kimliği ilk kez girdiğinde geçerli bir adres. Olmazsa QueryProxy hesabı ne bağlayabilir ne oluşturabilir; giriş reddedilir. Zaten tanıdığı bir kimlik (aynı issuer ve sub) onsuz da girer.
Daha önce görmediği her hesap için doğrulanmış e-posta (aşağıya bakın): email_verified değeri true. Microsoft’un ID token claim referansı bu claim’i Entra ID için listelemez; onun için email_verified yoksa ve xms_edov değeri true ise adres doğrulanmış sayılır. Açıkça false gelen email_verified reddedilir. İki claim de adresin doğrulandığını söylemiyorsa adres doğrulanmamış sayılır.
Görünen ad için name ya da preferred_username. İkisi de yoksa adresin @ öncesi kullanılır.

İlk giriş, bağlama ve doğrulanmış e-posta

İlk girişte yeni kullanıcı oluşturulur (just-in-time provisioning); ama yalnızca sağlayıcı adresin doğrulandığını söylüyorsa (email_verified true; Entra ID için xms_edov true). Yeni kullanıcının parolası ve takımı yoktur; rol eşlemesi ya da bir yönetici ona takım verene kadar böyle kalır. Bu yolla kimse sistem yöneticisi olmaz.
Aynı e-posta adresine sahip mevcut bir yerel hesap sağlayıcıya bağlanır; bu da yalnızca adres aynı biçimde doğrulanmışsa olur. Bağlama user.sso_linked olarak denetlenir. Bağlandıktan sonra hesap, siz QUERYPROXY_LOCAL_LOGIN ile parola girişini kısıtlamadıkça parolasını korur.
Adres doğrulanmamışsa giriş reddedilir ve ret auth.sso_refused olarak denetlenir.
Başka bir sağlayıcı subject’ine zaten bağlı yerel hesap da reddedilir; çünkü e-posta eşleşmesi tek başına bir şey kanıtlamaz. Bu ret denetim günlüğüne değil, uygulama günlüğüne yazılır.
Askıya alınmış ve silinmiş kullanıcılar SSO ile de giremez.

Kullanıcının beyan ettiği adresi doğrulamayan bir sağlayıcı bağlamayın. Doğrulanmamış adresleri doğrulanmış gösteren bir sağlayıcı, aynı e-postaya sahip bir yerel hesabı ele geçirebilir.

QUERYPROXY_OIDC_ISSUER’ı sonradan değiştirmek mevcut SSO hesaplarını taşımaz: bunlar eski issuer’a bağlıdır ve e-postayla eşleştirilmek yerine reddedilir.

SSO’nun yazdığı denetim olayları: auth.sso_login, auth.sso_refused, user.sso_provisioned, user.sso_linked ve user.role_synced.

Rol eşlemesi

QUERYPROXY_OIDC_ROLE_MAP, sağlayıcı gruplarını her girişte takım rollerine çevirir. Her girdi grup:takım:rol biçimindedir; girdiler virgülle ayrılır:

QUERYPROXY_OIDC_ROLE_MAP=platform-dba:payments:dba,platform-dev:payments:developer,security:payments:auditor

grup, grup claim’indeki değerlerle birebir, büyük/küçük harfe duyarlı bir dize olarak karşılaştırılır. Girdi sağdan bölünür; bu yüzden grup adı iki nokta içerebilir.
takım, var olan bir takımın slug’ı ya da adıdır. Var olmayan bir takımı gösteren girdi atlanır ve günlüğe yazılır.
rol dba, developer ya da auditor’dır. Sistem yöneticisi bayrağı bir gruptan verilemez.
Aynı takıma birden çok grup ulaşırsa en yüksek rol kazanır (dba, sonra developer, sonra auditor).

QueryProxy her girişte kullanıcının eşlemenin adını andığı takımlardaki üyeliklerini gruplarla aynı hâle getirir: ekler, değiştirir ve kaldırır; her değişikliği user.role_synced olarak denetim günlüğüne yazar. Eşlemenin anmadığı takımlardaki üyeliklere dokunulmaz. Böylece o takımlar için doğruluk kaynağı sağlayıcı olur: orada elle değiştirdiğiniz rol, kullanıcının bir sonraki girişinde ezilir.

Bilmeniz gerekenler:

Değişiklikler bir sonraki girişte uygulanır. QueryProxy sağlayıcıyı yoklamaz. Birinin erişimini hemen kesmek için Users ekranında askıya alın: bu, açık oturumlarını sonlandırır.
Grup claim’inin olmaması girişi reddettirir. Rol eşlemesi ayarlıyken grup claim’i olmayan bir ID token reddedilir, günlüğe yazılır ve hiçbir şey değiştirilmez. Boş bir grup listesi geçerli bir yanıttır ve olduğu gibi uygulanır: kullanıcı eşlenen takımlardaki rollerini kaybeder.
Microsoft Entra ID group overage desteklenmez. Kullanıcı çok fazla gruba üyeyse Entra ID groups claim’ini koymaz ve Microsoft Graph’a yönlendirir; QueryProxy bu yönlendirmeyi izlemez, bu yüzden rol eşlemesi ayarlıyken bu kullanıcılar reddedilir. Sınırın altında kalma yolları için Entra ID örneğine bakın.
ID token grup claim’ini taşımıyorsa ya da e-postanın doğrulanıp doğrulanmadığı hakkında bir şey söylemiyorsa (ne email_verified ne xms_edov), QueryProxy eksik claim’ler için sağlayıcının userinfo uç noktasını da okur.
Rol eşlemesi isteğe bağlıdır. Eşleme olmadan SSO ile giren kullanıcılar bir yönetici ekleyene kadar takımsız kalır.

Sağlayıcı örnekleri

Projenin uçtan uca test ettiği tek sağlayıcı Keycloak’tur (CI iş akışı bir Keycloak 26.8.1 konteyneri üzerinden oturum açar ve grup eşlemesini denetler). Diğer üçü sağlayıcının belgelerini izler; devreye almadan önce bir test kullanıcısıyla deneyin.

Keycloak

Realm’inizde standart (authorization code) akışı kullanan ve istemci secret’ı olan bir OpenID Connect istemcisi oluşturun. Geçerli redirect URI’yi yukarıdaki gibi verin.
İstemcinin özel kapsamına, token claim adı groups olan bir Group Membership mapper’ı ekleyin ve Add to ID token açık kalsın.
Full group path için karar verin. Açıkken grup adları /engineering/backend gibi yollardır ve rol eşlemesi tam o metni kullanmalıdır. Kapatırsanız düz adlar gelir.
Ayarlar:

QUERYPROXY_OIDC_ISSUER=https://keycloak.example.com/realms/queryproxy
QUERYPROXY_OIDC_CLIENT_ID=queryproxy
QUERYPROXY_OIDC_CLIENT_SECRET=...
QUERYPROXY_OIDC_ROLE_MAP=dba-team:payments:dba,developers:payments:developer

Yalnızca adresi Keycloak’un doğrulanmış (email_verified) bildirdiği kullanıcılar oluşturulabilir ya da bağlanabilir. Kaynak: Keycloak server administration guide.

Microsoft Entra ID

App registrations altında yukarıdaki redirect URI ile bir web uygulaması kaydedin ve bir istemci secret’ı oluşturun.
Kiracınızın v2.0 issuer’ını kullanın: https://login.microsoftonline.com/<tenant-id>/v2.0.
Token configuration altında bir groups claim ekleyin. Entra ID varsayılan olarak claim’e grup nesne kimliklerini (object ID) koyar; rol eşlemesi girdileri bu kimlikleri kullanır (0760b6cf-170e-4a14-91b3-4b78e0739963:payments:dba).
Token başına 200 grup sınırının altında kalmak için tüm gruplar yerine Groups assigned to the application seçeneğini seçin; sınırı aşan kullanıcılara groups claim’i verilmez ve rol eşlemesi ayarlıyken reddedilirler.
QueryProxy’nin e-postayı doğrulamak için kullandığı claim’leri ekleyin. Token configuration altında Add optional claim’i seçin, ID token türünü seçin, xms_edov’u ve token zaten bir e-posta adresi taşımıyorsa email’i işaretleyip Add’e basın. (xms_edov yalnızca email claim’i varken döner. QueryProxy varsayılan olarak email kapsamını ister; v2.0 uç noktasında bu kapsam da email claim’ini verir.) Portal xms_edov’u listelemiyorsa onu uygulamanın Manifest bölümünde optionalClaims.idToken altına ekleyin; Microsoft manifesti isteğe bağlı claim yapılandırmanın diğer yolu olarak belgeler.

QUERYPROXY_OIDC_ISSUER=https://login.microsoftonline.com/<tenant-id>/v2.0
QUERYPROXY_OIDC_CLIENT_ID=<application-client-id>
QUERYPROXY_OIDC_CLIENT_SECRET=...
QUERYPROXY_OIDC_ROLE_MAP=<group-object-id>:payments:dba

xms_edov olmadan ilk giriş reddedilir. Microsoft’un ID token claim referansı Entra ID için bir email_verified claim’i listelemez. xms_edov’u ID token’a eklemezseniz QueryProxy adresin doğrulandığını anlayamaz; hesabı ne oluşturur ne bağlar: giriş reddedilir ve ret auth.sso_refused olarak denetlenir. xms_edov yalnızca kiracı adresin alan adını doğrulamışsa true olur; Microsoft, Facebook ve SAML/WS-Fed hesaplarının doğrulanmış alan adı olmadığını belirtir, bu yüzden bu kullanıcılar da reddedilir.

Kaynaklar: Configure optional claims, Optional claims reference (xms_edov, email), Group claims in tokens.

Okta

Bir OIDC web uygulaması oluşturun ve redirect URI’yi kaydedin.
ID token’a bir groups claim ekleyin: uygulamanın Sign On sekmesinde OpenID Connect ID Token bölümünü düzenleyin ve claim adı groups olan, eşlediğiniz grupları döndüren bir filtreyle Group claim type ayarlayın. Özel bir authorization server’da bunun yerine ID token’a Groups değer türünde bir claim ekleyin.
Org authorization server ile groups kapsamını isteyin:

QUERYPROXY_OIDC_ISSUER=https://example.okta.com
QUERYPROXY_OIDC_CLIENT_ID=<client-id>
QUERYPROXY_OIDC_CLIENT_SECRET=...
QUERYPROXY_OIDC_SCOPES="openid email profile groups"
QUERYPROXY_OIDC_ROLE_MAP=Platform DBA:payments:dba

Özel bir authorization server’da issuer onun URL’sidir, örneğin https://example.okta.com/oauth2/default; orada gruplar eklediğiniz claim’den gelir ve groups, QUERYPROXY_OIDC_SCOPES içinde yalnızca o claim’i bir groups kapsamına bağladıysanız gerekir. Kaynak: Customize tokens with a groups claim.

Google

Google Cloud konsolunda Web application türünde bir OAuth istemcisi oluşturun ve redirect URI’yi ekleyin. Google’ın issuer’ı https://accounts.google.com’dur ve email kapsamı istendiğinde ID token’ı email_verified taşır. Google’ın OpenID Connect belgeleri bir groups claim’i anlatmaz; bu yüzden Google’ı yalnızca giriş için kullanın, QUERYPROXY_OIDC_ROLE_MAP’i boş bırakın ve takımları kullanıcılara elle verin.

QUERYPROXY_OIDC_ISSUER=https://accounts.google.com
QUERYPROXY_OIDC_CLIENT_ID=<client-id>.apps.googleusercontent.com
QUERYPROXY_OIDC_CLIENT_SECRET=...

Kaynak: OpenID Connect | Google Identity.

Çıkış yapma

SSO ile girmiş bir kullanıcı QueryProxy’den çıkınca QueryProxy kimlik sağlayıcıdaki oturumu da sonlandırır (RP-initiated logout); kullanıcı orada da çıkmış olur. Tarayıcıyı sağlayıcının end_session_endpoint adresine, kullanıcının ID token’ı id_token_hint, client_id ve post-logout redirect URI’si {APP_URL}/login ile yönlendirir.

Sağlayıcı discovery belgesinde bir end_session_endpoint yayımlamalıdır. Yoksa ya da discovery belgesi okunamıyorsa çıkış yalnızca QueryProxy oturumunu sonlandırır ve giriş sayfasına döner.
Parolayla açılmış oturum ve yerel kullanıcı sağlayıcıya asla yönlendirilmez.
ID token yalnızca bu amaçla sunucu tarafındaki oturumda tutulur. Günlüğe ya da denetim günlüğüne yazılmaz.
Çıkış, eskiden olduğu gibi CSRF token’lı bir POST’tur.

SSO’nun yanında parola girişi

QUERYPROXY_LOCAL_LOGIN, parolayı hâlâ kimin kullanabileceğini sınırlar:

Değer	Anlamı
`all`	Varsayılan. Parolası olan herkes kullanabilir
`admins_only`	Yalnızca sistem yöneticileri parolayla girer (break-glass erişimi); diğer herkes SSO kullanır
`none`	Parola girişi ve parola sıfırlama kapalıdır

Bilinmeyen bir değer admins_only sayılır. none’ı ayarlamadan önce SSO’nun, onu kullanabilen bir yönetici hesabıyla çalıştığından emin olun: geri girmek için değişkeni değiştirip yeniden başlatmanız gerekir.

Yalnızca SSO üzerinden var olan hesapların yerel parolası yoktur. Sağlayıcıya bağlı bir kullanıcı sıfırlama bağlantısıyla parola almaz ve yöneticinin Reset password işlemi, QUERYPROXY_LOCAL_LOGIN ne derse desin onu reddeder. Profil sayfasındaki parola formu yerel parolası olmayan kullanıcılarda gizlenir. SCIM’in açtığı hesaplar SSO hesabı sayılır. QUERYPROXY_REQUIRE_2FA, sağlayıcıya bağlanmış ve parolasıyla giren yerel hesap için geçerli olmaya devam eder.

Sağlayıcıya bağlı ve daha önce yerel parolası olan bir kullanıcı, QUERYPROXY_LOCAL_LOGIN all olduğu sürece o parolayla girmeye devam edebilir ve profil sayfasından değiştirebilir. Sağlayıcıyı herkes için tek giriş yolu yapmak için QUERYPROXY_LOCAL_LOGIN=admins_only ya da none ayarlayın.

Sınırlar

Sağlayıcıda çıkış bir end_session_endpoint ister. Bunu yayımlamayan bir sağlayıcı kullanıcıyı orada açık bırakır; bkz. Çıkış yapma.
Kurulum başına tek sağlayıcı. SAML desteklenmez. Girişler arasında erişimi kaldırmak SCIM ile kullanıcı sağlamanın işidir.
Parolası olmayan bir SSO kullanıcısı için kişisel erişim token’ı oluşturmak, son 15 dakika içinde SSO ile girmiş olmayı ister; bkz. REST API ve token’lar.

Sonraki adımlar

Kullanıcıları sağlayıcıdan oluşturmak ve askıya almak için SCIM ile kullanıcı sağlama.
Değişkenlerin bağlamı için Yapılandırma.
Kontrol listesinin kalanı için Üretim güvenliği.
Her takım rolünün neye izin verdiği için Onay akışı.