On this page:
Target audience:
CAST AI Administrators
Authentication modes
The CAST Application Engineering Dashboard has two authentication modes available for use:
| Mode | Description |
|---|---|
| Static List | This mode is enabled by default and relies on simple username/password authentication defined in an XML configuration file within the web application. |
| Active Directory | This mode must be specifically enabled and allows users to authenticate with their corporate Active Directory login. |
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 | Role | Notes |
|---|---|---|---|
| guest | my_password | NO_ROLE | See 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-AED\WEB-INF\users.properties
This file contains the following section which defines the usernames that can access the CAST Application Engineering Dashboard:
guest=my_password,enabled,NO_ROLE
As shown in the above code, each user is defined in 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-AED - 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
Roles are defined in the following file:
%CATALINA_HOME%\webapps\CAST-AED\WEB-INF\users.properties
Currently, two roles are available:
| Role | Default user with this role | Notes |
|---|---|---|
| ROLE_ADMIN | N/A | The ROLE_ADMIN role provides permission to execute the following actions:
In addition, a user with the ROLE_ADMIN role:
Note that:
|
| QUALITY_MANAGER | N/A | The QUALITY_MANAGER role provides permission to add and remove objects from the Action Plan. |
To grant a role to a user, change the NO_ROLE parameter to ROLE_ADMIN or QUALITY_MANAGER in the users.properties file:
jhu=mypassword,enabled,ROLE_ADMIN dch=mypassword,enabled,QUALITY_MANAGER
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 it is possible to grant both roles to one user if required - use a comma to separate the user roles:
jhu=cast,enabled,ROLE_ADMIN,QUALITY_MANAGER
User groups
Users can be grouped together to facilitate authorization assignments (see CAST-AED - 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-AED\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>
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-AED\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 Engineering Dashboard using their Active Directory login - authentication is therefore the responsibility of the corporate Active Directory.
Note that:
- enabling Active Directory mode will disable the Static List mode
- if you need to encrypt the login and password parameters to avoid entering values in clear text, please see: CAST-AAD-AED - Encrypt login and password for datasource and Active Directory
by default, the log mechanism is configured to provide logging information to debug Active Directory authentication issues - If you have encountered issues activating Active Directory authentication, please check the log file (see CAST-AAD-AED - Configuring the Log and Audit Trail for more information about the log file location).
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-AED\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
Roles are defined in the following file:
%CATALINA_HOME%\webapps\CAST-AED\WEB-INF\ldap-roles.xml
Currently, two roles are available:
| Role | Notes |
|---|---|
| ROLE_ADMIN | The ROLE_ADMIN role provides permission to execute the following actions:
In addition, a user with the ROLE_ADMIN role:
Note that:
|
| QUALITY_MANAGER | The QUALITY_MANAGER role provides permission to add and remove objects from the Action Plan. |
To grant a role to a user, change the NO_ROLE parameter to ROLE_ADMIN or QUALITY_MANAGER in the ldap-roles.xml file:
<root> <role-assignment user="jhu" role="ROLE_ADMIN"/> <role-assignment user="dch" role="QUALITY_MANAGER"/> </root>
You can also grant all members of an LDAP group a role via the ldap-roles.xml file:
<root> <role-assignment group="CN=corporate.company.admins" role="ROLE_ADMIN"/> <role-assignment group="CN=corporate.company.actionplan" role="QUALITY_MANAGER"/> </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.
Note that it is possible to grant multiple roles to a user or group if required. Place each role on one line. For example, to add the roles ROLE_ADMIN and QUALITY_MANAGER roles to the group corporate.company.admins and to the user JHU, do as follows:
<root> <role-assignment user="JHU" role="ROLE_ADMIN"/> <role-assignment user="JHU" role="QUALITY_MANAGER"/> <role-assignment group="CN=corporate.company.admins" role="ROLE_ADMIN"/> <role-assignment group="CN=corporate.company.admins" role="QUALITY_MANAGER"/> </root>
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 Engineering Dashboard configuration file, instead the groups that have been created in Active Directory can be used to define data authorization (see CAST-AED - Configuring data authorization). However, sometimes the groups that have been defined in Active Directory are not appropriate for use in the CAST Application Engineering 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-AED - 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-AED\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-AED - Configuring data authorization):
%CATALINA_HOME%\webapps\CAST-AED\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):
