Начало работы

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

Пошаговая интеграция веб-приложения и бэкенд-сервиса с Julia за несколько минут.

На этой странице собраны два базовых сценария интеграции: вход пользователя в клиентском приложении и проверка его токена на стороне вашего бэкенда.

Сценарий 1: вход пользователя в веб-приложении

Направьте пользователя на редирект

Отправьте браузер пользователя на /v1/auth/redirect, передав выданный вашему приложению sourceId:

GET https://auth.mirea.app/v1/auth/redirect?sourceId=<ваш-client-application-uuid>

Julia перенаправит пользователя на страницу входа провайдера идентичности.

Получите одноразовый code на своём callback URL

После успешного входа Julia вернёт пользователя на зарегистрированный callback_url вашего приложения с query-параметром code:

https://your-app.example.com/auth/callback?code=<trade-code>

Одноразовый код действителен 5 минут и может быть использован только один раз.

Обменяйте code на пару JWT-токенов

Отправьте POST /v1/auth/oauth/exchange:

curl -X POST https://auth.mirea.app/v1/auth/oauth/exchange \
  -H "Content-Type: application/json" \
  -d '{"code": "<trade-code>"}'

В ответе придут access_token, refresh_token и время жизни access-токена в секундах (expires_in):

{
  "access_token": "eyJhbGciOiJFZERTQSIs...",
  "refresh_token": "eyJhbGciOiJFZERTQSIs...",
  "expires_in": 900
}

Запросите профиль текущего пользователя

Используйте access_token в заголовке Authorization: Bearer:

curl https://auth.mirea.app/v1/users/@me \
  -H "Authorization: Bearer <access_token>"

Подробнее о жизненном цикле сессии, обновлении токенов и выходе читайте в разделе OAuth Flow.


Сценарий 2: проверка JWT на стороне бэкенда

Julia подписывает все JWT алгоритмом EdDSA (Ed25519). Проверять подпись можно локально без обращения к Julia на каждый запрос.

Получите публичный ключ и метаданные

Загрузите конфигурацию и публичный ключ через стандартные discovery-эндпоинты:

curl https://auth.mirea.app/.well-known/openid-configuration
curl https://auth.mirea.app/.well-known/jwks.json

Альтернативно ключ доступен в base64 или pem по адресу GET /v1/auth/publickey?type=pem.

Валидируйте токен в своём сервисе

При валидации проверяйте:

  • алгоритм подписи — строго EdDSA;
  • iss и aud — соответствуют значениям из конфигурации;
  • exp / nbf — токен активен по времени;
  • token_type == "access" — чтобы refresh-токен не мог использоваться вместо access-токена.

Примеры валидации в официальных SDK:

using Cyberzone.Julia.Contracts.Crypto;
using Cyberzone.Julia.Contracts.Crypto.EdDsa;
using Microsoft.IdentityModel.Tokens;

var key = new EdDsaSecurityKey(Base64UrlEncoder.DecodeBytes(jwk.X));

options.MapInboundClaims = false;
options.TokenValidationParameters = new TokenValidationParameters
{
    ValidAlgorithms = [ExtendedSecurityAlgorithms.EdDsa],
    ValidIssuer = issuer,
    ValidAudience = audience,
    ValidateLifetime = true,
    IssuerSigningKeyResolver = (_, _, kid, _) =>
        string.IsNullOrEmpty(kid) || kid == key.KeyId ? [key] : [],
};
В ASP.NET Core обязательно выставляйте MapInboundClaims = false, иначе стандартный обработчик переименует sub в URI-клейм и разбор JuliaPrincipal не сработает.

Периодически обновляйте публичный ключ

Кешируйте ключ в памяти и обновляйте его по таймеру (например, раз в 5–15 минут). Не делайте запрос к JWKS на каждый неизвестный kid — это защитит ваш сервис и Julia от лишней нагрузки при поддельных токенах.

Куда дальше

JWT и Discovery

Полный список claims, формат JWKS и работа со списком отозванных токенов.

Пакеты для .NET

Подключение Cyberzone.Julia.Contracts и Cyberzone.Julia.Authorization.

Пакет для Go

Подключение julia-go (v0.1.0-rc.1): HTTP/gRPC middleware, права и API-ключи.