Summary: an explanation of how to authenticate with the RestAPI using an API key - primarily to enable the Report Generator to authenticate when SAML mode is active.

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:

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.

  • An API Key is available in CAST Dashboard package v. ≥ 1.11.0.
  • It may also be necessary to do this when using LDAP authentication mode.

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

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

CLI

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.