Download the PHP package globaltrustid/php without Composer

globaltrustid/php

GlobalTrustID'nin resmî PHP istemcisi. Üç işi yapar:

1. "GlobalTrustID ile giriş" — OAuth 2.0 / OpenID Connect, PKCE (S256) ile.
2. Kimlik doğrulama — QR oluşturur, kullanıcı telefonuyla onaylar, sonucu okursunuz.
3. Webhook doğrulama — gelen bildirimin gerçekten bizden geldiğini kanıtlar.

• Bağımlılık yok — yalnızca curl, json ve openssl eklentileri.
• PHP 5.6'dan 8.x'e kadar aynı kod. Eski paylaşımlı hostinglerde de çalışır.
• Laravel ve CodeIgniter için hazır entegrasyon.

İçindekiler

• Kurulum
• İki ayrı kimlik bilgisi
• 1. GlobalTrustID ile giriş
• 2. Kimlik doğrulama (QR)
• 3. Webhook
• Laravel
• CodeIgniter 4
• Alanlar (scope)
• API
• Composer olmadan
• Sık karşılaşılanlar

Kurulum

Gereken: PHP 5.6+, ext-curl, ext-json, ext-openssl.

İki ayrı kimlik bilgisi

Bu, çalışmayan entegrasyonların en sık sebebi. api_key ile client_secret aynı şey değildir:

sk_live_... bir API anahtarıdır ve api_key alanına yazılır — OAuth istemcisinin sırrı değildir. Yalnızca giriş yapacaksanız api_key'e, yalnızca kimlik doğrulaması yapacaksanız client_id/client_secret'a ihtiyacınız yok.

Public istemci kullanıyorsanız client_secret yazmayın. Tarayıcı ya da mobil uygulama sır saklayamaz; akışı PKCE korur. Panelde "Public istemci" kutusu bunun için.

1. GlobalTrustID ile giriş

Yönlendirme sayfası:

Callback sayfası:

handleCallback() PKCE verifier'ını ve state'i depodan okur, state'i sabit zamanlı karşılaştırır (CSRF), kodu token'a çevirir ve profili döner. Token'lar $user['_tokens'] altındadır.

loginUrl() çağrılmadan önce oturumun başlamış olması gerekir. Varsayılan depo $_SESSION kullanır ve gerekirse session_start()'ı kendisi çağırır.

2. Kimlik doğrulama (QR)

Kullanıcının kimliğini doğrulatmak için — giriş değil.

Kullanıcı QR'ı GlobalTrustID uygulamasıyla okutup onayladıktan sonra:

"Bu kişi kimliğini gerçekten doğruladı mı?"

Ad ve e-posta kullanıcının kendi yazdığı profilden de gelebilir; kimlik numarası ve belge numarası gelemez — onlar yalnızca çipten çıkar. Bu metot tam olarak buna bakar.

Sonuçları beklemek yerine size gönderilmesini isterseniz verify()'a bir webhook adresi verin.

3. Webhook

Bu adımı atlamayın. Webhook adresiniz herkese açıktır; imzayı doğrulamadan gövdeye güvenirseniz, size sahte bir approved gönderen herkes kimlik doğrulamasını atlatmış olur.

Gövdeyi JSON'a çevirip yeniden kodlarsanız boşluk ve anahtar sırası değişir, imza tutmaz. Ham baytları doğrulayın.

verifyWebhook() ayrıca zaman damgasına bakar: imza geçerli olsa bile 5 dakikadan eski bir istek reddedilir (replay koruması). Kuyruğa alınmış webhook'ları sonradan işliyorsanız $tolerance parametresini 0 yapın.

Laravel

Paket auto-discovery ile bulunur; config/app.php'ye bir şey eklemeniz gerekmez.

İstemciyi kapsayıcıdan alın, elle new Client(...) yazmayın: sağlayıcı onu Laravel oturumuyla kuruyor. Elle kurarsanız PKCE verifier'ı $_SESSION'a yazılır ve Laravel oturumu Redis/veritabanı sürücüsündeyse callback'te geri okunamaz.

Facade da var:

Tam örnek: examples/laravel/.

CodeIgniter 4

CI4'te kendini bağlayan bir sağlayıcı yok; istemciyi bir Services girdisiyle kurarsınız. Hazır dosyalar: examples/codeigniter/.

Alanlar (scope)

Kullanıcı onay ekranında tam olarak ne istediğinizi görür. İstemediğiniz hiçbir alan size gelmez.

"Yalnızca çipten" işaretli alanlar kullanıcının profilinden doldurulamaz; istemek, NFC ile belge okumasının yapılmış olmasını şart koşar. Listeyi kodda Client::chipOnlyScopes() ile alabilirsiniz.

age.over_18, yaş sınırı denetlemek için doğum tarihi istemenin yerine geçer: kullanıcı doğum gününü paylaşmadan reşit olduğunu kanıtlar.

address ve identity.passport_number HENÜZ İSTEMEYİN. Sunucunun keşif belgesinde (/.well-known/openid-configuration) görünüyorlar ama mobil uygulama bugün ikisini de dolduramıyor — kimlik cüzdanı özelliğiyle gelecekler. Onay için istenen ALANLARIN TAMAMININ dolu olması gerektiğinden, bu ikisini istemek oturumu onaylanamaz hâle getirir: kullanıcı "Onayla"ya basamaz ve sebebini anlamaz.

API

new Client(array $config)

OAuth

• loginUrl($scope = 'openid'): string
• handleCallback($query = null): array
• exchangeCode($code, $codeVerifier): array
• refresh($refreshToken): array
• userInfo($accessToken): array

Kimlik doğrulama

• verify($scope, $webhookUrl = ''): array
• result($sessionId): array
• isApproved($sessionId): bool
• isIdentityVerified($result): bool
• qrUrl($sessionId): string
• Client::chipOnlyScopes(): array

Webhook

• verifyWebhook($rawBody, $signature = null, $timestamp = null, $tolerance = 300): bool

Hatalar GlobalTrustID\Exception olarak fırlatılır.

Composer olmadan

Eski bir kurulumda Composer yoksa dosyaları doğrudan dahil edebilirsiniz:

Sık karşılaşılanlar

"client_secret gerekli" diyor ama public istemcim var. client_secret alanını hiç yazmayın. Boş bir dize göndermek sunucuya "sırrım var ama boş" demektir.

"state eşleşmedi (CSRF şüphesi)". Giriş başka bir tarayıcıda başlatılmış, oturum süresi dolmuş ya da oturum deposu iki istek arasında paylaşılmıyor. Laravel/CI4 kullanıyorsanız oturum deposunu doğru bağladığınızdan emin olun.

"oturum bulunamadı". loginUrl() ile handleCallback() farklı oturumlarda çalışıyor. Yük dengeleyici arkasındaysanız oturumların sunucular arasında paylaşıldığından emin olun.

Webhook imzası tutmuyor. Ham gövdeyi doğruluyor musunuz? $_POST, $request->all() ya da getJSON() gövdeyi çözüp yeniden kodlar ve imza artık tutmaz.

identity boş geliyor. Sonuçlar kalıcı saklanmaz, kısa süre sonra silinir. Onay gelir gelmez okuyun ya da webhook kullanın.

Destek

• Sorun bildirimi: GitHub Issues
• Dokümantasyon: docs.globaltrust.id

Lisans

MIT — bkz. LICENSE.