OAuth Flow и сессии
Авторизация конечных пользователей в 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. Токены этой сессии немедленно перестают приниматься.
GET /v1/users/{uuid}/sessions и DELETE /v1/users/{uuid}/sessions/{sessionId}. Подробнее — на странице Пользователи и сессии.