OIDC Authentication Configuration and Testing for Brightcove Beacon

In this topic, you will learn how to configure your OIDC based identity provider to authenticate Beacon users.

Introduction

This document details the configuration of how you can use your OIDC (OpenID Connect) based identity provider to authenticate your viewers in Brightcove Beacon apps. Before you jump into details, a big picture of the process is helpful. Think of your Beacon app as a bank ATM machine. What the user needs is a bank card to access the money in the ATM. Likewise, your viewer needs an ID to access the videos in your Beacon app. Here's a table relating entities in the analogy:

ATM/Bank Card Beacon App
ATM Beacon App
Functionality/connectivity ATM to authorize transaction OAuth 2.0
Bank card JSON Web Token (JWT) from OIDC
Process to issue bank card OIDC

Just as the bank card must have the ATM and underlying functionality of that device, so OIDC must have OAuth to function. It is often stated that OIDC "sits on top of" OAuth.

Setting up and testing authentication

Perform the following tasks to configure and test your OIDC identity provider with Beacon:

  1. Obtain from Brightcove the callback URLs to be added to the OIDC provider as allowed redirect URIs. The identity provider uses these URIs to redirect viewers with their authorization code Sign-in URL to QA and Test environments. Both environments specify the redirect URIs to redirect the User with their authorization code.
  2. Implement and provide API endpoints to the OTT Delivery Team for the following responses:
    • Access Token (JWT)
    • ID Token (JWT)
    • Refresh Token
    • User Info
    • Authorize
    • Pairing codes - required only if Smart TV, Android TV, Fire TV or Apple TV are in scope; see notes for Roku
    • JWKS
    • Logout
    • OpenID Connect Discovery (/.well-known/openid-configuration) - If this is configured properly and provided, the OTT Delivery Team can discover the endpoints and provide Beacon engineering ticket as noted in step f. Below
  3. Configure redirect URLs for login and logout as allowed redirect URLs, if required by by your identity provider.
  4. Create a client ID for all apps in scope and provides them to the OTT Delivery Team.
  5. Creates test users in your identity provider and supply test credentials to the OTT Delivery Team.

For your information, Brightcove entities will then:

  1. OTT Delivery Team creates a ticket with data from steps 2 and 5 above for Beacon CMS in OTT board.
  2. OTT Delivery Team creates a ticket with data from steps 4 and 5 above for Beacon Beacon apps in OTT board.
  3. Beacon CMS team configures Beacon CMS with URLs from step 6 above.
  4. Beacon apps teams configure apps with client ID from step 5 above and dev-tests with provided test users.
  5. OTT Delivery Team QA teams validate end-to-end authentication before qualifying the builds for UAT release.

Tokens and user response

Three tokens are involved in having your OIDC based identity provider authenticate your viewers, those being:

  • access_token
  • id_token
  • refresh_token

Access token

The access token must have the following claims for authentication support alone:

  • sub
  • iss
  • exp
  • iat
  • aud (only if requested)

Here is an example access token response that your OIDC provider token endpoint may provide:

access token raw

Here is the access token decoded:

access token decoded

ID Token

The id token must have the following claims for authentication support alone:

  • sub
  • iss
  • exp
  • iat
  • aud
  • nonce

Here is an example ID token response that your OIDC provider token endpoint may provide:

id token raw

Here is the ID token decoded:

id token decoded

Refresh token

The refresh token is just an identifier. It does not contain any data. The data is the token itself.

User info response

The user info response is a JSON object and must have the following fields for authentication support alone:

  • sub
  • name/nickname/full_name/displayName (one or more)
  • email

Here is an example user info response:

user info response

Known issues

  • For Roku implementations, a custom engagement with Brightcove Global Services is required. This is due to Roku's certification requirements. Failure to do this will result in Roku rejecting the channel from being published in the Roku store. For more information see Roku's On-device authentication document.