OpenID Connect

OpenID Connect Nedir?

OpenID Connect, kullanıcının kimliğini harici bir kimlik sağlayıcısında (Google, Microsoft Entra ID, Apple, Keycloak, Okta gibi) doğrulatan Authentication Providers türüdür. OAuth2 üzerine kurulu bir kimlik katmanıdır: kullanıcı sağlayıcının yetkilendirme sayfasına yönlendirilir, orada giriş yapar ve TR7'ye geri döner; TR7 aldığı yetkilendirme koduyla belirteç alır. Parola TR7'ye hiç gelmez.

OAuth2'den farkı, sağlayıcının kullanıcı kimliğini imzalı bir ID belirteci (ID token) olarak döndürmesidir. TR7 bu belirtecin imzasını sağlayıcının anahtar kümesiyle (JWKS) doğrular ve tekrar saldırılarına karşı nonce değerini denetler; böylece kimlik bilgisinin gerçekten sağlayıcıdan geldiği güvence altına alınır. Sağlayıcı destekliyorsa kimlik doğrulaması için OAuth2 yerine bu tür tercih edilir.

Nasıl çalışır?

1. Sağlayıcıda (ör. Google Cloud Console, Entra ID) bir uygulama kaydı oluşturulur; Client ID, Client Secret alınır ve TR7'nin Redirect URI adresi kaydedilir.
2. TR7'de Provider Type olarak OpenID Connect seçilir; OAuth Provider alanından hazır sağlayıcı ya da Custom Provider seçilir ve istemci bilgileri girilir.
3. Profil, AGS etkin vService'in erişim akışına Authentication Provider adımı olarak eklenir; kullanıcı /oauth yolu üzerinden sağlayıcıya yönlendirilir.
4. ID belirtecinin imzası ve nonce değeri doğrulanır; kullanıcı bilgileri otomatik eşlemeyle oturum özniteliklerine yazılır ve akış success geçişinden devam eder.

Hazır OAuth Provider Kataloğu

OAuth Provider alanından hazır bir sağlayıcı seçildiğinde yetkilendirme, belirteç, kullanıcı bilgisi, çıkış ve belirteç iptali adresleri, varsayılan kapsamlar ve PKCE ile istemci doğrulama ayarları TR7 tarafından sağlanır; formda istemci bilgileri (Client ID, Client Secret, OAuth Scopes, Redirect URI), sağlayıcıya özgü alanlar, çıkış anahtarları ve ID belirteci alanları (JWKS URI, Skip Signature Verification, Skip Nonce Validation) görünür. Custom Provider seçildiğinde bütün uç noktalar elle girilir.

OAuth Provider	Ek alan	Çıkış ve iptal anahtarları	Not
e-Devlet	-	Sign Out from Provider on Logout	Kapsamlar ; ile ayrılır; TÜRKSAT ile sözleşme gerektirir
Google	Hosted Domain, Access Type, Prompt	Revoke Tokens on Logout
Microsoft	Tenant (varsayılan common)	Sign Out from Provider on Logout	Entra ID kiracısı: common, organizations, consumers ya da kiracı kimliği veya alan adı
GitHub	-	-
Apple	Team ID, Key ID, Private Key (.p8)	Revoke Tokens on Logout	Yalnızca bu türde listelenir; istemci gizli anahtarı TR7 tarafından üretilir. Kullanıcı bilgisi uç noktası yoktur; kimlik bilgileri ID belirtecinden okunur ve kullanıcının adı yalnızca ilk yetkilendirmede döner
GitHub Enterprise	GitHub Enterprise Address (zorunlu)	-
GitLab	GitLab Address (varsayılan https://gitlab.com)	Revoke Tokens on Logout
Keycloak	Realm URL (zorunlu)	Revoke ve Sign out
Okta	Okta Domain (zorunlu)	Revoke ve Sign out	PKCE (S256) açık
Auth0	Auth0 Tenant Address (zorunlu)	Revoke ve Sign out
X (Twitter)	-	Revoke Tokens on Logout	E-posta eşlemesi yoktur; PKCE (S256) açık
LinkedIn	-	Revoke Tokens on Logout
Facebook	-	-
Yandex	-	-

Hazır sağlayıcıların uç nokta adresleri profile yazılmaz; her çalışmada TR7'nin kataloğundan uygulanır. Sağlayıcıya özgü alanların varsayılanları (ör. Microsoft Tenant ya da Google Access Type ve Prompt) ise profile kaydedilir. Profili Custom Provider'a çevirmek adres alanlarını boş bırakır.

Sağlayıcıya Özgü Alanlar

Hazır bir sağlayıcı seçildiğinde formda adres alanlarının yerine sağlayıcının gerektirdiği alanlar görüntülenir:

Alan	Sağlayıcı	Anlamı
Tenant	Microsoft	Entra ID kiracısı; varsayılan common.
GitHub Enterprise Address	GitHub Enterprise	Kurulumun adresi; zorunlu.
GitLab Address	GitLab	Kurulumun adresi; varsayılan https://gitlab.com.
Realm URL	Keycloak	Realm adresi; zorunlu.
Okta Domain	Okta	Okta alan adı; zorunlu.
Auth0 Tenant Address	Auth0	Kiracı adresi; zorunlu.
Hosted Domain	Google	Girişin sınırlandırılacağı Google Workspace alan adı.
Access Type	Google	Online (default) ya da Offline (get refresh token).
Prompt	Google	None, Consent ya da Select Account (default).
Team ID	Apple	Apple geliştirici takım kimliği; 10 karakterdir ve zorunludur.
Key ID	Apple	Apple imzalama anahtarının kimliği; zorunludur.
Private Key (.p8)	Apple	Apple imzalama anahtarının -----BEGIN PRIVATE KEY----- bloğundaki içerik; zorunludur, cihazdan dışarı çıkmaz. İstemci gizli anahtarı her istekte bu anahtarla imzalanan bir ES256 JWT olarak üretilir.

Operasyonel En İyi Uygulamalar

• Uç noktalar keşifle. Custom Provider'da adresler elle yazılmak yerine Fetch Endpoints from Issuer ile doldurulmalıdır; yazım hataları giriş akışını sessizce bozar.
• Redirect URI yol olarak. Redirect URI alanına tam adres yerine yol (/ags-portal/oauth gibi) yazıldığında aynı profil vService'in her alan adında çalışır; adres sağlayıcı tarafında da kayıtlı olmalıdır.
• İmza doğrulaması açık. Skip Signature Verification ve Skip Nonce Validation yalnızca test ya da nonce desteklemeyen sağlayıcılar için açılmalıdır; üretimde kapalı tutulmalıdır.
• Kilitleme sağlayıcıda. Kilitleme genellikle sağlayıcı tarafında yapılır; Lockout Behavior için No Lockout ya da Use Gateway Defaults seçilmelidir.
• Çıkışta sağlayıcıdan da çıkış. Paylaşılan bilgisayarların kullanıldığı ortamlarda Sign Out from Provider on Logout açılmalıdır; aksi hâlde kullanıcı bir sonraki girişte parola sorulmadan içeri alınır.

Nasıl Eklenir?

Yeni bir OpenID Connect sağlayıcısı, TR7 web yönetim arayüzü üzerinden aşağıdaki adımlarla eklenir:

1. Sol altta bulunan TR7 logosuna tıklanarak Configuration Menu açılır.
2. AGS → Authentication → Authentication Providers → Add adımları takip edilir.
3. Profil için benzersiz ve açıklayıcı bir isim girilir; Provider Type olarak OpenID Connect seçilir.
4. OAuth Provider seçilir ve istemci bilgileri girilir.
5. Add butonuna tıklanarak profil eklenir.

Profil Ekleme Formu

AGS → Authentication → Authentication Providers → Add adımları takip edilerek Provider Type alanında OpenID Connect seçildiğinde form aşağıdaki alanlarla açılır.

OpenID Connect Seçiliyken Form (Custom Provider)

OpenID Connect Formunun Devamı

INFO

Provider Name Zorunlu

Profilin adı; listede, akış şemasındaki adım seçiminde, oturum listesinde ve loglarda profili tanımlar. Ad cihazda benzersiz olmalıdır; aynı adla ikinci bir profil kaydedilmez ve Name is used uyarısı görüntülenir. Boş bırakıldığında Required field uyarısı görüntülenir.

INFO

Provider Type Zorunlu

Sağlayıcı türü; bu sayfada OpenID Connect seçilidir. Tür değiştirildiğinde yalnızca yeni türün alanları görüntülenir ve kaydedilir; tür düzenleme formunda da değiştirilir.

INFO

Namespace Varsayılan: varsayılan route tablosu

TR7'nin sağlayıcıya yaptığı belirteç ve kullanıcı bilgisi isteklerinin çıkacağı Route Tables kaydı; internet erişimi olan route tablosu seçilmelidir. Alan cihazın varsayılan route tablosuyla dolu gelir; bu tablonun adı cihaza göre değişir (ör. DEFAULT ya da DEFAULT_ROUTE).

INFO

OAuth Provider Varsayılan: Custom Provider

Hazır sağlayıcılardan biri ya da Custom Provider seçilir (bkz. Hazır OAuth Provider Kataloğu). Hazır sağlayıcı seçildiğinde uç nokta adresleri, Fetch Endpoints from Issuer butonu ve protokol alanları (Client Authentication, Enable PKCE, User Info Request Method, User Info Parameters) gizlenir. Client ID, Client Secret, OAuth Scopes, Redirect URI, sağlayıcıya özgü alanlar, çıkış anahtarları ile JWKS URI, Skip Signature Verification ve Skip Nonce Validation alanları görüntülenmeye devam eder.

INFO

Fetch Endpoints from Issuer

Yalnızca Custom Provider seçiliyken görünen buton; sağlayıcının keşif belgesinden uç noktaları doldurur (bkz. Fetch Endpoints from Issuer).

INFO

Authorization URL Zorunlu (Custom Provider)

Kullanıcının giriş için yönlendirileceği sağlayıcı uç noktası (https://provider.com/oauth/authorize gibi).

INFO

Token URL Zorunlu (Custom Provider)

Yetkilendirme kodunun belirteçle değiştirildiği uç nokta.

INFO

User Info URL Zorunlu (Custom Provider)

Erişim belirteciyle kullanıcı bilgisinin okunduğu uç nokta.

INFO

Logout URL

Sağlayıcının çıkış uç noktası; isteğe bağlıdır. Girildiğinde Sign Out from Provider on Logout anahtarı görüntülenir.

INFO

Token Revocation URL

Sağlayıcının belirteç iptali uç noktası; isteğe bağlıdır. Girildiğinde Revoke Tokens on Logout anahtarı görüntülenir.

INFO

Client ID Zorunlu

Sağlayıcıda kayıtlı uygulamanın istemci kimliği.

INFO

Client Secret

Sağlayıcıda kayıtlı uygulamanın gizli anahtarı; maskeli alana girilir, önizlemede ******** olarak gösterilir. Genel istemcilerde (Client Authentication: Public client — no client secret sent) boş bırakılır.

INFO

OAuth Scopes

İstenecek kapsamlar boşlukla ayrılarak girilir (openid email profile); e-Devlet'te ; ile ayrılır. Hazır sağlayıcılar için varsayılan kapsamlar katalogda tanımlıdır; alan doldurulduğunda girilen değer kullanılır.

INFO

Redirect URI Zorunlu

Sağlayıcının kullanıcıyı geri göndereceği adres. Tam adres ya da yalnızca yol (/ags-portal/oauth gibi) girilir; yol girildiğinde adres, isteğin geldiği şema ve alan adıyla tamamlanır. Aynı adres sağlayıcı tarafındaki uygulama kaydına da yazılmalıdır.

INFO

Client Authentication Varsayılan: client_secret_post

Yalnızca Custom Provider'da görünür. İstemci kimlik bilgilerinin belirteç uç noktasına nasıl gönderileceği seçilir:

Seçenek	Anlamı
Credentials in request body — client_secret_post (default)	Kimlik ve gizli anahtar istek gövdesinde gönderilir.
HTTP Basic header — client_secret_basic	Kimlik ve gizli anahtar Authorization: Basic başlığında gönderilir.
Public client — no client secret sent	Gizli anahtar gönderilmez; mobil ve tek sayfa uygulamalar gibi genel istemciler için, genellikle PKCE ile birlikte.

INFO

Enable PKCE Varsayılan: Disabled

Yalnızca Custom Provider'da görünür. Açıldığında yetkilendirme kodunun ele geçirilmesine karşı PKCE koruması uygulanır.

PKCE Challenge Method Varsayılan: SHA256 (Recommended)

Yalnızca Enable PKCE açıkken görüntülenir.

Seçenek	Anlamı
SHA256 (Recommended)	Doğrulayıcı SHA256 ile özetlenerek gönderilir.
Plain (Not Recommended)	Doğrulayıcı özetlenmeden gönderilir; yalnızca SHA256 desteklemeyen sağlayıcılar için.

INFO

User Info Request Method Varsayılan: GET with Bearer header (default)

Yalnızca Custom Provider'da görünür. Kullanıcı bilgisi uç noktasının nasıl çağrılacağı seçilir:

Seçenek	Anlamı
GET with Bearer Header (default)	Belirteç Authorization: Bearer başlığıyla GET isteğinde gönderilir.
POST Form Parameters	Bilgiler POST isteğinde form parametresi olarak gönderilir.

INFO

User Info Parameters Varsayılan: Disabled

Anahtar açıldığında kullanıcı bilgisi isteğine eklenecek ek parametreler için Parameter Name ve Parameter Value tablosu görüntülenir; her satırda iki alan da zorunludur ve Parameter Name değerleri tekrar etmez. Parametreler GET'te sorgu dizesine, POST'ta form gövdesine eklenir. Değerlerde {accessToken}, {clientId}, {clientSecret} ve {scope} yer tutucuları kullanılır.

INFO

Revoke Tokens on Logout Varsayılan: Disabled

Bir belirteç iptali adresi tanımlıyken görünür. Açıkken oturum kapatılırken oturumun belirteçleri sağlayıcının iptal uç noktasına gönderilir; sağlayıcı yanıt vermezse çıkış yine tamamlanır.

INFO

Sign Out from Provider on Logout Varsayılan: Disabled

Bir çıkış adresi tanımlıyken görünür. Açıkken yerel oturum kapatıldıktan sonra tarayıcı sağlayıcının çıkış adresine yönlendirilir; kapalıyken kullanıcı bir sonraki girişte sağlayıcıda hâlâ oturumu açık olduğu için parola sorulmadan içeri alınır.

INFO

JWKS URI

ID belirteci imzasının doğrulanacağı anahtar kümesinin (JSON Web Key Set) adresi (https://provider.com/.well-known/jwks.json gibi). Fetch Endpoints from Issuer ile doldurulur. Hazır sağlayıcılarda alan boş görünse de adres TR7'nin kataloğundan gelir; katalog her sağlayıcının anahtar adresini kendi biçiminde tutar (ör. Keycloak {tenant}/protocol/openid-connect/certs, Okta {tenant}/oauth2/v1/keys, Auth0 {tenant}/.well-known/jwks.json, GitLab {tenant}/oauth/discovery/keys). Custom Provider'da alan boş bırakıldığında adres yayıncı adresinden türetilir; türetilen adres sağlayıcının gerçek anahtar adresinden farklıysa imza doğrulaması yapılamaz, bu nedenle alan elle ya da keşifle doldurulmalıdır.

INFO

Skip Signature Verification Varsayılan: Disabled

Açıkken ID belirtecinin imzası doğrulanmaz. Yalnızca kendinden imzalı belirteçlerle yapılan testler için kullanılır; üretimde kapalı tutulmalıdır.

INFO

Skip Nonce Validation Varsayılan: Disabled

Açıkken tekrar saldırısı korumasını sağlayan nonce denetimi yapılmaz. Nonce değerini ID belirtecinde geri döndürmeyen sağlayıcılar (LinkedIn gibi) için açılır.

User Attribute Mapping

INFO

Custom User Attribute Mapping Varsayılan: No customisation

Sağlayıcı yanıtındaki alanların oturum özniteliklerine nasıl eşleneceği yönetilir. Alanın solundaki bilgi çubuğu, seçili sağlayıcı için otomatik eşlenen alan sayısını gösterir; Custom Provider'da bu sayı 15'tir: 15 fields are filled in automatically for this provider. Hazır sağlayıcılarda sayı değişir (ör. Google 8, e-Devlet 9, GitHub 6, X 4). Çubuktaki ok simgesine tıklandığında otomatik eşlenen satırlar ve her birinin JSONata ifadesi listelenir; satır başına ifadeyi JSONata çalışma alanında inceleyen bir çip ile kopyalama işlemleri bulunur. Otomatik eşlemesi olmayan sağlayıcılarda çubukta No automatic mapping for this provider - every attribute has to be mapped below yazar.

Sağdaki anahtar Customised konumuna alındığında AGS Attribute ve Source Attribute tablosu görüntülenir: sol kolonda oturum özniteliği (öneri listesiyle), sağ kolonda sağlayıcı yanıtı üzerinde değerlendirilen JSONata ifadesi girilir. Anahtar açıldığında çubuğun sağında satır ekleyen + Add bağlantısı belirir. Otomatik satırla aynı özniteliği hedefleyen özel satır otomatik olanı geçersiz kılar (replaced below rozeti) ve bilgi çubuğunun metni, kaç otomatik satırın değiştirildiğini de söyleyen … fields are filled in automatically; you replace … of them biçimine döner. AGS'nin standart öznitelikleri dışında bir ad girildiğinde bu öznitelik vService'te özel kullanıcı alanı olarak tanımlanır; _ ile başlayan adlar gizli alan sayılır ve özel kullanıcı alanı üretmez.

Lockout Configuration

INFO

Lockout Behavior Varsayılan: Use gateway defaults

Bu sağlayıcıdaki başarısız denemelerin hangi kilitleme politikalarıyla sayılacağı seçilir:

Seçenek	Anlamı
Use Gateway Defaults	vService'in Default Lockout Policies listesindeki politikalar kullanılır.
Replace Defaults	Yalnızca Lockout Policies alanında seçilen politikalar kullanılır.
Add to Defaults	vService'in varsayılan politikalarına ek olarak Lockout Policies alanında seçilenler de kullanılır.
No Lockout	Bu sağlayıcıda başarısız denemeler sayılmaz, kilitleme yapılmaz.

Lockout Policies

Replace Defaults ya da Add to Defaults seçiliyken görüntülenir; Account Lockout Policies ekranındaki hazır ve tanımlı politikalar seçilir.

INFO

Add

Add butonuna tıklanarak profil eklenir; sekme kapanır ve profil listede görüntülenir.

Fetch Endpoints from Issuer

Custom Provider seçili formdaki Fetch Endpoints from Issuer butonu, Issuer URL ve Route Table alanlı bir pencere açar. Girilen yayıncı adresine /.well-known/openid-configuration eklenerek keşif belgesi seçilen route tablosundan (varsayılan: profilin Namespace'i) alınır; tam .well-known adresi de yapıştırılabilir.

Authorization URL, Token URL ve JWKS URI her zaman doldurulur; User Info URL, Logout URL ve Token Revocation URL yalnızca keşif belgesinde duyurulmuşsa yazılır. Sağlayıcının duyurduğu openid profile email kapsamları eklenir, duyurulmuşsa Enable PKCE (SHA256) açılır ve Client Authentication için sağlayıcının desteklediği yöntemlerden client_secret_post, client_secret_basic ve none sırasıyla ilki seçilir.

http:// ya da https:// ile başlamayan adresler, yönlendirme yapan adresler, TR7'nin kendi adresleri, HTML sayfa döndüren adresler, 256 KB'ı aşan belgeler ve authorization_endpoint ya da token_endpoint alanını taşımayan belgeler reddedilir; getirme en fazla 8 saniye sürer. Başarı Endpoint fields were filled from the issuer's discovery document iletisiyle bildirilir. Hata iletisi Discovery failed: ile başlar, sağlayıcıdan gelen hatayı taşır ve Tip: enter the provider's identity/issuer address, not its website — it usually starts with accounts., login. or id. ipucuyla biter. İşlem kullanıcı işlem kaydına yazılmaz.