RPI Realtime authentication

Overview

Each RPI Realtime endpoint method is linked to a role. Roles are used in both types of authentication supported at the RPI Realtime API:

• Basic (static token)

• OAuth

The following section in the values.yaml configuration file allows you to specify whether to use basic or oauth authentication, as well as the corresponding options:

realtimeapi:
  # The default authentication method for the Realtime API is an authentication 
  # token in the header of the call to the API endpoint
  authentication:
    # Supported options are 
    # - basic
    # - oauth
    type: basic
    # With basic authentication, methods protected by the Standard role do not require an RPIAuthKey 
    # authentication token whereas the rest require a token.
    basic:
      authToken: 00000000-0000-0000-0000-000000000000
      standard: false
      forms: true
      listenerQueue: true
      recommendations: true
    # Once OAuth authentication is enabled, it takes precedence over the usage of static token authentication.
    # An RPI Realtime authentication database must be made available, and 
    # Refer to https://docs.redpointglobal.com/rpi/rpi-realtime-authentication
    oauth:
      databaseName: RPIRealtimeCore
      accessTokenLifetimeSeconds: 360
      refreshTokenLifetimeSeconds: 360

Each of these authentication options is discussed separately below.

Basic (static token) authentication

If you’re using basic authentication, methods protected by the Standard role do not require an RPIAuthKey authentication token by default (standard: false), whereas those protected by the Forms, ListenerQueue, and Recommendations roles do require a token by default. When using basic authentication, an RPIAuthKey authentication token needs to be passed when making calls to API endpoint methods that require the roles listed therein.

realtimeapi:
  authentication:
    type: basic
    basic:
      authToken: 00000000-0000-0000-0000-000000000000
      standard: false
      forms: true
      listenerQueue: true
      recommendations: true

If authentication is not satisfied when calling a method, the following body is returned:

{
    "Message": "Authorization has been denied for this request."
}

The return's status is 401 Unauthorized.

OAuth authentication

To enable RPI Realtime OAuth authentication, carry out the actions below.

Database

Run the following SQL script: DeploymentFiles\SQL Server\Useful Scripts\Realtime\RealtimeCore.sql to make an RPI Realtime authentication database available with tables. We recommend that you create this OAuth database on the same SQL Server hosting the Pulse and Pulse Logging operational databases.

Configuration

In the values.yaml configuration file, set the authentication type to oauth and set the databaseName to the RPI Realtime authentication database created in the last step.

realtimeapi:
  authentication:
    type: oauth
    oauth:
      databaseName: RPIRealtimeCore
      accessTokenLifetimeSeconds: 360
      refreshTokenLifetimeSeconds: 360

You can optionally adjust the following settings:

• accessTokenLifetimeSeconds: access token's lifetime, in seconds.

• refreshTokenLifetimeSeconds: refresh token's lifetime, in seconds.

Once OAuth authentication is enabled, it takes precedence over the usage of static token authentication.

Token endpoint

To use RPI Realtime with OAuth, call the RPI Realtime Token endpoint ([Realtime server]/connect/token), passing a username and password. The endpoint is used to obtain a bearer token, which is a time-limited token that defines the user making subsequent calls to Realtime API endpoints. The roles associated with the bearer token are defined when it's generated.

If roles change, you will need to generate new a token to pick up the changes.

The following is an example of how to generate the token:

# Requesting a Token
TOKEN=$(curl -L -X POST \
  "http://$REALTIME_API_ADDRESS/connect/token/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=password" \
  --data-urlencode "client_id=$CLIENT_ID" \
  --data-urlencode "username=$USERNAME" \
  --data-urlencode "password=$PASSWORD" \
  --data-urlencode "client_secret=$CLIENT_SECRET" | jq -r '.access_token')
# Get version information for Realtime API and Realtime Agent
curl -X GET "https://$REALTIME_API_ADDRESS/api/v2/system/version" \
 -H "accept: application/json" \
 -H "Authorization: Bearer $TOKEN" | jq 

Where…

• client_id refers to the ClientId value stored in the [RPIRealtimeCore].[dbo].[OpenIddictApplications] table.

• client_secret is the original (unhashed) value of the ClientSecret stored in the same table.

• username is the username of a valid RPI user with the appropriate roles assigned.

• password is the password associated with the specified RPI user.

Pass the following in the call to the token endpoint:

• Headers:

  • Content-Type: application/x-www-form-urlencoded

• Body:

  • x-www-form-urlencoded

  • Keys:

    • grant_type: password

    • username

    • password

The following represents an example of a bearer token returned by the endpoint:

{
    "resource": "resource-server",
    "token_type": "Bearer",
    "access_token": "CfDJ8IbSSMi3VZdJnFSayQaR4O5WqBuu-oif0HYOBsO6ChiE3wEI9ojNuSFed9xNPEmvRsS6yLKp-s7WBeSmXM415McSFc3fYSDYa8ZL0lsNnVksgZzb2AZSR3hEhhfmE4HEIJpM_r29pvuCwZPsMiLIzj8NSwuUNNhk-Bk5A4p6hAVE7Q1oQr0xBGQcGAwoA-ipBiRGQOnWxGUd9cbM7rC7a2SYQD0bRYUd6JTIbWLDrmLmXPYyebjSxVyYw18TbIiVQh3OAvF6g0mPcMWTCTHwjw9PzukiiRjhVgSyq7FPjq_KBvDb012quHeqQJ9TaDGHqLxZ8I0UoOoOry38gD5jeF1PxljZ6LuVO6ot8wevtpK8KZwY15aTbfgPGEtMrIihIFNgVWzlDwwS7f0t7erEVxkn9ODmn32v6W401vqthn3R4m6ZMWSAyR8EhbwYdSurE4M65EH1ENPbU6nyjMYgSpngaHUaid7M84bhtGZJe5sVPm1Zzkh2xvbAsPQ99QbifPP0Xhq3ilrm5PEHD5ox8J7Xo5j8iAyNpiChg24Nh-2VQmsyL5RN_ZAYbmf2w0MOc9pse2YEcbIlr4L088op3roYA8qmAnnCc91MIkhSRcvtIYKLL-IJ0yB02daxO_zkxVSQukv8jd9TdVz48uN3Z0fTTLXYEPBsGtUsbY_QnD8ZLc1aMSBu8jcDQWcwh11hQq6YRrHZ8M5BeMx8bi-St61n5do5WA7x-EzW0HYTAXG7BGLrtT2mlTJrcctDza3Pm41p12FQFQmgIqDBbamiyvc",
    "expires_in": 1209600
}

Users

Two users are provided out-of-the-box for use when using RPI Realtime with OAuth:

• coreuser: associated with all roles.

• standarduser: associated with the Standard, Forms, ListenerQueue, and Recommendations roles.

Default passwords for the above are available on request.

The following roles are supported:

• Administrator

• Forms

• Interaction

• ListenerQueue

• Recommendations

• Standard

• System

• Views

The RPI Realtime documentation includes details of the roles required to access specific endpoints.

User management endpoints

A series of Account endpoints are provided to facilitate management of RPI OAuth users. Full details are provided at the RPI Realtime API documentation.

RPI OAuth user

RPI itself requires OAuth user credentials, which are used when publishing content, for example. The credentials are set using the following system configuration settings within the RPI client configuration:

• RealtimeAPICredentials

• RealtimeAPIUseCredentials

The RPI user must be associated with the Interaction role.