Page tree
Skip to end of metadata
Go to start of metadata

Summary: This section details how to configure a license key for accessing a CAST Dashboard Service via the CAST Application Engineering Dashboard or the CAST RestAPI.

Introduction

When you want to access a CAST Dashboard Service (i.e. via the CAST Application Engineering Dashboard  or the CAST RestAPI), a special license key is required. This license key grants specific access to one or multiple CAST Dashboard Services for the web application in which it is installed (i.e. the CAST Application Engineering Dashboard or the CAST RestAPI).

This key restricts users via a token system in two ways:

  1. A GLOBAL token is consumed for each named user authorized to access “All Applications” in all the target CAST Dashboard Service(s) - for example an Architect
  2. A UNIT token is consumed for each named user authorized to access a named Application in a specific CAST Dashboard Service - for example a Project Leader
  • A RESTRICTED key will have a specific number of GLOBAL and UNIT tokens assigned to it. In the example above, "2/4" tokens is equal to 2 GLOBAL tokens and 4 UNIT tokens.
  • An UNRESTRICTED key will not specify the number of GLOBAL and UNIT tokens assigned to it. In the example above, "2/4" tokens section is replaced by "Unrestricted".

Notes

  • The license key is not limited in time and can be used indefinitely.
  • Users that have been granted the ROLE_ADMIN do not require a license key to access a CAST Dashboard Service. A user with the ROLE_ADMIN role can ONLY use the CAST Application Engineering Dashboard/RestAPI for validating new snapshots during the initial application on-boarding process. The ROLE_ADMIN role MUST NOT be used for on-going end-user use of the CAST Application Engineering Dashboard/RestAPI.
  • The license key discussed in this document is not the same as a global license key that is installed via the CAST Management Studio. This global license key does not grant any access right to the CAST Dashboard Service via the CAST RestAPI.
  • The CAST Application Analytics Dashboard is unaffected by the license key requirement because the dashboard interacts only with CAST Measurement Services which do not require a license key access.

Where do I obtain a license key from?

A license key can only be generated by CAST Support. Please contact the CAST Consultant responsible for your project, or contact your Account Manager to request your key. This key will usually be sent via email.

How do I install a license key?

Installing a license key is relatively straightforward:

  • First create a new empty text file - you can do so by right clicking in File Explorer and selecting New > Text Document
  • Rename the new text file license.key - you may be warned that changing a file's extension could cause the file to become unstable: click Yes when prompted.
  • Now open the text file in a text editor and paste the license key that you have been sent into the first line.
  • Save the license.key file.
  • Now copy or move the license.key file to the following location, where <web_application> is the name of the folder in which you have deployed the CAST Application Engineering Dashboard or the CAST RestAPI which requires licensing:
%CATALINA_HOME%\webapps\<web_application>\WEB-INF\license.key
  • Following any changes you make, restart your application server so that the changes are taken into account.

How can I check whether a license key has been successfully installed?

To check whether a license key has been successfully installed in the web application, you can use the RestAPI interface:

  • Open a browser and go to the following URL, ensuring that you modify it to conform to your environment:
http://<server>:<port>/<web_application>/static/default.html
  • Login (using the Basic Authentication field with any user (it does not have to be a user that has the ROLE_ADMIN role)
  • Now enter "server" in the URI field and click Submit:

  • The result will be shown the Response (Pre-view) tab. In this example, you can see that a restricted license key has been installed:

Note that the following statuses may be returned:

StatusDescription

UNRESTRICTED_LICENSE

An unrestricted license has been successfully installed.

RESTRICTED_LICENSE

A restricted license has been successfully installed.
GLOBAL_ACCESS_TOKENS_EXCEEDEDThe number of GLOBAL tokens on a restricted license has been exceeded.
UNIT_ACCESS_TOKENS_EXCEEDEDThe number of UNIT tokens on a restricted license has been exceeded.

NO_LICENSE_KEY

No license.key file exists at the expected location.
INVALID_LICENSE_KEYThe license.key file exists at the expected location but the license key itself does not conform to the expected format.
CANNOT_ACCESS_LICENSE_KEYThe license.key file exists at the expected location but the license key itself does not exist.
INVALID_LICENSE_FILEThe license.key file exists at the expected location but the file is invalid or corrupt.

How to authorize users when using a RESTRICTED license key

If you have installed a restricted license key (i.e. a key that specifies the number of GLOBAL/UNIT tokens), you can authorize named users to access either ALL the applications in all the target CAST Dashboard Services (a GLOBAL token), or you can authorize named users to access a named Application in a specific CAST Dashboard Service (a UNIT token).

  • This authorization is achieved using the following XML file, which you can edit in a text editor:
%CATALINA_HOME%\webapps\<web_application>\WEB-INF\license.xml
  • Authorization is achieved by adding a line into the file. Each line you add to file will use up ONE single GLOBAL or UNIT token.

Note that when a RESTRICTED license key is installed, any authorizations that you have configured in the authorizations.xml file (see CAST-AED - Configuring data authorization and CAST-AAD - Configuring data authorization (which is also valid for the RestAPI) will be completely ignored. In other words:

  • only the authorizations listed in license.xml will be taken into account when a RESTRICTED license is installed.
  • it is not possible to define authorizations based on groups, the allUsers scope, patterns, tags, categories when a RESTRICTED license is installed.

Authorize a named user to access ALL Applications in ALL the target CAST Dashboard Services

Add the following line under the commented text to grant the user "James" access to ALL applications. Doing so will use ONE single GLOBAL token:

<!-- Each following line will consume a global access token -->
<authorization user="James" allApplications="true"/>

Following any changes you make, save the license.xml file and restart your application server so that the changes are taken into account.

Authorize a named user to access a named Application in a target CAST Dashboard Service

Add the following line under the commented text to grant the user "John" access to the "MEUDON" Application stored in the "V800_CENTRAL" CAST Dashboard Service. Doing so will use ONE single UNIT token:

<!--Each following line will consume a unit access token -->
<authorization user="John" application="MEUDON" adgDatabase="V800_CENTRAL"/>   

Following any changes you make, save the license.xml file and restart your application server so that the changes are taken into account.

What happens on a RESTRICTED license key if I authorize more users than I am licensed for?

Take the following situation:

  1. You are using a RESTRICTED license key (i.e. a key that specifies the number of GLOBAL/UNIT tokens)
  2. You are limited to 2 GLOBAL tokens (2 users with ALL Application authorization) and 5 UNIT tokens (5 users with named Application authorization) on your license key
  3. You authorize (via the license.xml file) either:
    1. 3 users to access ALL Applications
    2. 6 users to access a named Application

In either situation you are in breach of your license:

  • A message will be displayed on every page in the CAST Application Engineering Dashboard as follows:
THIS SOFTWARE IS SUBJECT TO A LIMITED ACCESS.
There are too many authorized users to connect to your Application Engineering Dashboard.
To avoid this limitation, you can contact your CAST Project Manager to update your licensing terms & conditions.

What should you do when you receive the "limited access" message?

If you receive the message described above, you have two options:

  1. Review and reconfigure the users that have been authorized to access data in the CAST Dashboard Service using the license.xml file - i.e. decrease the number of users that have been granted access.
  2. Contact the CAST Consultant responsible for your project, or contact your Account Manager to request an update to your license.

What happens if I attempt to access data when no license key is present?

CAST Application Engineering Dashboard

If a user attempts to login to the CAST Application Analytics Dashboard when no license key has been configured, the following message will be displayed:

Note that users that have been granted the ROLE_ADMIN role do not require a license key to access a CAST Dashboard Service. Out of the box, no user in Static List mode has this role.

CAST Rest API

If you are using the CAST Rest API interface directly, you will be permitted to log in, but when attempting to retrieve data from a CAST Dashboard Service, a 403 Forbidden will be displayed:

 

  • No labels