Giriş ve SSO

Üretimde Orbtrace kendine ait parola tutmaz. Herkes mevcut kimlik sağlayıcınız (SSO) üzerinden giriş yapar — e-posta ya da Slack için kullandığınızın aynısı. Sağlayıcıyı bir defa konfigüre eder, Orbtrace'i yeniden başlatırsınız; ekibiniz giriş yapmaya başlar. Önerilen yol budur: IdP'nizin MFA'sı, koşullu erişimi ve işten-ayrılma akışı otomatik olarak geçerli olur.

Bir de tek bir break-glass yerel admin girişi var — IdP'siz taze bir kurulumun asla dışarıda kalmaması için bir kullanıcı adı/parola formu. SSO konfigüre edilmeden yapılan ilk açılışta Orbtrace onu kuruluma özel, üretilmiş bir parolayla otomatik oluşturur ve ilk girişte parola değişikliğini zorunlu kılar. Aşağıda anlatılıyor; üretim girişi değil break-glass olduğuna dair net bir uyarıyla (MFA yok, lockout yok).

Bu sayfa şunları anlatıyor:

• Neler destekleniyor (tek tabloda)
• İlk yöneticiyi kim olarak belirleriz (ve opsiyonel yerel giriş)
• Her sağlayıcı için adım-adım konfigürasyon
• Birden fazla sağlayıcıyı paralel çalıştırmak
• Bir sağlayıcıyı kapatmak
• Her kullanıcının iki olası rolü
• Bir şey çalışmadığında nereye bakılır

Neler destekleniyor

Orbtrace'i şu seçeneklerden herhangi birine — veya birkaçına aynı anda — bağlayabilirsiniz:

İlk yöneticiyi kim olarak belirleriz

Orbtrace'i ilk başlattığınızda kimsenin rolü yoktur. İlk giren kişi sıradan bir kullanıcıdır — ekranları görebilir ama Yönetim alanında hiçbir şeyi değiştiremez.

Belli bir operatör e-postasını baştan yönetici olarak sabitlemek için dağıtımınıza şunu ekleyin:

ORBTRACE_BOOTSTRAP_ADMIN_USERNAME=siz@sirketiniz.com

Bu e-posta herhangi bir sağlayıcı üzerinden ilk kez giriş yaptığında Orbtrace o hesaba Yönetici rolü verir. Eğer hesap zaten sıradan kullanıcı olarak duruyorsa bir sonraki girişte yükseltir. Karşılaştırma büyük/küçük harf duyarsızdır; Siz@Sirketiniz.com ve siz@sirketiniz.com aynı kabul edilir. Orbtrace bunu her girişte yeniden uygular, böylece sabitlenen operatör admin'liğini asla kazara kaybetmez.

Break-glass yerel admin (taze kurulumlar)

SSO konfigüre edilmemiş taze bir kurulum asla dışarıda kalmaz: Orbtrace ilk açılışta yerel bir break-glass admin oluşturur — kullanıcı adı admin@orbtrace.local (ya da pinlediğiniz ORBTRACE_BOOTSTRAP_ADMIN_USERNAME), parolası kuruluma özel, üretilmiş bir değerdir. Kasıtlı olarak sabit bir varsayılan parola yoktur — her kuruluma gömülü ortak bir kimlik kritik bir zafiyet olurdu; bu yüzden parola her seferinde rastgeledir ve Orbtrace bir oturum vermeden önce ilk girişinizde yeni bir parola belirlemeniz zorunludur.

Üretilen parolayı nereden okursunuz:

• Helm — chart onu bir Secret'ta saklar (upgrade'lerde korunur):

  kubectl -n <namespace> get secret <release>-bootstrap-admin \
    -o jsonpath='{.data.password}' | base64 -d

• Docker Compose / çıplak JAR — açılış logunda bir kez yazılır:

  docker compose logs orbtrace-server | grep "BREAK-GLASS"

Herhangi bir SSO sağlayıcısı konfigüre etmek otomatik üretimi kapatır (saf-SSO giriş sayfası). Helm'de break-glass admin'i orbtrace.bootstrapAdmin.enabled=false ile açıkça da kapatabilirsiniz.

Parolayı kendiniz belirlemek

Üretilen yerine ilk parolayı kendiniz seçmek isterseniz iki değeri de ayarlayın:

ORBTRACE_BOOTSTRAP_ADMIN_USERNAME=siz@sirketiniz.com
ORBTRACE_BOOTSTRAP_ADMIN_PASSWORD=güçlü-bir-parola

Giriş sayfası bir kullanıcı adı/parola formu gösterir (SSO düğmelerinin yanında). Parola açılışta BCrypt ile hash'lenerek veritabanına yazılır ve ilk girişte yine değiştirmeniz istenir (ORBTRACE_BOOTSTRAP_ADMIN_FORCE_PASSWORD_CHANGE=false ile vazgeçebilirsiniz). Uygulama içinden bir kez değiştirdikten sonra kimlik sizindir — env değeri yeniden başlatmalarda artık onu ezmez.

Google konfigürasyonu

Google Cloud Console üzerinde bir OAuth istemcisi oluşturacaksınız. Google size iki değer verecek — bir client ID ve bir client secret — bunları Orbtrace'in .env dosyasına yapıştıracaksınız.

1. 1

   Google Cloud Console'u açın

   console.cloud.google.com'a gidin ve şirket alan adınızın Google Workspace yöneticisi hesabıyla giriş yapın. Daha önce yapmadıysanız bir proje oluşturun (isim herhangi bir şey olabilir; sadece bir iç etiket).

2. 2

   OAuth consent screen'i konfigüre edin

   Sol menüden APIs & Services → OAuth consent screen'i açın. Şirketiniz Workspace'teyse Internal (sadece Workspace içindekiler giriş yapabilsin), değilse External seçin. Uygulama adını ("Orbtrace"), destek e-postasını ve şirket alan adınızı doldurup kaydedin.

3. 3

   OAuth istemcisini oluşturun

   APIs & Services → Credentials sayfasında Create credentials → OAuth client ID ile Web application seçin.

   Authorized redirect URIs alanına aşağıdaki URL'yi ekleyin — https://orbtrace.example.com yerine kendi Orbtrace URL'nizi yazın:

   https://orbtrace.example.com/login/oauth2/code/google

   Create'e basın. Google size bir Client ID ve Client Secret gösterir. İkisini de kopyalayın — secret değeri daha sonra tekrar görüntülenemez.

4. 4

   Orbtrace'in .env dosyasına yapıştırın

   Orbtrace'in çalıştığı sunucuda docker/.env dosyasını açın, şu iki satırı bulup değerleri yapıştırın:

   GOOGLE_CLIENT_ID=<Google'ın gösterdiği client ID>
   GOOGLE_CLIENT_SECRET=<Google'ın gösterdiği client secret>

5. 5

   Orbtrace'i yeniden başlatın

   Aynı klasörden:

   docker compose up -d --force-recreate orbtrace

   Giriş ekranında artık Google ile devam et butonu görünecektir. Tıklayın, Google hesabınızla giriş yapın — Orbtrace ana ekranına düşersiniz.

Microsoft (Entra ID) konfigürasyonu

Entra yönetim merkezinde bir uygulama kaydedeceksiniz. Microsoft size bir client ID, bir client secret ve bir tenant ID verecek.

1. 1

   Entra yönetim merkezini açın

   entra.microsoft.com'a gidin ve uygulama kaydetme yetkisi olan bir Microsoft 365 hesabıyla giriş yapın (Global Administrator, Application Administrator veya Cloud Application Administrator).

2. 2

   Yeni bir uygulama kaydedin

   Identity → Applications → App registrations → New registration'a gidin.

   • Name: Orbtrace (kullanıcıların giriş sırasında göreceği isim)
   • Supported account types: "Accounts in this organizational directory only" — sadece kendi tenant'ınızdaki kullanıcılar girebilsin
   • Redirect URI: tipini Web seçip URL'yi girin:

   https://orbtrace.example.com/login/oauth2/code/microsoft

   Register'a basın. Açılan özet sayfasında Application (client) ID ve Directory (tenant) ID görünür; ikisini kopyalayın.

3. 3

   Bir client secret oluşturun

   Certificates & secrets → Client secrets → New client secret'i açın. Bir açıklama yazıp süre seçin (Microsoft mutlaka bir süre ister; 24 ay makul — biten süreden önce yenilemek için takvime hatırlatma koyun).

   Add'e basın. Microsoft secret'ı sadece bir kez gösterir — hemen kopyalayın. Daha sonra tekrar görüntülenemez.

4. 4

   Gerekli izinleri verin

   API permissions'ı açın. Varsayılan User.Read izni zaten oradadır ve yeterlidir. Tenant'ınız yönetici onayı istiyorsa Grant admin consent for <tenant adı> butonuna basın.

5. 5

   Orbtrace'in .env dosyasına yapıştırın

   docker/.env dosyasını açın:

   MICROSOFT_CLIENT_ID=<Application (client) ID>
   MICROSOFT_CLIENT_SECRET=<client secret değeri>
   MICROSOFT_TENANT=<Directory (tenant) ID>

   Tenant ID girişi kendi kuruluşunuza kilitler. Herhangi bir Microsoft hesabıyla giriş yapılmasını istiyorsanız (nadiren istenir) common yazın — ama genelde istenen bu değildir.

6. 6

   Orbtrace'i yeniden başlatın

   docker compose up -d --force-recreate orbtrace

   Giriş ekranında artık Microsoft ile devam et butonu görünür.

GitHub konfigürasyonu

Organizasyon ayarlarında bir GitHub OAuth App oluşturacaksınız.

1. 1

   Organizasyonun OAuth Apps sayfasını açın

   Organizasyon sahibi olarak GitHub'a giriş yapın. organizasyonunuz → Settings → Developer settings → OAuth Apps → New OAuth App'e gidin.

   (Kişisel hesaplarda da çalışır — Settings → Developer settings → OAuth Apps — ama şirket kullanımı için organizasyona ait uygulama tercih edilmelidir.)

2. 2

   Uygulama formunu doldurun

   • Application name: Orbtrace
   • Homepage URL: https://orbtrace.example.com
   • Authorization callback URL:

   https://orbtrace.example.com/login/oauth2/code/github

   Register application'a basın. Açılan sayfada Client ID görünür.

3. 3

   Client secret üretin

   Aynı sayfada Generate a new client secret butonuna basın. Değeri kopyalayın — GitHub yalnızca bir kez gösterir.

4. 4

   Orbtrace'in .env dosyasına yapıştırın

   GITHUB_CLIENT_ID=<client ID>
   GITHUB_CLIENT_SECRET=<client secret>

5. 5

   Orbtrace'i yeniden başlatın

   docker compose up -d --force-recreate orbtrace

   Giriş ekranında artık GitHub ile devam et butonu görünür.

Özel kimlik sağlayıcı (OIDC) konfigürasyonu

Keycloak, Authelia, Auth0, Okta, JumpCloud, OneLogin, Ping ve OIDC konuşan tüm kimlik sistemleri için yol budur. IdP'nizden üç şey toplayacaksınız:

1. Bir Client ID ve Client Secret (Orbtrace'i uygulama olarak kaydettiğinizde IdP verir)

2. Bir Issuer URL (bazen "OIDC discovery URL" veya "metadata URL" deniyor; IdP'nizin konfigürasyonuna işaret eder)

3. IdP içine kaydedilecek redirect URL — her zaman şu olur:

   https://orbtrace.example.com/login/oauth2/code/oidc

1. 1

   Orbtrace'i IdP'nizde bir uygulama olarak kaydedin

   IdP'nizin yönetim panelinde yeni bir OIDC istemcisi/uygulaması yaratın. Menü adı IdP'ye göre değişir:

   • Keycloak: Realm → Clients → Create client → protokol olarak OpenID Connect seçin
   • Auth0: Applications → Create application → Regular Web Application
   • Okta: Applications → Create App Integration → OIDC - OpenID Connect → Web Application
   • Authelia: configuration.yml'da identity_providers.oidc.clients altına yeni bir kayıt ekleyin
   • JumpCloud / OneLogin / Ping: "OIDC application" veya "Web application" şablonunu arayın

   Yukarıdaki redirect URL'yi kullanın. Çoğu IdP hangi OIDC akışına izin verileceğini sorar; Authorization code seçin (bazen "Standard flow" diye etiketlenir). IdP'nin openid, email ve profile scope'larını döndürdüğünden emin olun.

2. 2

   Issuer URL'yi kopyalayın

   Her OIDC sağlayıcısı konfigürasyonunu bilinen bir adreste yayınlar. Yaygın şekiller:

   Sağlayıcı	Issuer URL şekli
   Keycloak	https://sso.example.com/realms/<realm-adı>
   Auth0	https://<tenant>.auth0.com/
   Okta	https://<tenant>.okta.com/oauth2/default
   Authelia	https://auth.example.com
   Microsoft Entra (OIDC olarak)	https://login.microsoftonline.com/<tenant-id>/v2.0

   Emin değilseniz: <issuer-url-niz>/.well-known/openid-configuration adresini tarayıcıda açın. JSON görüyorsanız URL doğrudur (yalnızca /.well-known/... ekini çıkarın). 404 görüyorsanız URL yanlış.

3. 3

   Hepsini Orbtrace'in .env dosyasına yapıştırın

   OIDC_CLIENT_ID=<IdP'nin verdiği client ID>
   OIDC_CLIENT_SECRET=<IdP'nin verdiği client secret>
   OIDC_ISSUER_URI=<2. adımdaki issuer URL>
   ORBTRACE_OIDC_DISPLAY_NAME=Acme SSO

   ORBTRACE_OIDC_DISPLAY_NAME giriş butonunda görünecek etikettir. Ekibinizin tanıyacağı bir isim verin — "Acme SSO", "Keycloak", "Şirket Girişi" gibi. Boş bırakırsanız buton "Tek Oturum Açma ile devam et" olur.

4. 4

   Orbtrace'i yeniden başlatın

   docker compose up -d --force-recreate orbtrace

   Orbtrace açılışta IdP'nizin konfigürasyonunu bir kere çeker — başka hiçbir şey ayarlamanız gerekmez. Giriş ekranında özel butonunuz görünür.

Birden fazla sağlayıcıyı paralel çalıştırmak

Ekstra bir şey gerekmez — istediğiniz her sağlayıcı için değişkenleri doldurun, yeniden başlatın. Tüm konfigüre edilmiş sağlayıcıların butonu giriş ekranında paralel olarak görünür.

Yaygın kombinasyon:

• Özel OIDC (Keycloak, kurumsal SSO) — çalışanlar için birincil yol
• Google — kurumsal hesabı olmayan birkaç dış kaynaklı için

İkisini aynı anda konfigüre edersiniz. Çalışanlar bir butona, dış kaynaklılar diğerine basar.

Bir sağlayıcıyı kapatmak

Bir sağlayıcıyı giriş ekranından gizlemek için: .env içindeki değişkenlerini boşaltıp yeniden başlatın.

# Google'ı devre dışı bırakmak — ikisini de boş bırak:
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

Sonraki açılışta buton kaybolur. O sağlayıcı üzerinden oluşmuş mevcut hesaplar Orbtrace'te kalır — sadece artık giriş yapamazlar (sağlayıcıyı tekrar açana veya o kullanıcıyı başka bir sağlayıcıya taşıyana kadar).

Roller

Orbtrace'in tam olarak iki rolü vardır. Her kullanıcı bunlardan birine sahiptir.

İlk yönetici ORBTRACE_BOOTSTRAP_ADMIN_USERNAME ile belirlenir (yukarıya bakın). Sonrasında herhangi bir yönetici, başka kullanıcıları Yönetim → Kullanıcılar üzerinden yükseltebilir. Orbtrace, son kalan yöneticiyi düşürmenize izin vermez — her zaman diğerlerini kurtarabilecek en az bir hesap kalır.

Bir şey çalışmadığında

En sık karşılaşılan tuzakların kısa kontrol listesi.

Listede olmayan bir şey varsa Sorun Giderme sayfasını veya docker compose logs orbtrace çıktısını kontrol edin — giriş hataları WARN seviyesinde tek satırlık net bir gerekçeyle düşer.

Sonraki adım

• İlk sağlayıcınızı yeni konfigüre ettiniz → İlk giriş sayfasındaki 5 dakikalık giriş-sonrası kontrol listesiyle devam edin.
• Tüm ayarların kapsamlı listesi → Konfigürasyon sayfasına bakın.
• Kullanıcı davet etmek / yönetmek → Yönetici olarak giriş yaptıktan sonra Yönetim → Kullanıcılar içinde.