Authentication

To ensure that only valid devices and users connect to and use the OpenTV Platform, it provides authentication services and will authorise incoming requests.

Some deployments might have additional layers of security at a lower network level, for example, geo-ip filtering, firewall IP whitelist, or DHCP IP whitelist.

Client authentication is primarily controlled by the use of an authentication token. The HTTP Router, HDM and SDP are responsible for client authentication functionality in the platform.

To access most services in the OpenTV Platform an authentication token is required. A token can be obtained by calling the signon API on HDM. The specific API to use depends on the device type.

Set Top Box signon

NOCS devices only: A Set Top Box for signon purposes is a device that has NOCS (NAGRA On Chip Security). Set Top Boxes that don't have NOCS (such as an Android STB) should be treated as open devices.

Set Top Box devices are typically pre-provisioned, in that the device and security device information are already present in the OpenTV Platform at the time of signon. Where this is not the case, the HDM is responsible for dynamically provisioning the device during the first signon. In any case, the signon API is the same.

Send a GET request to:

https://<server>:<port>/api/authentication/v2/stbsignontokens

Use the following request header if required:

Use the following request parameters:

The request response is described below.

Open device signon

Any device that does not include NOCS is considered an open device.

Open devices are typically not pre-provisioned, as the service provider is not typically involved in the management of the customers open device. The typical scenario is that the customer already owns an open device, such as a tablet or smart phone, has downloaded the service provider's application, and now wants to use it. Therefore, at first signon, the system will have information only about the user and their account, not the device itself.

Depending on the deployment solution, the OpenTV Player can be run in direct or non-direct mode. In direct mode, the player is responsible for communication directly with NAGRA PRM. This includes device initialisation, which provisions the device in the PRM server and OpenTV Platform. In non-direct mode, communication to NAGRA PRM occurs via the OpenTV Platform, and the UI application is responsible for instigating these requests.

Direct mode

In direct mode, a call to the OpenTV Player SDK will initialise the device directly to NAGRA PRM. This should occur before the UI application loads. Upon successful initialisation the device will be provisioned in the PRM server and OpenTV Platform, so a deviceId will be available from the Secure PlayerSDK.

Send a GET request to:

https://<server>:<port>/api/authentication/v2/nmpsignontokens

Use the following request header if required:

Use the following request parameters:

The request response is described below.

Non-direct mode

Signon by username and password

In non-direct mode, the client must first sign on by username and password only, to get access to do anything else, including initialisation. The smartcardId of the Home Gateway Set Top Box should be provided if one exists and the open device application is acting as a companion application to it.

Send a GET request to:

https://<server>:<port>/api/authentication/v2/nmpsignontokens

Use the following request header if required:

Use the following request parameters:

The request response is described below.

Initialise device

The client device must then be provisioned in the OpenTV Platform and PRM server.

Send a GET or POST request to:

https://server:port/qsp/gateway/http/js/nmpextendedservice/initializeDevice

The size of GET requests may be limited to as little as 2 KB. If the request is larger than 2 KB, use POST instead.

Use the following request parameters:

This will return opaque data in the JSON response, which must be passed down to the OpenTV Player. The OpenTV Player will decode the data and provide access to the deviceId, which can then be used to identify the device in subsequent signons.

Success response

A success response takes the following form:

{
   "resultCode": "0", 
   "result": 
   {
      "downloadURL": null, 
      "status": "OK", 
      "masterVersion": null, 
      "response": "<base64String>"
   }, 
   "token": "<base64String>", 
   "requestId": "<UUID>"
}

Error response

An error response takes the following form:

{
   "resultCode": "0", 
   "result": 
   {
      "downloadURL": null, 
      "status": "INTERNAL_ERROR", 
      "masterVersion": null
   },
   "token": "<base64Value>", 
   "requestId": "<UUID>"
}

Signon by username, password, and device ID

After initialisation, signon must always be done using username, password and device ID. The device ID is required to update the context of the token so that the OpenTV Platform understands what device is making each request, as well as the user. Some APIs will not function if this signon is not performed rather than signon only by username and password.

If the open device is acting as a companion device to a home gateway, in some cases the smartcard ID of the home gateway should be provided in the signon request to identify the gateway device that the open device is paired with. This information is used to authorise playback between the gateway and open device.

Send a GET request to:

https://<server>:<port>/api/authentication/v2/nmpsignontokens

Use the following request header if required:

Use the following request parameters:

The request response is described below.

Signon response

The response to HDM stbsignontokens and nmpsignontokens requests have the same form.

Success response

A successful response is an HTTP 200 with these headers:

Success response body example

This contains the authentication token and is a JSON object of the format:

{
   "token":    {
      "token": "AAABPw/ZSn3g69MSRQHUax04lct21zc25cZyy/h03fJDOcpv3JOKqeUMUaHJLMrTW1OPcj5pYAsF3CmmQYT!0cgARfAHPiPJ",
      "result": null,
      "resultCode": "0",
      "requestId": "283882958"
   },
   "expiry": 1370364066047
}

Error responses

Authorisation

Once a request token is obtained, it should be sent with all subsequent requests to the OpenTV Platform. Each module within the OpenTV Platform will authorise the request being made by validating that the caller is allowed to make the request, and that the parameters supplied are expected based on the caller. The business rules vary between differing APIs; some examples are:

• A device should be able to return only data applicable to it or other devices within the same account.
• A device should be able to purchase items only for itself or other devices within the same account.
• A device should be able to request content licenses only for itself or for playback between itself or another device within the same account.

Authorisation will be transparent between the client and the target API unless the authorisation fails, in which case an error should be returned. The error will depend on the API used.

See also

The full HDM API documentation.

As an alternative to the HDM signon API, the equivalent operations can be performed via SDP APIs. For details refer to the full SDP API documentation.