Host Platform Authentication

Introduction

In order to use Host platform authentication via Hyperscale, Hyperscale assumes that the Host Platform Authentication Services will support the following standards:

• OpenID Connect Discovery 1.0
• RFC7519 - JSON Web Token (JWT)
• RFC7523 - JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grant

Hyperscale Configuration

To integrate with the Host Platform Authentication Services, the Hyperscale tenant needs to be configured with the following "hostPlatformAuth" properties:

HS Device Provisioning

The mapping of a Hyperscale Device identifier (deviceId) to a subscriber's account needs to be configured in the Host Platform Authentication Services before the device is powered up. This will allow the Host Platform Authentication Services to verify the client assertion and generate the specific access token for the subscriber.

The HS Device Identifier will be carried by the "sub" (subject) claim as per RFC7519 - JSON Web Token (JWT)

HS Device Initialization

On boot up, the HS Device will perform the authentication flow with the Hyperscale Platform.

Once the HS Device is authenticated, the Hyperscale Platform will create an assertion and initiate the authentication flow with the Host Platform Authentication Services by requesting an access token.

The format of the assertion is as per JSON Web Token (JWT) and it includes the following fields/claims:

• "iss" (Issuer): see Hyperscale configuration
• "aud" (Audience): see Hyperscale configuration
• "iat" (Issued At): generated on each request per JWT spec
• "jti" (JWT ID): generated on each request as per JWT spec
• "exp" (Expiration): generated on each request per JWT spec
• "sub" (Subject): string that carries a prefix and the deviceId. The prefix is configurable as described in "Hyperscale configuration".

The request might trigger the OIDC Connect Discovery Protocol as specified in OpenID Connect Discovery 1.0

Once the assertion, including the signature, has been verified, the Host Platform Authentication Services is expected to return an access token for the deviceId provided. This access token will be cached by the Hyperscale Platform.

The following diagram summarises the sequence of calls between the Hyperscale Platform and the Host Platform Authentication Services.

Web Application Initialisation

On boot up, the Customer's Web Application is expected to retrieve an access token from Hyperscale using the Hyperscale Client Library API.

At this point, as indicated in the previous diagram, Hyperscale already has the access_token in the cache and it doesn't need to call the Host Platform Authentication Services.

Once the Web Application has the access_token, it can start calling the Host Platform APIs.

The following diagram summarises the sequence of calls between the Web Application and Hyperscale to retrieve the access token before calling the Host Application APIs.

Access Token Expired

The Web Application will carry on using the access token retrieved from Hyperscale to call Host Application APIs and, at some point, the token will expire and the Host Platform will return "Unauthorised".

The Web Application will need to request a refresh of the token via the Hyperscale Client Library API and, once it has been refreshed, it will need to retrieve the net token before calling the Host Platform APIs again.

The following diagram summarises the sequence of calls required to renew the token via the Hyperscale Client Library API.

Example

Let's assume we have a HS Device with a deviceId identifier and a Hyperscale tenant with the following "hostPlatformAuth" configuration parameters:

base url: <auth_base_url>
subject: <urn:synamedia:oauth:identifier:hyperscale:{deviceId}>
audience: <auth_base_url>
grant type: urn:ietf:params:oauth:grant-type:jwt-bearer
issuer: <issuer>

The HS Device boots up and authenticates/registers with the Hyperscale platform. The Hyperscale platform then generates the following client_assertion:

{
  "iss": “<issuer>”,
  "aud": “<auth_base_url>”,
  "iat": 1657016405,
  "jti": "4d79f2c7-11c8-4ab6-97d9-24bc7cc28f02",
  "sub": "urn:synamedia:oauth:identifier:hyperscale:deviceId",
  "exp": 1657102805
}

Hyperscale encrypts the client_assertion and requests the access_token:

curl --location --request POST <auth_base_url> \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer' \
--data-urlencode 'assertion=<encrypted_client_assertion>'

The Host Platform Authentication Services detect that it needs to do OIGC Discovery:

curl <issuer>/.well-known/openid-configuration
Response (discovery document):
{
  "issuer": "<issuer>",
  "jwks_uri": "<jwks_uri>",
  "id_token_signing_alg_values_supported": [
    "RS256",
    "RS384"
  ]
}

curl <jwks_uri>
Response (signing keys):
{
  "keys": [
    {
      "kty": "RSA",
      "e": "AQAB",
      "use": "sig",
      "kid": "e-R0BZ6QOUvXyHEKhUbVE38egrjuXgzsQprzCmWhtw0",
      "alg": "RS256",
      "n": <public_key>
    }
  ]
}

Once the Host Platform Authentication Services have the latest public_key, they decrypt and validate the client_assertion and return the access_token:

Response (to Hyperscale request for access_token):
{
    "scope": "browse playback",
    "expires_in": 604800,
    "token_type": "bearer",
    "guest_mode": false,
    "access_token": “<access_token>”
}

Hyperscale stores the access_token. Once the Web Application boots up, it can retrieve the token via the Hyperscale Client Library and start calling the Host Platform APIs.