🚧

Beta

Please note that it is a Beta feature.

📘

Important

PIN Pair Login can only be used with Cleeng Single Sign-On. So you can utilize it only if Cleeng is your identity provider.

Overview

Device Login (PIN Pair Login) functionality allows users to easily sign in on input-constrained devices that connect to the internet (for example TVs, set-top-boxes, etc.). Rather than authenticate the user directly, the device asks the user to go to a link on their computer or smartphone and authorize the device. The goal is to avoid a poor user experience for devices that do not have an easy way to enter text.

For example, PIN Pair login integration simplifies the login process for TV apps by allowing users to authenticate using a code generated on the TV screen.

PIN Pair Login Benefits:

• It is a secure authentication mechanism used to verify a user’s identity using a dynamic code or PIN.
• It is an effective method for authenticating users on TVs and other devices, providing a balance between security and user convenience.
• It leverages the user’s familiarity with their mobile or desktop devices to facilitate a more secure and user-friendly authentication process on devices that have limited input capabilities, like TVs.

This functionality enables end-users to:

• generate a PIN code on their connected device, called requesting device (e.g. TV or set-top-box) that will allow them to sign in without a need to type in their credentials with a remote
• authorize TV sign-in by typing in the PIN code on an authorizing device (for example a smartphone, tablet, or computer).

The functionality enables broadcasters to:

• generate a PIN code on a connected device (requesting device) via API that will allow to authenticate the access using an authorizing device (for example a phone, a computer)
• use a mobile device (authorizing device) to validate the PIN via API and confirm the connected device’s (requesting device’s) authentication.

Main Concepts

Requesting Device - A device that requests the authentication code, displays it and then gets authenticated when it is confirmed. This is typically a TV.

Authorizing Device - A device that opens the verification URL and confirms the code.

Code - A 6-character alphanumeric authentication code that is used to authorize the device.

• Code Format - A code format is as follows: a code consists of 6 characters using case-insensitive English letters [A-Z] and digits [0-9]. Example: A1BC2D.
• Code Expiration - To keep the app secure and prevent unused codes from accumulating, each code has an expiration date. The expiration time can be set by each broadcaster, but it cannot be more than 15 minutes. The default expiration time is 10 minutes, which means that if the user does not complete the browser flow within 10 minutes, the code expires, and generating a new code on the device will be required to authenticate.

Verification URL - an optional verification URL returned alongside code generation. The option of providing verification URL allows you to extract hardcoded redirection URLs from the client application. The redirection URLs are dynamically provided, which simplifies the future updates.

What you have to do

Prerequisites

As a broadcaster you need to be aware and take care of the following points before you start implementing PIN Pair Login:

1. You have to use Cleeng SSO to be able to integrate PIN Pair Login. (Cleeng must be your identity provider, as the integration does not work with external identity providers).

2. Implement the front-end components to request and display the authentication code or QR code using the API endpoints exposed by Cleeng.

3. Implement the landing page and authentication request verification front-end components using the API endpoints exposed by Cleeng.

4. Configure PIN-Pair Login in the Cleeng Dashboard.
   Active PIN Pair integration in the Cleeng Dashboard is a necessary condition to start the flow.
   Log in to Cleeng Dashboard, go to Admin Settings > Integration Hub > PIN Pair Login. Provide the configuration information:

   • Code Expiration Time - It is the lifetime of a code in minutes. Set the time after which the authentication code expires. It must be between 1 and 15 minutes. Default is 10 minutes.

     📘

     • You can modify default values at any time to fit your specific requirements.
     • If you change a default value and want to go back to the original, you can easily revert to the default.
     • Default values may be updated by the external system. If you want a value to remain unchanged, manually enter the value instead of relying on the default.

   • Verification URL (optional) - provide a base URL where users will verify and authorize their device.

   Click the Save button to save the settings. Once ready, click the Connect PIN Pair Login button to activate the integration.

   

Implementation Steps

The functionality consists of 3 major steps in which three endpoints need to be triggered for a device to be successfully authorized:

1. Sending authentication request on the requesting device (e.g. TV) (Step 1: TV APP Flow in the overview diagram below)
2. Authorization on the authorizing device (e.g. mobile or computer) (Step 2: Browser Flow in the overview diagram below)
3. Retrieving credentials for a particular device (Step 3: TV APP Flow in the overview diagram below)

PIN Pair login is often used on TVs because of its convenience, so for the purposes of this tutorial we will use a TV as an example of a requesting device.

Please see the overview of the PIN Pair login flow in the diagram and the details that follow.

Step 1: TV App Flow - Sending authentication request on the requesting device

1. The user starts the app on the requesting device (e.g. TV).
2. The requesting device requests an authorization code by calling the Generate code endpoint (POST /v1/codes/generate). The request should be sent with the following parameters (all of them are required):deviceId, deviceName, broadcasterId.
3. A unique authentication code and a link to the page (optional) where the user can enter the code is returned.

Step 2: Browser App Flow - Authorization on the authorizing device

1. The user visits the verification URL on the authorizing device (e.g. their computer).
2. The user registers or logs in (this step is outside of PIN Pair).
   Registration or login can be accomplished using MediaStore API (see Register and Login endpoints).
3. Once the user registers/logs in, a request to authorize the device can be made. To make the request, the app must use the JWT token returned by the MediaStore API after registration or login.
4. The authorizing device sends the authorization code to Cleeng API. It authorizes the code by calling the Authorize code endpoint (POST /v1/codes/authorize).
5. The Cleeng platform marks the code as authorized.

Step 3: TV App Flow - Retrieving credentials for a particular device

1. The requesting device makes a call to the Check code endpoint (GET /v1/codes/check) with the code, deviceId, and broadcasterId.
2. If the code is successfully authorized, the device retrieves credentials that will allow it to communicate with Cleeng API.

Testing Guidance

Testing process will depend on the TV app implementation. Once the implementation steps are completed, the following scenarios can be executed in order to validate the correct PIN Pair login integration:

1. PIN Pair login - positive flow

• On the TV app (the requesting device): when a user initiates the login process, they are presented with the authentication code and a link to be used in order to complete the login.
• The user follows the link on the authorizing device and logs in to Cleeng.
• The TV app detects the successful login attempt on the authorizing device and authorizes the user on the TV as well.

2. PIN Pair login with a new code when a previous one expires

• On the TV app: a user initiates the login process and gets a code and a link to be used on an authorizing device but they’re unable to complete the authorization within the token validity period.
• The user is able to receive a new code on the TV app which later can be used on the authorizing device.
• The TV app detects the successful login attempt on the authorizing device and authorizes the user on the TV as well.

3. PIN Pair login attempt with an expired code

• On the TV app: a user initiates the login process and gets a code and a link to be used on an authorizing device, but they are trying to complete the login on the authorizing device when the code has already expired.
• The application on the authorizing device should handle the error in a clear manner for the user.
• The TV app will not proceed with the login completion.