Категории

Интеграция с системой аутентификации и авторизации (SSO)

Кратко этапы интеграции с SSO выглядят так:

  • запросить доступ к API SSO на тестовом контуре и дождаться ответа с секретным ключом;
  • реализовать логику обращения к нашему API;
  • добавить кнопку авторизации через Университет 20.35;
  • протестировать взаимодействие с нашим API, в том числе бизнес-логику;
  • запросить доступ к API SSO на промышленном контуре.

Для получения консультации по интеграции в рамках тестового контура необходимо с корпоративного адреса электронной почты ответить на ранее направленное письмо на apps@2035.university с сутью вопроса, приложив по возможности скриншоты/скринкасты до и после описываемого события, url и параметры запросов.

Запрос доступов к API SSO

Доступы на тестовый и промышленный контур запрашиваются по единому формату. Для запроса доступа к ИС необходимо с корпоративного адреса отправить письмо на apps@2035.university с темой письма «Доступы на проект «БАС» _Полное_название_организации_ Тестовый/Промышленный контур».

В теле письма необходимо указать:

  • Проект: БАС
  • Полное название организации
  • Контур: тестовый/промышленный
  • Ответственное за интеграцию лицо:
    • ФИО
    • email
    • телефон.
  • Домен/ссылка сервиса (url) – адрес, откуда будут отправляться запросы. Если ссылок несколько, то нужно будет создавать несколько OAuth клиентов;
  • Домен/ссылка перенаправления (redirect_uri) – адрес, на который будет перенаправлен пользователь после авторизации в SSO, к которому также будет добавлен get параметр code;
  • Идентификатор приложения клиента (client_id) – формируется клиентом самостоятельно и проверяется Университетом 2035 на уникальность (обычно название организации на латинице без пробелов, например, «nashaorganizaciya»). Не желательно оставить пустым - тогда он будет сгенерирован автоматически в виде уникального идентификатора.

В течение 3 дней вы получите в ответ письмо с client_id и с секретным ключом.

Взаимодействие с провайдером аутентификации и авторизации (SSO)

Провайдер аутентификации и авторизации (SSO) является сервисом авторизации, работающим по протоколу OAuth2.

Для начала взаимодействия необходимо выполнить последовательно действия по подключению к SSO, сообщив идентификатор приложения (client_id) и ссылку перенаправления (redirect_uri), получив в ответ токен.

При аутентификации веб-приложений, во время прямого взаимодействия с пользователем используется аутентификация при помощи OAuth2, и в этом случае информацию из профиля пользователя можно получить по ссылке users/me.

URL SSO для тестового контура https://sso.u2035test.ru.

URL SSO для промышленного контура https://sso.2035.university.

Начало процесса авторизации

GET

/oauth2/authorize?client_id=<client_id></client_id>&redirect_uri=<redirect_uri></redirect_uri>&response_type=code

где:

  • <CLIENT_ID> - идентификатор приложения, зарегистрированного в SSO;
  • <redirect_uri> - адрес, на который будет перенаправлен пользователь, к которому также будет добавлен get параметр YOUR_CODE_FROM_AUTHORIZE.</redirect_uri>

Здесь и ниже значение параметра REDIRECT_URI должно совпадать со значением, переданным при подключении, если будет отличаться, то будет возвращен код ошибки.

Получение sso_access_token

POST /oauth2/access_token

-H"content-type: application/x-www-form-urlencoded"

Тело запроса:

client_id=<client_id></client_id>&client_secret=<client_secret></client_secret>&code=<your_code_from_authorize></your_code_from_authorize>&grant_type=authorization_code&redirect_uri=<redirect_uri></redirect_uri>

где:

  • <client_id> - идентификатор приложения, зарегистрированного в SSO;</client_id>
  • <client _secret=""> - токен для SSO, получаемый при выполнении порядка подключения к API;</client>
  • <your_code_from_authorize> - code, полученный в ответе на запрос в пункте «Начало процесса авторизации»;</your_code_from_authorize>
  • <redirect_uri> - адрес, на который будет перенаправлен пользователь после авторизации в SSO, к которому также будет добавлен get параметр SSO_ACCESS_TOKEN.</redirect_uri>

Запрос идентификатора пользователя (leader_id, unti_id)

GET /users/me

-H"Authorization: Bearer <sso_access_token></sso_access_token>

<sso_access_token> - токен, полученный в ответе на запрос в пункте «Получение sso_access_token». </sso_access_token>

Формат ответа:

  • unti_id (int) id пользователя
  • username (str) логин
  • email (str) емейл
  • lastname (str) фамилия
  • firstname (str) имя
  • secondname (str) отчество
  • leader_id (str) id пользователя в leader-id
  • tags (list) список тегов пользователя

Пример бэкенда для python https://pastebin.com/F3Z5MFSz.

Пример бэкенда для PHP (moodle плагин) https://github.com/u2035/moodle-sso-oauth.

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

* {

"unti_id": 1,

"username": "user",

"email": "user@example.com",

"lastname": "Иванов",

"firstname": "Иван",

"secondname": "Иванович",

"leader_id": "123456",

"tags": ["assistant"],

}

* 401 если пользователь не авторизован

Обращаем ваше внимание, что email адрес не проходил валидации с нашей стороны.

Кнопка авторизации через Университет 20.35

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

Гайд для провайдеров по использованию элементов дизайна 2035 (в том числе кнопок входа).

Тестирование

Для подтверждения того, что вы успешно прошли авторизацию в тестовом контуре, вам нужно будет в запросе на доступ к продуктовому контуру указать ваш Leader ID и содержание ответа «GET /users/me» для данного пользователя.

Для получения консультации по интеграции в рамках тестового контура необходимо с корпоративного адреса электронной почты ответить на ранее направленное письмо на apps@2035.university с сутью вопроса, приложив по возможности скриншоты/скринкасты до и после описываемого события, url и параметры запросов.

Сценарии тестирования

Необходимо протестировать основные сценарии:

  1. Прозрачная авторизация в системе провайдера не зарегистрированного ранее пользователя.
  2. При прямом переходе на курс неавторизованного пользователя, а также в случае автоматического прекращения сессии пользователя по времени на сайте провайдера, должна быть возможность по кнопке войти через Университет 20.35. Кнопка должна соответствовать одной из https://files.2035.university/d/26a31d08ce9a442fa713/.


Типовые ошибки при интеграции с SSO

Ошибка:
Сервис отвечает “invalid_request The requested redirect didn't match the client settings” в запросе /oauth2/authorize.
Решение:
В запросе указали неверный redirect_uri (отличающийся от указанного в запросе на доступ). Напишите письмо с просьбой изменить его.
Указанный в запросе redirect_uri, должен точно совпадать с прописанным в настройках клиента (например, если в клиенте https://staging.experts.work/, а в запросе http://staging.experts.work/ или https://staging.experts.work или https://staging.experts.work/auth/callback/, вы получите ошибку)!

Ошибка:
500 в запросе /oauth2/access_token
Решение:
В запросе на /oauth2/authorize не нужно указывать scope=openid и nonce, из-за этого потом возникает 500 в запросе /oauth2/access_token.

Ошибка:
500 в запросе /oauth2/access_token.
Решение:
Некорректное значение client_secret в /oauth2/access_token. Проверьте, что передаете корректное значение в соответствии с контуром, не потеряли символы в конце/начале и т.п.

Ошибка:
invalid_grant в запросе /users/me.
Решение:
Невалидный access_token, проверьте, что подставляете корректный.

Ошибка:
unauthorized_client An unauthorized client tried to access your resources.
Решение:
Некорректный client_secret или client_id, проверьте, что подставляете корректный (не потеряли/не добавили знаки/пробелы, используете нужную среду (прод/тест).

Частые вопросы по интеграции с SSO

Вопрос:
Откуда выполнять код - с сервера или с клиента?
Ответ:
Только с сервера! Это единственный безопасный вариант.

Вопрос:
Какая информация будет в payload?
Ответ:
Там будет ключ access_token и (3) refresh_token. Это довольно легко можно проверить, пройдя шаги для получения токена, если уже есть client/secret.

Вопрос:
Как произвести валидацию токена? Например, есть ли endpoint получения публичного ключа?
Ответ:
Например, запросить информацию о пользователе /users/me, этот эндпоинт требует валидный токен.

Вопрос:
Что за вход через госуслуги?
Ответ:
В документации на интеграцию описана авторизация только через LeaderID, и только так и надо авторизовать.
Авторизация через Госуслуги есть только на тестовой среде, тестируем в рамках другого проекта, тестовые среды у нас не разделены.