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

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

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

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

порт 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. Передаваемые данные должны

Обязательные claim-ы:

«sub» — идентификатор пользователя в системе Провайдера;
«email» — электронная почта;
«first_name» — имя пользователя;
«family_name» — фамилия пользователя.

Рекомендуемые claim-ы, в дополнение к обязательным:

«middle_name» — отчество пользователя;
«name» — ФИО, в качестве разделителя используется пробел.
«picture» — ссылка на изображение пользователя;
«profile_url» — ссылка на профиль сотрудника в корпоративном портале;
«group» — группы пользователя;
«title» — должность;
«phone» — номер телефона.

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