OpenProof / Développement

Connectez n’importe quelle application via OAuth/OIDC standard.

OpenProof est indépendant du langage à la frontière du protocole. Utilisez les SDK fournis lorsqu’ils sont utiles, ou intégrez-le depuis tout langage capable de gérer HTTPS et OAuth 2.0/OpenID Connect.

Lire le manuel Référence API OpenAPI YAML

Le modèle d’intégration

fluxAuthorization 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

Utilisez des jetons OAuth/OIDC pour l’intégration produit. Le cookie de session sécurisé OpenProof appartient à l’origine compte/admin OpenProof et ne doit pas être copié dans le domaine de votre produit.

Commencer par Discovery

URLremplacer auth.example.com

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

Discovery est la méthode recommandée pour que les clients réutilisables découvrent les endpoints d’autorisation, de token, UserInfo, introspection et les autres endpoints du protocole.

Enregistrer votre produit

Un propriétaire actif avec IAL2 peut utiliser /admin/console ou l’API d’administration.

Créer une application

curlsession propriétaire requise

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"
  }'

Créer un client

curlclient web

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

Type	Client typique	Secret
`browser`	SPA / navigateur uniquement	Aucun
`native`	iOS / Android / desktop	Aucun
`web`	Application web server-rendered / backend	Renvoyé une fois ; backend uniquement
`service`	Machine-to-machine	Renvoyé une fois

Authorization Code + PKCE S256

Générez un verifier aléatoire, dérivez son challenge S256 et générez des valeurs aléatoires pour state and nonce. Conservez verifier/state/nonce uniquement pendant la durée de cette transaction de connexion.

requête d’autorisationconceptuel

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

Lors du callback, exigez que la valeur renvoyée state and iss corresponde à la transaction/issuer configuré avant l’échange de token.

Échange de token

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'

Validation du ID token

Vérifiez la signature RS256 avec le JWKS de l’issuer. Validez au minimum iss, aud, exp, iat et la valeur originale nonce ; respectez également nbf, azp and at_hash lorsqu’ils sont présents.

JavaScript / navigateur

Le dépôt fournit un package SDK orienté navigateur nommé @openproof/identity. Il génère PKCE/state/nonce, valide state/issuer au callback et vérifie le ID token RS256 avec JWKS.

javascriptclient navigateur public

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

Les clients navigateur n’ont pas de client secret.

N’intégrez jamais un web or service client secret dans du JavaScript livré à un utilisateur.

Node.js

Utilisez un client OIDC mature pour votre framework, ou utilisez fetch() pour le protocole documenté. Conservez les identifiants confidentiels dans l’environnement serveur/secret store.

javascriptéchange de token côté serveur

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

Utilisez une bibliothèque OIDC/JWT pour le cache JWKS, la vérification des signatures et la validation des claims plutôt que d’implémenter vous-même la vérification cryptographique.

PHP

Toute bibliothèque PHP OAuth/OIDC maintenue peut utiliser OpenProof comme issuer. Le protocole direct repose sur HTTPS classique et OAuth encodé en formulaire.

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

Validez les ID tokens avec un package JWT/OIDC maintenu et le JWKS de l’issuer. N’implémentez pas la vérification RSA/JWK de façon ad hoc.

C++

Le SDK C++26 du dépôt est exporté sous le nom openproof.sdk. Il est indépendant du transport afin que vous puissiez conserver votre stack Boost.Beast, Qt Network ou libcurl.

c++Configuration du SDK

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';

Le SDK fournit des helpers pour créer la transaction de connexion, construire les requêtes authorization-code, gérer refresh et UserInfo. Un exemple relying-party minimal se trouve dans examples/reference-client.

Python, Go, Rust, Java, C# et autres langages

Vous n’avez pas besoin d’un SDK spécifique à OpenProof. Configurez une bibliothèque OAuth/OIDC conforme aux standards avec l’issuer OpenProof. L’implémentation sûre minimale est : Discovery → PKCE/state/nonce → redirection d’autorisation → contrôles callback → échange de token → validation signature/claims JWKS → autorisation access token.

UserInfo et 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'

Les refresh tokens tournent. Persistez le nouveau token de manière atomique et supprimez l’ancienne valeur. La protection replay peut révoquer toute la famille.

Protéger votre API

Enregistrez une ressource avec une audience exacte et des scopes restreints.

curlenregistrer une ressource

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

Votre backend doit contrôler la validité du token, l’audience exacte, le scope requis et les règles métier du produit. Un token valide ne constitue pas à lui seul une autorisation suffisante.

Introspection

curlbackend confidentiel

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'

gateway OpenProof

Vous pouvez aussi placer les routes produit derrière OpenProof et imposer rôle, assurance, scope et audience dans une politique de route statique avant le proxy vers votre backend.

Service à service

Utilisez un service client, provisionnez les audiences/scopes autorisés, puis demandez un access token avec client_credentials.

curlgrant machine

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'

Le résultat contient uniquement un access token. Il n’y a ni refresh token ni session humaine.

API de compte

Lorsque le libre-service du compte et la livraison de vérification sont activés, OpenProof expose l’inscription, la possession vérifiée d’e-mail/téléphone, la réinitialisation de mot de passe, les profils, TOTP, les codes de récupération et les passkeys.

Rôle	Endpoint
Inscription	`POST /account/signup`
Vérification e-mail	`POST /account/email/verify`
Début de réinitialisation du mot de passe	`POST /account/password/forgot`
Fin de réinitialisation du mot de passe	`POST /account/password/reset`
Profil	`GET/PATCH /account/profile`
Inscription TOTP	`POST /account/totp/start` → `/complete`
Connexion par passkey	`POST /auth/passkey/options` → `/verify`
Méthodes liées	`GET /account/connections`

Une identité canonique.

N’utilisez pas l’e-mail Google/GitHub comme clé utilisateur de votre produit. Un utilisateur peut lier plusieurs méthodes de connexion tout en conservant le même subject OpenProof stable.

Gestion des erreurs et protection des secrets

Les erreurs contiennent un code stable, un message sûr pour le client et un request ID. Branchez la logique sur code/status, pas sur le texte. Traitez 401 comme authentification absente/invalide, 403 comme autorité/assurance insuffisante, 409 comme conflit d’état et 429 comme signal de backoff.

Ne journalisez jamais mots de passe, TOTP/codes de récupération, secrets de vérification, authorization codes, access/refresh tokens, client secrets confidentiels, cookies, preuves DPoP ou clés privées.