Code Flow

Содержание

Authorization Code Flow с PKCE — стандартный способ аутентификации пользователя и получения доступа к API. Подходит для веб-приложений, мобильных приложений и SPA. Поток обеспечивает защиту кода авторизации даже без хранения секретов на клиенте.

Термины

  • Клиент — ваше приложение.
  • Пользователь — владелец учётной записи.
  • Авторизационный сервер — auth.regos.uz (Единый профиль).
  • Ресурсный сервер — целевой API, принимающий access_token.
  • PKCE — защита обмена кода на токены с помощью code_verifier и code_challenge.

CodeFlow_scheme

Что подготовить

  1. Получите client_id у сотрудников REGOS.
  2. Зарегистрируйте redirect_uri (HTTPS) на стороне авторизационного сервера.
  3. Обеспечьте HTTPS во всех запросах.

Важно. Для публичных клиентов (мобильное/SPA) client_secret не используется. Для серверных клиентов храните client_secret только на сервере.

PKCE: подготовка

Сформируйте параметры на клиенте.

  1. code_verifier — случайная строка длиной 43–128 символов из A–Z a–z 0–9 - . _ ~.
    Пример: dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
  2. code_challenge = BASE64URL(SHA256(ASCII(code_verifier)))
    Метод: S256.
    Пример: E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM

Рекомендация. Используйте только code_challenge_method=S256.

Шаг 1. Направьте пользователя на авторизацию

Endpoint: https://auth.regos.uz/oauth/authorize
Метод: GET

Обязательные параметры:

  • response_type=code
  • client_id
  • redirect_uri — строго как зарегистрирован
  • code_challenge
  • code_challenge_method=S256
  • state — случайная строка для защиты от CSRF

Пример запроса:


GET [https://auth.regos.uz/oauth/authorize](https://auth.regos.uz/oauth/authorize)?
response_type=code&
client_id=client_123abcd45ef678901&
redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&
code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&
code_challenge_method=S256&
state=2d86c3b9f7

Шаг 2. Примите код авторизации

После входа сервер выполнит редирект на redirect_uri:

[https://app.example.com/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=2d86c3b9f7](https://app.example.com/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=2d86c3b9f7)
  1. Проверьте совпадение state.
  2. Считайте code — он нужен для обмена на токены.
    При ошибке вернутся error и error_description.

Шаг 3. Обменяйте код на токены

Endpoint: https://auth.regos.uz/oauth/token
Метод: POST
Заголовок: Content-Type: application/x-www-form-urlencoded

Тело запроса:

  • grant_type=authorization_code
  • code
  • redirect_uri — тот же, что в шаге 5
  • client_id
  • code_verifier — исходное значение из шага 4

Пример (cURL):

curl -X POST https://auth.regos.uz/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=SplxlOBeZQQYbYS6WxSbIA" \
  -d "redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback" \
  -d "client_id=client_123abcd45ef678901" \
  -d "code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"

Ответ сервера: токены и использование

Успешный ответ содержит:

  • access_token — токен доступа к API;
  • id_token — JWT по OpenID Connect с данными профиля;
  • refresh_token — токен обновления;
  • token_type — Bearer;
  • expires_in — срок жизни access_token (секунды).

Пример:

{
  "access_token": "eyJhbGciOiJ...access...",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9....",
  "refresh_token": "def50200...refresh...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Обновите access_token по refresh_token

Endpoint: https://auth.regos.uz/oauth/token
Метод: POST
Заголовок: Content-Type: application/x-www-form-urlencoded

Тело запроса:

  • grant_type=refresh_token
  • refresh_token
  • client_id

Пример (cURL):

curl -X POST https://auth.regos.uz/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=def50200...refresh..." \
  -d "client_id=client_123abcd45ef678901"

Ответ содержит новый access_token и, при необходимости, новый refresh_token.

10. id_token: состав и проверка

id_token — это JWT из трёх частей: Header, Payload, Signature.

Пример Header:

{ "alg": "RS256", "typ": "JWT" }

Пример Payload:

{
  "sid": "9e84c64b-f25e-44b9-944d-fd27248b50c1",
  "sub": "b72d1a59-4d94-47cf-a85e-ae33b483d5e2",
  "iss": "https://auth.regos.uz",
  "iat": 1747671021,
  "exp": 1747671921,
  "auth_time": 1747671021,
  "email": "user123@example.com",
  "email_verified": true,
  "phone_number": "+998987654321",
  "phone_number_verified": true,
  "given_name": "John",
  "family_name": "Doe",
  "picture": "https://example.com/pic.jpg",
  "company": "Company Example",
  "aud": "client_123abcd45ef678901"
}

Проверьте на сервере:

  1. Подпись по JWKS и алгоритм RS256.
  2. Значения iss, aud.
  3. Срок действия exp (и при необходимости iat, auth_time, nonce).