Kimlik Doğrulama

Bu API, sistemden sisteme Client Credentials tarzı bir kimlik doğrulama modeli kullanır.

Tam kapsamlı bağımsız bir OAuth Authorization Server değildir. Standartlara uygun bir token uç noktası ve korunan API rotaları için Bearer JWT koruması sağlar.

İlk sürüm modeli

Karar	Değer
Akış	Client Credentials
Client sayısı	Tek standart integration client
Kimlik bilgisi kaynağı	Ortam değişkenleri (.env)
Token isteği kimlik doğrulaması	HTTP Basic
Access token	JWT (HS256)
Varsayılan süre	60 dakika (expires_in=3600)
Refresh token	Desteklenmez
Scope	Desteklenmez
MongoDB client kaydı	Kullanılmaz

Yapılandırma

Değişken	Varsayılan	Notlar
AUTH_ENABLED	false	Token uç noktasını ve Bearer korumasını açar
AUTH_CLIENT_ID	boş	Açıkken zorunlu
AUTH_CLIENT_SECRET	boş	Açıkken zorunlu, en az 32 karakter
AUTH_JWT_SECRET	boş	Açıkken zorunlu, en az 32 byte, client secret ile aynı olamaz
AUTH_ISSUER	iqv-integration-api	JWT iss
AUTH_AUDIENCE	iqv-integration-api	JWT aud
AUTH_ACCESS_TOKEN_TTL	60m	Pozitif, en fazla 24 saat
AUTH_TOKEN_MAX_BODY_BYTES	16384	Token uç noktası gövde limiti

AUTH_ENABLED=false

• Token uç noktası kaydedilmez (404)
• POST /api/v1/inbound/work-orders Bearer token olmadan açık kalır
• Yerel geliştirme için uygundur

AUTH_ENABLED=true

Örnek:

env AUTH_ENABLED=true AUTH_CLIENT_ID=iqv-standard-integration AUTH_CLIENT_SECRET= AUTH_JWT_SECRET= AUTH_ISSUER=iqv-integration-api AUTH_AUDIENCE=iqv-integration-api AUTH_ACCESS_TOKEN_TTL=60m

Secret üretimi (depo içine yazmayın):

```powershell

48 karakterlik rastgele secret örneği (sonucu commit etmeyin)

$alphabet = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789' -join (1..48 | ForEach-Object { $alphabet[(Get-Random -Maximum $alphabet.Length)] }) ```

Production ortamında kriptografik olarak güvenli bir secret yönetim aracı tercih edin.

Token uç noktası

text POST {PUBLIC_BASE_URL}/api/v1/auth/token

İstek

Başlıklar:

http Authorization: Basic BASE64(client_id:client_secret) Content-Type: application/x-www-form-urlencoded Accept: application/json

Gövde:

text grant_type=client_credentials

Kurallar:

• Kimlik bilgileri yalnız Basic Authorization başlığından alınır
• client_id / client_secret gövdeye veya query string’e yazılmaz
• JSON gövdeler reddedilir (415)
• Token uç noktası yalnız JSON yanıt üretir

Başarılı yanıt

json { "success": true, "request_id": "uuid", "data": { "access_token": "jwt-token", "token_type": "Bearer", "expires_in": 3600 }, "error": null }

Yanıt başlıkları Cache-Control: no-store ve Pragma: no-cache içerir.

Access token kullanımı

Korunan uç noktalar şunu ister:

http Authorization: Bearer <access_token>

İş emri örneği:

http POST {PUBLIC_BASE_URL}/api/v1/inbound/work-orders Authorization: Bearer <access_token> Content-Type: application/json Accept: application/json

XML isteklerinde de aynı Authorization başlığı kullanılır:

http POST {PUBLIC_BASE_URL}/api/v1/inbound/work-orders Authorization: Bearer <access_token> Content-Type: application/xml Accept: application/xml

Client çalışma rehberi (ERP / cron)

1. Client credentials ile token alın.
2. Tokenı güvenli bellek/cache alanında saklayın.
3. Süresi dolmamış token ile POST (ve ileride GET) isteklerini gönderin.
4. Her cron çalışmasında yeniden token almayın.
5. Token yoksa, süresi dolmuşsa veya bitmesine 5 dakikadan az kaldıysa yenileyin.
6. Refresh token kullanmayın.
7. API 401 dönerse bir kez yeni token alıp isteği tekrar deneyin.

Public ve korunan rotalar

Public:

• GET /
• GET /health/live
• GET /health/ready
• GET /health/details (mevcut etkinleştirme kuralları aynı)
• POST /api/v1/auth/token (yalnız auth açıksa)

AUTH_ENABLED=true iken korunan:

• POST /api/v1/inbound/work-orders

Taşıma güvenliği

• Production ortamında HTTPS / TLS zorunludur.
• Yerel geliştirmede güvenilir ağlarda HTTP kullanılabilir.
• Client secret veya access token’ı güvenilmeyen açık metin kanallardan göndermeyin.

Hata kodları

Kod	HTTP	Anlam
INVALID_REQUEST	400	Eksik grant_type veya hatalı token isteği
UNSUPPORTED_GRANT_TYPE	400	grant_type değeri client_credentials değil
INVALID_CLIENT	401	Basic client kimlik doğrulaması başarısız
AUTHENTICATION_REQUIRED	401	Bearer token eksik
INVALID_TOKEN	401	Bearer token geçersiz veya süresi dolmuş
NOT_ACCEPTABLE	406	Token uç noktasında desteklenmeyen Accept
PAYLOAD_TOO_LARGE	413	Token gövdesi limiti aşıldı
UNSUPPORTED_MEDIA_TYPE	415	Form olmayan token Content-Type
INTERNAL_ERROR	500	Beklenmeyen hata

Postman

1. {PUBLIC_BASE_URL}/api/v1/auth/token adresine POST isteği oluşturun.
2. Authorization sekmesi: Type Basic Auth, username = client id, password = client secret.
3. Body: x-www-form-urlencoded, grant_type = client_credentials.
4. Headers: Accept: application/json.
5. data.access_token değerini kopyalayın.
6. İş emri isteklerinde Authorization tipini Bearer Token yapın.

PowerShell örneği

```powershell $baseUrl = $env:PUBLIC_BASE_URL

Token isteği (curl.exe)

$tokenJson = curl.exe -sS -X POST "$baseUrl/api/v1/auth/token" -u "$($env:AUTH_CLIENT_ID):$($env:AUTH_CLIENT_SECRET)" -H "Content-Type: application/x-www-form-urlencoded" -H "Accept: application/json" -d "grant_type=client_credentials"

$tokenResponse = $tokenJson | ConvertFrom-Json $accessToken = $tokenResponse.data.access_token

curl.exe -sS -X POST "$baseUrl/api/v1/inbound/work-orders" -H "Authorization: Bearer $accessToken" -H "Content-Type: application/json" -H "Accept: application/json" --data-binary "@work-order.json" ```

curl örneği

```bash BASE_URL="${PUBLIC_BASE_URL}"

curl -sS -X POST "${BASE_URL}/api/v1/auth/token" \ -u "${AUTH_CLIENT_ID}:${AUTH_CLIENT_SECRET}" \ -H "Content-Type: application/x-www-form-urlencoded" \ -H "Accept: application/json" \ -d "grant_type=client_credentials"

curl -sS -X POST "${BASE_URL}/api/v1/inbound/work-orders" \ -H "Authorization: Bearer ${ACCESS_TOKEN}" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ --data-binary @work-order.json ```

Production sertleştirme takip maddeleri

Bu branch’te uygulanmamıştır; sonraki aşamada önerilir:

• Token uç noktası rate limiting
• Secret rotation prosedürleri
• Gerekirse çoklu client kaydı