Подключайте любое приложение через стандарт OAuth/OIDC.
OpenProof не зависит от языка на границе протокола. Используйте поставляемые SDK там, где они помогают, или интегрируйте их с любым языком, поддерживающим HTTPS и OAuth 2.0/OpenID Connect.
Модель интеграции
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 и не должен копироваться в домен вашего продукта.
Начните с Дискавери
https://auth.example.com/.well-known/openid-configuration https://auth.example.com/.well-known/jwks.json
Обнаружение — это предпочтительный способ для клиентов многократного использования узнать авторизацию, токен, информацию о пользователе, самоанализ и связанные конечные точки протокола.
Зарегистрируйте свой продукт
Активный владелец с IAL2 может использовать /admin/console или API администрирования.
Создать заявку
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 --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"]
}'| Добрый | Типичный клиент | Секрет |
|---|---|---|
browser | SPA / только для браузера | Никто |
native | iOS/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 чтобы соответствовать транзакции/настроенному эмитенту перед обменом токенов.
Обмен токенов
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.
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);
Никогда не вставляйте конфиденциальную информацию web или service секрет клиента в JavaScript, отправленный пользователю.
Node.js
Используйте зрелый клиент OIDC для своей платформы или используйте собственный fetch() для документированного протокола. Храните конфиденциальные учетные данные в вашей серверной среде/секретном хранилище.
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 с кодировкой формы.
<?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.
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 → авторизация токена доступа.
Информация о пользователе и обновите
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'
Токены обновления вращаются. Сохраните новый токен атомарно и отбросьте старое значение. Защиту от повтора могут отозвать всю семью.
Защитите свой API
Зарегистрируйте ресурс с точной аудиторией и узкой сферой применения.
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 --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 --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 |
| Регистрация TOTP | POST /account/totp/start → /complete |
| Вход с паролем | POST /auth/passkey/options → /verify |
| Связанные методы | GET /account/connections |
Не вводите ключ пользователя вашего продукта по электронной почте Google/GitHub. Пользователь может связать несколько методов входа, сохраняя при этом один и тот же стабильный объект OpenProof.
Обработка ошибок и секретная гигиена
Ошибки включают стабильный код, безопасное для клиента сообщение и идентификатор запроса. Ветка по коду/статусу, а не прозе. Считайте 401 как отсутствующую/недействительную аутентификацию, 403 как недостаточные полномочия/гарантии, 409 как конфликт состояний и 429 как сигнал отсрочки.
Никогда не регистрируйте пароли, коды TOTP/восстановления, секреты проверки, коды авторизации, токены доступа/обновления, конфиденциальные секреты клиентов, файлы cookie, доказательства DPoP или закрытые ключи.