OpenID Connect ile tek oturum açma

Bu rehberin sonunda hub'ın giriş sayfasında kimlik sağlayıcınız için bir Şununla oturum aç: … butonu bulunur. Kişiler şirket hesaplarıyla girer, Proxus ilk girişte kullanıcılarını oluşturur ve Proxus rollerini sağlayıcıdaki grupları belirler. Çok faktörlü giriş, parola kuralları ve hesap kilitleme sağlayıcıda yapılır.

Proxus, OpenID Connect destekleyen her sağlayıcıyla çalışır: Keycloak, Microsoft Entra ID, Okta, Auth0, Authentik, AD FS ve diğerleri. Active Directory'nize ya da LDAP'ınıza bağlı bir Keycloak, o hesapları Proxus'a getirir (Keycloak üzerinden Active Directory). Bir sağlayıcı olmadan AD kullanıcı adı ve parolasıyla giriş için Active Directory ve LDAP ile giriş sayfasına bakın.

Başlamadan önce

• Proxus'ta Administrators rolüne sahip bir kullanıcı ve hub'ın yapılandırmasına erişim (Proxus-config.toml dosyası ya da konteynerin ortam değişkenleri).
• Kimlik sağlayıcıda uygulama (client) kaydedebilen bir yönetici.
• Kişilerin hub'ı açtığı adres, örneğin https://proxus.example.com. Sağlayıcı kişileri girişten sonra bu adrese geri gönderir.

Nasıl çalışır

1. Kişi hub'ın giriş sayfasında Şununla oturum aç: … butonunu seçer ve sağlayıcıda oturum açar.
2. Sağlayıcı kişiyi kim olduğu ve grupları bilgisiyle hub'a geri gönderir.
3. Proxus, bu sağlayıcıdaki bu hesaba ait kullanıcıyı bulur. İlk seferde kullanıcıyı sağlayıcıdaki kullanıcı adıyla oluşturur.
4. Proxus, kullanıcıya gruplarından eşlenen Proxus rollerini verir; artık üyesi olmadığı grupların eşlenen rollerini geri alır. Eşlemede adı geçmeyen roller, bir yöneticinin verdiği gibi kalır.
5. Proxus'tan çıkış, sağlayıcıdaki oturumu da kapatır; aynı tarayıcıdaki bir sonraki kişi yeniden oturum açmak zorunda kalır.

Parolayla giriş, butonun yanında kullanılabilir kalır. Sağlayıcıya ulaşılamadığı durumlar için en az bir yönetici hesabını parolayla bırakın.

Adım 1: Proxus'u sağlayıcıya kaydedin

Yetkilendirme kodu akışıyla (authorization code) gizli anahtarlı bir uygulama kaydedin. Proxus'un ihtiyaç duyduğu değerler:

<scheme>, 2. adımda sağlayıcıya verdiğiniz kısa addır; örneğin keycloak ya da entra.

Keycloak

En hızlısı: şablonu içe aktarın. proxus-hub-client.json dosyasını indirin. Realm'de Clients > Import client'ı açın, dosyayı seçin ve Save'e basın. Dosyada secret ve adres yoktur: Keycloak yeni bir secret oluşturur, adresleri siz eklersiniz.

1. İçe aktarılan client'ta Settings'i açın ve yukarıdaki tablodaki redirect URI'yi ve çıkış sonrası redirect URI'yi kendi merkez sunucunuzun adresiyle girin.
2. Credentials sekmesinden client secret'ı kopyalayın.
3. Kişileri, 2. adımdaki rol eşlemesinde adını kullandığınız gruplara ekleyin (ya da onlara realm rolleri verin).

Şablon hem kişinin gruplarını (groups claim'i, yolsuz) hem de realm rollerini (roles claim'i) gönderir; Proxus ikisini de okur. PKCE'li (S256) authorization code akışını kullanır ve parola ile token almayı kapatır.

Elle, aynı ayarlar:

1. Realm'de Clients bölümünü açın ve Create client'ı seçin. Client tipi OpenID Connect, client kimliği örneğin proxus-hub.
2. Client authentication'ı açın ve Standard flow'u açık bırakın. Advanced altında Proof Key for Code Exchange Code Challenge Method değerini S256 yapın.
3. Yukarıdaki tablodaki redirect URI'yi ve çıkış sonrası redirect URI'yi girin.
4. Credentials sekmesinden client secret'ı kopyalayın.
5. Grupları ekleyin: Client scopes > proxus-hub-dedicated > Add mapper > By configuration > Group Membership. Token claim name groups, Full group path kapalı, Add to ID token ve Add to userinfo açık.
6. proxus-admins ve proxus-operators gibi gruplar oluşturun ve kişileri bu gruplara ekleyin (ya da Active Directory gruplarınızı bunlara eşleyin).

Issuer adresi (Proxus'taki Authority) https://<keycloak adresi>/realms/<realm> biçimindedir.

Microsoft Entra ID

App registrations altında bir uygulama kaydedin, bir Web redirect URI'si ve bir client secret ekleyin. Token configuration altında groups bilgisini ekleyin. Entra grup kimliklerini gönderir; bu yüzden rol eşlemesinde grup kimlikleri kullanılır. Authority https://login.microsoftonline.com/<tenant kimliği>/v2.0 biçimindedir.

Okta

Yukarıdaki redirect URI'leriyle bir OIDC - Web Application uygulama entegrasyonu oluşturun. Yetkilendirme sunucusuna bir groups bilgisi ekleyin (filtre örneğin Starts with proxus-). Authority https://<Okta alanınız>/oauth2/default biçimindedir.

Adım 2: Sağlayıcıyı Proxus'a ekleyin

Sağlayıcıyı Proxus-config.toml dosyasına ya da aynı anahtarları ortam değişkeni olarak ekleyin:

[[Authentication.Oidc.Providers]]
Scheme = "keycloak"
DisplayName = "Keycloak"
Authority = "https://sso.example.com/realms/plant"
ClientId = "proxus-hub"
ClientSecret = "<client secret>"
DefaultRoles = ["Default"]

[Authentication.Oidc.Providers.RoleMap]
proxus-admins = ["Administrators"]
proxus-operators = ["Operator"]

environment:
  Authentication__Oidc__Providers__0__Scheme: keycloak
  Authentication__Oidc__Providers__0__DisplayName: Keycloak
  Authentication__Oidc__Providers__0__Authority: https://sso.example.com/realms/plant
  Authentication__Oidc__Providers__0__ClientId: proxus-hub
  Authentication__Oidc__Providers__0__ClientSecret: ${OIDC_CLIENT_SECRET}
  Authentication__Oidc__Providers__0__DefaultRoles__0: Default
  Authentication__Oidc__Providers__0__RoleMap__proxus-admins__0: Administrators
  Authentication__Oidc__Providers__0__RoleMap__proxus-operators__0: Operator

Hub'ı yeniden başlatın. Giriş sayfasında artık Oturum aç'ın altında Şununla oturum aç: Keycloak (1) butonu görünür.

Tüm anahtarlar Yapılandırma anahtarları sayfasında listelenir.

Client secret'ı paylaşılan dosyalarda tutmayın: ortam değişkeni olarak verin ya da yapılandırma klasörünü yalnızca hub'ın okuyabileceği şekilde koruyun.

Birden fazla sağlayıcı tanımlanabilir: kendi Scheme değeriyle bir [[Authentication.Oidc.Providers]] bloğu daha ekleyin (ortam değişkenlerinde 1 indeksi). Her biri kendi butonunu alır.

Adım 3: Grupları rollere eşleyin

RoleMap, bir sağlayıcı grubunu (ya da rolünü) bir veya birden fazla Proxus rolüne bağlar. Adlar büyük-küçük harf ayrımı olmadan karşılaştırılır; /proxus-admins gibi bir Keycloak grup yolu proxus-admins ile eşleşir.

• Eşlenen roller sağlayıcıyı izler. Kişi her girişte üyesi olduğu grupların eşlenen rollerini alır, ayrıldığı grupların eşlenen rollerini kaybeder.
• Diğer roller kalır. Hiçbir grubun eşlemediği bir rol, örneğin bir yöneticinin elle verdiği rol, girişle asla geri alınmaz.
• DefaultRoles kullanıcı oluşturulurken bir kez verilir.
• Eşlemede adı geçen ama Proxus'ta olmayan bir rol atlanır ve log'a yazılır.

Yerleşik rollerin neye izin verdiği için Kullanıcılar ve roller sayfasına bakın.

Adım 4: Test edin

1. Hub'ı gizli bir tarayıcı penceresinde açın ve sağlayıcının butonunu seçin.
2. Eşlenen bir gruptaki bir hesapla oturum açın.
3. Bir yönetici olarak Güvenlik > Kullanıcılar ekranını açın. Yeni kullanıcı eşlenen rolleriyle listelenir ve yalnızca sağlayıcı üzerinden oturum açar.
4. Çıkış yapın ve butonu yeniden seçin: sağlayıcı parolayı yeniden sorar.

Mevcut kullanıcılar

Bir giriş, oluşturmadığı bir Proxus kullanıcısını asla devralmaz. Kişinin aynı kullanıcı adıyla zaten bir Proxus kullanıcısı varsa, sağlayıcıyla ilk girişi reddedilir ve log'a yazılır; LinkExistingUsers = true yaparsanız ilk giriş sağlayıcı hesabını o kullanıcıya bağlar ve kişi rollerini korur. Bunu yalnızca kullanıcı adlarına güvendiğiniz bir sağlayıcıyla kullanın.

Yalnızca bir yöneticinin önceden bağladığı kişilerin girmesine izin vermek için CreateUsers = false yapın.

API, MCP ve servis hesapları

Programlar da aynı sağlayıcıyı kullanabilir: bir betik, bir veri platformu ya da bir yapay zekâ asistanı sağlayıcıdan bir access token alır ve onu bir Proxus API token'ıyla değiştirir. Hiçbir Proxus parolası paylaşılmaz.

1. Sağlayıcıda access token'ların hedef kitlesine (audience) Proxus'u ekleyin. Keycloak'ta: Client scopes > proxus-hub-dedicated > Add mapper > By configuration > Audience, Included Client Audience proxus-hub, Add to access token açık. Bir kişiye bağlı olmayan programlar için client'ta Service accounts roles'u açın ve client credentials akışını kullanın.

2. Sağlayıcının access token'ını bir Proxus token'ıyla değiştirin:

   curl -X POST https://proxus.example.com/api/Authentication/Exchange \
     -H "Content-Type: application/json" \
     -d '{"accessToken":"<sağlayıcıdan alınan access token>"}'

   Yanıt, REST API girişindeki gibi bir Proxus token'ıdır. Kişi ya da servis hesabı, giriş sayfasındaki girişle tamamen aynı şekilde bulunur ya da oluşturulur ve eşlenen rollerini alır. Servis hesabı, sağlayıcının verdiği kullanıcı adıyla oluşturulur; örneğin service-account-proxus-hub.

3. Bir MCP istemcisi de aynı yolla oturum açar: kullanıcı adı ve parola yerine accessToken ile auth_login. Bkz. MCP.

Token, sağlayıcı tarafından imzalanmış, süresi içinde, sağlayıcının Authority adresinden gelmiş olmalı ve hedef kitlesinde ApiAudiences değerlerinden birini (varsayılan olarak ClientId) taşımalıdır. Bunun dışındaki her token 401 ile reddedilir. Bir sağlayıcı için değişimi kapatmak üzere AcceptApiTokens = false yapın.

Çok faktörlü giriş

Çok faktörlü giriş, passkey'ler ve parola sıfırlama, kişi Proxus'a dönmeden önce sağlayıcıda yapılır. Bunları orada açın: Keycloak'ta örneğin OTP ya da WebAuthn'i zorunlu eylem (required action) olarak ya da tarayıcı akışında ekleyin. Proxus'ta bunun için bir ayar gerekmez.

Formlardaki elektronik imzalar

Sağlayıcının oluşturduğu bir kullanıcının Proxus parolası yoktur. Elektronik imza isteyen formlar bu kişilerden bunun yerine bir kez belirledikleri imza PIN'ini ister. Kapatılmış bir kullanıcı sağlayıcı üzerinden de giremez.

Bir yol altında ya da proxy arkasında hub

• Siemens Industrial Edge ve yol tabanlı kurulumlar. /proxus gibi bir yol altında redirect URI'ler https://<cihaz>/proxus/signin-<scheme> ve https://<cihaz>/proxus/signout-callback-<scheme> olur.
• Ters proxy. Proxy, hub'ın dönüş adresini kişilerin kullandığı adresle kurabilmesi için X-Forwarded-Proto ve X-Forwarded-Host başlıklarını iletmelidir.
• Birden fazla hub örneği (Kubernetes). Arayüzün geri kalanında olduğu gibi oturumları tek bir örnekte tutun (sticky sessions).

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

Sırada ne var

• Kullanıcılar ve roller
• UNS yetkileri: kişileri tesisin bölümleriyle sınırlayın
• Güvenlik: sıkılaştırma kontrol listesi