Перейти к основному содержимому

Реализация OAuth 2.1 через Easy ID

Авторизацию через Easy ID можно легко интегрировать в ваше приложение с помощью протокола OAuth 2.1.


Шаг 1: Перенаправить пользователя по ссылке на авторизацию

При нажатии на кнопку Войти через Easy ID с фирменным логотипом, пользователя нужно перенаправить по специальной ссылке:

GET
https://id.easyx.ru/oauth?client_id=1&redirect_uri=https://your.site/oauth/easyid/callback&scope=account email&response_type=code&state=Zm5KlLjIXGfRqWSs7ylPGM9KjVs4EFw0RxYAs81H&code_challenge=X_oN7OHUML93M1tQXsrQnqn9QqlXbcEz3Q1nk2PaV8E&code_challenge_method=S256

Параметры

Required

client_id

Integer

Идентификатор приложения, которое запрашивает авторизацию. Это значение можно найти в настройках приложения

Required

redirect_uri

String

Ссылка, по которой будет перенаправлен пользователь после того, как он разрешит приложению доступ

Required

response_type

String

Что в ответ должно получить приложение после того, как пользователь разрешит доступ. Принимает значение code

Required

state

String [32..224]

Случайно сгенерированная строка состояния, состоящая из символов a-z, A-Z, 0-9, _, -. Передается на старте авторизации и должна возвращаться приложению без изменения. Иначе ответ можно считать подмененным

Сохраните значение state до второго шага

Required

code_challenge

String

Значение code_verifier, преобразованное с помощью code_challenge_method и закодированное в base64

Порядок преобразований: BASE64-ENCODE(SHA256(code_verifier)) RFC-7636 Code Challenge

Сохраните значение code_verifier до третьего шага

Required

code_challenge_method

String

Метод преобразования code_verifier в code_challenge. Принимает значение S256

scope

String

Список прав доступа, разделенный пробелами, которые нужны приложению. Если параметр не указан, берется минимальное значение по умолчанию — account

lang

String

Язык интерфейса страницы авторизации. Принимает значения ru, en. Если не передано, выбирается автоматически

Шаг 2: Обработка результата авторизации

После успешного входа в Easy ID произойдет редирект на адрес, указанный в redirect_uri.

GET
https://your.site/oauth/easyid/callback?code=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiL0.eyJpYXQiOjE3NTU0MzA3OTcsImp0aSI6IjUwZmE1NTIwLTQ5MjItNDMwZC04YjZiLWY4NzQ5Y2Y4ZGNjNSIsImlzcyf1ImlkMi5lYXN5eC5ydSIsInN1YiI1ImNvZGUiLCJhdWQiOiJpZDIuZWFzeXgucnUiLCJDeHAiOjE3NTU0MzEwOTcsIm5iZiI6MTc1NTQzMDc5NywiZGF0YSI6eyJhdXRob3JpemF0aW9uIjp7ImlkIjoxNn19fQ.bDaie8_31EszqoIrmWcitE3ujPY5DmifnZSlSIcup2E&state=Zm5KlLjIXGfRqWSs7ylPGM9KjVs4EFw0RxYAs81H

Параметры

Required

code

String

Код авторизации, который потребуется обменять на access_token и refresh_token на третьем шаге

Required

state

String

Строка состояния, сгенерированная на первом шаге. Проверьте, что она совпадает с тем значением state, которое было передано на первом шаге, чтобы убедиться, что запрос подлинный

Шаг 3: Получение токена пользователя

Обменяйте полученный на втором шаге code на access_token с помощью HTTP запроса API.

POST
https://id.easyx.ru/oauth/token

Запрос

Request schema application/x-www-form-urlencoded

Required

grant_type

String

Принимает значение authorization_code

Required

code

String

Код авторизации, полученный на предыдущем шаге

Required

code_verifier

String

Значение code_verifier из первого шаге

Required

client_id

Integer

Идентификатор приложения, которое запрашивает авторизацию. Это значение можно найти в настройках приложения

Required

redirect_uri

String

Адрес для редиректа после авторизации. Такой же, как на втором шаге

client_secret

String

Секретный ключ приложения, которое запрашивает авторизацию. Это значение можно найти в настройках приложения

Ответ

200
Запрос успешно обработан

Required

token_type

String

Тип токена. Принимает значение bearer

Required

access_token

String

Access token пользователя, который можно использовать при дальнейших вызовах API

Required

expires_in

Integer

Метка времени в часовом поясе UTC, определяющая до какого момента access_token может быть использован

По истечении срока действия токена его следует обновить с помощью refresh_token

Required

refresh_token

String

Refresh token пользователя, который можно использовать при обновлении Access token, когда его срок действия подходит к концу

400
Ошибка в параметрах

Required

error_code

String

Код ошибки

Required

error_message

String

Описание ошибки

403
Приложение выключено

Required

error_code

String

Код ошибки

Required

error_message

String

Описание ошибки

403
Неверный секретный ключ

Required

error_code

String

Код ошибки

Required

error_message

String

Описание ошибки

403
Переданный code не предназначен для этой цели

Required

error_code

String

Код ошибки

Required

error_message

String

Описание ошибки

404
Приложение не найдено

Required

error_code

String

Код ошибки

Required

error_message

String

Описание ошибки

404
Некорректный code_verifier

Required

error_code

String

Код ошибки

Required

error_message

String

Описание ошибки

410
Срок действия кода code истек

Required

error_code

String

Код ошибки

Required

error_message

String

Описание ошибки

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

Payload

Content Type

application/x-www-form-urlencoded

{
    "grant_type": "authorization_code",
    "code": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiL0.eyJpYXQiOjE3NTU0MzA3OTcsImp0aSI6IjUwZmE1NTIwLTQ5MjItNDMwZC04YjZiLWY4NzQ5Y2Y4ZGNjNSIsImlzcyf1ImlkMi5lYXN5eC5ydSIsInN1YiI1ImNvZGUiLCJhdWQiOiJpZDIuZWFzeXgucnUiLCJDeHAiOjE3NTU0MzEwOTcsIm5iZiI6MTc1NTQzMDc5NywiZGF0YSI6eyJhdXRob3JpemF0aW9uIjp7ImlkIjoxNn19fQ.bDaie8_31EszqoIrmWcitE3ujPY5DmifnZSlSIcup2E",
    "code_verifier": "wdokH1zpwaZYtEe2HjSvIfH5dgXAHm-ptLP9ae8GU2c",
    "client_id": 1,
    "redirect_uri": "https://your.site/oauth/easyid/callback",
    "client_secret": "BHTHL4sMDtipYZ8vKX7fDQrHucTmPScGxp7b03xXc3qU"
}

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

200
400
403
403
404

Content Type

application/json

{
    "token_type": "bearer",
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiL0.eyJpYXQiOjE3NTU0MzA3OTcsImp0aSI6IjUwZmE1NTIwLTQ5MjItNDMwZC04YjZiLWY4NzQ5Y2Y4ZGNjNSIsImlzcyf1ImlkMi5lYXN5eC5ydSIsInN1YiI1ImNvZGUiLCJhdWQiOiJpZDIuZWFzeXgucnUiLCJDeHAiOjE3NTU0MzEwOTcsIm5iZiI6MTc1NTQzMDc5NywiZGF0YSI6eyJhdXlgP3JpemF0aW9uIjp7ImlkIjoxNn19fQ.bDaie8_31EszqoIrmWcitE3ujPY5DmifnZSlSIcup2E",
    "expires_in": 1755472901,
    "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiL0.eyJpYXQiOjE3NTU0MzA3OTcsImp0aSI6IjUwZmE1NTIwLTQ5MjItNDMwZC04YjZiLWY4NzQ5Y2Y4ZGNjNSIsImlzcyf1ImlkMi5lYXN5eC5ydSIsInN1YiI1ImNvZGUiLCJhdWQiOiJpZDIuZWFzeXgucnUiLCJDeHAiOjE3NTU0MzEwOTcsIm5iZiI6MTc1NTQzMDc5NywiZGF0YSI6eyJhdXlgP3JpemF0aW9uIjp7ImlkIjoxNn19fQ.bDaie8_31EszqoIrmWcitE3ujPY5DmifnZSlSIcup2E"
}
{
  "error_code": "bad_request",
  "error_message": "Parameter `client_id` is required"
}
{
  "error_code": "application_disabled",
  "error_message": "Application with given `client_id` is disabled"
}
{
  "error_code": "client_secret_not_match",
  "error_message": "Client secret does not match"
}
{
  "error_code": "application_not_found",
  "error_message": "Application with given `client_id` was not found"
}

Шаг 4: Получение пользовательских данных (опционально)

После того как ваше приложение получило access_token, вы можете использовать его для запроса пользовательских данных через метод API.

Шаг 5: Обновление токена пользователя

Вы можете получить новый Access token пользователя, если срок действия старого подходит к концу или уже истек. Для этого вам понадобится refresh_token, полученный на третьем шаге

POST
https://id.easyx.ru/oauth/token

Запрос

Request schema application/x-www-form-urlencoded

Required

grant_type

String

Принимает значение refresh_token

Required

refresh_token

String

Значение refresh_token, полученное на третьем шаге

Required

client_id

Integer

Идентификатор приложения, которое запрашивает обновленный Access token. Это значение можно найти в настройках приложения

Access token может обновить только то приложение, которое изначально его запросило

client_secret

String

Секретный ключ приложения, которое запрашивает обновленный Access token. Это значение можно найти в настройках приложения

Ответ

200
Запрос успешно обработан

Required

token_type

String

Тип токена. Принимает значение bearer

Required

access_token

String

Access token пользователя, который можно использовать при дальнейших вызовах API

Required

expires_in

Integer

Метка времени в часовом поясе UTC, определяющая до какого момента access_token может быть использован

По истечении срока действия токена его следует обновить с помощью refresh_token

Required

refresh_token

String

Refresh token пользователя, который можно использовать при обновлении Access token, когда его срок действия подходит к концу

400
Ошибка в параметрах

Required

error_code

String

Код ошибки

Required

error_message

String

Описание ошибки

403
Приложение выключено

Required

error_code

String

Код ошибки

Required

error_message

String

Описание ошибки

403
Неверный секретный ключ

Required

error_code

String

Код ошибки

Required

error_message

String

Описание ошибки

404
Приложение не найдено

Required

error_code

String

Код ошибки

Required

error_message

String

Описание ошибки

410
Срок действия refresh_token истек

Required

error_code

String

Код ошибки

Required

error_message

String

Описание ошибки

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

Payload

Content Type

application/x-www-form-urlencoded

{
    "grant_type": "refresh_token",
    "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiL0.eyJpYXQiOjE3NTU0MzA3OTcsImp0aSI6IjUwZmE1NTIwLTQ5MjItNDMwZC04YjZiLWY4NzQ5Y2Y4ZGNjNSIsImlzcyf1ImlkMi5lYXN5eC5ydSIsInN1YiI1ImNvZGUiLCJhdWQiOiJpZDIuZWFzeXgucnUiLCJDeHAiOjE3NTU0MzEwOTcsIm5iZiI6MTc1NTQzMDc5NywiZGF0YSI6eyJhdXRob3JpemF0aW9uIjp7ImlkIjoxNn19fQ.bDaie8_31EszqoIrmWcitE3ujPY5DmifnZSlSIcup2E",
    "client_id": 1,
    "client_secret": "BHTHL4sMDtipYZ8vKX7fDQrHucTmPScGxp7b03xXc3qU"
}

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

200
400
403
403
404

Content Type

application/json

{
    "token_type": "bearer",
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiL0.eyJpYXQiOjE3NTU0MzA3OTcsImp0aSI6IjUwZmE1NTIwLTQ5MjItNDMwZC04YjZiLWY4NzQ5Y2Y4ZGNjNSIsImlzcyf1ImlkMi5lYXN5eC5ydSIsInN1YiI1ImNvZGUiLCJhdWQiOiJpZDIuZWFzeXgucnUiLCJDeHAiOjE3NTU0MzEwOTcsIm5iZiI6MTc1NTQzMDc5NywiZGF0YSI6eyJhdXlgP3JpemF0aW9uIjp7ImlkIjoxNn19fQ.bDaie8_31EszqoIrmWcitE3ujPY5DmifnZSlSIcup2E",
    "expires_in": 1755472901,
    "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiL0.eyJpYXQiOjE3NTU0MzA3OTcsImp0aSI6IjUwZmE1NTIwLTQ5MjItNDMwZC04YjZiLWY4NzQ5Y2Y4ZGNjNSIsImlzcyf1ImlkMi5lYXN5eC5ydSIsInN1YiI1ImNvZGUiLCJhdWQiOiJpZDIuZWFzeXgucnUiLCJDeHAiOjE3NTU0MzEwOTcsIm5iZiI6MTc1NTQzMDc5NywiZGF0YSI6eyJhdXlgP3JpemF0aW9uIjp7ImlkIjoxNn19fQ.bDaie8_31EszqoIrmWcitE3ujPY5DmifnZSlSIcup2E"
}
{
  "error_code": "bad_request",
  "error_message": "Parameter `client_id` is required"
}
{
  "error_code": "application_disabled",
  "error_message": "Application with given `client_id` is disabled"
}
{
  "error_code": "client_secret_not_match",
  "error_message": "Client secret does not match"
}
{
  "error_code": "application_not_found",
  "error_message": "Application with given `client_id` was not found"
}

Шаг 6: Инвалидация токена (выход из аккаунта)

Если вы больше не планируете использовать Access token пользователя, в целях безопасности мы настоятельно рекомендуем отозвать действующий Access token, чтобы принудительно приостановить его действие. При этом, чтобы получить новый Access token, вам необходимо пройти повторную процедуру авторизации, начиная с первого шаге

POST
https://id.easyx.ru/oauth/logout

Запрос

Request schema application/x-www-form-urlencoded

Required

access_token

String

Access token пользователя, полученный на третьем шаге

Required

client_id

Integer

Идентификатор приложения, которое аннулирует Access token. Это значение можно найти в настройках приложения

Access token может аннулировать только то приложение, которое изначально его запросило

client_secret

String

Секретный ключ приложения, которое аннулирует Access token. Это значение можно найти в настройках приложения

Ответ

200
Запрос успешно обработан
400
Ошибка в параметрах

Required

error_code

String

Код ошибки

Required

error_message

String

Описание ошибки

403
Приложение выключено

Required

error_code

String

Код ошибки

Required

error_message

String

Описание ошибки

403
Неверный секретный ключ

Required

error_code

String

Код ошибки

Required

error_message

String

Описание ошибки

404
Приложение не найдено

Required

error_code

String

Код ошибки

Required

error_message

String

Описание ошибки

410
Срок действия access_token истек

Required

error_code

String

Код ошибки

Required

error_message

String

Описание ошибки

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

Payload

Content Type

application/x-www-form-urlencoded

{
    "grant_type": "refresh_token",
    "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiL0.eyJpYXQiOjE3NTU0MzA3OTcsImp0aSI6IjUwZmE1NTIwLTQ5MjItNDMwZC04YjZiLWY4NzQ5Y2Y4ZGNjNSIsImlzcyf1ImlkMi5lYXN5eC5ydSIsInN1YiI1ImNvZGUiLCJhdWQiOiJpZDIuZWFzeXgucnUiLCJDeHAiOjE3NTU0MzEwOTcsIm5iZiI6MTc1NTQzMDc5NywiZGF0YSI6eyJhdXRob3JpemF0aW9uIjp7ImlkIjoxNn19fQ.bDaie8_31EszqoIrmWcitE3ujPY5DmifnZSlSIcup2E",
    "client_id": 1,
    "client_secret": "BHTHL4sMDtipYZ8vKX7fDQrHucTmPScGxp7b03xXc3qU"
}

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

200
400
403
403
404

Content Type

application/json

{}
{
  "error_code": "bad_request",
  "error_message": "Parameter `client_id` is required"
}
{
  "error_code": "application_disabled",
  "error_message": "Application with given `client_id` is disabled"
}
{
  "error_code": "client_secret_not_match",
  "error_message": "Client secret does not match"
}
{
  "error_code": "application_not_found",
  "error_message": "Application with given `client_id` was not found"
}