Genyleap/Docs
OpenProof / Geliştirme

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

akışAuthorization Code + PKCE
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

URL’lerauth.example.com değerini değiştirin
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

curlowner oturumu gerekli
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

curlweb client
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ürTipik clientSecret
browserSPA / yalnızca tarayıcıYok
nativeiOS / Android / desktopYok
webServer-rendered / backend web uygulamasıBir kez döner; yalnızca backend
serviceMakineden makineyeBir 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.

authorization isteğikavramsal
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

curlapplication/x-www-form-urlencoded
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.

javascriptpublic browser client
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();
javascriptcallback
const tokens = await identity.handleCallback();

console.log(tokens.id_token_claims.sub);

const profile =
  await identity.userInfo(tokens.access_token);
Tarayıcı client’larının client secret’ı yoktur.

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.

javascriptserver-side token exchange
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.

phptoken exchange
<?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.

c++SDK yapılandırması
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

curlUserInfo
curl --fail-with-body \
  https://auth.example.com/oauth/userinfo \
  -H 'Authorization: Bearer ACCESS_TOKEN'
curlrefresh 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.

curlresource kaydet
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

curlgizli backend
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.

curlmachine grant
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ıtPOST /account/signup
E-posta doğrulamaPOST /account/email/verify
Parola sıfırlamayı başlatPOST /account/password/forgot
Parola sıfırlamayı tamamlaPOST /account/password/reset
ProfilGET/PATCH /account/profile
TOTP kaydıPOST /account/totp/start/complete
Passkey ile girişPOST /auth/passkey/options/verify
Bağlı yöntemlerGET /account/connections
Tek kanonik kimlik.

Ü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.