Genyleap/Docs
OpenProof / Entwicklung

Binden Sie jede Anwendung über standardkonformes OAuth/OIDC an.

OpenProof ist an der Protokollgrenze sprachunabhängig. Verwenden Sie die mitgelieferten SDKs dort, wo sie helfen, oder integrieren Sie aus jeder Sprache, die HTTPS und OAuth 2.0/OpenID Connect unterstützt.

Das Integrationsmodell

AblaufAuthorization 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

Verwenden Sie OAuth/OIDC-Token für die Produktintegration. Das sichere OpenProof-Sitzungscookie gehört zum OpenProof-Account-/Admin-Origin und darf nicht in Ihre Produktdomain kopiert werden.

Mit Discovery beginnen

URLsauth.example.com ersetzen
https://auth.example.com/.well-known/openid-configuration
https://auth.example.com/.well-known/jwks.json

Discovery ist der bevorzugte Weg für wiederverwendbare Clients, um Authorization-, Token-, UserInfo-, Introspection- und weitere Protokollendpunkte zu ermitteln.

Produkt registrieren

Ein aktiver Owner mit IAL2 kann /admin/console oder die Administrations-API.

Anwendung erstellen

curlOwner-Sitzung erforderlich
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 erstellen

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"]
  }'
TypTypischer ClientSecret
browserSPA / nur BrowserKeines
nativeiOS / Android / desktopKeines
webServerseitige/Backend-WebanwendungEinmal zurückgegeben; nur Backend
serviceMachine-to-MachineEinmal zurückgegeben

Authorization Code + PKCE S256

Erzeugen Sie einen zufälligen Verifier, leiten Sie daraus die S256-Challenge ab und erzeugen Sie zufällige Werte für state and nonce. Speichern Sie Verifier/State/Nonce nur für die Lebensdauer dieser Anmeldetransaktion.

Authorization-Anfragekonzeptionell
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

Beim Callback muss der zurückgegebene Wert state and iss vor dem Token-Austausch mit der Transaktion bzw. dem konfigurierten Issuer übereinstimmen.

Token-Austausch

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-Validierung

Prüfen Sie die RS256-Signatur mit dem JWKS des Issuers. Validieren Sie mindestens iss, aud, exp, iat und den ursprünglichen nonce; berücksichtigen Sie außerdem nbf, azp and at_hash sofern vorhanden.

JavaScript / Browser

Das Repository enthält ein browserorientiertes SDK-Paket namens @openproof/identity. Es erzeugt PKCE/State/Nonce, validiert State/Issuer beim Callback und prüft das RS256-ID-Token gegen JWKS.

javascriptöffentlicher 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);
Browser-Clients haben kein Client Secret.

Betten Sie niemals ein vertrauliches web or service Client Secret in JavaScript ein, das an einen Nutzer ausgeliefert wird.

Node.js

Verwenden Sie einen ausgereiften OIDC-Client für Ihr Framework oder nutzen Sie natives fetch() für das dokumentierte Protokoll. Vertrauliche Zugangsdaten gehören in Ihre Serverumgebung bzw. Ihren Secret Store.

javascriptserverseitiger Token-Austausch
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();

Nutzen Sie eine OIDC/JWT-Bibliothek für JWKS-Caching, Signaturprüfung und Claim-Validierung, statt kryptografische Prüfungen selbst zu implementieren.

PHP

Jede gepflegte PHP-OAuth/OIDC-Bibliothek kann OpenProof als Issuer verwenden. Das direkte Protokoll ist normales HTTPS mit formularcodiertem OAuth.

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));
}

Validieren Sie ID-Token mit einem gepflegten JWT/OIDC-Paket und dem JWKS des Issuers. Implementieren Sie RSA/JWK-Prüfungen nicht ad hoc.

C++

Das C++26-SDK des Repositorys wird exportiert als openproof.sdk. Es ist transportneutral, sodass Sie Ihren bestehenden Stack mit Boost.Beast, Qt Network oder libcurl beibehalten können.

c++SDK-Konfiguration
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';

Das SDK bietet Hilfsfunktionen zum Erzeugen von Login-Transaktionen, zum Aufbau von Authorization-Code-Anfragen, für Refresh und UserInfo. Ein minimales Relying-Party-Beispiel befindet sich in examples/reference-client.

Python, Go, Rust, Java, C# und weitere Sprachen

Sie benötigen kein OpenProof-spezifisches SDK. Konfigurieren Sie eine standardkonforme OAuth/OIDC-Bibliothek mit dem OpenProof-Issuer. Die minimale sichere Implementierung lautet: Discovery → PKCE/State/Nonce → Authorization-Redirect → Callback-Prüfungen → Token-Austausch → JWKS-Signatur-/Claim-Validierung → Access-Token-Autorisierung.

UserInfo und 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 rotieren. Speichern Sie das neue Token atomar und verwerfen Sie den alten Wert. Replay-Schutz kann die gesamte Token-Familie widerrufen.

API schützen

Registrieren Sie eine Resource mit exakter Audience und eng gefassten Scopes.

curlResource registrieren
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"]
  }'

Ihr Backend sollte Token-Gültigkeit, exakte Audience, erforderlichen Scope und Geschäftsregeln des Produkts autorisieren. Ein gültiges Token allein ist keine ausreichende Autorisierung.

Introspection

curlvertrauliches 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

Alternativ können Sie Produktrouten hinter OpenProof platzieren und Rolle, Assurance, Scope und Audience in einer statischen Routenrichtlinie durchsetzen, bevor zum Backend weitergeleitet wird.

Service-to-Service

Verwenden Sie einen service Client, provisionieren Sie erlaubte Audiences/Scopes und fordern Sie anschließend ein Access Token an mit 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'

Das Ergebnis ist ausschließlich ein Access Token. Es gibt weder Refresh Token noch menschliche Sitzung.

Account-APIs

Wenn Account-Self-Service und Verifizierungszustellung aktiviert sind, stellt OpenProof Registrierung, bestätigten E-Mail-/Telefonbesitz, Passwort-Reset, Profile, TOTP, Recovery Codes und Passkeys bereit.

ZweckEndpoint
RegistrierungPOST /account/signup
E-Mail-VerifizierungPOST /account/email/verify
Passwort-Reset startenPOST /account/password/forgot
Passwort-Reset abschließenPOST /account/password/reset
ProfilGET/PATCH /account/profile
TOTP-EinrichtungPOST /account/totp/start/complete
Passkey-AnmeldungPOST /auth/passkey/options/verify
Verknüpfte MethodenGET /account/connections
Eine kanonische Identität.

Verwenden Sie die Google-/GitHub-E-Mail nicht als Schlüssel für Produktnutzer. Ein Nutzer kann mehrere Anmeldemethoden verknüpfen und dabei dasselbe stabile OpenProof-Subject behalten.

Fehlerbehandlung und Secret-Hygiene

Fehler enthalten einen stabilen Code, eine client-sichere Nachricht und eine Request-ID. Verzweigen Sie anhand von Code/Status, nicht anhand von Fließtext. Behandeln Sie 401 als fehlende/ungültige Authentifizierung, 403 als unzureichende Berechtigung/Assurance, 409 als Zustandskonflikt und 429 als Backoff-Signal.

Protokollieren Sie niemals Passwörter, TOTP-/Recovery-Codes, Verifizierungssecrets, Authorization Codes, Access-/Refresh-Token, vertrauliche Client Secrets, Cookies, DPoP-Proofs oder private Schlüssel.