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
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
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
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
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"]
}'| Typ | Typischer Client | Secret |
|---|---|---|
browser | SPA / nur Browser | Keines |
native | iOS / Android / desktop | Keines |
web | Serverseitige/Backend-Webanwendung | Einmal zurückgegeben; nur Backend |
service | Machine-to-Machine | Einmal 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.
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
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.
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);
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.
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.
<?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.
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
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 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.
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
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.
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.
| Zweck | Endpoint |
|---|---|
| Registrierung | POST /account/signup |
| E-Mail-Verifizierung | POST /account/email/verify |
| Passwort-Reset starten | POST /account/password/forgot |
| Passwort-Reset abschließen | POST /account/password/reset |
| Profil | GET/PATCH /account/profile |
| TOTP-Einrichtung | POST /account/totp/start → /complete |
| Passkey-Anmeldung | POST /auth/passkey/options → /verify |
| Verknüpfte Methoden | GET /account/connections |
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.