Supporting SSO for Roku devices for Vimeo OTT

If you are an OTT Seller leveraging Single Sign-On that wishes to support Roku devices with their Identity Provider, you must create and support additional authorization endpoints. 

Roku applications undergo a certification process before they are available in The Channel Store. One of the requirements of this process is that Customers must be able to sign in and create accounts without ever being redirected off of the device (such as to pair their device with their account on the web).

To satisfy these Roku requirements, you must build an integration endpoint for OTT to authenticate with. This will allow authentication and account creation directly on the Identity Provider from Roku.

In this article

• Implementation
• Configuration
• Endpoint URLs
• Credentials
• Authentication
• Token Endpoint
• Sign Up Endpoint

Implementation

OTT requires two server-to-server calls in order to accomplish this. These endpoints are designed in accordance with OpenID Connect, conforming where possible (authentication) and imitating where not possible (sign-up).

Configuration

You should be in close contact with their Account Manager to provide these values and update the site accordingly. 

Endpoint URLs

You will need to implement two endpoints. The URLs for these endpoints will need to be added to the OTT site configuration. Contact your Account Manager with these values.

• Token Endpoint URL
• Sign Up Endpoint URL

Credentials

You will need to provide credentials for calling these endpoints. These credentials will be used in accordance with the OAuth 2.0 specification. These credentials will need to be added to their OTT site configuration. Contact your Account Manager with these values.

• OAuth Client ID
• OAuth Client Secret

Authentication

All requests to your Identity Provider endpoints will be authenticated using the configured OAuth Client ID and Client Secret via HTTP Basic authentication. The Client ID and Client Secret will be joined with a colon, base-64 encoded, and passed in the Authorization header.

For reference, see the following pseudo-code

 encoded_client_credentials =
  Base64.encode64("#{client_id}:#{client_secret}")

headers['Authorization'] = "Basic #{encoded_client_credentials}" 

Token Endpoint

The Token Endpoint is used to authenticate customers from the Roku applications.

This endpoint uses the following configuration:

• Token Endpoint URL
• OAuth Client ID
• OAuth Client Secret

Request

This endpoint must support incoming requests that conform to the OAuth 2.0 Resource Owner Password Credentials grant type specification. Additionally, this endpoint must support the OpenID and email OpenID Connect scopes (and may support the profile scope).

POST ${token_url_path}
Host: ${token_url_host}
Authorization: Basic ${encoded_client_credentials}
Content-Type: application/x-www-form-urlencoded

grant_type=password
&username=user@example.com
&password=1234luggage
&scope=openid+email+profile 

Response

In accordance with the OpenID Connect specification, the response must include an id_token.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "{token}",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "{refresh_token}",
  "scope": "openid email profile",
  "id_token": "..."
} 

The id_token must be a JWT that includes the user's unique, immutable identifier (as sub) as well as their email address (as email). The id_token may also include their full name (as name).

{
"email": "user@example.com",
"name": "Jane Doe",
"sub": "123e4567-e89b-12d3-a456-426614174000"
} 

Status Codes

• 2XX — success
• 4XX — all other client errors; where possible, responses should conform to the OAuth 2.0 error response specification

Sign Up Endpoint

The Sign Up Endpoint is used to register new customers from the Roku applications.

This endpoint uses the following configuration

• Sign Up Endpoint URL
• OAuth Client ID
• OAuth Client Secret

Request

This endpoint accepts requests that look similar to those used for the Resource Owner Password Credentials grant type, e.g., receiving the email address as username.

POST ${signup_url_path}
Host: ${signup_url_host}
Authorization: Basic ${encoded_client_credentials}
Content-Type: application/x-www-form-urlencoded

username=user@example.com
&password=1234luggage 

Response

Status Codes

• 2XX — success; the customer may now authenticate with the provided username and password
• 4XX — all other client errors; where possible, responses should conform to the OAuth 2.0 error response specification