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

On this page:

Target audience:

CAST AI Administrators

Summary: This section describes how to configure user authentication for your CAST Application Analytics Dashboard, including users and groups.

Authentication modes

The CAST Application Analytics Dashboard has two authentication modes available for use:

ModeDescription
Static ListThis mode is enabled by default and relies on simple username/password authentication defined in an XML configuration file within the web application.
Active DirectoryThis mode must be specifically enabled and allows users to authenticate with their corporate Active Directory login. This mode is highly recommended and should be implemented where possible.
Note that enabling Active Directory mode will disable the Static List mode.

Static List mode

This mode is enabled by default "out of the box" with the following username and case sensitive password (usernames are NOT case sensitive):

Username
Password
RoleNotes
guestmy_passwordNO_ROLESee the section below for more information about roles.

If you would like to alter the password for these existing usernames, or you would like to add additional username/passwords, you need to modify the following file with a text editor:

%CATALINA_HOME%\webapps\CAST-AAD\WEB-INF\users.properties

This file contains the following section which defines the usernames that can access the CAST Application Analytics Dashboard:

guest=my_password,enabled,NO_ROLE

A user is defined on a single line.

If the username or password contains special characters (non US-ANSI characters) such as é,è,à,ç,ù,… : you must ensure that your text editor saves the user.properties file with iso-8859-1 encoding

Users

Adding a new user

To add a new user, add an additional line. For example this will add in a username "jhu" with the password "mypassword" with no role granted:

guest=my_password,enabled,NO_ROLE
jhu=mypassword,enabled,NO_ROLE

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

 Note that when you add a new user and defining "NO_ROLE", the user will initially not have access to any data - an error will be displayed when the user attempts to log in. You must therefore either:

  • configure an Authorization (see CAST-AAD - Configuring data authorization) specific to the new user to grant the user access to data
  • or grant the user the ROLE_ADMIN role which has access to all data and therefore does not require an authorization configuration (but you should use this role with caution!)

Removing an existing user

To remove an existing user, simply remove the corresponding line from the users.properties file. Following any changes you make, save the users.properties file and then restart your application server so that the changes are taken into account.

Editing an existing user

To edit an existing user, simply edit the corresponding line in the users.properties file. Following any changes you make, save the users.properties file and then restart your application server so that the changes are taken into account.

Disabling a user without removing it from the users.properties file

To disable a user, change the enabled parameter to disabled:

jhu=mypassword,disabled,NO_ROLE

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

User roles

Currently, only one user role can be granted to a user. This is the ROLE_ADMIN role which is not granted to any user by default. Roles are defined in the following file:

%CATALINA_HOME%\webapps\CAST-AAD\WEB-INF\users.properties

Note that the ROLE_ADMIN role provides permission to execute the following actions:

In addition:

To grant the ROLE_ADMIN role to a user, change the NO_ROLE parameter to ROLE_ADMIN in the users.properties file:

jhu=mypassword,enabled,ROLE_ADMIN

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

User groups

Users can be grouped together to facilitate authorization assignments (see CAST-AAD - Configuring data authorization) - for example, a set of users can be assigned to a group and that group can then be authorized to view the required data instead of having to authorize individual users. Groups are defined in the following file:

%CATALINA_HOME%\webapps\CAST-AAD\WEB-INF\groups.xml

Adding a new group

Each line of the groups.xml file defines group membership for a user. The following example defines users guest1 and guest2 as members of the team1 group:

<root>
   <membership group="team1" user="guest1"/>
   <membership group="team1" user="guest2"/>
</root>

A user can be a member of several groups. The following file defines user guest1 as member of the team1 and team2 groups:

 

<root>
   <membership group="team1" user="guest1"/>
   <membership group="team2" user="guest1"/>
</root>
Following any changes you make, save the groups.xml and then restart your application server so that the changes are taken into account. 

Active Directory mode

This mode allows users to authenticate with their corporate Active Directory login. Active Directory mode is not enabled "out of the box" and you must specifically enable and then configure it if you need to use it. To do so, modify the following file with a text editor:

%CATALINA_HOME%\webapps\CAST-AAD\WEB-INF\web.xml

Find the following sections in the file:

<context-param>
    <description>Select authentication mode: activedirectory or staticlist</description>
    <param-name>authentication.mode</param-name>
    <param-value>staticlist</param-value>
</context-param>

------------------

<context-param>
   <description>Active directory: base search path build from your domain name</description>
   <param-name>authentication.activedirectory.domain</param-name>
   <param-value>[dc=domaine,dc=societe,dc=com]</param-value>
</context-param>
        
<context-param>
   <description>Active directory: LDAP URL Server</description>
   <param-name>authentication.activedirectory.ldapurl</param-name>
   <param-value>[ldap://...]</param-value>
</context-param>
    
<context-param>
   <description>Active directory: user</description>
   <param-name>authentication.activedirectory.login</param-name>
   <param-value>[user@domaine.societe.com]</param-value>
</context-param>
    
<context-param>
   <description>Active directory: password</description>
   <param-name>authentication.activedirectory.password</param-name>
   <param-value>[password]</param-value>
</context-param>

Change the above parameters as follows:

  • In the authentication.mode parameter, change staticlist to activedirectory. This will disable Static List mode authentication and enable Active Directory mode
  • In the authentication.activedirectory.domain parameter, enter your own Active Directory domain name in LDAP format (dc=corp,dc=castsoftware,dc=com)
  • In the authentication.activedirectory.ldapurl parameter, enter the URL of your LDAP server using the ldap://host[:port] format
  • In the authentication.activedirectory.login parameter, enter the details of a user in the Active Directory database that has read-only rights (you may want to create a user specifically for this purpose)
  • In the authentication.activedirectory.password parameter, enter the password for the user specified in the authentication.activedirectory.login parameter

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

Users should now be able to access the CAST Application Analytics Dashboard using their Active Directory login - authentication is therefore the responsibility of the corporate Active Directory.

Note that:

Note about using LDAPS (LDAP over SSL)

If your LDAP server requires that you use LDAPS (LDAP over SSL) then you must ensure that the following is done:

  • Use a ldaps:// URL in the authentication.activedirectory.ldapurl parameter in %CATALINA_HOME%\webapps\CAST-AAD\WEB-INF\web.xml.
  • The LDAP server's SSL certificate or a parent certificate (CA) also needs to be imported into the truststore for the default Java implementation (i.e. JRE) used by the web application server. To do this, you need to use the keytool command line utility (provided with the JRE - see https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html for more information) on the workstation on which the web application server is running. For example:
%JAVA_HOME%\bin\keytool -importcert -alias [alias] -keystore [path-to-jre/lib/security/cacerts] -file [path-to-certificate-file]

Note that you may be prompted for the password of the keystore. By default this password is set to "changeit".

User roles

Currently, only one user role can be granted to a user. This is the ROLE_ADMIN role which is not granted to any user by default. Roles are defined in the following file:

%CATALINA_HOME%\webapps\CAST-AAD\WEB-INF\ldap-roles.xml

Note that the ROLE_ADMIN role provides permission to execute the following actions:

In addition:

To grant the ROLE_ADMIN role to a user, change the NO_ROLE parameter to ROLE_ADMIN in the ldap-roles.xml file:

<root>
   <role-assignment user="JHU" role="ROLE_ADMIN"/>
</root>

You can also grant all members of an LDAP group the ROLE_ADMIN role in the ldap-roles.xml file:

<root>
   <role-assignment group="CN=company.dashboard-users" role="ROLE_ADMIN"/>
</root>
Following any changes you make, save the ldap-roles.xml file and then restart your application server so that the changes are taken into account.

User groups

When using Active Directory authentication mode, group organization is usually configured on the Active Directory side - in other words, user groups are not defined in any CAST Application Analytics Dashboard configuration file, instead the groups that have been created in Active Directory can be used to define data authorization (see CAST-AAD - Configuring data authorization). However, sometimes the groups that have been defined in Active Directory are not appropriate for use in the CAST Application Analytics Dashboard to configure data authorization and it may be impossible to modify or create new Active Directory groups to achieve what is required.

As such, it is possible to make an Active Directory user a member of a Static List authentication group and then use that Static List group to define data authorization (see CAST-AAD - Configuring data authorization). Static List authentication mode does not need to be active for this to function correctly.

To add an Active Directory user to a Static List authentication mode group, edit the following file:

%CATALINA_HOME%\webapps\CAST-AAD\WEB-INF\groups.xml

Then, to add the Active Directory users "J.Doe" and "F.Bloggs" to the "France" group, do as follows:

<root>
	<membership group="France" user="J.Doe"/>
	<membership group="France" user="F.Bloggs"/>
</root>

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

Using the group in a data authorization

You can then use the "France" group to define data authorization via the following file (see CAST-AAD - Configuring data authorization):

%CATALINA_HOME%\webapps\CAST-AAD\WEB-INF\authorizations.xml

For example:

<root>
	<!-- authorize a static-list group (France) to access a specific application -->
	<authorization group="France" application="Billing platforms" adgDatabase="demo_800_central"/>
</root>

What happens when an Active Directory user is a member of an Active Directory group and a Static List group and each group has different data authorization

If Active Directory UserX belongs to two groups (group1 in Static List and group2 in Active Directory group),and we define authorization for these two groups at the same time, then the authorization will form a "union" as shown in the diagram below. The result is that UserX can access data that is authorized for each group):

  • No labels