OAuth Uygulamaları

Kendi ürününüzde "GlobalTrustID ile giriş yap" düğmesi sunun. Kullanıcı GlobalTrustID hesabıyla oturum açar, hangi bilgileri paylaşacağını görür ve siz doğrulanmış bir kimlikle başlarsınız.

Standart OpenID Connect: kendi dilinizdeki hazır bir OIDC kütüphanesi çalışır, özel bir istemci yazmanız gerekmez.

Doğrulama oturumu ile farkı#

Scope sözlüğü ortaktır: doğrulama oturumunda identity.first_name isteyen bir entegrasyon, OAuth'a geçtiğinde aynı adı kullanmaya devam eder. Bkz. Scope sözlüğü.

1. Uygulamanızı kaydedin#

Panelde Entegrasyonlar → OAuth uygulamaları bölümünden uygulama oluşturun. Vereceğiniz şeyler:

• Ad — kullanıcı onay ekranında bunu görür.
• Yönlendirme adresleri — tarayıcının geri döneceği adresler. Tam eşleşme aranır; listede olmayan bir adrese asla yönlendirme yapılmaz.
• İzinli scope'lar — uygulamanın isteyebileceği alanlar.
• Cihaz üstü giriş — yalnızca mobil uygulamalar için. İşaretlendiğinde yönlendirme adresi olarak ters-DNS bir şema (com.sirketiniz.uygulama://gti) ya da loopback adresi de kabul edilir. Bkz. React Native.

Karşılığında client_id (gtid_ ile başlar) ve gizli istemci seçtiyseniz client_secret (gtis_ ile başlar) alırsınız.

Gizli mi, public mi#

Sırrı saklayamayacak bir yerde çalışıyorsanız (tek sayfa uygulama, mobil) public istemci seçin. Sırrı tarayıcıya koymak, sırrı hiç kullanmamakla aynı şeydir — üstelik sakladığınız yanılgısıyla.

2. Keşif belgesi#

Uç noktaları elle yazmayın, kütüphanenize bu adresi verin:

https://globaltrust.id/.well-known/openid-configuration

Desteklenenler: response_type=code, authorization_code ve refresh_token grant'leri, PKCE S256 / plain, id_token imzası RS256.

3. Kullanıcıyı yönlendirin#

https://globaltrust.id/oauth/authorize
  ?client_id=gtid_...
  &redirect_uri=https://sizin-siteniz.com/callback
  &response_type=code
  &scope=openid%20identity.first_name%20identity.last_name
  &state=RASTGELE_DEGER
  &code_challenge=PKCE_CHALLENGE
  &code_challenge_method=S256

Kullanıcı bir QR onay ekranı görür: telefonundaki GlobalTrustID uygulamasıyla okutur, hangi alanları paylaşacağını görür ve onaylar. Onay verildiğinde tarayıcı redirect_uri'nize döner:

https://sizin-siteniz.com/callback?code=...&state=RASTGELE_DEGER

4. Kodu token ile değişin#

curl -X POST https://globaltrust.id/oauth/token \
  -d grant_type=authorization_code \
  -d code=AUTH_CODE \
  -d redirect_uri=https://sizin-siteniz.com/callback \
  -d client_id=gtid_... \
  -d client_secret=GIZLI_ANAHTAR \
  -d code_verifier=PKCE_VERIFIER

İstemci kimliğini gövdede (client_secret_post) ya da Authorization: Basic başlığında (client_secret_basic) gönderebilirsiniz. Public istemciler ikisini de göndermez, yalnızca code_verifier ile doğrulanır.

{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "...",
  "id_token": "eyJhbGciOiJSUzI1NiIs...",
  "scope": "openid identity.first_name identity.last_name"
}

Kod tek kullanımlıktır. İkinci kez denenirse invalid_grant alırsınız — bu bir hata değil, sızmış bir kodun kullanılmasını engelleyen kasıtlı davranıştır.

5. Kimliği okuyun#

İki yol var ve aynı veriyi verirler.

id_token içinden (önerilen)#

İmzalı bir JWT. JWKS ile doğrulayın, ekstra istek gerekmez.

/oauth/userinfo ile#

curl https://globaltrust.id/oauth/userinfo \
  -H "Authorization: Bearer ACCESS_TOKEN"

Claim karşılıkları#

given_name ve family_name birlikte geldiğinde name de üretilir.

6. Oturumu yenileyin#

curl -X POST https://globaltrust.id/oauth/token \
  -d grant_type=refresh_token \
  -d refresh_token=REFRESH_TOKEN \
  -d client_id=gtid_...

Faturalandırma#

Her tamamlanan giriş, istenen scope'lara göre kontör harcar — doğrulama oturumlarıyla aynı tarife. Yalnızca openid isteyen bir giriş en ucuz seçenektir. Bkz. Bir sorgu kaç kontör.

Sosyal hesap doğrulaması ile karıştırmayın#

GlobalTrustID mobil uygulamasında kullanıcıların Instagram hesabını doğrulayabildiği bir akış vardır. Bu, uygulamanın kendi içindeki bir doğrulama adımıdır — entegratörlerin kullanacağı bir OAuth arayüzü değildir ve bu sayfada anlatılan özellikle ilgisi yoktur.

Hata alırsanız#

"Yönlendirme adresi kayıtlı değil" ekranı görüyorsanız redirect_uri panelde tanımlı olanla birebir aynı değildir — sondaki eğik çizgi bile fark eder.