Introduction

If you have enabled SAML authentication mode for your CAST Dashboard/RestAPI deployment, certain CAST features and services will not be able to authenticate to access data, for example:

• Report Generator
• Automated actions using CURL (for example cache reload)

This is because SAML is designed as a single sign-on mode for browsers and therefore non-browser clients (like Report Generator and CURL) cannot use the protocol. In order to resolve this issue, CAST provides the ability to define an API Key in the CAST dashboards/RestAPI that can be used to bypass SAML authentication.

How does this work?

• SAML authentication mode is enabled and configured for your CAST dashboard/RestAPI deployment
• In addition, an API Key is defined in the security.properties file (WAR 1.x) or application.properties file (WAR / ZIP / JAR ≥ 2.x) in your CAST dashboard/RestAPI deployment
• The API Key is used instead of a password in clients that cannot authenticate using SAML
• Clients must use two specific HTTP headers to ensure that the API Key is used (Report Generator is pre-configured to send these headers)
  • X-API-KEY: the API Key matching the key defined in the security.properties or application.properties file
  • X-API-USER: a defined user name to obtain a CAST dashboard/RestAPI role and data authorization
• When an API Key is used to bypass SAML mode, the user will be automatically granted the "ADMIN" role even if this role has not explicitly been granted to the user in question.

Configuration

Configuring an API Key is simple. Locate the following file in your CAST dashboard/RestAPI/integrated RestAPI deployment and edit it with a text editor:

WAR 1.x
CATALINA_HOME\webapps\<dashboard>\WEB-INF\security.properties

WAR ≥ 2.x
CATALINA_HOME\webapps\<deployed_war>\WEB-INF\classes\application.properties

ZIP ≥ 2.x
<unpacked_zip>\application.properties

JAR ≥ 2.5
%PROGRAMDATA%\CAST\Dashboards\<dashboard>\application.properties

Docker
You must modify the application.properties file within the container itself. To do so run:

docker ps //lists all containers, use it to find the Dashboard container ID
docker exec -it <dashboard_container_ID> bash //enters the Dashboard container in a bash shell
cd /cast/shared_data/dashboards/health_engineering/config //moves into the folder where the application.properties file is located
vi application.properties //opens the file in the vi editor

Locate the following section:

#security.apikey=...

First uncomment the security.apikey line:

security.apikey=...

Now add a key after the = sign on the security.apikey line. You can use any string of characters - CAST recommends generating a random string of at least 16 characters, for example:

security.apikey=G]MauT-9/*<dev8r

Following any changes you make, save the security.properties / application.properties file and then restart your application server so that the changes are taken into account.

Using the API key

Report Generator

To use the API key, you can define it in the GUI or via the command line (both the traditional Windows version and the cross-platform CAST Report Generator for Dashboards version). See the following documentation for more information:

GUI

• Configuring access to the data

CLI

• Report Generator - Command line interface
• CAST Report Generator for Dashboards

Automated actions using CURL

To use the API Key in automated CURL actions, use the following syntax:

• X-API-KEY: the API Key matching the key defined in the security.properties / application.properties file
• X-API-USER: a defined user name to obtain a CAST dashboard/RestAPI role and data authorization

An example is given for reloading the server cache.