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

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

On this page:

Summary: This section describes how to configure user authentication for the CAST dashboards.

Introduction

The CAST dashboards have various authentication modes available for use:

Mode
Description
Notes
Default authenticationThis mode is active by default and relies on simple username/password authentication defined in the application-security-default.xml configuration file within the web application.
  • CAST recommends using Standard LDAP because this avoids having to manually manage individual usernames and passwords via the Default authentication mode.
  • Only one mode can be active at a time.
Standard LDAP

This mode is inactive by default and allows users to authenticate with a standard LDAP server. For example:

  • Basic Active Directory domain controllers
  • Other members of the Active Directory family such as ADAM / AD LDS
  • Non-Microsoft directories such as Apache, Oracle, Novell etc.

Note that the configuration of the Standard LDAP mode requires detailed knowledge of your environment's LDAP implementation - i.e. an LDAP administrator should help with this.

SAMLThis mode is inactive by default and allows users to authenticate via SAML.


Authentication mode activation

 Click here to expand...

The activation of the available authentication modes is governed by the security.properties configuration file within the web application:

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

In the security.properties configuration file, activation is handled by the following section. In the "out of the box" state, the default security mode is active as shown below. Only one mode can be active at a time:

# ===================
# Security parameters
# ===================

# Applicable security mode
# ------------------------
#  - default    ->    The initial mode when you deploy the application
#  - ldap       ->    Set this mode for authentication over LDAP(S)
#  - saml       ->    Set this mode for authentication over SAML
security.mode=default

To activate a mode, change the following line to the required security mode. For example, to change from the Default authentication security mode to Standard LDAP, do as follows. Change:

security.mode=default

to:

security.mode=ldap

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

Default authentication mode

 Click here to expand...

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

GroupNotes
guestmy_passwordNoGroupSee the section below for more information about groups.

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

CATALINA_HOME\webapps\<dashboard>\WEB-INF\users.properties

This file contains the following section which defines the usernames that can access the Security Dashboard:

guest=my_password,NoGroup,enabled
  • 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
  • The enabled/disabled entry must ALWAYS be placed at the very end of the line.
  • This user does not have permission to access any data, therefore you must either grant this user specific roles or grant access to the data via an authorization.

Users

Adding a new user

To add a new user, add an additional line into the users.properties file. The following examples will add in a username "jhu" with the password "password" with no group configuration:

guest=my_password,NoGroup,enabled
jhu=password,NoGroup,enable

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, 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 Data authorization) specific to the new user to grant the user access to data
  • or grant the user (or the group the user belongs to) the 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, 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, 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=password,NoGroup,disabled

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 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\<dashboard>\WEB-INF\users.properties

Adding a new group

In this example we will add the group "CIO" and associate the existing user "jhu" to that group:

jhu=password,NoGroup,enabled

Replace the NoGroup entry with the name of the group "CIO", ensuring that enabled is always at the end of the line:

jhu=password,CIO,enabled

If other users should also be members of this group, add them in the same way:

jhu=password,CIO,enabled
dch=password,CIO,enabled

A user can be a member of several groups. The following defines the existing user "jhu" as member of the "CIO" and "Users" groups - i.e. comma separated group names:

jhu=password,CIO,Users,enabled

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 a group name is defined in the users.properties file the group is automatically created. The group does not need to be declared or defined anywhere else. 

Standard LDAP mode

 Click here to expand...


Note that the configuration of the Standard LDAP mode requires detailed knowledge of your environment's LDAP implementation - i.e. an LDAP administrator should help with this.

This mode is not enabled by default "out of the box". It may be used with any LDAP compatible corporate directory. It allows users to login to the dashboard with their corporate LDAP credentials. LDAP groups can also be used for authorization assignments and for role assignments.

CAST has provided place holder parameters, so you must change these before authentication will work correctly. To do so, modify the following configuration file within the web application:

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

This file contains the following section which defines the required parameters:

# Parameters for ldap mode
# ------------------------
security.ldap.url=ldap://directory.example.com/
security.ldap.account.dn=cn=serviceaccount,dc=example,dc=com
security.ldap.account.password=password
security.ldap.account.key=
security.ldap.usersearch.base=dc=example,dc=com
security.ldap.usersearch.filter=(&(objectClass=user)(sAMAccountName={0}))
security.ldap.groupsearch.base=dc=example,dc=com
security.ldap.groupsearch.filter=(&(objectClass=group)(member={0}))

You first need to change the following parameters marked in red to match the URL and the service account required to connect to your LDAP directory:

  • security.ldap.url=ldap://directory.example.com/
  • security.ldap.account.dn=cn=serviceaccount,dc=example,dc=com
  • security.ldap.account.password=password

Leave the following line blank unless you need to encrypt the credentials to avoid entering values in clear text, please see: Encrypt login and password for database and LDAP for more information about this:

  • security.ldap.account.key=

You then need to change the following parameters marked in red related to searching the users/groups in your directory:

  • security.ldap.usersearch.base > The root tree node from which users should be searched
  • security.ldap.usersearch.filter > The criteria for searching users: you must change "user" and "sAMAccountName" to match your directory structure
  • security.ldap.groupsearch.base > The root tree node from which groups should be searched
  • security.ldap.groupsearch.filter > The criteria for searching users: you must change "group" and "member" to match your directory structure

For example:

  • security.ldap.usersearch.base=dc=example,dc=com
  • security.ldap.usersearch.filter=(&(objectClass=user)(sAMAccountName={0}))
  • security.ldap.groupsearch.base=dc=example,dc=com
  • security.ldap.groupsearch.filter=(&(objectClass=group)(member={0}))

For some LDAP servers:

  • the security.ldap.usersearch.filter parameter may take the following form "security.ldap.usersearch.filter=(&(objectClass=inetOrgPerson)(uid={0}))"
  • the security.ldap.groupsearch.filter parameter may take the following form "security.ldap.groupsearch.filter=(&(objectClass=groupOfNames)(member={0]))"

Following any changes you make, save the security.properties file and then restart your application server so that the changes are taken into account. Users should now be able to access the dashboard using their corporate LDAP login - authentication is therefore the responsibility of the corporate LDAP directory.

Note that:

  • enabling Standard LDAP mode will disable the Default Authentication mode
  • 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 Configuring the Log and Audit Trail for more information about the log file location).
  • by default LDAP users 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 Data authorization) specific to the user (or to a group the user belongs to) to grant the user access to data
    • or grant the user (or the group the user belongs to) the ADMIN role which has access to all data and therefore does not require an authorization configuration (but you should use this role with caution!)

Notes about Groups

  • Users can be grouped together to facilitate authorization assignments (see 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. In Standard LDAP mode, Groups are retrieved directly from the LDAP directory as configured in CATALINA_HOME\webapps\<dashboard>\WEB-INF\security.properties.
  • Nested groups are supported, both for authorization assignments (see Data authorization) and for role assignments. For instance, if user jdoe is member of groupA, which is member of groupB which is used to define an authorization or role, then jdoe will be attributed the groupB authorizations/roles.

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 security.ldap.url parameter in CATALINA_HOME\webapps\<dashboard>\WEB-INF\security.properties
  • 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".

SAML mode

 Click here to expand...

Unable to render {include} The included page could not be found.

  • No labels