Table of Contents
- High Level Process Overview
- Channel Activation Using RF SSO
- Channel Activation
- FAQ (Frequently Asked Questions)
- Glossary of Terms
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
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.
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.
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).
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:
The roku_pucid should be represented as a UUID derived from well-defined Roku Namespace UUID. The URI-Template follows:
Associative Array Contents
An informative example of the contents in the associative array “cred” from a successful response follows:
An error response returns and empty json object and additional status information.
An informative example of a failed response follows:
FAQ (Frequently Asked Questions)
- 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.
- 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.
- 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.
- 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
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.
RF SSO endpoint that services Roku Player interactions.
A Partner proprietary authorization credential.
An identifier that identifies Roku or Partner as the caller to a service.
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.
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.)
Roku Device, such as a Roku Streaming Stick, Roku 3, or Roku TV.
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.
A Roku-defined Partner Unique Customer IDentifier. This identifier is represented as a UUID.
The entity with a Roku Login Account and optionally a pre-existing Partner Channel Login Account.