Connecting Smart Device (IoT) applications#

General information#

Blitz Identity Provider supports the ability to authorize smart device applications (voice assistant applications, Smart TV, chatbots) using a user account on another device. For such authorization, the RFC 8628 OAuth 2.0 Device Authorization Grant. is used.

Connection settings#

In order to interact with Blitz Identity Provider, the application must use the following addresses:

  • URL for receiving the authorization confirmation code (OAuth 2.0 Device Authorization Grant):

    • https://login-test.company.com/blitz/oauth/da (test environment)

    • https://login.company.com/blitz/oauth/da (production environment)

  • URL for getting and updating the access token:

    • https://login-test.company.com/blitz/oauth/te (test environment)

    • https://login.company.com/blitz/oauth/te (production environment)

  • URL for getting user data:

    • https://login-test.company.com/blitz/oauth/me (test environment)

    • https://login.company.com/blitz/oauth/me (production environment))

  • URL for getting access token data:

    • https://login-test.company.com/blitz/oauth/introspect (test environment)

    • https://login.company.com/blitz/oauth/introspect (production environment)

  • URL for performing the logout:

    • https://login-test.company.com/blitz/oauth/logout (test environment)

    • https://login.company.com/blitz/oauth/logout (production environment)

All these URLs, as well as additional information, are located at the address of dynamically updated settings (metadata) of each Blitz Identity Provider environment:

Tip

See RFC 8414 OAuth 2.0 Authorization Server Metadata.

  • https://login-test.company.com/blitz/.well-known/openid-configuration (test environment)

  • https://login.company.com/blitz/.well-known/openid-configuration (production environment)

Application developers can use a single link to Blitz Identity Provider metadata instead of listing all of the URLs in their application’s configuration.

Getting the authorization code#

To initiate authorization, the smart device application must make a request to Blitz Identity Provider for the service to receive the authorization confirmation code (/oauth/da). The request must be made using the POST method. The request must contain the header Authorization with the value Basic {secret}, where secret is client_id:client_secret (for example, app:topsecret) in Base64 format.

Example of a header:

Authorization: Basic ZHluOkNTSTo…dx

The request body must contain the following parameters:

  • client_id is the application ID;

  • scope is requested permissions.

Request example:

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

client_id=test-app&scope=profile

In response, Blitz Identity Provider will return the data required to confirm login on another device:

  • device_code is a device code;

  • user_code is the authorization request confirmation code displayed to the user;

  • verification_uri is a link to a page where the user can enter a confirmation code for the authorization request;

  • verification_uri_complete is a link to a page where the authorization request confirmation code has already been substituted as a parameter;

  • expires_in is the lifetime of the user code in seconds;

  • interval is the recommended waiting period in seconds when the application asks the user to enter the authorization request confirmation code.

Example of a response with successful execution of the request:

{
    "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
}

Upon receiving a response, the smart device application should instruct the user to click on the verification_uri link and enter the code from user_code.

Note

The link in verification_uri is displayed according to the settings set in Blitz Identity Provider. It is recommended to configure this link to be short and easy for users to enter, as well as well perceived by ear or beautifully displayed on the Smart TV screen. From this link, redirection should be configured to the handler for user input of the confirmation code located on the page https://login.company.com/blitz/oauth/device?ci=client_id, where instead of client_id you need to set the ID of the application registered in Blitz Identity Provider, from the settings of which the allowed login methods and settings for the appearance of the login page will be taken.

Depending on the type of smart device, you need to choose the most user-friendly method. For example:

  • When logging in to a Smart TV, the application can draw the user a QR code in which encode the link from verification_uri_complete. Then the user will need to point the phone’s camera at the QR code and log in on the phone.

  • When logging in to the chatbot, the application can draw the user a button that opens a link from verification_uri_complete. in the browser.` Then the user will need to log in to their device’s browser.

  • When logging in to the voice assistant application, the application can instruct the user which site he should go to and voice the code that the user must enter, or the application can send the user an SMS message or an e-mail with instructions.

Getting a security token#

After providing instructions to the user, the smart device application should start polling Blitz Identity Provider with an interval from the interval parameter to obtain security tokens. To do this, the application must access Blitz Identity Provider using the POST method at the URL to receive a token (/oauth/te). The request must contain the header Authorization with the value Basic {secret}, where secret is the client_id:client_secret of the mobile application instance in Base64 format.

The request body must contain parameters:

  • grant_type is the value urn:ietf:params:oauth:grant-type:device_code;

  • device_code is the previously received device code.

Request example:

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

If the user has not yet confirmed authorization, Blitz Identity Provider will return the following response with an error:

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

If the user code has expired or the code is incorrect, Blitz Identity Provider will return the following error response:

{
    "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."
}

If the user has confirmed authorization, Blitz Identity Provider will return the access token and information about it to the application, as well as the update token.

Example of a response with successful execution of the request:

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

Using the received access token, the smart device application can запросить up-to-date user data from Blitz Identity Provider.