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:

• Static Token

• OAuth

Each of these is discussed separately below.

Static token authentication

The following section appears at the appsettings.json configuration file. It allows you to specify whether an RPIAuthKey authentication token needs to be passed when making calls to API endpoint methods that require the roles listed therein.

"BasicAuthenticationRequireToken": {
    "Standard": false,
    "Forms": true,
    "ListenerQueue": true,
    "Recommendations": true,
    "Views": true
}

In this case, methods protected by the Standard role do not require an RPIAuthKey authentication token, whereas those protected by the Forms role do require a token.

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

An RPI Realtime authentication database must be made available, and tables created therein through running the following SQL script: DeploymentFiles\SQL Server\Useful Scripts\Realtime\RealtimeCore.sql.

Configuration

The Authentication__EnableOAuth environment variable must be set to true. In addition, a DefaultConnection connection string must be configured to the RP Realtime authentication database.

The following additional environment variables apply:

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

• Authentication__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, the RPI Realtime Token endpoint ([Realtime server]/connect/token) must be called, and a username and password passed to the same. 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 at point of its generation.

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

The following should be passed 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 Swagger 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:

• RealtimeAPICredentials

• RealtimeAPIUseCredentials

The RPI user must be associated with the Interaction role.