Her uygulamayı standart OAuth/OIDC üzerinden bağlayın.
OpenProof protokol sınırında programlama dilinden bağımsızdır. Sağlanan SDK’leri yararlı oldukları yerde kullanın veya HTTPS ile OAuth 2.0/OpenID Connect destekleyen herhangi bir dilden entegre edin.
Entegrasyon modeli
Your app ↓ redirect OpenProof /oauth/authorize ↓ authentication / provider / passkey / wallet ↓ your callback?code=...&state=...&iss=... ↓ code + verifier OpenProof /oauth/token ↓ access_token + id_token + optional refresh_token
Ürün entegrasyonu için OAuth/OIDC token’larını kullanın. Güvenli OpenProof oturum cookie’si OpenProof hesap/yönetim origin’ine aittir ve ürün domain’inize kopyalanmamalıdır.
Discovery ile başlayın
https://auth.example.com/.well-known/openid-configuration https://auth.example.com/.well-known/jwks.json
Yeniden kullanılabilir client’ların authorization, token, UserInfo, introspection ve ilgili protokol endpoint’lerini öğrenmesi için tercih edilen yöntem Discovery’dir.
Ürününüzü kaydedin
IAL2 seviyesinde aktif bir owner şunları kullanabilir: /admin/console veya administration API.
Application oluşturun
curl --fail-with-body -b owner.cookies \
https://auth.example.com/admin/applications \
-H 'Content-Type: application/json' \
-d '{
"identifier":"example-web",
"name":"Example Web",
"environment":"production"
}'Client oluşturun
curl --fail-with-body -b owner.cookies \
https://auth.example.com/admin/clients \
-H 'Content-Type: application/json' \
-d '{
"application_id":"APPLICATION_ID",
"name":"Example Web",
"kind":"web",
"redirect_uris":["https://app.example.com/oauth/callback"],
"scopes":["openid","profile","offline_access"]
}'| Tür | Tipik client | Secret |
|---|---|---|
browser | SPA / yalnızca tarayıcı | Yok |
native | iOS / Android / desktop | Yok |
web | Server-rendered / backend web uygulaması | Bir kez döner; yalnızca backend |
service | Makineden makineye | Bir kez döner |
Authorization Code + PKCE S256
Rastgele bir verifier üretin, S256 challenge’ını türetin ve rastgele state and nonce. üretin. verifier/state/nonce değerlerini yalnızca o giriş işleminin ömrü boyunca saklayın.
GET /oauth/authorize? response_type=code &client_id=CLIENT_ID &redirect_uri=https://app.example.com/oauth/callback &scope=openid profile offline_access &code_challenge=PKCE_CHALLENGE &code_challenge_method=S256 &state=STATE &nonce=NONCE
Callback sırasında dönen state and iss değerinin token exchange öncesinde işlem/yapılandırılmış issuer ile eşleşmesini zorunlu kılın.
Token exchange
curl --fail-with-body https://auth.example.com/oauth/token \ -H 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=authorization_code' \ --data-urlencode 'client_id=CLIENT_ID' \ --data-urlencode 'code=AUTHORIZATION_CODE' \ --data-urlencode 'redirect_uri=https://app.example.com/oauth/callback' \ --data-urlencode 'code_verifier=PKCE_VERIFIER'
ID token doğrulaması
RS256 imzasını issuer JWKS ile doğrulayın. En az şunları doğrulayın: iss, aud, exp, iat ve özgün nonce; ayrıca nbf, azp and at_hash varsa dikkate alın.
JavaScript / tarayıcı
Repository, tarayıcı odaklı şu SDK paketini sunar: @openproof/identity. Bu paket PKCE/state/nonce üretir, callback state/issuer değerlerini doğrular ve RS256 ID token’ını JWKS üzerinden kontrol eder.
import { OpenProofIdentity } from "@openproof/identity";
const identity = new OpenProofIdentity({
issuer: "https://auth.example.com",
clientId: "CLIENT_ID",
redirectUri: "https://app.example.com/oauth/callback",
scopes: ["openid", "profile", "offline_access"]
});
await identity.login();const tokens = await identity.handleCallback(); console.log(tokens.id_token_claims.sub); const profile = await identity.userInfo(tokens.access_token);
Gizli bir web or service client secret’ını kullanıcıya gönderilen JavaScript içine gömmeyin.
Node.js
Framework’ünüz için olgun bir OIDC client kullanın veya belgelenen protokol için native fetch() kullanın. Gizli credential’ları sunucu ortamınızda/secret store içinde tutun.
const body = new URLSearchParams({
grant_type: "authorization_code",
client_id: process.env.OPENPROOF_CLIENT_ID,
code,
redirect_uri: "https://app.example.com/oauth/callback",
code_verifier: verifier
});
const response = await fetch(
"https://auth.example.com/oauth/token",
{
method: "POST",
headers: {
"content-type":
"application/x-www-form-urlencoded"
},
body
}
);
if (!response.ok) {
throw new Error(
`OpenProof token exchange failed: ${response.status}`
);
}
const tokens = await response.json();JWKS cache, imza doğrulama ve claim doğrulama için kriptografik doğrulamayı kendiniz yazmak yerine bir OIDC/JWT kütüphanesi kullanın.
PHP
Bakımı yapılan herhangi bir PHP OAuth/OIDC kütüphanesi OpenProof’u issuer olarak kullanabilir. Doğrudan protokol normal HTTPS ve form-encoded OAuth’tur.
<?php
$payload = http_build_query([
'grant_type' => 'authorization_code',
'client_id' => getenv('OPENPROOF_CLIENT_ID'),
'code' => $_GET['code'],
'redirect_uri' =>
'https://app.example.com/oauth/callback',
'code_verifier' =>
$_SESSION['openproof_pkce_verifier'],
]);
$curl = curl_init(
'https://auth.example.com/oauth/token'
);
curl_setopt_array($curl, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $payload,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/x-www-form-urlencoded'
],
]);
$body = curl_exec($curl);
if ($body === false) {
throw new RuntimeException(curl_error($curl));
}ID token’larını bakımı yapılan bir JWT/OIDC paketi ve issuer JWKS ile doğrulayın. RSA/JWK doğrulamasını ad hoc uygulamayın.
C++
Repository içindeki C++26 SDK şu adla export edilir: openproof.sdk. Transport katmanından bağımsızdır; mevcut Boost.Beast, Qt Network veya libcurl stack’inizi koruyabilirsiniz.
import openproof.sdk;
auto config =
openproof::sdk::ClientConfig::create(
"https://auth.example.com",
"CLIENT_ID",
"http://127.0.0.1:49152/callback",
{"openid", "profile", "offline_access"});
openproof::sdk::IdentityClient client{
std::move(config).value()
};
auto login = client.beginLogin();
std::cout <<
login->authorizationUrl()
<< '\n';SDK; giriş işlemi oluşturma, authorization-code isteği kurma, refresh ve UserInfo için helper’lar sağlar. Minimal bir relying-party örneği şurada bulunur: examples/reference-client.
Python, Go, Rust, Java, C# ve diğer diller
OpenProof’a özel bir SDK’ye ihtiyacınız yoktur. Standartlara uyumlu bir OAuth/OIDC kütüphanesini OpenProof issuer ile yapılandırın. Minimum güvenli uygulama sırası: Discovery → PKCE/state/nonce → authorization redirect → callback kontrolleri → token exchange → JWKS imza/claim doğrulaması → access-token authorization.
UserInfo ve refresh
curl --fail-with-body \ https://auth.example.com/oauth/userinfo \ -H 'Authorization: Bearer ACCESS_TOKEN'
curl --fail-with-body \ https://auth.example.com/oauth/token \ -H 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=refresh_token' \ --data-urlencode 'client_id=CLIENT_ID' \ --data-urlencode 'refresh_token=REFRESH_TOKEN'
Refresh token’lar rotate edilir. Yeni token’ı atomik olarak saklayın ve eski değeri atın. Replay koruması tüm aileyi revoke edebilir.
API’nizi koruyun
Tam audience ve dar kapsamlı scope’larla bir resource kaydedin.
curl --fail-with-body -b owner.cookies \
https://auth.example.com/admin/resources \
-H 'Content-Type: application/json' \
-d '{
"audience":"https://api.example.com/rides",
"name":"Ride API",
"scopes":["rides:read","rides:request"]
}'Backend’iniz token geçerliliğini, tam audience’ı, gerekli scope’u ve ürün iş kurallarını authorize etmelidir. Geçerli bir token tek başına yeterli authorization değildir.
Introspection
curl --fail-with-body \ https://auth.example.com/oauth/introspect \ -H 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'client_id=CONFIDENTIAL_CLIENT_ID' \ --data-urlencode 'client_secret=CLIENT_SECRET' \ --data-urlencode 'token=ACCESS_TOKEN'
OpenProof gateway
Alternatif olarak ürün route’larını OpenProof arkasına koyun ve backend’e proxy etmeden önce statik route policy içinde role, assurance, scope ve audience uygulayın.
Servisten servise
Bir service client kullanın, izin verilen audience/scope’ları provision edin ve ardından şu yöntemle access token isteyin: client_credentials.
curl --fail-with-body \ https://auth.example.com/oauth/token \ -H 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'client_id=CLIENT_ID' \ --data-urlencode 'client_secret=CLIENT_SECRET' \ --data-urlencode 'scope=rides:dispatch' \ --data-urlencode 'resource=https://api.example.com/dispatch'
Sonuç yalnızca access token’dır. Refresh token veya insan oturumu yoktur.
Hesap API’leri
Hesap self-service ve verification delivery etkin olduğunda OpenProof; kayıt, doğrulanmış e-posta/telefon sahipliği, parola sıfırlama, profil, TOTP, recovery code ve passkey işlevlerini sunar.
| Amaç | Endpoint |
|---|---|
| Kayıt | POST /account/signup |
| E-posta doğrulama | POST /account/email/verify |
| Parola sıfırlamayı başlat | POST /account/password/forgot |
| Parola sıfırlamayı tamamla | POST /account/password/reset |
| Profil | GET/PATCH /account/profile |
| TOTP kaydı | POST /account/totp/start → /complete |
| Passkey ile giriş | POST /auth/passkey/options → /verify |
| Bağlı yöntemler | GET /account/connections |
Ürün kullanıcınızı Google/GitHub e-postasına göre key etmeyin. Kullanıcı aynı stabil OpenProof subject’ini korurken birden fazla giriş yöntemini bağlayabilir.
Hata yönetimi ve secret hijyeni
Hatalar stabil bir code, client için güvenli mesaj ve request ID içerir. Metne değil code/status değerine göre dallanın. 401’i eksik/geçersiz kimlik doğrulama, 403’ü yetersiz yetki/assurance, 409’u state çatışması ve 429’u backoff sinyali olarak ele alın.
Parola, TOTP/recovery code, verification secret, authorization code, access/refresh token, gizli client secret, cookie, DPoP proof veya private key değerlerini asla loglamayın.