Kimlik Doğrulama

Platformun kimlik sağlayıcısı Keycloak 26’dır ve https://tfs-auth.karyabilisim.com adresinde tfs realm’i ile hizmet verir. API’ler kimliği Authorization: Bearer <token> başlığından alır:

GET /api/v1/contracts/ctr_01J8ZK4T2M HTTP/1.1
Host: tfs-api.karyabilisim.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

OIDC uçları

Uç	Adres
Discovery	`https://tfs-auth.karyabilisim.com/realms/tfs/.well-known/openid-configuration`
`authorization_endpoint`	`https://tfs-auth.karyabilisim.com/realms/tfs/protocol/openid-connect/auth`
`token_endpoint`	`https://tfs-auth.karyabilisim.com/realms/tfs/protocol/openid-connect/token`

Uç adreslerini koda gömmek yerine discovery belgesinden çözmeniz önerilir.

SPA’lar: Authorization Code + PKCE (S256)

Tek sayfa uygulamalar (ör. operasyon konsolunun tfs-ops public client’ı) client secret taşımaz; Authorization Code + PKCE (S256) akışı kullanılır:

Uygulama rastgele bir code_verifier üretir ve SHA-256 özetinden code_challenge değerini türetir.
Kullanıcı authorization_endpoint’e yönlendirilir (response_type=code, code_challenge_method=S256).
Keycloak, girişin ardından uygulamaya kısa ömürlü bir code döndürür.
Uygulama code + code_verifier ikilisini token_endpoint’e göndererek erişim jetonunu alır; Keycloak, verifier’ın özetinin challenge ile eşleştiğini doğrular.

Jetonun içeriği: izin kodları

Erişim jetonları tfs-core-api audience’ı ile kesilir. Realm rolleri, platformun izin kodlarının kendisidir (ör. party:create, contract:approve); API’ler izinleri jetonun realm_access.roles alanından okur:

{
  "aud": "tfs-core-api",
  "azp": "tfs-ops",
  "preferred_username": "ops-user-1",
  "realm_access": {
    "roles": ["party:create", "contract:approve", "report:prepare"]
  }
}

Uçlar izin tabanlıdır; örneğin sözleşme onayı contract:approve ister. Dört göz ilkesine tabi uçlarda hazırlayan ile onaylayan aynı kullanıcı olamaz — aksi halde 409 ve FOUR_EYES_SAME_USER döner.

Test için parola akışı

Entegrasyon testlerinde tarayıcı akışı yerine password grant ile jeton alabilirsiniz:

curl -s "https://tfs-auth.karyabilisim.com/realms/tfs/protocol/openid-connect/token" \
  -d "grant_type=password" \
  -d "client_id=tfs-ops" \
  -d "username=ops-user-1" \
  -d "password=<parola>"

Yanıttaki access_token değerini Authorization: Bearer başlığına koyun.

Geliştirici başlıkları — dağıtılmış ortamlarda reddedilir

x-dev-user, x-dev-permissions, x-dev-party ve x-dev-partner başlıkları yalnızca yerel geliştirme içindir. Bir kimlik sağlayıcı yapılandırılmışsa (OIDC_ISSUER) her iki API yüzeyi de bunları reddeder — tfs-api.karyabilisim.com dâhil.

Bu bir düzen tercihi değil. x-dev-permissions olduğu gibi kabul edilir: çağıran hangi izni yazarsa onu alır. Ortada kimlik sağlayıcı yokken ve arkasında gerçek veri yokken bu zararsızdır. Sağlayıcı varken tam bir kimlik doğrulama ve yetkilendirme atlatmasıdır — URL’e erişebilen herkes kendini onaylayıcı ilan edip tüm sözleşme kütüğünü okuyabilir, sözleşme onaylayabilir, ödeme yaptırabilir ya da herhangi bir partyId yazıp o müşterinin sözleşmelerini /api/v1/my/* üzerinden görebilirdi. Dağıtılmış platform 27 Ağustos 2026’ya kadar bunu kabul ediyordu.

Dolayısıyla dağıtılmış bir ortama karşı gerçek bir jeton gerekir: betikler için yukarıdaki password grant, tarayıcılar için PKCE. Dev başlığı gönderen her istek MSG-G-12 alır.