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 и не должен копироваться в домен вашего продукта.

Начните с Дискавери

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

Обнаружение — это предпочтительный способ для клиентов многократного использования узнать авторизацию, токен, информацию о пользователе, самоанализ и связанные конечные точки протокола.

Зарегистрируйте свой продукт

Активный владелец с 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. Сохраняйте верификатор/состояние/одноразовый номер только на протяжении всей транзакции входа в систему.

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

Проверка идентификационного токена

Проверьте подпись 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 предоставляет помощники для создания транзакций входа в систему, создания запроса кода авторизации, обновления и информации о пользователе. Минимальный пример доверяющей стороны живет в examples/reference-client.

Python, Go, Rust, Java, C# и другие языки.

Вам не нужен SDK для OpenProof. Настройте соответствующую стандартам библиотеку OAuth/OIDC с помощью издателя OpenProof. Минимально безопасная реализация — это Discovery → PKCE/state/nonce → перенаправление авторизации → проверки обратного вызова → обмен токенами → проверка подписи/заявления JWKS → авторизация токена доступа.

Информация о пользователе и обновите

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 и задайте роль, гарантию, область действия и аудиторию в политике статического маршрутизации перед проксированием на серверную часть.

Сервис-за-сервис

Используйте 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 или закрытые ключи.