Superset'e şirket hesabıyla giriş: LDAP mi, OAuth mu?

Kullanıcılar şirket dizininde (Active Directory ya da başka bir LDAP sunucusu) duruyorsa Superset'te AUTH_TYPE = AUTH_LDAP ile parolayı doğrudan dizine sorabilirsiniz. Keycloak, Okta gibi bir kimlik sağlayıcınız varsa AUTH_OAUTH daha doğal yoldur. Her iki yolda da asıl iş girişin kendisi değil, grubun hangi role dönüşeceği ve bu rolün her girişte yeniden yazılıp yazılmayacağıdır. Aşağıdaki ayar adları Superset ve Flask-AppBuilder belgelerinden alındı; örnekler belgedeki ayar adlarıyla kurulmuş örneklerdir, kendi dizininize uyarlanması gerekir.

ASF sürüm kataloğu Superset 6.1.0'ı (13 Mayıs 2026) "Released" gösteriyor. Aşağıdaki ayar anlatımı Superset 6.0.0 belge kaynağına ve Flask-AppBuilder'ın (FAB, Superset'in kullandığı giriş altyapısı) güncel belgesine dayanır.

Dört giriş yönteminden hangisi sizin kurulumunuza uyar

Superset giriş işini FAB'a bırakır. Superset'in config.py dosyasındaki yoruma göre AUTH_TYPE için AUTH_DB, AUTH_LDAP ve AUTH_REMOTE_USER seçenekleri var; OAuth için yapılandırma belgesi AUTH_OAUTH örneği veriyor.

Tablodaki "ne zaman" sütunu bir yargıdır, belge cümlesi değildir. Kural olarak: kimlik sağlayıcı varsa OAuth, yoksa ve dizin varsa LDAP, hiçbiri yoksa AUTH_DB. Bir Superset örneğinde aynı anda tek AUTH_TYPE değeri tanımlanır.

Active Directory'ye LDAP ile bağlanan ayar dosyası

Önce paket: Superset belgesine göre LDAP için python-ldap paketi kurulu olmalı. Ardından superset_config.py içine, FAB belgesindeki ayar adlarıyla şu iskelet yazılır. Sunucu adı, DN'ler ve grup adları örnektir.

import os
from flask_appbuilder.security.manager import AUTH_LDAP

AUTH_TYPE = AUTH_LDAP
AUTH_LDAP_SERVER = "ldaps://dc1.sirket.local:636"
AUTH_LDAP_USE_TLS = False

AUTH_LDAP_BIND_USER = "CN=svc-superset,OU=Servis,DC=sirket,DC=local"
AUTH_LDAP_BIND_PASSWORD = os.environ["LDAP_BIND_PASSWORD"]
AUTH_LDAP_SEARCH = "DC=sirket,DC=local"
AUTH_LDAP_UID_FIELD = "sAMAccountName"
AUTH_LDAP_GROUP_FIELD = "memberOf"

AUTH_LDAP_FIRSTNAME_FIELD = "givenName"
AUTH_LDAP_LASTNAME_FIELD = "sn"
AUTH_LDAP_EMAIL_FIELD = "mail"

AUTH_USER_REGISTRATION = True
AUTH_USER_REGISTRATION_ROLE = "Public"

Satır satır neden böyle:

• ldaps:// adresi ve AUTH_LDAP_USE_TLS = False — birlikte kullanılır: FAB belgesi LDAPS için ldaps:// adresini AUTH_LDAP_USE_TLS = False ile, STARTTLS için ldap:// adresini AUTH_LDAP_USE_TLS = True ile eşleştiriyor. İkisini birden açmayın. Sertifika zincirini tanıtan ayarların adları bu yazıda yok; FAB belgesi bunları "Additional LDAP/TLS Options" diye ayrı bir bölüme bırakıyor.
• AUTH_LDAP_BIND_USER ve AUTH_LDAP_BIND_PASSWORD — arama için ayrı kullanıcı: FAB, arama için ayrı bir bağlanma kullanıcısı tanımlamaya izin veriyor. Parolayı dosyaya yazmak yerine ortam değişkeninden okumak sizin tercihinizdir; belge bunu şart koşmaz.
• AUTH_LDAP_UID_FIELD = "sAMAccountName" — Active Directory'de oturum adı alanı: FAB belgesi bu alanı "LDAP'taki kullanıcı adı alanı" olarak tarif eder ve tipik değerini uid verir. Active Directory'de oturum adı genelde sAMAccountName alanındadır; Superset GitHub kaydındaki bir AD yapılandırması da bunu kullanıyor.
• AUTH_LDAP_GROUP_FIELD = "memberOf" — açıkça yazmak yarar: FAB belgesine göre varsayılan zaten memberOf. Yine de açıkça yazmak anlamlı: bir Debian 12 + AD kurulumunda "Invalid login" hatası bu satır eklenince gitmiş (çözüm 29 Eylül 2025 tarihli yorumda paylaşılmış). Tek bir kullanıcı raporudur, her kurulum için garanti değildir.
• AUTH_USER_REGISTRATION = True — ilk girişte kullanıcıyı oluşturur: FAB belgesinin LDAP örneğinde bu satır AUTH_USER_REGISTRATION = True # allow users who are not already in the FAB DB yorumuyla geçer, yani dizinde olup Superset veritabanında henüz kaydı olmayan kullanıcıya izin verir. Superset'in UPDATING.md dosyasındaki "Next" başlığı altında ilgili bir not var: /register/ kayıt sayfası yalnızca kendi kendine kayıt destekleyen kimlik doğrulama türlerinde (AUTH_DB ve AUTH_OAUTH) ve AUTH_USER_REGISTRATION açıkken sunuluyor; LDAP, SAML ve AUTH_REMOTE_USER kurulumlarında gösterilmiyor. Aynı not bu kurulumların ilk girişte kullanıcı oluşturulması için AUTH_USER_REGISTRATION = True yazması gerektiğini söylüyor ve "First-login provisioning is unchanged" diyor; ilk girişte kullanıcı oluşturma değişmedi, satır örnekteki gibi kalıyor.

Grup rolü nasıl belirler: eşleme ve her girişte eşitleme

Kullanıcı girdikten sonra hangi panolara erişeceğini roller belirler. Superset belgesindeki örnek biçimine uyarlanmış LDAP eşlemesi:

AUTH_ROLES_MAPPING = {
    "CN=superset_users,OU=Gruplar,DC=sirket,DC=local": ["Gamma", "Alpha"],
    "CN=superset_admins,OU=Gruplar,DC=sirket,DC=local": ["Admin"],
}

AUTH_ROLES_SYNC_AT_LOGIN = True

Üç ayrıntı hata çıkarır:

1. AUTH_LDAP_SEARCH — tanımlı olmak zorunda. Superset belgesi LDAP grup eşlemesi için bunu şart koşuyor; yukarıdaki örnekte tanımlı.
2. Anahtar, grubun tam DN'idir. OAuth'ta anahtar sağlayıcının grup adıdır ("superset_users" gibi), LDAP'ta DN. FAB belgesi, eşlemedeki DN'ler için şunu söylüyor: LDAP harfe duyarsızdır, FAB duyarlıdır, bu yüzden harfler eşleşmelidir.
3. AUTH_ROLES_SYNC_AT_LOGIN = True iken roller her girişte yeniden yazılır. FAB belgesi bu ayarı "kullanıcının TÜM rollerini her girişte değiştir, ya da yalnız kayıtta" diye tarif ediyor; False ise roller yalnızca ilk kayıtta eşitlenir. Pratik sonuç: Superset arayüzünden bir kullanıcıya elle verdiğiniz rol, o kişi bir sonraki girişinde eşlemede yoksa silinir. Wikimedia'nın Superset kaydında aynı sınır şöyle yazılmış: eşitleme açık olduğu için roller OIDC eşlemesi dışında verilemiyor. Aynı kayıtta, yönetici hakkını programla vermek için superset-admins adlı ayrı bir LDAP grubu istenmiş.

İlk bloktaki AUTH_USER_REGISTRATION_ROLE = "Public" satırı için FAB belgesinin cümlesi şu: bu rol AUTH_ROLES_MAPPING'e ek olarak verilir. Yani eşlemeden gelen rollerin yanına kayıtlı her kullanıcıya Public de eklenir. Public rolünün hangi izinleri taşıdığı kurulumunuza bağlıdır; örnekteki değer config.py içindeki yorum satırından geliyor. Satırı hiç yazmazsanız ne olacağını incelenen belgeler söylemiyor; satırı çıkarmadan önce rolün izinlerini Superset'in rol ekranından kontrol edin.

Karar: elle rol vermeye devam edecekseniz AUTH_ROLES_SYNC_AT_LOGIN = False yapın, roller yalnız kayıtta yazılır. Rolleri dizinden yönetecekseniz True bırakın ve her yetkiyi bir gruba bağlayın. İkisini karıştırırsanız elle verilen rol bir sonraki girişte düşer.

OAuth sağlayıcısıyla giriş: dönüş adresi ve rol eşlemesi

OAuth tarafı için Superset belgesinde tam bir OAUTH_PROVIDERS örneği var. Ana şekli AUTH_TYPE = AUTH_OAUTH, bir OAUTH_PROVIDERS listesi (sağlayıcı adı, client_id, client_secret, access_token_url, authorize_url gibi alanlar) ve AUTH_USER_REGISTRATION ile AUTH_USER_REGISTRATION_ROLE'dür. Alanların tamamı için Superset yapılandırma belgesindeki örneğe bakın; sağlayıcıya göre değişir.

Sağlayıcı tarafında tanımlayacağınız dönüş adresi belgeye göre şu biçimdedir:

https://<superset-webserver>/oauth-authorized/<provider-name>

Belgedeki örnekte sağlayıcı adı OAUTH_PROVIDERS içindeki name alanında egaSSO olarak geçiyor; aynı belge bu yapılandırma için dönüş adresini https://<superset-webserver>/oauth-authorized/egaSSO diye veriyor, yani adresteki <provider-name> kısmı sağlayıcının adıdır. Open edX kaydındaki adres de (…/oauth-authorized/openedxsso) aynı biçimde sağlayıcı adıyla bitiyor. Grup eşlemesi için aynı AUTH_ROLES_MAPPING kullanılır, anahtar olarak sağlayıcının gönderdiği grup adı yazılır.

Vekil arkasında dönüş adresi yanlış çıkıyorsa

Superset bir yük dengeleyici ya da ters vekilin arkasındaysa kendi dış adresini başlıklardan öğrenir. Belge: yük dengeleyici X-Forwarded-For ve X-Forwarded-Proto başlıklarını ekliyorsa ENABLE_PROXY_FIX = True yazılmalı. config.py dosyasında varsayılan False; ayarlar şöyle:

ENABLE_PROXY_FIX = True
PROXY_FIX_CONFIG = {"x_for": 1, "x_proto": 1, "x_host": 1, "x_port": 1, "x_prefix": 1}

Dosyadaki yorum: farklı bir porta vekillik ediliyorsa aşağı akışta sorun çıkmaması için x_port değeri 0 yapılmalı.

Belirti: sağlayıcı "geçersiz istek / yönlendirme adresi uyuşmuyor" diyor. Open edX forumunda 2025'te bildirilen bir olayda tanımlı adres https://…/oauth-authorized/openedxsso iken Superset'in ürettiği istek http://…:443/oauth-authorized/openedxsso çıkmış. Kullanıcı 8 Eylül 2025'te Tutor yapılandırmasına SUPERSET_ENABLE_PROXY_FIX: false ekleyerek geçici çözüm bulmuş. Foruma yanıt veren kişi, yapılandırmanın SUPERSET_ENABLE_PROXY_FIX değişkeninin değerine değil yalnız varlığına bakıyor gibi göründüğünü yazmış ("I think you are correct"). Bu Tutor'a özgü bir bulgudur, sizin kurulumunuz için geçerli olmayabilir. Genel ders şu: sağlayıcının hata sayfasında gördüğünüz dönüş adresini, kayıtlı adresle harf harf karşılaştırın; şema (http/https) ya da port farkı vekil ayarına işaret eder.

Giriş ekranında görülen belirtiler ve kaynaklı nedenleri

Tablo yalnızca belgede ya da kamuya açık bir kayıtta karşılığı bulunan durumları içerir.

Bağlanma kullanıcısı reddi ve sertifika hataları için güvenilir bir kaynak bulunmadığından tabloya alınmadı.

Gruplara hangi yetkiyi vereceğinize kim karar verecek

AUTH_ROLES_MAPPING sözlüğünü yazmadan önce hangi grubun hangi panoyu göreceğine birinin karar vermesi gerekir. Erişim denetiminin genel çerçevesi için veri güvenliği rehberine, karar sorumluluğu için veri yönetişimi rehberine bakabilirsiniz; aracın kendisi için Superset teknoloji sayfası var. Dizin, vekil ve rol modelini kurumsal bir kurulumda birlikte kurmak isterseniz Apache Superset danışmanlık sayfası hizmeti anlatıyor. BIAnalytics ürün sayfasında "LDAP Authentication & RBAC" başlığı altında "Active Directory entegrasyonu ile merkezi kullanıcı yönetimi" yazıyor: BIAnalytics.

Canlıya almadan önce kontrol listesi

• AUTH_TYPE tek bir yönteme ayarlı mı? AUTH_ROLES_SYNC_AT_LOGIN = True kullanacaksanız, yöntemi değiştirmeden önce dizinde superset_admins benzeri bir yönetici grubu açıp Admin rolüne eşleyin; yoksa eşitleme açıkken arayüzden verdiğiniz yönetici rolü sonraki girişte silinebilir.
• AUTH_LDAP_SEARCH dolu mu, eşlemedeki DN'ler dizindeki yazımla birebir mi?
• Eşitleme açıksa elle verilmiş rolleri bir gruba taşıyın.
• Ters vekil varsa sağlayıcıda kayıtlı dönüş adresiyle gerçek istekteki adresi karşılaştırın.
• Bağlanma kullanıcısının parolasını yapılandırma dosyasına düz yazmayın.