OpenID Connect - Flextell

Flextell, OAuth 2.0 üzerine OpenID Connect 1.0 katmanı sunar. OIDC sayesinde yalnızca API’ye erişim değil, kullanıcının kimliğini doğrulama (sign-in) akışı da kurabilirsiniz — Flextell’i bir “Sign in with Flextell” identity provider olarak kullanabilirsiniz.

OIDC akışı, standart Authorization Code akışı ile aynı uçları kullanır. Tek yapmanız gereken scope parametresine openid eklemek ve dönen id_token’ı işlemek.

Temel farkları

Düz OAuth 2.0	OIDC (OAuth 2.0 + `openid` scope)
`access_token` + `refresh_token`	`access_token` + `refresh_token` + `id_token`
API’yi çağırmanın yetkisi	+ Kullanıcının kim olduğunun kanıtı
`/oauth/token`	Aynı + `/oauth/userinfo`, `/oauth/jwks`, `/.well-known/openid-configuration`

Discovery

Uçlarımızı kod tarafında sabitlemek yerine discovery URL’i çekerek dinamik olarak öğrenin:

GET https://dev.flextell.ai/.well-known/openid-configuration

Örnek yanıt

{
  "issuer": "https://dev.flextell.ai",
  "authorization_endpoint": "https://dev.flextell.ai/oauth/authorize",
  "token_endpoint": "https://dev.flextell.ai/oauth/token",
  "userinfo_endpoint": "https://dev.flextell.ai/oauth/userinfo",
  "jwks_uri": "https://dev.flextell.ai/oauth/jwks",
  "end_session_endpoint": "https://dev.flextell.ai/oauth/logout",
  "response_types_supported": ["code"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"],
  "scopes_supported": ["openid", "profile", "email", "phone", "..."],
  "code_challenge_methods_supported": ["plain", "S256"],
  "grant_types_supported": ["authorization_code", "refresh_token"]
}

Çoğu OIDC kütüphanesi (örn. openid-client Node, python-jose + authlib, AppAuth iOS/Android) yalnızca issuer URL’ini verdiğinizde discovery’yi otomatik yapar. Uçları manuel yazmak yerine bu yolu tercih edin.

`openid` scope’u ile yetki alma

Standart Authorization Code isteğine openid scope’unu ekleyin. Kullanıcı bilgilerini de almak istiyorsanız profile, email, phone scope’larını da ekleyebilirsiniz:

https://dev.flextell.ai/oauth/authorize
  ?response_type=code
  &client_id=SIZIN_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
  &scope=openid%20profile%20email
  &state=RASTGELE_STRING

Token yanıtı

openid scope’u talep edildiğinde /oauth/token yanıtına ekstra id_token alanı eklenir:

{
  "token_type": "Bearer",
  "expires_in": 1296000,
  "access_token": "eyJ0eXAiOiJKV1Q...",
  "refresh_token": "def502004d...",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

id_token nedir?

id_token RS256 ile imzalanmış bir JWT’dir. İçinde “bu access token’ı falanca kullanıcı aldı” ifadesinin imzalı kanıtı vardır.

Örnek payload (decode edilmiş)

{
  "iss": "https://dev.flextell.ai",
  "aud": "SIZIN_CLIENT_ID",
  "sub": "42",
  "iat": 1713515400,
  "exp": 1713519000,
  "name": "Ayşe Yılmaz",
  "email": "ayse@example.com",
  "phone_number": "+905551234567"
}

Alanlar

string

Token’ı üreten kimlik sağlayıcı. Her zaman https://dev.flextell.ai veya production’da https://app.flextell.ai.

string

Token’ın kimin için üretildiği — sizin client_id’niz. Kabul etmeden önce mutlaka doğrulayın; değilse token size ait değildir.

string

Kullanıcının Flextell’deki kalıcı ID’si. Kendi veritabanınızdaki hesabı bağlamak için bu değeri saklayın. E-posta değişse bile sub değişmez.

integer

Token’ın üretildiği Unix timestamp.

integer

Token’ın geçerlilik süresinin sonu (Unix timestamp).

string

Kullanıcının ad soyadı (yalnızca profile scope’u talep edildiyse).

string

Kullanıcının e-posta adresi (yalnızca email scope’u talep edildiyse).

string

Kullanıcının telefon numarası (yalnızca phone scope’u talep edildiyse).

Scope → claim eşlemesi

Scope	Eklenen claim’ler
`openid`	`sub` (zorunlu)
`profile`	`name`
`email`	`email`
`phone`	`phone_number`

id_token doğrulama

Flextell’den gelen id_token’ı backend’inizde mutlaka doğrulamanız gerekir. Asla imza kontrol etmeden güvenmeyin:

JWKS uçtan genel anahtarı çekin

GET https://dev.flextell.ai/oauth/jwks

Bu URL, RS256 doğrulaması için gereken RSA public key’leri JWK formatında döner. Kütüphaneniz bu anahtarı cache’leyebilir.

İmzayı RS256 ile doğrulayın

JWT’nin header’ı {"alg": "RS256", "typ": "JWT"} olmalıdır. Public key ile imza eşleşmiyorsa token’ı reddedin.

Claim'leri doğrulayın

iss → https://dev.flextell.ai veya https://app.flextell.ai olmalı.
aud → sizin client_id’niz olmalı.
exp → şimdiki zamandan büyük olmalı (saat farkı için ±60 sn tolerans tipiktir).
iat → gelecek bir zaman olmamalı.

Node.js (jose kütüphanesi) örneği

import { createRemoteJWKSet, jwtVerify } from "jose";

const JWKS = createRemoteJWKSet(new URL("https://dev.flextell.ai/oauth/jwks"));

const { payload } = await jwtVerify(idToken, JWKS, {
  issuer: "https://dev.flextell.ai",
  audience: process.env.FLEXTELL_CLIENT_ID,
});

// payload.sub → kullanıcı ID'si (kendi DB'nizde flextell_user_id olarak saklayın)
// payload.email, payload.name → profil bilgileri

UserInfo endpoint’i

id_token içindeki claim’ler dışında, access token ile /oauth/userinfo endpoint’ine istek atarak aynı bilgileri canlı olarak sorgulayabilirsiniz. Kullanıcı daha sonra profil bilgilerini değiştirdiyse güncel hali burada döner:

curl --request GET \
  --url https://dev.flextell.ai/oauth/userinfo \
  --header "Authorization: Bearer SIZIN_ACCESS_TOKEN"

Yanıt

{
  "sub": "42",
  "name": "Ayşe Yılmaz",
  "email": "ayse@example.com",
  "phone_number": "+905551234567"
}

Dönen alanlar access token’da onaylanmış scope’lara göre filtrelenir. Örneğin token’da yalnızca openid varsa sadece sub döner.

Logout (end_session_endpoint)

OIDC standart çıkış akışı için Token İptali → OpenID Connect ile oturum sonlandırma sayfasına bakın.

PKCE ile güvenli istemciler

SPA veya native mobil uygulamalar client_secret saklayamadığı için OIDC akışını PKCE (Proof Key for Code Exchange) ile kullanmalıdır. Detaylar: PKCE Akışı.

Sık sorulanlar

id_token’ı API isteklerinde Bearer olarak kullanabilir miyim? Hayır. id_token kimlik kanıtıdır, yetki tokeni değildir. API’ye erişim için her zaman access_token kullanın. id_token’ı yenileyebilir miyim? Evet. Refresh token ile yeni bir access token aldığınızda — eğer orijinal istek openid scope’u içeriyordu — yanıtta yeni bir id_token da döner. Claim’lerde hangi kullanıcı adı döner? name claim’i kullanıcının Flextell hesabındaki “Ad Soyad” alanıdır. Boşsa claim de boş gelir. phone_number_verified gibi standart OIDC claim’leri destekleniyor mu? Şu anda yalnızca sub, name, email, phone_number dönüyor. Yeni claim’ler eklendiğinde Changelog’da duyurulacak.

Sonraki adımlar

PKCE Akışı

SPA ve mobil uygulamalar için güvenli code exchange.

Token İptali

end_session_endpoint ile tek seferde logout.

Scopes

openid, profile, email, phone izinleri.

Authorization Code

OAuth akışının tüm detayları.

​Temel farkları

​Discovery

​Örnek yanıt

​openid scope’u ile yetki alma

​Token yanıtı

​id_token nedir?

​Örnek payload (decode edilmiş)

​Alanlar

​Scope → claim eşlemesi

​id_token doğrulama

​Node.js (jose kütüphanesi) örneği

​UserInfo endpoint’i

​Yanıt

​Logout (end_session_endpoint)

​PKCE ile güvenli istemciler

​Sık sorulanlar

​Sonraki adımlar

PKCE Akışı

Token İptali

Scopes

Authorization Code

Temel farkları

Discovery

Örnek yanıt

`openid` scope’u ile yetki alma

Token yanıtı

id_token nedir?

Örnek payload (decode edilmiş)

Alanlar

Scope → claim eşlemesi

id_token doğrulama

Node.js (jose kütüphanesi) örneği

UserInfo endpoint’i

Yanıt

Logout (end_session_endpoint)

PKCE ile güvenli istemciler

Sık sorulanlar

Sonraki adımlar