OAuth-сервер

Регистрация
Получение токена
Перевыпуск токена доступа


Регистрация

По протоколу OAuth 2.0 пользователи могут зарегистрировать свои приложения для работы с API сервисов Руцентра.

OAuth 2.0 основан на использовании базовых веб-технологий: HTTP-запросах, редиректах и т. п. Поэтому использование OAuth 2.0 возможно на любой платформе с доступом к интернету и браузеру: на сайтах, в мобильных и desktop-приложениях или плагинах для браузеров.

Для разработки приложения и дальнейшей его работы с API необходимо зарегистрировать приложение на OAuth-сервере Руцентра и пройти процедуру получения токена. После чего полученный токен можно использовать в запросах к API сервисов Руцентра.

Регистрация приложения.

Для выполнения процедуры регистрации необходимо авторизоваться в личном кабинете. Чтобы зарегистрировать приложение на OAuth-сервере Руцентра, выполните следующие действия:

  • Перейдите на страницу регистрации приложения.
  • Укажите название вашего приложения в поле Название приложения.
  • Нажмите на кнопку Зарегистрировать приложение.
  • После регистрации приложения OAuth-сервер Руцентра сгенерирует идентификатор и пароль приложения (параметры client_id и client_secret протокола OAuth 2.0), которые нужно будет указать при запросе токена.

Управление приложениями. Сменить пароль приложения (параметр client_secret протокола OAuth 2.0) можно в разделе Управление приложениями.

Получение токена

При получении запроса через API сервисов Руцентра необходимо аутентифицировать клиента и приложение, через которое был послан запрос. Каждый запрос маркируется токеном, выданным OAuth-сервером Руцентра. Как правило, токен передается в HTTP-заголовке Authorization. Для GET-запроса токен может быть передан как параметр token.

Токен используется вместо имени и пароля владельца приложения. Область доступа токена задается при выпуске токена, через параметр scope, который на вход принимает список допустимых областей (регулярные выражения), разделенных пробелами.

Все запросы к OAuth-серверу должны передаваться по протоколу HTTPS.

Запрос с использованием базовой HTTP-авторизации

Запрос имеет вид:

POST https://api.nic.ru/oauth/token HTTP/1.1
Authorization: Basic <base64-encoded-string>
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=login&password=A3ddj3w&scope=GET%3A%2Fdns-master%2F.%2B

В заголовке Authorization передается строка <client_id>:<client_secret>, закодированная методом base64. Здесь <client_id> — идентификатор приложения, <client_secret> — пароль приложения (оба атрибута генерируются после регистрации приложения).

Используемые параметры:

grant_type — тип ответа. Обязательный параметр, параметру grant_type всегда присваивается значение password;
username — логин пользователя. В качестве логина пользователя используется договор, например, username=123/NIC-REG;
password —пароль пользователя. Можно использовать административный или технический пароль, например, password=qwerty;
scope —это последовательность регулярных выражений, разделенных пробелами, которые описывают область доступа приложения.

Для получения токена перевыпуска в запросе на получение токена доступа необходимо задать параметр offline со значением, отличным от нуля.

Параметр запроса командой curl:

curl --location --request POST 'https://api.nic.ru/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'password=xxxxxxxxxxxxxxxx' \
--data-urlencode 'client_id=xxxxxxxxxx' \
--data-urlencode 'client_secret=xxxxxxxxxxxxx' \
--data-urlencode 'username=xxxxxxx/NIC-D' \
--data-urlencode 'scope=.*'

Запрос в случае явной передачи идентификатора и пароля приложения

Запрос имеет вид:

POST https://api.nic.ru/oauth/token HTTP/1.1
Content-Type: application/x-www-from-urlencoded

grant_type=password&username=123/NIC-D&password=A3ddj3w&scope=GET%3A%3Fdns-master%2F.%2B&client_id=123123&client_secret=appp123123

Используемые параметры:

grant_type — тип ответа. Обязательный параметр, параметру grant_type всегда присваивается значение password;
username — логин пользователя. В качестве логина пользователя используется договор, например, username=123/NIC-REG;
password — пароль пользователя. Можно использовать административный или технический пароль, например, password=qwerty;
scope — это последовательность регулярных выражений, разделенных пробелами, которые описывают область доступа приложения;
client_id — идентификатор приложения, который генерируется после регистрации приложения, например: client_id=123123;
client_secret — пароль приложения, генерируется после регистрации приложения, например: client_secret=appp123123.

Для получения токена перевыпуска в запросе на получение токена доступа необходимо задать параметр offline со значением, отличным от нуля.

Формат ответа в случае успеха

В случае успеха OAuth-сервер передает данные как JSON-документ:

HTTP/1.1 200 OK
Content-Type: application/json;charset-UTF-8
Cache-Control: no-store
Pragma: no-cache

{
"access_token":"2YotnFZFEjr1zCsicMWpAA",
"token_type":"example",
"expires_in":3600,
"refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
"example_parameter":"example_value"
}

Параметры ответа:

access_token — токен, с которым приложение может работать от имени пользователя;
expires_in — время жизни токена доступа. Значение указывается в секундах.

Формат ответа в случае ошибки

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=UTF-8
Chach-Control: no-store
Pragma: no-cache

{
   "error":"invalid_request"
}

HTTP-код ответа может быть 400, 401. В теле ответа помимо error могут быть дополнительные параметры, например:

invalid_request — неверный формат запроса;
invalid_grant — неверный или просроченный код подтверждения;
unsupported_grant_type — неверное значение параметра grant_type.

Перевыпуск токена доступа

Перевыпуск с использованием схемы Authorization Basic

Перевыпуск токенов доступа осуществляется через токен перевыпуска (refresh token), который должен быть получен во время выпуска токена доступа (для конфиденциальных клиентов).

Запрос имеет вид:

POST https://api.nic.ru/oauth/token HTTP/1.1
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA

В HTTP-заголовке Authorization передается строка <client_id>:<client_secret>, закодированная методом base64. Здесь <client_id> - идентификатор приложения, <client_secret> - пароль приложения (оба атрибута генерируются после регистрации приложения).

Параметр grant_type=refresh_token, а параметр refresh_token должен содержать значениe токена перевыпуска (например: refresh_token=tGzv3JOkF0XG5Qx2TlKWIA).

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

Альтернативный вариант, вместо заголовка Authorization используется передача параметров client_id и client_secret:

POST https://api.nic.ru/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA&client_id=app12312312&client_secret=password

Формат ответа в случае успеха

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "token_type":"Bearer",
  "expires_in":3600,
  "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
}

Формат ответа в случае ошибки

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
   "error":"invalid_request"
}

HTTP-код ответа может быть 400, 401. В теле ответа помимо error могут быть дополнительные параметры, например:

invalid_request — неверный формат запроса;
invalid_grant — неверный или просроченный код подтверждения;
unsupported_grant_type — неверное значение параметра grant_type.

Всё ещё остались вопросы?