Быстрый старт

Настройте аутентификацию за 5 минут.

1. Создайте Realm

Откройте админ-панель и создайте новый realm:

https://your-domain.com/admin

Перейдите в Realms > Create. Задайте имя (например "My App"). VoxKey автоматически генерирует UUID, RSA-ключи и Management API.

Запомните Realm UUID -- он нужен для всех эндпоинтов.

2. Добавьте провайдер аутентификации

Перейдите на вкладку Auth Providers вашего realm и добавьте хотя бы один провайдер:

• LoginPass -- для аутентификации по email/паролю
• Google / GitHub / Discord -- для социального входа (нужны OAuth2-креденшелы из консоли разработчика провайдера)

3. Зарегистрируйте приложение

Перейдите в Applications > Create и выберите тип:

Тип	Когда использовать	PKCE
Traditional Web	Серверные приложения (Laravel, Rails, Django)	Опционально
SPA	React, Vue, Angular приложения	Обязательно
M2M	Бэкенд-сервисы, cron-задачи	Не применимо

Добавьте redirect URI (например http://localhost:3000/callback).

Сохраните Client ID и Client Secret (для конфиденциальных клиентов).

4. Получите OIDC-эндпоинты

Запросите OpenID Connect discovery document:

curl https://your-domain.com/oauth2/{realmUUID}/.well-known/openid-configuration

Ответ содержит все эндпоинты:

{
  "authorization_endpoint": "/oauth2/{realmUUID}/code",
  "token_endpoint": "/oauth2/{realmUUID}/token",
  "userinfo_endpoint": "/oauth2/{realmUUID}/userinfo",
  "jwks_uri": "/oauth2/{realmUUID}/oidc/jwks",
  "introspection_endpoint": "/oauth2/{realmUUID}/introspect",
  "revocation_endpoint": "/oauth2/{realmUUID}/revoke"
}

5. Протестируйте процесс входа

Начало авторизации

Перенаправьте пользователя на эндпоинт авторизации:

https://your-domain.com/oauth2/{realmUUID}/code
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=http://localhost:3000/callback
  &scope=openid profile email
  &state=random_state_value
  &code_challenge=PKCE_CHALLENGE
  &code_challenge_method=S256

Пользователь проходит аутентификацию и возвращается с authorization code.

Обмен кода на токены

curl -X POST https://your-domain.com/oauth2/{realmUUID}/token \
  -d grant_type=authorization_code \
  -d code=AUTHORIZATION_CODE \
  -d redirect_uri=http://localhost:3000/callback \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_SECRET \
  -d code_verifier=PKCE_VERIFIER

Ответ:

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def50...",
  "id_token": "eyJ..."
}

Получение информации о пользователе

curl https://your-domain.com/oauth2/{realmUUID}/userinfo \
  -H "Authorization: Bearer ACCESS_TOKEN"

Что дальше

• Защита API с валидацией JWT
• Настройка RBAC с кастомными ролями и скоупами
• Настройка MFA для realm