Roku SDK Documentation : Roku Federated Identity Single Sign-On

Table of Contents


Introduction

This specification defines a mechanism and protocols for the Roku Federated Identity SSO (RF SSO) service, whereby a Channel Partner can authorize a Roku service to share a federated identity unique to that channel in order to establish an Account Link between a Roku Customer account and a Partner User account. This account link can be used to automatically sign a user in to a Partner Channel Application, especially when the user has added an additional Roku device to their Roku account or has performed a factory reset.

High Level Process Overview

Step 1. User launches Partner Channel Application.

Step 2: The Channel Application determines if the Roku device is linked to the Partner content service (most likely by locating a proprietary credential in the local registry.)

Step 3: If the device is not linked, the channel application requests a roku_pucid (A Roku-defined Partner Unique Customer Identifier) from the RF SSO service.

Step 4: The Channel Application securely passes the roku_pucid up to the Partner service and if there is a Partner customer account with the matching roku_pucid, the local registry is updated and the user is automatically signed in.


Note: If the partner service does not have a matching roku_pucid, the user is prompted to sign in or create an account (if required). The roku_pucid obtained is stored on the Partner service and the registry is updated.

Additionally, Channel Applications that do not require customers to actively create accounts can still obtain the roku_pucid to provide users a consistent personalized experience on more than one Roku device linked to the same Roku account.

 

 Important: If a customer has actively signed out of the Partner application, the local registry should note this so that they are not automatically signed in upon the next launch of the channel.

The sequence diagram (in the following section) depict the protocol flows between the various actors using the RF SSO service. This diagram is only illustrative and does not represent the actual sequence of interaction. 

Channel Activation Using RF SSO

Pre-requisites

A user should have:

  • activated their Roku Player, and
  • linked their player to a Roku Customer Account.

In the event the customer does not have a Roku account they must create a new account at this time.

Note: On the first Player, the customer must add a Channel to their device. The Channel will be added automatically to subsequent devices during activation.

Channel Activation

The following protocol sequence is initiated by the Channel application on the Roku Player at startup. The Channel application determines if the Roku Player is linked to the Partner content service (most likely by locating a proprietary credential in the local registry.) If the device is not linked or explicitly signed out of the Channel (this state information must also persist in the registry) then the protocol interactions defined in this section should be initiated. 

Figure 1: Partner Channel Activation protocol

The protocol interactions between RF SSO, Partner and Player must use the HTTP POST method for requests. All requests and responses must be expressed as JSON objects with the Content-Type of “application/json”.  This simplifies request, response generation, and processing to support a single encoding.

All traffic is communicated over a Server authenticated TLS connection unless explicitly specified otherwise.

Request Partner Unique Customer Identifier (roku_pucid)

This request must be executed in the context of the Channel application. This should occur at channel launch whenever the Channel’s proprietary authentication credential is not in the Channel’s local registry AND the user has not explicitly signed out of the Channel.

The BrightScript ChannelStore API is invoked to initiate this protocol interaction. 

 

store  = CreateObject(“roChannelStore”)
cred   = store.GetChannelCred()

 

The interaction MUST use TLS Mutual Authentication between the Roku Player and the Channel Store Identity Service. The Identity service shall only release the roku_pucid to an authorized Roku Streaming Player. This request must be made using a published channel (either private or public).

Response Examples

Successful Response URI

A successful response to the request must be encoded as a JSON object. The token_type for this response must be the URI:

 

urn:roku:pucid:token_type:pucid_token

 

Roku_pucid UUID

The roku_pucid should be represented as a UUID derived from well-defined Roku Namespace UUID. The URI-Template follows:

 

urn:roku:pucid:<channel-id>:<user-id>:<random>

Associative Array Contents

An informative example of the contents in the associative array “cred” from a successful response follows:

 

{
    channelID: "12345"
    json: "{
      "error":null,
      "roku_pucid":"deedcafe-721c-59e1-8b82-a2a511d9b876",
      "token_type":"urn:roku:pucid:token_type:pucid_token"
    }”
    publisherDeviceID: "7229876e-0d1e-5f60-b19b-7f6ccef2a8e8"
    status: 0
}

Request Error

An error response returns and empty json object and additional status information.

An informative example of a failed response follows:

 

{
    channelID: "12345"
    json:
    publisherDeviceID: "7229876e-0d1e-5f60-b19b-7f6ccef2a8e8"
    status:  400
}

 

FAQ (Frequently Asked Questions)

  1. Q: If a user manually signs out of the channel, are they automatically signed in the next time they launch the channel?

    A:
     No, if a user manually signs out, they will need to sign in again the next time. The channel registry should be updated to ensure they are not automatically signed in.

  2. Q: If the user is signed into the channel using RF SSO on multiple devices and then signs out, are they automatically signed out of all devices?

    A: No. They will only be signed out on that particular device that they signed out with.

  3. Q: If the user is signed in to the channel using RF SSO on multiple devices, then signs out on one device and signs in with a different channel partner user account, are the other devices impacted?

    A: No. The user would remain signed in on the other devices with the previous user account.

  4. Q: Can more than one Roku account be linked to a channel's user account?

    A: This is up to you. We will return the PUCID (Partner Unique Customer Identifier), but this is your decision if you want to associate more than one PUCID with a customer account.

Glossary of Terms

Term

Description

Account Linking

An association between a Roku Customer account and a Partner User account. Account Linking enables the RF SSO service to request Partner Artifacts for any of the Roku Players linked to a given Roku Customer account.

API

RF SSO endpoint that services Roku Player interactions.

artifact

A Partner proprietary authorization credential.  

client_id

An identifier that identifies Roku or Partner as the caller to a service.

device_info

See: roku_pucid

Device Linking

An association of a specific Roku Streaming Player to a Partner User account.

Device Linking may also refer to the association of a specific Roku Player to a Roku Customer account.

Partner

Used in sequence diagrams to refer to the Channel Partner Services such as Account Login Service, Federation Service and token endpoints. In the figures these services are depicted as one entity only to simplify the diagram. It is likely that a Channel Partner will have independent instances of these services (i.e., an account service, federation service and token endpoint.)

Player

Roku Device, such as a Roku Streaming Stick, Roku 3, or Roku TV.

Roku SSO

Used in sequence diagram to refer to the web service Roku implements to support identity federation. This service specifically manages the binding of a Roku Customer Account with either a VoD Service Account or a VoD Login Account Roku TV.

roku_pucid

A Roku-defined Partner Unique Customer IDentifier. This identifier is represented as a UUID.

User jjjjjdjjjjjjtttttttttttttttttttttttttttttttt

The entity with a Roku Login Account and optionally a pre-existing Partner Channel Login Account.

Attachments:

icons8-Inspection-40.png (image/png)
icons8-Error-40.png (image/png)
arrowup.png (image/png)
RokuConnect.png (image/png)