Подключение приложений умных устройств (IoT)#

Общие сведения#

В Blitz Identity Provider реализована поддержка возможности авторизации приложений умных устройств (приложений голосовых помощников, Smart TV, чат-ботов) с использованием учетной записи пользователя на другом устройстве. Для такой авторизации используется спецификация RFC 8628 OAuth 2.0 Device Authorization Grant.

Настройки подключения#

В целях взаимодействия с Blitz Identity Provider приложение должно использовать следующие адреса:

  • URL для получения кода подтверждения авторизации (OAuth 2.0 Device Authorization Grant):

    • https://login-test.company.com/blitz/oauth/da (тестовая среда)

    • https://login.company.com/blitz/oauth/da (продуктивная среда)

  • URL для получения и обновления маркера доступа:

    • https://login-test.company.com/blitz/oauth/te (тестовая среда)

    • https://login.company.com/blitz/oauth/te (продуктивная среда)

  • URL для получения данных пользователя:

    • https://login-test.company.com/blitz/oauth/me (тестовая среда)

    • https://login.company.com/blitz/oauth/me (продуктивная среда)

  • URL для получения данных о маркере доступа:

    • https://login-test.company.com/blitz/oauth/introspect (тестовая среда)

    • https://login.company.com/blitz/oauth/introspect (продуктивная среда)

  • URL для выполнения логаута:

    • https://login-test.company.com/blitz/oauth/logout (тестовая среда)

    • https://login.company.com/blitz/oauth/logout (продуктивная среда)

Все эти URL, а также дополнительные сведения, размещены по адресу динамически обновляемых настроек (метаданных) каждой среды Blitz Identity Provider:

Совет

См. RFC 8414 OAuth 2.0 Authorization Server Metadata.

  • https://login-test.company.com/blitz/.well-known/openid-configuration (тестовая среда)

  • https://login.company.com/blitz/.well-known/openid-configuration (продуктивная среда)

Разработчики приложений могут не прописывать все указанные URL в конфигурации своего приложения, а использовать в настойках единую ссылку на метаданные Blitz Identity Provider.

Получение кода авторизации#

Для инициирования авторизации приложение умного устройства должно сделать запрос в адрес Blitz Identity Provider на сервис получения кода подтверждения авторизации (/oauth/da). Запрос должен быть сделан методом POST. Запрос должен содержать заголовок Authorization со значением Basic {secret}, где secret – это client_id:client_secret (например, app:topsecret) в формате Base64.

Пример заголовка:

Authorization: Basic ZHluOkNTSTo…dx

Тело запроса должно содержать следующие параметры:

  • client_id – идентификатор приложения;

  • scope – запрашиваемые разрешения.

Пример запроса:

POST /blitz/oauth/da HTTP/1.1
Authorization: Basic ZHluOkNTSTo…dx
Content-Type: application/x-www-form-urlencoded

client_id=test-app&scope=profile

В ответ Blitz Identity Provider вернет данные, необходимые для подтверждения входа на другом устройстве:

  • device_code – код устройства;

  • user_code – отображаемый пользователю код подтверждения запроса авторизации;

  • verification_uri – ссылка на страницу, на которой пользователь может ввести код подтверждения запроса авторизации;

  • verification_uri_complete – ссылка на страницу, в которой в качестве параметра уже подставлен код подтверждения запроса авторизации;

  • expires_in – время жизни пользовательского кода в секундах;

  • interval – рекомендуемый период ожидания в секундах при опрашивании приложением ввода пользователем кода подтверждения запроса авторизации.

Пример ответа с успешным выполнением запроса:

{
    "device_code": "7Lz30lK57bWaKHBYxM8kW7KpOFvDg_4ujz3LpQxcleE",
    "user_code": "934-367-578",
    "verification_uri": "https://device.company.com",
    "verification_uri_complete": "https://device.company.com?uc=934-367-578",
    "expires_in": 300,
    "interval": 5
}

Получив ответ приложение умного устройства должно инструктировать пользователя, чтобы он перешел по ссылке verification_uri и ввел код из user_code.

Примечание

Ссылка в verification_uri выводится в соответствии с настройками, заданными в Blitz Identity Provider. Рекомендуется настроить, чтобы эта ссылка была короткой и удобной для ввода пользователям, а также хорошо воспринималась на слух или красиво отображалась на экране Смарт ТВ. С данной ссылки должна быть настроена переадресация на обработчик ввода пользователем кода подтверждения, расположенный на странице https://login.company.com/blitz/oauth/device?ci=client_id, где вместо client_id нужно задать идентификатор зарегистрированного в Blitz Identity Provider приложения, из настроек которого будут браться разрешенные способы входа и настройки внешнего вида страницы входа.

В зависимости от типа умного устройства нужно выбрать наиболее удобный для пользователя способ. Например:

  • При авторизации в Smart TV приложение может отрисовать пользователю QR-код, в котором закодировать ссылку из verification_uri_complete. Тогда пользователю нужно будет навести камеру телефона на QR-код и пройти авторизацию на телефоне.

  • При авторизации в чат-боте приложение может отрисовать пользователю кнопку, открывающую в браузере ссылку из verification_uri_complete. Тогда пользователю нужно будет пройти авторизацию в браузере своего устройства.

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

Получение маркера безопасности#

После предоставления пользователю инструкций приложение умного устройства должно с интервалом из параметра interval начать осуществлять опрос Blitz Identity Provider для получения маркеров безопасности. Для этого приложение должно обращаться в Blitz Identity Provider методом POST на URL для получения маркера (/oauth/te). Запрос должен содержать заголовок Authorization со значением Basic {secret}, где secret – это client_id:client_secret экземпляра мобильного приложения в формате Base64.

Тело запроса должно содержать параметры:

  • grant_type – значение urn:ietf:params:oauth:grant-type:device_code;

  • device_code – ранее полученный код устройства.

Пример запроса:

POST /blitz/oauth/te HTTP/1.1
Authorization: Basic cG9…A==
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:device_code&device_code=Yrn…\_0

Если пользователь еще не подтвердил авторизацию, то Blitz Identity Provider вернет следующий ответ с ошибкой:

{
    "error": "authorization_pending",
    "error_description": "The authorization request is still pending"
}

Если срок действия пользовательского кода истек или код неправильный, то Blitz Identity Provider вернет следующий ответ с ошибкой:

{
    "error": "invalid_grant",
    "error_description": "The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client."
}

Если пользователь подтвердил авторизацию, то Blitz Identity Provider вернет приложению маркер доступа и информацию о нем, а также маркер обновления.

Пример ответа с успешным выполнением запроса:

{
    "access_token": "eyJ…tA",
    "refresh_token": "wVE…cw",
    "scope": "profile",
    "token_type": "Bearer",
    "expires_in": 3600
}

Используя полученный маркер доступа, приложение умного устройства может запросить актуальные данные пользователя из Blitz Identity Provider.