Genyleap/Docs
OpenProof / Розробка

Підключіть будь-яку програму через стандартний OAuth/OIDC.

OpenProof не залежить від мови на межі протоколу. Використовуйте надіслані SDK, якщо вони допомагають, або інтегруйте з будь-якої мови, яка підтримує HTTPS і OAuth 2.0/OpenID Connect.

Інтеграційна модель

потік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

Використовуйте маркери OAuth/OIDC для інтеграції продукту. Захищений сеансовий файл cookie OpenProof належить до облікового запису OpenProof/адміністратора, і його не можна копіювати в домен вашого продукту.

Почніть із Discovery

URL-адресизамінити auth.example.com
https://auth.example.com/.well-known/openid-configuration
https://auth.example.com/.well-known/jwks.json

Виявлення є кращим способом для багаторазових клієнтів дізнатися про авторизацію, маркер, UserInfo, самоаналіз та відповідні кінцеві точки протоколу.

Зареєструйте свій продукт

Активний власник з IAL2 може використовувати /admin/console або API адміністрування.

Створіть додаток

curlпотрібна сесія власника
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"
  }'

Створіть клієнта

curlвеб-клієнт
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"]
  }'
ДобрийТиповий клієнтСекрет
browserSPA / лише для браузераЖодного
nativeiOS / Android / робочий стілЖодного
webСерверний веб-програма/серверна програмаПовернувся один раз; лише бекенд
serviceМашина-машинаПовернувся один раз

Код авторизації + PKCE S256

Згенеруйте випадковий верифікатор, виведіть його виклик S256 і згенеруйте випадковий state і nonce. Зберігайте verifier/state/nonce лише протягом життя цієї транзакції входу.

запит авторизаціїконцептуальний
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

При зворотному дзвінку вимагайте повернення state і iss щоб відповідати транзакції/налаштованому емітенту перед обміном маркерів.

Обмін токенів

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

Перевірте підпис RS256 у емітента JWKS. Підтвердити принаймні iss, aud, exp, iat і оригінал nonce; честь nbf, azp і at_hash при наявності.

JavaScript / браузер

Репозиторій постачає орієнтований на браузер пакет SDK під назвою @openproof/identity. Він генерує PKCE/state/nonce, перевіряє стан зворотного виклику/емітента та перевіряє ідентифікаційний маркер RS256 на JWKS.

javascriptзагальнодоступний клієнт браузера
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();
javascriptзворотній дзвінок
const tokens = await identity.handleCallback();

console.log(tokens.id_token_claims.sub);

const profile =
  await identity.userInfo(tokens.access_token);
Клієнти браузера не мають секрету клієнта.

Ніколи не вставляйте конфіденційну інформацію web або service секрет клієнта в JavaScript, який надсилається користувачеві.

Node.js

Використовуйте зрілий клієнт OIDC для своєї структури або використовуйте нативний fetch() за задокументований протокол. Зберігайте конфіденційні облікові дані у серверному середовищі/секретному сховищі.

javascriptобмін маркерами на стороні сервера
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();

Використовуйте бібліотеку OIDC/JWT для кешування JWKS, перевірки підпису та перевірки претензій замість написання криптографічної перевірки самостійно.

PHP

Будь-яка підтримувана бібліотека PHP OAuth/OIDC може використовувати OpenProof як емітента. Прямим протоколом є звичайний HTTPS і закодований у формі 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));
}

Перевірте маркери ідентифікатора за допомогою підтримуваного пакета JWT/OIDC і емітента JWKS. Не використовуйте спеціальну перевірку RSA/JWK.

C++

Репозиторій C++26 SDK експортується як openproof.sdk. Він транспортно-нейтральний, тому ви можете зберегти наявний стек Boost.Beast, Qt Network або libcurl.

c++Конфігурація 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';

SDK надає помічники для створення транзакцій входу, створення запиту на код авторизації, оновлення та UserInfo. Існує мінімальний приклад повіряючої сторони examples/reference-client.

Python, Go, Rust, Java, C# та інші мови

Вам не потрібен спеціальний SDK для OpenProof. Налаштуйте сумісну зі стандартами бібліотеку OAuth/OIDC за допомогою емітента OpenProof. Мінімальна безпечна реалізація: виявлення → PKCE/state/nonce → перенаправлення авторизації → перевірки зворотного виклику → обмін маркерами → перевірка підпису/твердження JWKS → авторизація маркера доступу.

UserInfo та оновити

curlUserInfo
curl --fail-with-body \
  https://auth.example.com/oauth/userinfo \
  -H 'Authorization: Bearer ACCESS_TOKEN'
curlмаркер оновлення
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'

Жетони оновлення змінюються. Збережіть новий маркер атомарно та відкиньте старе значення. Захист від повторного відтворення може відкликати всю родину.

Захистіть свій API

Зареєструйте ресурс із точною аудиторією та вузькими рамками.

curlзареєструвати ресурс
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"]
  }'

Ваш сервер має авторизувати дійсність маркера, точну аудиторію, необхідний обсяг і бізнес-правила продукту. Дійсний маркер сам по собі не є достатньою авторизацією.

самоаналіз

curlконфіденційний бекенд
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

Крім того, розмістіть маршрути продукту позаду OpenProof і застосуйте роль, гарантію, обсяг і аудиторію в статичній політиці маршрутів перед проксі-сервером у вашому сервері.

Сервіс-сервіс

Використовуйте a service клієнт і надання дозволених аудиторій/областей, а потім запитайте маркер доступу за допомогою client_credentials.

curlмашинний грант
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'

Результатом є лише маркер доступу. Немає маркера оновлення або сеансу користувача.

API облікового запису

Коли ввімкнено самообслуговування облікового запису та доставку підтвердження, OpenProof відкриває реєстрацію, підтверджену електронну пошту/телефон, скидання пароля, профілі, TOTP, коди відновлення та ключі доступу.

призначенняЕндпоінт
РеєстраціяPOST /account/signup
Підтвердження електронної поштиPOST /account/email/verify
Початок скидання пароляPOST /account/password/forgot
Скидання пароля завершеноPOST /account/password/reset
ПрофільGET/PATCH /account/profile
Реєстрація TOTPPOST /account/totp/start → /complete
Пароль для входуPOST /auth/passkey/options → /verify
Зв'язані методиGET /account/connections
Одна канонічна ідентичність.

Не вказуйте користувача продукту електронною поштою Google/GitHub. Користувач може зв’язати кілька методів входу, зберігаючи той самий стабільний суб’єкт OpenProof.

Обробка помилок і секретна гігієна

Помилки включають стабільний код, безпечне для клієнта повідомлення та ідентифікатор запиту. Гілка по коду/статусу, а не прозі. Розглядайте 401 як відсутню/недійсну автентифікацію, 403 як недостатні повноваження/запевнення, 409 як конфлікт стану та 429 як сигнал відстрочки.

Ніколи не реєструйте паролі, коди TOTP/відновлення, секрети підтвердження, коди авторизації, маркери доступу/оновлення, конфіденційні секрети клієнта, файли cookie, підтвердження DPoP або приватні ключі.