Инструкция по интеграции с цифровой платформой УНТИ 2035

Цифровой след. Общие сведения

Цифровой след (ЦС) – это данные об образовательной, профессиональной или иной деятельности человека, представленные в электронной форме.
Цифровой след используется для анализа развития человека с целью подтверждения получения им нового опыта деятельности, подготовки рекомендаций по следующему шагу развития, накопления данных о траекториях развития, для совершенствования работы системы рекомендаций.

Формат цифрового следа

Цифровой след передается в формате xAPI (https://xapi.com/).

Структуры данных и протоколы для приема цифрового следа: Структуры данных и протоколы для приема цифрового следа.

Интерфейсы Платформы Университет.2035 для сбора ЦС

На платформе 2035 цифровой след хранится в LRS - специализированном хранилище данных о цифровом следе пользователя. LRS предоставляет API для загрузки цифрового следа.

Возможны два варианта загрузки цифрового следа в LRS:

• Провайдер контента может передать подготовленный файл формата xAPI в систему Университета.2035 вручную через POST запрос в LRS. 
• В случае если система обучения (LMS) Провайдера контента имеет возможность установки готовых плагинов по передаче данных в формате xAPI, то цифровой след может передаваться с использованием плагина.

Обратите внимание, что плагины могут не поддерживать все необходимые требования к составу и передаче цифрового следа.

Для синхронизации id студента, по которому ОО будет передавать на платформу цифровой след, необходимо также реализовать интеграцию с системой аутентификации и авторизации (SSO) Платформы Университета 2035.

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

Этапы интеграции с Университетом 2035

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

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

Все эти этапы подробнее описаны ниже.

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

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

Необходимо с корпоративного адреса электронной почты отправить письмо на apps@2035.university следующего содержания:

1. Тема письма: Подключение к API SSO Полное наименование организации. Тестовый/Продуктовый контур;
2. Текст письма:

• Наименование организации: Полное наименование организации;
• Проект: Проект;
• Контур: тестовый/продуктовый;
• Домен/ссылка сервиса (url) – адрес, откуда будут отправляться запросы. Если ссылок несколько, то нужно будет создавать несколько OAuth клиентов;
• Домен/ссылка перенаправления (redirect_uri) – адрес, на который будет перенаправлен пользователь после авторизации в SSO, к которому также будет добавлен get параметр code; Обратите внимание: redirect_uri, который вы будете указывать в запросе, должен точно совпадать с прописанным в настройках клиента (например, если в клиенте https://staging.experts.work/, а в запросе http://staging.experts.work/ или https://staging.experts.work или https://staging.experts.work/auth/callback/, вы получите ошибку)!
• Идентификатор приложения клиента (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>&redirect_uri=<redirect_uri>&response_type=code</redirect_uri></client_id>

где:

• <app_id> - идентификатор приложения, зарегистрированного в sso;</app_id>
• <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) емейл
• image (dict) словарь, где ключи это разрешение картинки, а значения - url этой картинки
•  lastname (str) фамилия
• firstname (str) имя
•  secondname (str) отчество
•  gender (str) male|female
•  date_of_birth (str) формат %d.%m.%Y
•  tel (list) список телефонных номеров
• job (dict)
• leader_id (str) id пользователя в leader-id
•  tags (list) список тегов пользователя
• city (str) город
•  user_consent (list)
• hashes (dict) хэши пользователя в разных системах

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

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

Из ответа необходимо выбрать только leader_id и записать в учетные данные пользователя, чтобы в дальнейшем вместе со сведениями о нём передавать и этот параметр.

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

* {

      "unti_id": 1,

      "username": "user",

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

      "image": {

       "Small": "http://example.com/photo_sm.jpg",

       "Medium": "http://example.com/photo_m.jpg",

       "Large": "http://example.com/photo_lg.jpg",

       "Original": "http://example.com/photo.jpg",

      },

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

      "firstname": "Иван",

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

      "gender": "male",

      "date_of_birth": "31.01.1980",

      "tel": ["+7 (999) 999-99-99"],

      "job": {

       "EndMonth": null,

       "EndYear": null,

       "StartMonth": null,

       "StartYear": null,

       "Position": "position",

       "Company": {

           "Name": "company",

           "Id": 1,

           "CompanyId": 2

       }

      },

      "leader_id": "123456",

      "tags": ["assistant"],

      "city": "Москва",

      "user_consent": {"accepted": true, "created_at": "2020-06-17T12:40:58.135866Z"},

      "hashes": {"gtm": "12341234-1234-1234-1234-123412341234"}

  }

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

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

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

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

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

Частые ошибки

Ошибка:
Сервис отвечает “invalid_request The requested redirect didn't match the client settings.”

Решение:
В запросе указали неверный redirect_uri (отличающийся от указанного в запросе на доступ). Напишите письмо с просьбой изменить его.
Указанный в запросе redirect_uri, должен точно совпадать с прописанным в настройках клиента (например, если в клиенте https://staging.experts.work/, а в запросе http://staging.experts.work/ или https://staging.experts.work или https://staging.experts.work/auth/callback/, вы получите ошибку)!

Загрузка цифрового следа с использованием API к LRS

Этапы интеграции с Университетом 2035

Для интеграции с LRS Университета 2035 необходимо последовательно совершить следующие действия:

1. Запросить доступ к тестовому хранилищу LRS, в которое вы будете загружать данные. Если вы работаете с нами по нескольким проектам, для каждого проекта нужно отдельное хранилище. Правила выдачи прав доступа описаны ниже.
2. Протестировать передачу в LRS полного пакета стейтментов по одному пользователю. Подробно описан ниже. Процесс тестирования двухсторонний, с участием технических специалистов Платформы 2035 и провайдера. 
3. Запросить доступ к хранилищу LRS на продуктовом контуре. После получения доступа вы сможете загружать ЦС на на продуктовом контуре.

Как получить доступ к тестовому хранилищу

Направьте заявку на выдачу токена письмом на электронную почту apps@2035.university:

1. Тема: Доступ к тестовому External LRS, название организации.
2. Текст: Просим выдать логин, пароль и basic auth токен к External LRS.
3. Для какого контура: Тестовый.
4. Организация (юридическое наименование, как в договоре).
5. Название проекта, в рамках которого проходит интеграция.

В ответ вы немедленно получите автоответ от нашего саппорта, что заявка принята. Затем в течение 3 дней заявка будет обработана, и вы получите письмо с информацией, необходимой для доступа. Сразу после этого вы можете приступать к тестированию передачи ЦС.

Этапы тестирования интеграции с тестовым стендом LRS Университета 2035

В Университете 2035 используется LRS (Learning Record Store, хранилище учебных активностей) под названием «Learning Locker».

Документация на английском языке тут: http://docs.learninglocker.net/welcome/.

Интеграция с LRS Университета 2035 заключается в 2-х аспектах:

1. Настройка инструмента оправки запросов к RESTful API на стороне LRS.
   1. Отправка фактов в LRS;
   2. Получение фактов из LRS.
2. Настройка шаблонов отправки сообщений (xAPI) для каждого фиксируемого факта.

Перед началом подключения к API LRS вы получили параметры доступа к нему, которые должны выглядеть так:

1. xAPI Endpoint: https://lrs-external.u2035test.ru/data/xAPI
2. Key: ffcdf8e906c2975e299e305cc695b92bdd4251f1
3. Secret: b7970235d91ee57a382a75dddd825ce8732abb9b
4. Basic: ZmZjZGY4ZTkwwwMyOTc1ZTI5OWUzMDVjYzY5NWI5MmJhZTQyNTFmMTpiNzk3MDIzNWQ5MWVlNTdhMzgyYTc1ZWVlZDgyNWNlODczMmFiYjli

Пояснения к параметрам:

1. Первый параметр для всех организаций одинаковый – это адрес API тестового стенда LRS Университета 2035.
2. Второй, третий и четвертый – индивидуальные для каждого хранилища для каждой организации (на стороне LRS для организации может быть настроено несколько хранилищ). Приведены измененные параметры только для того, чтобы был пример, как они должны выглядеть.
3. Используется либо 2-й и 3-й параметры, либо 4-й, они являются взаимозаменяемыми, только два первых указываются в полях логин и пароль некоторых инструментов отправки REST-запросов, а последний тоже самое только в base64-кодировке и используется в параметре Authorization заголовка запроса.

Ниже по тексту будут представлены в качестве примеров скриншоты из бесплатного инструмента работы с REST API Postman.

Настройка параметров и проверка связи

Необходимо в средстве/механизме оправки REST запросов указать Адрес API (первый параметр выше + /statements).

Параметры заголовка - параметры авторизации (2-3 или 4 параметры указанные выше).

Обязательные параметры:

Для проверки связи выполните следующие действия:

1. Отправить запрос «Get» с указанными на предыдущем этапе данными. В ответ должен вернуться статус 200 (ОК).
2. Если данные, указанные на предыдущем шаге указаны не верно, то в ответ на отправленный запрос отобразится статус ошибки:
   1. Не найден API, если адрес URL указан неправильно.
   2. 404 Not Found, если к адресу не добавили /statements.
   3. 400 Bad Request, если не указаны заголовки или указаны не верно (X-Experience-API-Version обязателен для любых запросов, content-type для Get не обязателен).
   4. 401 Unauthorized, если неправильно указали параметры авторизации.
      
3. Вторым запросом для проверки подключения к LRS отправить запрос «POST» с ранее указанными параметрами и простым сообщением в теле запроса: {"Test":"тест"}. В ответ на такой запрос должен быть получен статус 400 Bad Request телом ответа:

 {
    "errorId": "aa9c8065-6884-48ac-adfd-b283f49e14ad",
    "warnings": [
        "Missing required value in 'statements.0.actor'",
        "Missing required value in 'statements.0.verb'",
        "Missing required value in 'statements.0.object'",
    "Unknown keys (Test) set in 'statements.0'"
]
}

Данный ответ означает, что запрос был отправлен в LRS, но его структура не соответствует структуре xAPI, предполагающий обязательные элементы, описывающие факт: actor, verb и object.

Получение указанного ответа означает, что настройка и тестирование вашего средства/механизма отправки запросов в LRS завершено и нужно переходить к формированию корректных сообщений о фактах обучения в формате xAPI.

Как получить доступ на продуктовом контуре

Получение доступов на продуктовый LRS аналогичен получению доступа к тестовому хранилищу.

Направьте заявку на выдачу токена письмом на электронную почту apps@2035.university:

1. Тема: Доступ к продуктовому External LRS, название организации.
2. Текст: Просим выдать логин, пароль и basic auth токен к External LRS.
3. Для какого контура: Продуктовый.
4. Организация (юридическое наименование, как в договоре).
5. Название проекта, в рамках которого проходит интеграция.

В ответ вы немедленно получите автоответ от нашего саппорта, что заявка принята. Затем в течение 3 дней заявка будет обработана, и вы получите письмо с логином, паролем и секретным ключом.