Аутентификация

OAuth Flow и сессии

Авторизация пользователей через редирект, обмен trade code на JWT, обновление refresh-токена и завершение сессии.

Авторизация конечных пользователей в Julia построена на редиректном OAuth-потоке с одноразовым кодом обмена (trade code). Все маршруты этой группы находятся под /v1/auth.

Схема авторизации

1. Клиент  ── GET /v1/auth/redirect?sourceId=<uuid> ──▶ Julia
2. Julia   ── 302 Redirect ───────────────────────────▶ Провайдер входа
3. Провайдер ── Callback ─────────────────────────────▶ Julia (/v1/auth/oauth/callback/{provider})
4. Julia   ── 302 Redirect: <callback_url>?code=... ──▶ Клиент
5. Клиент  ── POST /v1/auth/oauth/exchange { code } ──▶ Julia
6. Julia   ── 200 OK { access_token, refresh_token } ─▶ Клиент

1. Инициализация входа

GET /v1/auth/redirect?sourceId=<client_application_uuid>&service=<provider>
ПараметрОбязательныйОписание
sourceIdДаUUID зарегистрированного клиентского приложения (ClientApplication). Определяет, на какой callback_url вернуть пользователя после входа.
serviceНетИдентификатор провайдера входа. Если не указан, используется провайдер по умолчанию.

Julia проверяет sourceId, создаёт временное состояние авторизации (действует 10 минут) и отвечает 302 Found на страницу входа провайдера. При неизвестном sourceId или неактивном провайдере возвращается 400 Bad Request.

2. Возврат на клиент и обмен code

После успешной аутентификации Julia перенаправляет браузер на зарегистрированный callback_url клиентского приложения с query-параметром code:

https://app.example.com/callback?code=019f9bdc-13b5-7e2b-bc68-ccf3446d2cc0

Клиентское приложение должно обменять полученный код на пару JWT-токенов:

POST /v1/auth/oauth/exchange
Content-Type: application/json

{
  "code": "019f9bdc-13b5-7e2b-bc68-ccf3446d2cc0"
}

Успешный ответ (200 OK):

{
  "access_token": "eyJhbGciOiJFZERTQSIs...",
  "refresh_token": "eyJhbGciOiJFZERTQSIs...",
  "expires_in": 900
}
  • access_token — короткоживущий JWT для доступа к API (Authorization: Bearer <access_token>).
  • refresh_token — долгоживущий JWT для продления сессии.
  • expires_in — время жизни access_token в секундах.
code является одноразовым и действителен 5 минут. Повторная отправка того же кода или отправка просроченного кода возвращает 400 Bad Request.

3. Обновление токенов

Когда срок действия access_token подходит к концу, запросите новую пару через POST /v1/auth/refresh:

POST /v1/auth/refresh
Content-Type: application/json

{
  "refresh_token": "eyJhbGciOiJFZERTQSIs..."
}

Поведение при обновлении:

  • refresh_token ротируется: предыдущий refresh-токен сессии отзывается, а в ответе возвращаются новые access_token и refresh_token в рамках той же сессии (sid).
  • Если refresh-токен истёк, отозван или сессия завершена, сервер отвечает 400 Bad Request — пользователю нужно пройти вход заново.

4. Завершение сессии (Logout)

Для выхода из системы отправьте POST /v1/auth/logout с действующим access_token пользователя:

POST /v1/auth/logout
Authorization: Bearer <access_token>
Content-Type: application/json

{}
  • По умолчанию завершается текущая сессия, указанная в claim sid переданного JWT.
  • Можно явно указать другую собственную сессию в теле запроса ({ "session_id": "<uuid>" }).
  • Успешный ответ — 204 No Content. Токены этой сессии немедленно перестают приниматься.
Для управления всеми активными сессиями пользователя (просмотр списка устройств/IP и завершение конкретной сессии) также доступны эндпоинты GET /v1/users/{uuid}/sessions и DELETE /v1/users/{uuid}/sessions/{sessionId}. Подробнее — на странице Пользователи и сессии.