Требования к внешней системе

Доступ к системе Провайдера
Протоколы аутентификации
Эндпоинты (Endpoint)

Доступ к системе Провайдера

Для корректного взаимодействия по сети между Контуром и системой Провайдера, клиенту необходимо обеспечить следующий доступ до своей системы:

порт 443 TCP;
включить в wihte-list диапазоны адресов серверов Контура:
- 46.17.200.0/21
- 89.169.16.0/22
- 185.161.180.0/22

Протоколы аутентификации

Контур выполняет подключение к внешним Провайдерам по двум протоколам:

OpenID Connect
или OAuth 2.0. Схема — только Authorization Code.

Эндпоинты (Endpoint)

Независимо от того, какой протокол используется, внешний Провайдер всегда должен предоставлять следующие методы:

Адрес для аутентификации (Authorization Endpoint).
Token Endpoint.
Userinfo Endpoint (опционально).

Адрес для аутентификации (Authorization Endpoint)

Эндпоинт Провайдера учетных записей, на который Контур будет отправлять запрос для получения кода подтверждения на аутентификацию.

GET <address>/authorize?&client_id=<client_id>&scope=<scopes>&state=<state_value>&redirect_uri=http://www.example.com/&response_type=code

Параметры запроса

client_id	Идентификатор приложения, выдается Контуру при регистрации приложения во внешней системе Провайдера.
scope	Список разрешений, которые необходимы приложению Контура в текущей сессии для получения необходимых клеймов пользователей.
state	Уникальная строка состояния, которая нужна для защиты от CSRF атак, а также для передачи пользовательского контекста. Сохраняется без изменений при перенаправлении пользователя на redirect_uri.
redirect_uri	URL, на который нужно перенаправить пользователя после того, как он аутентифицировался. Принимает значения: Тестовая среда: https://auth-gateway.testkontur.ru/login/callback Боевая среда: https://auth-gateway.kontur.ru/login/callback
response_type	Ответ, который нужно получить от провайдера. В данном случае всегда принимает значение code, так как аутентификация будет проходить по схеме Authorization_code.

Данные в возвращаемом URL

Пользователь должен быть перенаправлен на url, указанный в redirect_uri, с параметрами, зависящими от результата:

Результат	Параметр	Описание	Пример ответа
Аутентификация прошла успешно	state	Строка состояния, которую провайдер возвращает без изменения.	`HTTP/1.1 302 Found Location: https://www.example.com? code=SplxlOBeZQQYbYS6WxSbIA &state=af0ifjsldkj`
Аутентификация прошла успешно	code	Код подтверждения, который можно обменять на токен.
Аутентификация закончилась ошибкой	error	Ошибка аутентификации. Возвращается вместо кода, если пользователь или сервер по какой-то причине не выдал разрешение на доступ к данным.	`HTTP/1.1 302 Found Location: https://www.example.com? error=access_denied`

Token Endpoint

Эндпоинт, формирующий авторизационные токены по схеме Authorization_code. С помощью это метода Контур будет получать Access Token с бэкенда.

POST <address>/token

Заголовки запроса

Content-Type

application/x-www-form-urlencoded

Тело запроса

redirect_uri	URL, на который получили код подтверждения.
grant_type	Способ запроса токена. Принимает значение authorization_code.
code	Код подтверждения, полученный в запросе на Authorization Endpoint.
client_secret	Ключ приложения, выдается Контуру при регистрации приложения во внешней системе.
client_id	Идентификатор приложения, выдается Контуру при регистрации приложения во внешней системе.

Ответ запроса

Метод должен всегда возвращать ответ в формате JSON. Обязательные параметры отмечены звездочкой (*).

access_token*	Токен доступа, который можно использовать для обращения к источнику данных о пользователе.
expires_in	Время жизни Access Token в секундах. Если параметр не вернулся в ответе, то считается, что Access Token живет бесконечно.
refresh_token	Токен, необходимый для обновления Access Token. Если параметр не вернулся в ответе, то считается, что Access Token живет бесконечно.
id_token	Id Token для идентификации пользователя, полученный по протоколу OpenId Connect.

POST /token
 
HEADERS
Content-type: application/x-www-form-urlencoded
 
BODY
{
    client_id=<client_id>,
    client_secret=<client_secret>,
    code=SplxlOBeZQQYbYS6WxSbIA,
    redirect_uri=http://www.example.com,
    grant_type=authorization_code
}
 
RESPONSE
200 OK
Content-type: application/json
{
   «access_token»: <access_token>,
    «expires_in»: <expires_in_seconds>,
    «refresh_token»: <refresh_token>
    «id_token»: <id_token>
}

Userinfo Endpoint

Дополнительный Эндпоинт, через который можно передать информацию о пользователе из системы Провайдера.

GET <address>/userinfo

Заголовки запроса
Метод должен принимать заголовок Authorization: Bearer <token>, где <token> это авторизационный токен пользователя (Access Token), полученный на Token Endoint в обмен на код.

Ответ запроса

Метод должен всегда возвращать ответ в формате JSON. Обязательные параметры отмечены звездочкой (*).

sub*	Идентификатор пользователя в системе Провайдера.
email	Электронная почта.
given_name	Имя пользователя.
family_name	Фамилия пользователя.
middle_name	Отчество пользователя.
title	Должность.

Claim Mapping

Контур принимает информацию о пользователе из внешней системы Провайдера в виде claim'ов в id_token при запросе на Token Endpoint или в ответе с UserInfo Endpoint. Передаваемые данные могут включать следующее, обязательные данные отмечены звездочкой (*):

sub*	Идентификатор пользователя в системе Провайдера/
email*	Электронная почта.
first_name*	Имя пользователя.
family_name*	Фамилия пользователя.
middle_name	Отчество пользователя.
name	ФИО. В качестве разделителя используется пробел.
picture	Ссылка на изображение пользователя.
profile_url	Ссылка на профиль сотрудника в корпоративном портале.
group	Группы пользователя.
title	Должность.
phone	Номер телефона.

Если у интегратора нет возможности передавать данные о пользователе в стандартных клеймах, Контур может настроить соответствие информационных атрибутов как в системе клиента.