Категории

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

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

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

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

Обратите внимание!
Для ускорения обработки обращений всю дальнейшую переписку лучше вести с этого же адреса.


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

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

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

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

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

Для тестирования выдается временный доступ на 5 рабочих дней. По истечении 5 рабочих дней доступ отзывается. Доступ может быть продлен по запросу.

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

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

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

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

URL SSO https://sso.2035.university.

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

GET

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

где:

  • <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_secret=<client_secret>&code=<your_code_from_authorize>&grant_type=authorization_code&redirect_uri=<redirect_uri></redirect_uri></your_code_from_authorize></client_secret></client_id>

где:

  • <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 (в том числе кнопок входа) находится здесь:

Гайд для провайдеров по использованию элементов дизайна 2035

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

Для получения консультации по интеграции в рамках тестового контура необходимо с корпоративного адреса электронной почты ответить на ранее направленное письмо на 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, этот эндпоинт требует валидный токен.