Sign-in for web TV

The JavaScript SDK implements the device grant flow, also known as the device auth grant, to enable OAuth 2.0 authentication for single sign-on (SSO). This flow is intended for devices with limited input capabilities, like smart TVs and game consoles, including Tizen, WebOS, Xbox, and Playstation. This quickstart guides you in creating an OpenPass client to integrate with your device and implement SSO for the open internet.

Follow these instructions to install the SDK, then configure your site to reference it and run the limited input device grant flow.

The following sections detail each step.

1. Install the SDK

You can install the SDK on a CDN or use NPM.

Installing using CDN has limitations. Unlike NPM, developers have limited control over the code they can use for shipping when compiling, and they cannot deploy or optimize JavaScript bundles by including dependencies like OpenPass. Also, some developers prefer to fix versions in NPM.

CDN

To install on a CDN, run the following command.

<script src="https://cdn.myopenpass.com/openpass-js-sdk/v4/openpass-js-sdk.min.js"></script>

NPM

To install using NPM, run the following command in your project.

npm install @openpass/openpass-js-sdk

In your code, reference the library. Here is an example:

// ES6 / TypeScript
import { OpenPassClient } from "@openpass/openpass-js-sdk";

When completed, go to the following step.

2. Initialize the OpenPass client

The OpenPass client in your web application manages the link generation for your sign-in button and handles the results of user sign-ins.

To initialize an instance of the OpenPass client, update the option parameters in the new OpenPassClient(options) method. The client is created once in your application and referenced in the appropriate places.

openPassClient = new OpenPassClient({ clientId: "{{clientId}}" });

When initialization is complete, go to the following step.

3. Authorize the device to start the flow.

Call the authorizeDevice method to initiate the device auth flow.

const authorizeDeviceDataResponse = await openPassClient.authorizeDevice({});

For a full list of parameters, see API reference.

Once you receive the device authorization response, you must display the verificationUriComplete link (through the QR code or other means) to the user so they can authenticate on another device.

4. Get the device token to finalize the flow.

To check the status of the authentication flow and retrieve the tokens, implement the deviceToken method using the deviceCode value returned from the authorizeDevice call.

try {
  // wait `authorizeDeviceData.interval` seconds

  // Check the status of the device token request.
  const deviceTokenWithStatus = await openpassClient.deviceToken({ deviceCode: authorizeDeviceData.deviceCode });

  if (deviceTokenWithStatus.status === "ok") {
    console.log("User authenticated on another device. Id token: " + deviceTokenWithStatus.tokens.idToken);

  } else if (deviceTokenWithStatus.status === "authorization_pending") {
    console.log("Authorization pending...");
    // wait `authorizeDeviceData.interval` seconds before next poll

  } else if (deviceTokenWithStatus.status === "slow_down") {
    console.log("Authorization pending, slow down polling...");
    // wait (`authorizeDeviceData.interval` x multiplier) seconds before next poll
  }

} catch (e) {
  console.log(e);
}

For a full description of the response, see the API reference.

Enable polling

To enable polling and monitor the result from the deviceToken method each time, use the following setInterval code example and specify the number of attempts.

// Poll for the device token using setInterval. Other techniques can be used, such as setTimeout or async/await with a delay.
let pollingInterval = setInterval(async () => {

    // A counter can be used to stop polling after a certain number of attempts.
    counter++;

    // Stop polling if polling is not enabled, or after a specified number of attempts.
    // Note: You can implement other logic to stop polling.
    if (!isPollingEnabled() || counter > maxPollingAttempts) {
        // To stop polling, clear the interval.
        clearInterval(pollingInterval);
        return;
    }

    try {

        // Call the get device token method.
        const deviceTokenResponse = await openPassClient.deviceToken({ deviceCode: authorizeDeviceData.deviceCode });

        // If the device token was returned successfully, stop polling and process the result.
        if (deviceTokenResponse.status === "ok") {

            // To stop polling, clear the interval.
            clearInterval(pollingInterval);

            // Process the response, which includes the ID token, access token, and refresh token.
            // Note: Implement your own logic to process the response.
            processTokenResponse(deviceTokenResponse);

        } else if (deviceTokenResponse.status === "authorization_pending") {
            // Authorization is pending, so continue polling.

        } else if (deviceTokenResponse.status === "slow_down") {
            // Slow down the polling. For example, increase the polling interval by 2 times. Note that this is not implemented in this example.
        }

    } catch (error) {
        // Handle any errors that occur during the call to the device token function.
        // Note: Implement your own error handling.
        handleError(error);
    }

}, pollInterval);

Additional resources

For more information, see the following pages:

• JavaScript API reference
• OpenPass Sample Sites
• UID2
• Integration best practices
• Co-branding guidelines