Быстрый старт: OAuth 2.0 за 5 минут

Info

Это пошаговое руководство по созданию Конфиденциальному OAuth 2.0 клиенту и получению access_token с использованием Authorization Code Flow и PKCE.

1. Создание приложения

  1. Войдите в свой аккаунт GitVerse.
  2. Перейдите в Настройки профиля или Настройки организации → Приложения.
  3. Нажмите Добавить приложение.
  4. Заполните форму:

Название: My First App
URI для перенаправления: https://your-server.ru/callback
Конфиденциальный клиент: ✓ (включено)
Пропускать авторизацию для публичных клиентов после первого доступа: ✗ (выключено)

  1. Нажмите Создать приложение.
  2. Сохраните ID клиента (client_id) и секрет клиента (client_secret). Секрет клиента отображается только один раз.

Warning

client_secret предназначен только для приложений, способных безопасно его хранить. Не размещайте секрет в фронтенд-коде, мобильном или десктопном приложении.

2. Подготовка PKCE и state

Перед началом авторизации создайте:

  • code_verifier — случайное значение, которое приложение сохраняет до обмена кода на токен;
  • code_challenge — SHA-256 от code_verifier, передаваемый GitVerse;
  • state — случайное значение для защиты OAuth-flow от CSRF.

Пример для Bash:

CODE_VERIFIER=$(openssl rand -base64 96 \
  | tr -d '=+/' \
  | cut -c1-64)
 
CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" \
  | openssl dgst -sha256 -binary \
  | openssl base64 -A \
  | tr '+/' '-_' \
  | tr -d '=')
 
STATE=$(openssl rand -hex 32)
 
printf 'CODE_VERIFIER=%s\n' "$CODE_VERIFIER"
printf 'CODE_CHALLENGE=%s\n' "$CODE_CHALLENGE"
printf 'STATE=%s\n' "$STATE"

Сохраните CODE_VERIFIER и STATE до завершения авторизации.

3. Инициация авторизации

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

https://gitverse.ru/signin/oauth/authorize
  ?client_id=ВАШ_CLIENT_ID
  &redirect_uri=https://your-server.ru%2Fcallback
  &response_type=code
  &scope=read:user
  &state=ВАШ_STATE
  &code_challenge=ВАШ_CODE_CHALLENGE
  &code_challenge_method=S256

В реальном приложении все параметры необходимо сделать URL-encoded.

Tip

4. Подтверждение доступа

  1. Войдите в свой аккаунт GitVerse (если еще не вошли).
  2. На странице подтверждения вы увидите:
    • название приложения: My First App;
    • запрашиваемые права: Пользователь: Чтение (read:user).
  3. Нажмите Авторизоваться.

5. Получение authorization code

После подтверждения GitVerse перенаправит пользователя на зарегистрированный redirect_uri:

https://your-server.ru/callback?code=gta_xxxxxx&state=ВАШ_STATE

Приложение должно:

  1. Получить значения code и state из query-параметров callback.
  2. Сравнить полученный state со значением, сохраненным перед началом авторизации.
  3. Прекратить авторизацию, если значения state не совпадают.

Warning

authorization code является одноразовым и имеет ограниченный срок действия. Не сохраняйте его как постоянный credential.

При ручном тестировании значение code можно скопировать из адресной строки браузера.

6. Обмен кода на access token

Отправьте POST-запрос на token endpoint:

curl -X POST 'https://gitverse.ru/login/oauth/access_token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code' \
  -d 'code=gta_xxxxxx' \
  -d 'redirect_uri=https://your-server.ru/callback' \
  -d 'client_id=ВАШ_CLIENT_ID' \
  -d 'client_secret=ВАШ_CLIENT_SECRET' \
  -d 'code_verifier=ВАШ_CODE_VERIFIER'

Значение redirect_uri должно соответствовать URI, использованному при получении authorization code.

Успешный ответ

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "eyUqbGciOiJSUzI7NiLm...",
  "scope": "read:user"
}

Tip

В ответе может содержаться refresh_token, используемый для получения нового access_token. Подробнее о сроках жизни, ротации и инвалидации токенов см. в Жизненном цикле токенов.

7. Использование access token

Теперь приложение может обращаться к API GitVerse в пределах предоставленных ему прав:

curl 'https://api.gitverse.ru/user' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Accept: application/vnd.gitverse.object+json;version=latest'

Пример ответа

{
  "id": 123,
  "login": "your_username"
}

Public Client

Для Public Client client_secret не используется. Такой клиент выполняет Authorization Code Flow с PKCE и при обмене кода передает client_id и code_verifier, но не client_secret.

Подробнее см. в разделе Типы клиентов.

Следующие шаги

Вид графа

Связанные страницы