# OpenID Connect ile tek oturum açma

> Kişiler şirketinizin kimlik sağlayıcısıyla girsin: Keycloak, Microsoft Entra ID, Okta ya da herhangi bir OpenID Connect sağlayıcısı.

Kaynak: https://proxus.io/tr/docs/administer/single-sign-on

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](https://proxus.io/tr/docs/administer/active-directory-keycloak)). Bir sağlayıcı olmadan AD
kullanıcı adı ve parolasıyla giriş için [Active Directory ve LDAP ile giriş](https://proxus.io/tr/docs/administer/active-directory)
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:

| Sağlayıcıdaki ayar | Değer |
| --- | --- |
| Redirect URI | `https://<hub adresi>/signin-<scheme>`, örneğin `https://proxus.example.com/signin-keycloak` |
| Çıkış sonrası redirect URI | `https://<hub adresi>/signout-callback-<scheme>` |
| Kapsamlar (scopes) | `openid`, `profile`, `email` |
| Gruplar | Kişinin gruplarını ya da rollerini taşıyan bir bilgi (claim); ID token'da ya da user info'da |

`<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](/keycloak/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:

```toml
[[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"]
```

```yaml
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.

*Ekran görüntüsü: Oturum aç düğmesinin altında Şununla oturum aç: Keycloak butonu işaretli giriş sayfası*

Tüm anahtarlar [Yapılandırma anahtarları](https://proxus.io/tr/docs/reference/configuration#authenticationoidcproviders) 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](https://proxus.io/tr/docs/administer/users-and-roles) 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:

   ```bash
   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](https://proxus.io/tr/docs/develop/rest-api) 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](https://proxus.io/tr/docs/develop/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](https://proxus.io/tr/docs/organize/forms)
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

| Ne görüyorsunuz | Neden | Ne yapmalı |
| --- | --- | --- |
| Sağlayıcı butonu yok. | Sağlayıcı kaydı eksik ya da hatalı. | Hub log'u başlangıçta kaydı ve sorunu söyler, örneğin `ClientId is missing`. |
| Sağlayıcı redirect URI'nin geçersiz olduğunu söylüyor. | Sağlayıcıda kayıtlı adres, hub'ın gönderdiğinden farklı. | Tam olarak `https://<hub adresi>/signin-<scheme>` kaydedin; hub bir yol altındaysa yoluyla birlikte. |
| Sağlayıcıda oturum açtıktan sonra yine giriş sayfası geliyor. | Proxus hesabı reddetti. | Hub log'u nedenini söyler: aynı adda bir Proxus kullanıcısı var (`LinkExistingUsers`), `CreateUsers` kapalı ya da kullanıcı kapatılmış. |
| Kişide olması gereken roller yok. | Grup bilgisi gelmiyor ya da başka bir adla geliyor. | Sağlayıcının `groups` bilgisini ID token'da ya da user info'da gönderdiğini kontrol edin ya da `RoleClaims` değerini kullandığı ada ayarlayın. |
| `Authority must use https`. | Sağlayıcı düz HTTP üzerinde. | HTTPS kullanın. Yalnızca test ortamında `RequireHttpsMetadata = false` yapın. |

## Sırada ne var

- [Kullanıcılar ve roller](https://proxus.io/tr/docs/administer/users-and-roles)
- [UNS yetkileri](https://proxus.io/tr/docs/administer/uns-permissions): kişileri tesisin bölümleriyle sınırlayın
- [Güvenlik](https://proxus.io/tr/docs/operate/security): sıkılaştırma kontrol listesi