Keycloak, kullanıcı rolleri ve kurumsal OIDC

Lunex kullanıcı girişini Keycloak üzerinden OpenID Connect (OIDC) ile gerçekleştirir. Kullanıcı adı/parola, MFA, oturum ve hesap yaşam döngüsü kimlik servisinde yönetilir. Lunex’in ayrı bir yerel kullanıcı/parola deposu yoktur.

Kurulumla gelen Keycloak’u veya kurumunuzun yönettiği bir Keycloak’u kullanabilirsiniz. Başka bir OIDC sağlayıcınız varsa onu Keycloak’a kimlik sağlayıcısı olarak bağlayın. Mevcut Lunex giriş yapılandırması, herhangi bir OIDC issuer adresini doğrudan girerek Keycloak’u değiştiren genel bir sağlayıcı ekranı sunmaz.

Üç farklı kimlik doğrulama ihtiyacı

Lunex’e giriş yapmış olmak yayımlanan her API’ye otomatik yetki vermez. Platform rolleri de API tüketicisinin iş yetkilerinin yerine geçmez. API güvenliği ve bağlantılar ayrı yapılandırılır.

Kullanıcı ekleme ve rol atama

Ön koşul: ilgili Keycloak realm’inde kullanıcı/rol yönetme yetkisi. Platformdaki platform-admin rolü, Keycloak’un yönetim yetkileriyle aynı rol değildir.

1. Kimlik yöneticinizin sağladığı Keycloak yönetim adresini açın; kurulumun Lunex realm’ini seçin. Varsayılan adı lunex’tir.
2. Users altında kullanıcı oluşturun veya mevcut hesabı açın. Kullanıcı adını ve e-posta alanını doldurun.
3. Yerel Keycloak hesabı kullanılıyorsa kuruluş politikanıza göre ilk parola veya gerekli hesap işlemlerini tanımlayın. Kurumsal sağlayıcıdan gelen kullanıcı için parolayı o sağlayıcı yönetir.
4. Kullanıcının Role mapping bölümünde gerekli realm rollerini atayın.
5. Kullanıcıdan yeniden oturum açmasını isteyin; rol değişikliğinin yeni access token’a geldiğini doğrulayın.

Roller kurulum genelindedir. Yalnızca platform-admin atamak proje yazma ve build yetkisi vermez. Rol adları büyük/küçük harfe ve tirelere duyarlıdır.

Git commit’i için e-posta zorunludur. Sadece kimlik sağlayıcısında e-posta bulunması yetmez; frontend access token’ına email claim’i olarak aktarılmalıdır. Kullanıcı adı preferred_username, roller realm_access.roles alanından okunur. Ad/soyad görüntüsü için given_name ve family_name kullanılabilir.

Hesap ve oturum yönetimi

Kullanıcı hesabı işlemleri için Keycloak’un hesap konsolu kullanılır; varsayılan yol https://login.example.com/realms/lunex/account/ biçimindedir. Lunex’te Account → Log out oturumu kapatır ve uygulama adresine döner. Parola değiştirme, MFA ve mevcut oturumları sonlandırma işlemlerini kimlik servisi politikanıza göre yönetin.

Parola kurtarma e-postası için kimlik servisinin SMTP ayarı gerekir. SMTP ayarlanmamış kurulumda kullanıcıya çalışmayan bir e-posta akışı önermeyin; kimlik yöneticisi yerel hesabın parolasını yönetim konsolundan sıfırlayabilir.

Kurulum sırasında verilen ilk yönetici parolaları güncel parola kayıtları değildir. Keycloak’ta değiştirilen insan parolasını kurulum dosyasına geri yazmanız gerekmez. Kurulum yükseltmesi için kullanılan makine hesabı ayrı tutulur.

Mevcut Keycloak’unuzu bağlama

Örnekte Lunex https://lunex.example.com, Keycloak https://login.example.com, realm lunex adreslerini kullanır. Kendi alan adlarınızı ve erişim modelinizi yerleştirin.

1. Realm ve platform rollerini hazırlayın

İlgili realm’de platform-admin, platform-developer, platform-user rollerini oluşturun. Kullanıcıların yetkilerini yukarıdaki tabloya göre atayın. Kurumsal grup adlarının bu realm rollerine otomatik eşlendiğini varsaymayın.

2. Tarayıcı istemcisini hazırlayın

frontend kimliğiyle OpenID Connect istemcisi oluşturun ve şu sözleşmeyi sağlayın:

Adresleri yalnızca gerçek uygulama origin’iyle sınırlayın; Web origins için yol veya sonuna /* eklemeyin. Tarayıcı istemcisinde client secret bulunmaz. Public client ve redirect/origin ilişkisinin ayrıntıları Keycloak istemci rehberinde açıklanır.

İstemciye lunex-api-audience adlı Audience mapper ekleyin: included client audience backend, access token claim açık, ID token claim kapalı. Bu sayede frontend access token’ı Lunex uygulama API’si için backend audience’ını taşır.

3. Uygulama API’si istemcisini hazırlayın

backend kimlikli OpenID Connect istemcisi, tarayıcı login akışı başlatmayan bearer-token alıcısıdır. Native realm tanımındaki karşılığı bearerOnly: true, publicClient: false, standardFlowEnabled: false, directAccessGrantsEnabled: false şeklindedir.

Lunex token’ın issuer ve audience bilgisini doğrular. Varsayılan audience backend’dir. İstemci adlarını değiştirirseniz chart değerlerini, audience mapper’ını ve token içeriğini birlikte güncelleyin.

4. Helm bağlantı ayarlarını verin

lunex:
  publicUrl: https://lunex.example.com
keycloak:
  enabled: false
  realm: lunex
  frontendClientId: frontend
  backendClientId: backend
  external:
    url: https://login.example.com
    internalUrl: https://keycloak.internal.example.com

external.url tarayıcının eriştiği Keycloak kök adresidir; sonuna /realms/lunex eklemeyin. internalUrl yalnızca Kubernetes içinden kullanılan adres farklıysa gerekir. Kurulum uygulama discovery adresini iç adresten, token issuer beklentisini public adresten üretir. İki adres aynı realm ve anahtarları sunmalıdır.

Temel ortam karşılıkları şöyledir:

LUNEX_KEYCLOAK_URL=https://login.example.com
LUNEX_KEYCLOAK_REALM=lunex
LUNEX_KEYCLOAK_FRONTEND_CLIENTID=frontend
LUNEX_KEYCLOAK_BACKEND_CLIENTID=backend
QUARKUS_OIDC_AUTH_SERVER_URL=https://keycloak.internal.example.com/realms/lunex
QUARKUS_OIDC_TOKEN_ISSUER=https://login.example.com/realms/lunex

Values dosyasını normal kurulum/yükseltme akışıyla uygulayın. Harici Keycloak’un istemcilerini ve URL değişikliklerini kimlik yöneticisi korur; Lunex harici sunucuya kendi kullanıcı/istemci uzlaştırma işi kurmaz.

5. Giriş ve yetkileri doğrulayın

1. Lunex’i tarayıcının eriştiği gerçek HTTPS adresinden açın.
2. Girişin doğru realm’e gittiğini, dönüşün doğru Lunex origin’ine geldiğini kontrol edin.
3. Bir izleyiciyle proje okumasını; bir geliştiriciyle deneme dosyası kaydetme ve Git commit’ini kontrol edin.
4. Yönetici hesabıyla System görünürlüğünü doğrulayın.
5. Log out ve tekrar giriş akışını deneyin.

Token tanılamasında iss, aud, preferred_username, email ve realm_access.roles alanlarını kontrol edin; ham bearer token’ı hata raporuna veya genel bir çevrimiçi çözümleyiciye koymayın.

Kurumsal OIDC sağlayıcısını Keycloak’a bağlama

Bu yapıdaki giriş yolu Kullanıcı → Keycloak → Kurumsal OIDC → Keycloak → Lunex şeklindedir. Lunex’e verilen token’ı Keycloak üretmeye devam eder.

1. Keycloak realm’inde Identity providers → OpenID Connect v1.0 seçin ve örneğin corporate alias’ı verin.
2. Kurumsal sağlayıcının discovery/issuer bilgisini, client ID ve gerekiyorsa client secret’ını girin.
3. Keycloak’un gösterdiği Redirect URI adresini kurumsal sağlayıcıdaki istemcinin izinli dönüş adresi olarak kaydedin. Bu adres Lunex’in kök adresi değildir.
4. Kullanıcı adı ve e-posta eşlemelerini belirleyin. Platform realm rollerini kullanıcıya veya yönetilen grup eşlemelerine atayın.
5. Deneme hesabıyla giriş, e-posta, roller ve çıkış davranışını kontrol edin.

Sağlayıcıya özgü claim/grup eşlemeleri ve logout davranışı kimlik yöneticisinin sorumluluğundadır; bağlantıyı etkinleştirmek her sağlayıcı için aynı sonuç garantisini vermez. Native prosedür Keycloak identity brokering rehberindedir.

Artemis konsoluna aynı hesapla giriş

Artemis konsolu, Lunex tarayıcı istemcisinden ayrı artemis-console public PKCE istemcisini kullanır. Harici Keycloak’ta broker konsolu da kullanılacaksa bu istemciyi ayrıca hazırlayın:

• Redirect ve logout adresi: https://broker.example.com/console/.
• Web origin: https://broker.example.com.
• PKCE: S256; standard flow açık, implicit/direct grant kapalı.
• Varsayılan scope’lar: basic, web-origins, acr, profile, email.
• Realm-role mapper: access token’a çok değerli lunex_artemis_roles claim’i; audience mapper: artemis-console.

Broker yönetim erişimi platform-admin rolüne bağlanır. Kullanıcının Lunex’e girebilmesi broker yönetim yetkisini tek başına sağlamaz. Kuyruk yönetimi rehberi konsol görevlerini açıklar.

Yazım ajanlarının girişi

Geliştiricilerin ajanları (Claude Code, Codex) Lunex’e lunex-agent public PKCE istemcisiyle, geliştiricinin kendi hesabıyla girer. Ajanın oturumu, Keycloak’ın varsayılan ayarıyla 30 gün kullanılmazsa sona erer. Kurulumla gelen Keycloak’ta istemci ve Keycloak’ın yayınladığı scope listesi kurulum ve yükseltmede kendiliğinden ayarlanır. Harici Keycloak’ta bunları ayrıca hazırlayın:

• Client ID: lunex-agent; public istemci.
• PKCE: S256; standard flow açık, implicit, direct access ve device grant kapalı.
• Redirect adresleri: http://localhost/callback/* ve http://127.0.0.1/callback/*. Keycloak portsuz loopback adresini her portla eşleştirir; ajanların rastgele seçtiği port için ek kayıt gerekmez.
• Web origin: yok.
• Varsayılan scope’lar ve backend audience mapper’ı frontend istemcisindekiyle aynı; opsiyonel scope olarak offline_access.
• Client scopes ekranında lunex-agent istemcisinde olmayan her OpenID Connect scope’unda Include in OpenID Provider Metadata ayarını kapatın (Keycloak 26.4.3 ve sonrası). Codex, Keycloak’ın listelediği her scope’u ister; Keycloak istemcide olmayan scope’u reddeder. Daha eski Keycloak sürümleri her scope’u listeler; Codex o zaman ikinci kez giriş ister ve 30 dakika kullanılmazsa ya da 10 saatte sona eren bir oturum alır.

Ajan oturumu, hesapta offline_access realm rolünü gerektirir. Keycloak’ta açılan hesaplar bu rolü realm’in varsayılan rolleriyle alır. 1.3.0 veya önceki sürümlerle kurulan sistemlerde ilk admin hesabında bu roller yoktur; bu hesapla ajan bağlanacaksa hesaba default-roles-<realm> rolünü atayın.

Giriş sorunlarını giderme