Integrating with the Beacon Web Store

This topic covers Beacon Web Store integration via OIDC (Open ID Connect).

Authentication through OIDC and entitlements

Authentication

Beacon leverages the following OAuth 2.0 flows for Authentication:

Authorization Code with PKCE: iOS, Android and Web

Authorization with PKCE
Device Flow (Oauth 2.0 Extension): Connected and Smart TVs

Device Flow

There are 3 tokens that are expected to be made available to Beacon:

Access token: validates that a user was able to authenticate and should be granted access to Beacon ( JWT format and need to include iss and sub )
Refresh token: allows the user to remain logged in after the access token expires by providing a mechanism to automatically obtain a new access token on behalf of the user (as long as user is allowed access) - this is especially important on TVs
Identity token: standardizes the way we obtain information about users

The following grant types should be supported:

authorization_code
refresh_token
urn:ietf:params:oauth:grant-type:device_code

Following Authentication provider endpoints will need to be configured in Beacon (customer needs to provide us these so that we can configure - if OpenID Connect Discovery is available we can discover these):

Access Token (JWT)
Refresh Token (JWT)
User Info
Revoke Token (JWT)
Authorize
Pairing codes
JWKS
Logout
OpenID Connect Discovery (/.well-known/openid-configuration) - Used for configuration of the system

Examples of items configured in Beacon CMS

Entitlements

In terms of telling Beacon about entitlements for users, Beacon provides the following API: https://beacon.brightcove.com/{instance}/webhook/beacon (API key provided by Brightcove)

The payload will be JSON:

[
  {
    "package_name": "string",			// Commerce package for SVOD or SKU for TVOD purchases - required
    "external_user_id": "string",			// User identifier (username or email depending on configuration of users)- required
    "transaction_id": "string",			// Unique transaction id for purchase - required for subscriptions (this will be used in renewal)
    "start_date": "string",				// Start date for entitlements 
    "end_date": "string",				// End date for entitlements (applicable if a rent or a subscription)
    "trial_end_date": "string",			// End date for a trial if applicable
    "effective_cancellation_date": "string",		// Date by when cancellation is effective (for example, end of current subscription period)
    "notification_type": "new",			// One of: new, renew, cancellation, buy or rent - required
    “payment_gateway”: “beaconstore”      // One of: “beaconstore”
  }
]

When using an external authentication system, the external_user_id corresponds to the subject value in the Access token