Accessing operator APIs using Keycloak

Overview

OpenTV Suite APIs are grouped into three categories:

Admin APIs – used to monitor the health of the deployment. (In a NAGRA-managed deployment, only NAGRA needs to use these APIs – operator personnel do not need to use them.)
Operator APIs – used by the operator to set up, configure, and control the platform. A subset of these APIs can be used by external systems that integrate with OpenTV Suite (such as CRM systems).
Client APIs – used by client applications that allow end users to consume content.

OpenTV Suite uses Keycloak to prevent unauthorised access to its admin and operator APIs. Before you can access any of these APIs, you must authenticate with Keycloak. If you do not, your requests will fail.

Client applications do not use Keycloak.

Prerequisites

The following must already be configured in Keycloak:

User roles called operatorRole and adminRole. (operatorRole is for the operator APIs and adminRole is for the admin APIs. These are set up by NAGRA as part of the deployment.)
Users to which the appropriate roles have been assigned:
- One or more users with the operatorRole role
- One or more users with the adminRole role
(In a NAGRA-managed system, only operatorRole is required.)
At least one client application

See Creating Keycloak clients and accounts.

Getting Keycloak access and refresh tokens

Before you can call any of the operator APIs, you must call Keycloak to get an access token and a refresh token. The request is explained in detail below.

Request

To request Keycloak access and refresh tokens, send a POST request to:

^{https://<host>:<port>/keycloak/auth/realms/nagra/protocol/openid-connect/token}

Note that the host here is the same as for other operator requests.

Mandatory fields

Mandatory headers:

Content-Type – must be application/x-www-form-urlencoded.

The request body must contain the following, as x-www-form-urlencoded key/value pairs:

grant_type – must be "password".
username – the name of the Keycloak user
password – the password for the Keycloak user
client_id – must be the client ID as configured in Keycloak

The username, password, and client_id are the ones you specified in Creating Keycloak clients and accounts.

Example

This is an example of the request body (in this case, in Postman's x-www-form-urlencoded Bulk Edit view):

CODE

grant_type:password
username:crm_client_user
password:1234
client_id:crm_client

Response

The response body includes the access and refresh tokens. Their validity periods are as follows:

Access token: five minutes
Refresh token: 30 minutes

These are the default validity times. They can be changed as follows if required.

Open https://<base_url>/keycloak/auth/admin/master/console in a web browser, where <base_url> is the base URL of the OpenTV Suite deployment.
Log in using the credentials that NAGRA provided to you as part of the deployment.
Go to Configure > Realm Settings > Tokens.
Change the values of SSO Session Idle and Access Token Lifespan as required.
Click Save.

Use the access token for subsequent operator API calls by adding it as a Bearer token to an Authorization header in each request.

Example

CODE

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ3aGVOd25SZWMyVF81RFVLcFlCNll5VUgtOEpIb0IxUHVvb1J4VHV6QzUwIn0.eyJqdGkiOiI4NGEyYmE1OS02YmViLTQ4OWQtOGNkNi0zZWFmMzRkNDZiNGQiLCJleHAiOjE1Nzc5NzYyMjMsIm5iZiI6MCwiaWF0IjoxNTc3OTc1OTIzLCJpc3MiOiJodHRwczovL29wZXJhdG9yLnNhbGVzLm90dnNlLmNvbS9rZXljbG9hay9hdXRoL3JlYWxtcy9uYWdyYSIsInN1YiI6IjE3NGJjMWZiLTE4MmMtNDY5MS1iNzhhLTJiZGNjZjBjN2M2NyIsInR5cCI6IkJlYXJlciIsImF6cCI6Im1hcnRpbl9jbGllbnQiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiI0YTZkZTc4YS1mNTYyLTRiNmEtYTk3Yi03YTdjYTE1NGZhY2YiLCJhY3IiOiIxIiwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9wZXJhdG9yUm9sZSJdfSwic2NvcGUiOiJwcm9maWxlIGVtYWlsIiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJtYXJ0aW4ifQ.s5luO7xZi9Qd8YJ3AyB9zjySzCX3-UWr_GyJgc-nrDCOedKoCqDSjtCgcdiDpEUvsWVxsGMQEWn5po9OHzbKE3hUyXQFLcJrvtY3yP3pqNc8nbVw8ijfRItNvhQLpStGtiRAY-xYWLrurCUSBZrmvvKztzh4YGr-CpbwRNdi1ggcrg2VBxEoj1zlBo0z4fxKCYdGYOeEAG0SAQlXA0_sVZM-104LZGC1n7UopkEOhzXSPIJLATYcFgLoWaLeJ1U65hYv2_k-4ZKy7svrZd4N8kh_L5_ellr_VqK_fZ05zBYUMHhPt1iEHUozSNfJ45CgkmVCMQKIWUzoqgqbnA7xgQ",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI3YjM5ZWM0Ny1hNDgyLTRhMmUtODMwMS0xOTQxNWZmNmQ3MDgifQ.eyJqdGkiOiJhOTEzYTU5OS1hOWNhLTQ3ZTctODRiMC1jZTY1ZDdjZjViYmUiLCJleHAiOjE1Nzc5Nzc3MjMsIm5iZiI6MCwiaWF0IjoxNTc3OTc1OTIzLCJpc3MiOiJodHRwczovL29wZXJhdG9yLnNhbGVzLm90dnNlLmNvbS9rZXljbG9hay9hdXRoL3JlYWxtcy9uYWdyYSIsImF1ZCI6Imh0dHBzOi8vb3BlcmF0b3Iuc2FsZXMub3R2c2UuY29tL2tleWNsb2FrL2F1dGgvcmVhbG1zL25hZ3JhIiwic3ViIjoiMTc0YmMxZmItMTgyYy00NjkxLWI3OGEtMmJkY2NmMGM3YzY3IiwidHlwIjoiUmVmcmVzaCIsImF6cCI6Im1hcnRpbl9jbGllbnQiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiI0YTZkZTc4YS1mNTYyLTRiNmEtYTk3Yi03YTdjYTE1NGZhY2YiLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsib3BlcmF0b3JSb2xlIl19LCJzY29wZSI6InByb2ZpbGUgZW1haWwifQ.l6b4dJSB7hdnoa9NpJyyczt0ZXFavWT6pO0ERtYW1uE",
    "token_type": "bearer",
    "not-before-policy": 0,
    "session_state": "4a6de78a-f562-4b6a-a97b-7a7ca154facf",
    "scope": "profile email"
}

Using the refresh token

Once the access token has expired, you can exchange the refresh token for new access and refresh tokens by calling the above API again, but this time passing the refresh token.

Request

To request a new access token using the refresh token, send a POST request to:

^{https://<host>:<port>/keycloak/auth/realms/nagra/protocol/openid-connect/token}

Mandatory fields

Mandatory headers:

Content-Type – must be application/x-www-form-urlencoded.

The request body must contain the following, as x-www-form-urlencoded key/value pairs:

grant_type – must be "refresh_token"
client_id – must be the client ID as configured in Keycloak.
refresh_token – the refresh token itself

Example

This is an example of the request body (in this case, in Postman's x-www-form-urlencoded Bulk Edit view):

CODE

grant_type:refresh_token
client_id:crm_client
refresh_token:eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI3YjM5ZWM0Ny1hNDgyLTRhMmUtODMwMS0xOTQxNWZmNmQ3MDgifQ.eyJqdGkiOiJhOTEzYTU5OS1hOWNhLTQ3ZTctODRiMC1jZTY1ZDdjZjViYmUiLCJleHAiOjE1Nzc5Nzc3MjMsIm5iZiI6MCwiaWF0IjoxNTc3OTc1OTIzLCJpc3MiOiJodHRwczovL29wZXJhdG9yLnNhbGVzLm90dnNlLmNvbS9rZXljbG9hay9hdXRoL3JlYWxtcy9uYWdyYSIsImF1ZCI6Imh0dHBzOi8vb3BlcmF0b3Iuc2FsZXMub3R2c2UuY29tL2tleWNsb2FrL2F1dGgvcmVhbG1zL25hZ3JhIiwic3ViIjoiMTc0YmMxZmItMTgyYy00NjkxLWI3OGEtMmJkY2NmMGM3YzY3IiwidHlwIjoiUmVmcmVzaCIsImF6cCI6Im1hcnRpbl9jbGllbnQiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiI0YTZkZTc4YS1mNTYyLTRiNmEtYTk3Yi03YTdjYTE1NGZhY2YiLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsib3BlcmF0b3JSb2xlIl19LCJzY29wZSI6InByb2ZpbGUgZW1haWwifQ.l6b4dJSB7hdnoa9NpJyyczt0ZXFavWT6pO0ERtYW1uE

Response

The response will contain new access and refresh tokens.

Example

CODE

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ3aGVOd25SZWMyVF81RFVLcFlCNll5VUgtOEpIb0IxUHVvb1J4VHV6QzUwIn0.eyJqdGkiOiIxMzk4MjIwNC01NmUzLTQ2ZmQtYWE4Yy1lNTg0ZDQ4NTg4NTMiLCJleHAiOjE1Nzc5NzcyMjIsIm5iZiI6MCwiaWF0IjoxNTc3OTc2OTIyLCJpc3MiOiJodHRwczovL29wZXJhdG9yLnNhbGVzLm90dnNlLmNvbS9rZXljbG9hay9hdXRoL3JlYWxtcy9uYWdyYSIsInN1YiI6IjE3NGJjMWZiLTE4MmMtNDY5MS1iNzhhLTJiZGNjZjBjN2M2NyIsInR5cCI6IkJlYXJlciIsImF6cCI6Im1hcnRpbl9jbGllbnQiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiJmMjM0ODgzNS0zNmIyLTRiNmItYWVmZi0wOGQ2OWRjNmRjMDEiLCJhY3IiOiIxIiwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9wZXJhdG9yUm9sZSJdfSwic2NvcGUiOiJwcm9maWxlIGVtYWlsIiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJtYXJ0aW4ifQ.ZwWfgaf1V4f3bY72zHf4QUT3PvoLJ0ZFkS6N1GanOKaYLhakNfSEXlNO4gY2oVWFsCFliDXBu2UMIr64bHnAhCBsH3AQDbsCmp-7GjS6sTRzpzFPyHQEjpm9ZehOvL5_s3gTtsRpdW9gm6XCHOpTos0kiGArOkiy-GLhQbFHi2hdhoe7FYyIn3oXygYO1uic1LtBwaJihAjW_iSsNIN8CLWpBKx9_zsMqyU5jWATOCC8MgpalYetTKlEA2vlfKxhB2ObBM8n-gfjbtHjfVteJK5yEsM-XH1oxnkDoZYltLz5cx92JxP1S-8oCWm9cAC5A3qg45I9fPOtspTMGRpSlQ",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI3YjM5ZWM0Ny1hNDgyLTRhMmUtODMwMS0xOTQxNWZmNmQ3MDgifQ.eyJqdGkiOiI0YzU3MDEwMC1hNmYyLTQzOWQtOTQwNS00Y2FmNzFmMTYwMWMiLCJleHAiOjE1Nzc5Nzg3MjIsIm5iZiI6MCwiaWF0IjoxNTc3OTc2OTIyLCJpc3MiOiJodHRwczovL29wZXJhdG9yLnNhbGVzLm90dnNlLmNvbS9rZXljbG9hay9hdXRoL3JlYWxtcy9uYWdyYSIsImF1ZCI6Imh0dHBzOi8vb3BlcmF0b3Iuc2FsZXMub3R2c2UuY29tL2tleWNsb2FrL2F1dGgvcmVhbG1zL25hZ3JhIiwic3ViIjoiMTc0YmMxZmItMTgyYy00NjkxLWI3OGEtMmJkY2NmMGM3YzY3IiwidHlwIjoiUmVmcmVzaCIsImF6cCI6Im1hcnRpbl9jbGllbnQiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiJmMjM0ODgzNS0zNmIyLTRiNmItYWVmZi0wOGQ2OWRjNmRjMDEiLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsib3BlcmF0b3JSb2xlIl19LCJzY29wZSI6InByb2ZpbGUgZW1haWwifQ.Nrlm5E14fyewxRN2K7fLb_NXb8075BO8E3KjcpRAG40",
    "token_type": "bearer",
    "not-before-policy": 0,
    "session_state": "f2348835-36b2-4b6b-aeff-08d69dc6dc01",
    "scope": "profile email"
}