oidc-authentication-for-beacon.html

<h1>{{ page.title }}</h1>
<article class="bcls-article">
  <summary>{{ page.description }}</summary>


  <section class="bcls-section">
    <h2 id="Introduction">Introduction</h2>
    <p>This document details the configuration of how you can use your OIDC 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:</p>
    <table class="bcls-table">
      <thead class="bcls-table__head">
        <tr>
          <th>ATM/Bank Card</th>
          <th>Beacon App</th>
        </tr>
      </thead>
      <tbody class="bcls-table__body">
        <tr>
          <td>ATM</td>
          <td>Beacon App</td>
        </tr>
        <tr>
          <td>Functionality/connectivity ATM to authorize transaction</td>
          <td>OAuth 2.0</td>
        </tr>
        <tr>
          <td>Bank card</td>
          <td>JSON Web Token (JWT) from OIDC </td>
        </tr>
        <tr>
          <td>Process to issue bank card</td>
          <td>OIDC</td>
        </tr>
      </tbody>
    </table>
    <p>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.</p>
  </section>


  <section class="bcls-section">
    <h2 id="section-name">Setting up and testing authentication</h2>
    <p>Perform the following tasks to configure and test your OIDC identity provider with Beacon:</p>
    <ol class="bcls-tasklist">
      <li>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.</li>
      <li>Implement and provide API endpoints to the OTT Delivery Team for the following responses:
        <ul>
          <li>Access Token (JWT)</li>
          <li>ID Token (JWT)</li>
          <li>Refresh Token</li>
          <li>User Info</li>
          <li>Authorize</li>
          <li>Pairing codes - required only if Smart TV, Android TV, Fire TV or Apple TV are in scope; see notes for Roku</li>
          <li>JWKS</li>
          <li>Logout</li>
          <li>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</li>
        </ul>
      </li>
      <li>Configure redirect URLs for login and logout as allowed redirect URLs, if required by by your identity provider.</li>
      <li>Create a client ID for all apps in scope and provides them to the OTT Delivery Team.</li>
      <li>Creates test users in your identity provider and supply test credentials to the OTT Delivery Team.</li>
    </ol>
    <p>For your information, Brightcove entities will then:</p>
    <ol class="bcls-tasklist">
      <li>OTT Delivery Team creates a ticket with data from steps 2 and 5 above for Beacon CMS in OTT board.</li>
      <li>OTT Delivery Team creates a ticket with data from steps 4 and 5 above for Beacon Beacon apps in OTT board.</li>
      <li>Beacon CMS team configures Beacon CMS with URLs from step 6 above.</li>
      <li>Beacon apps teams configure apps with client ID from step 5 above and dev-tests with provided test users.</li>
      <li>OTT Delivery Team QA teams validate end-to-end authentication before qualifying the builds for UAT release.</li>
    </ol>
  </section>


  <section class="bcls-section">
    <h2 id="Tokens">Tokens and user response</h2>
    <p>Three tokens are involved in having your OIDC based identity provider authenticate your viewers, those being:</p>
    <ul>
      <li>access_token</li>
      <li>id_token</li>
      <li>refresh_token</li>
    </ul>

    <h3>Access token</h3>
    <p>The access token must have the following claims for authentication support alone:</p>
    <ul>
      <li>sub</li>
      <li>iss</li>
      <li>exp</li>
      <li>iat</li>
      <li>aud (only if requested)</li>
    </ul>
    <p>Here is an example access token response that your OIDC provider token endpoint may provide:</p>
    <figure class="bcls-figure">
      <img class="bcls-image" src="/assets/images/s-general-img/oidc-authentication/access-token-raw.png" alt="access token raw">
    </figure>
    <p>Here is the access token decoded:</p>
    <figure class="bcls-figure">
      <img class="bcls-image" src="/assets/images/s-general-img/oidc-authentication/access-token-decoded.png" alt="access token decoded">
    </figure>

    <h3>ID Token</h3>
    <p>The id token must have the following claims for authentication support alone:</p>
    <ul>
      <li>sub</li>
      <li>iss</li>
      <li>exp</li>
      <li>iat</li>
      <li>aud</li>
      <li>nonce</li>
    </ul>
    <p>Here is an example ID token response that your OIDC provider token endpoint may provide:</p>
    <figure class="bcls-figure">
      <img class="bcls-image" src="/assets/images/s-general-img/oidc-authentication/id-token-raw.png" alt="id token raw">
    </figure>
    <p>Here is the ID token decoded:</p>
    <figure class="bcls-figure">
      <img class="bcls-image" src="/assets/images/s-general-img/oidc-authentication/id-token-decoded.png" alt="id token decoded">
    </figure>

    <h3>Refresh token</h3>
    <p>The refresh token is just an identifier. It does not contain any data. The data is the token itself.</p>

    <h3>User info response</h3>
    <p>The user info response is a JSON object and must have the following fields for authentication support alone:</p>
    <ul>
      <li>sub</li>
      <li>name/nickname/full_name/displayName (one or more)</li>
      <li>email</li>
    </ul>
    <p>Here is an example user info response:</p>
    <figure class="bcls-figure">
      <img class="bcls-image" src="/assets/images/s-general-img/oidc-authentication/user-info-response.png" alt="user info response">
    </figure>
  </section>

  <section class="bcls-section">
    <h2 id="Known issues">Known issues</h2>
    <ul>
      <li>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 <a href="https://developer.roku.com/docs/developer-program/authentication/on-device-authentication.md">On-device authentication</a> document.</li>
    </ul>
  </section>


</article>