Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Note

The ability to use encrypted passwords with WAR or ZIP files delivered in CAST Dashboards ≥ 2.0 is currently not supported.

Panel

Table of Contents


Info

Summary: this page describes how to encrypt logins and passwords for the CAST dashboardsDashboards/RestAPI:

  1. when connecting to CAST Storage Service/PostgreSQL (for connections to the Measurement/Dashboard schemas and to the user role/authorization database)
  2. when configuring LDAP authentication

Introduction

When configuring CAST dashboard Dashboard / RestAPI connections to CAST Storage Service/PostgreSQL (i.e. Measurement or /Dashboard Service schemas, or user roles/authorizations database) or to an LDAP server for corporate login mode, logins and passwords are defined in the relevant configuration files in clear text. This therefore represents a potential security risk. If your organization requires these logins and passwords to be encrypted, you can use the following instructions to do so.

Info
Note that this document already assumes that you have a working connection to your deployed CAST dashboard Dashboard or RestAPI.

Encrypting access to CAST Storage Service/PostgreSQL

Database server credential encryption is
Info
Note
  • For CAST Dashboards 1.x, encrypted CAST Storage Service/PostgreSQL credentials are only supported for Dashboards deployed on Apache Tomcat 8 or above.
  • By default in CAST Dashboards ≥ 2.5, the wizard installer will automatically encrypt the CAST Storage Service/PostgreSQL password.

To encrypt the login and password that are defined when configuring access to the CAST Storage Service/PostgreSQL instance where your Measurement or /Dashboard Service schemas are located , browse to the following URL to and to the CAST Storage Service/PostgreSQL instance where the User role/authorizations database is stored (by default this is called cast_dashboards), browse to the following URL to access the built in login/password key generation page:

Code Block
languagetext
WAR file deployment: http://<server>:[<port>]/<dashboard>/static/key.html
ZIP/JAR file deployment: http://<server>:[<port>]/static/key.html

Login with a user (whether static list or Active Directory) that has the ADMIN role - by default no users have this role in either static list mode or in Active Directory mode - see User authentication for more information.

...

When successfully authenticated, you now need to enter the credentials (login and password) for your target  CAST Storage Service/PostgreSQL instance (that you would ordinarily enter into the context.xml file for configuring access to the Measurement or Dashboard Service) and that you wish to encrypt. have a choice of method for encryption:

Both username and password combined (available in all releases)

If you want to encrypt both the username and the password, enter them in section 2In the example below, we have entered the default credentials for a  CAST CAST Storage Service/PostgreSQL instance (operator/CastAIP):

Now click the Encrypt button - CAST will then generate a key that relates to the credentials you entered:

...

You now need to copy this key to the clipboard or to a text file . To use the key in place of clear text database credentials, browse to the following fileand then follow the instructions below for your specific dashboard release:

For CAST Dashboards 1.x

noformat
Expand
titleClick to expand

Open the following file with a text editor:

Code Block
languagetext
CATALINA_HOME\webapps\<dashboard>\META-INF\context.xml

Open this file with a text editor and scroll down to the location of a database access resource you have previously configured, for example:

Find the following section of code and replace the line containing "username" and "password" with the key you generated previously:

Code Block
<Resource name="jdbc/domains/AAD" url="jdbc:postgresql://localhost:2280/postgres"
    initConnectionSqls="SET search_path TO CAST_MEASURE;"
    username="operator" password="CastAIP"
                      
    auth="Container" type="javax.sql.DataSource" driverClassName="org.postgresql.Driver"
    validationQuery="select 1"
    initialSize="5" maxActive="20" maxIdle="10" maxWait="-1"/>

...

For example:

key
Code Block
languagetext
<Resource name="
D228ED8B5E5690B3A75"

Add a new line directly underneath the line containing the "key" as follows - take note of the line that is specific to your release of CAST AIP and Apache Tomcat:

Code Block
languagetext
WARs delivered in CAST AIP ≥ 8.3.4 and all standalone CAST Dashboard Packages:

Tomcat ≥ 8 only: factory="com.castsoftware.adg.webservice.security.BasicDataSourceFactory"

WARs delivered in CAST AIP 8.3.0 - 8.3.3:
 
Tomcat 7: factory="com.castsoftware.adg.webservice.security.BasicDataSourceFactory"
Tomcat 8/8.5/9: factory="com.castsoftware.adg.webservice.security.BasicDataSourceFactory2"

Your database access resource should now look like this (this is an example for Tomcat ≥ 8 in CAST AIP ≥ 8.3.4 and all standalone CAST Dashboard Packages):

Code Block
languagexml
<Resource name="jdbc/domains/AAD" url="jdbc:postgresql://localhost:2280/postgres" initConnectionSqls="SET search_path TO CAST_MEASURE;" key="D228ED8B5E5690B3A75"
jdbc/domains/AAD" url="jdbc:postgresql://localhost:2280/postgres"
    initConnectionSqls="SET search_path TO CAST_MEASURE;"
	key="D228ED8B5E5690B3A75"

    auth="Container" type="javax.sql.DataSource" driverClassName="org.postgresql.Driver"
    validationQuery="select 1"
    initialSize="5" maxActive="20" maxIdle="10" maxWait="-1"/>

Now add a new line directly underneath the line containing the "key" entry as follows - take note of the line that is specific to your release of CAST AIP and Apache Tomcat:

Code Block
languagetext
WARs delivered in CAST AIP ≥ 8.3.4 and all standalone CAST Dashboard Packages:

Tomcat ≥ 8 only: factory="com.castsoftware.adg.webservice.security.BasicDataSourceFactory"

WARs delivered in CAST AIP 8.3.0 - 8.3.3:
 
Tomcat 7: factory="com.castsoftware.adg.webservice.security.BasicDataSourceFactory"
auth="Container" type="javax.sql.DataSource" driverClassName="org.postgresql.Driver" validationQuery="select 1" initialSize="5" maxActive="20" maxIdle="10" maxWait="-1"/>

Save the file, reload the cache (see Reload the cache) and then reload your CAST dashboard / RestAPI and ensure you can login and view the data you need to.

Info
You may need to repeat the above for each database server resource you have configured in the context.xml file.

Encrypting access to an LDAP server

...

Code Block
languagetext
security.ldap.account.dn=cn=serviceaccount,dc=example,dc=com
security.ldap.account.password=password

To avoid the need to do this, browse to the following URL to access the built in login/password key generation page:

Code Block
languagetext
http://<server>:[<port>]/<dashboard>/static/key.html

Login with a user (whether Default Authentication or LDAP) that has the ADMIN role - by default no users have this role in either mode - see User authentication for more information:

Image Removed

When successfully authenticated, you now need to enter the credentials (service account login and password) for your LDAP server that you would ordinarily enter into the security.properties file for configuring LDAP mode, and that you wish to encrypt. In the example below, we have entered the required LDAP credentials:

Image Removed

Info

Note that the encryption key combines the values assigned to the following lines in the security.properties file:

Code Block
security.ldap.account.dn=cn=serviceaccount,dc=example,dc=com
security.ldap.account.password=password

Therefore, you must enter in the "username" and "password" fields in the encryption tool EXACTLY what is entered in the "security.ldap.account.dn=" and "security.ldap.account.password=" lines in the security.properties file. For example, if the security.properties file contains:

Code Block
security.ldap.account.dn=CN=myserviceaccount,DC=example,DC=com
security.ldap.account.password=mypassword

...then you need to enter exactly the same in the following fields:

Image Removed

Now click the Encrypt button - CAST will then generate a key that relates to the credentials you entered:

Image Removed

You now need to copy this key to the clipboard or to a text file and then open the following file with a text editor:

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

Locate the following configuration in the file:

Code Block
languagetext
# 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}))

First remove the two lines with the security.ldap.account.dn and security.ldap.account.password parameters. Then enter the key generated previously into the line containing "key". This should give you the following:

Code Block
languagetext
# Parameters for ldap mode
# ------------------------
security.ldap.url=ldap://directory.example.com/
security.ldap.account.key=A9762B77F8A5B6C0A885BABD58DFA1438D77A51B94ECA09
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}))

...

Tomcat 8/8.5/9: factory="com.castsoftware.adg.webservice.security.BasicDataSourceFactory2"

Your database access resource should now look like this (this is an example for Tomcat ≥ 8 in CAST AIP ≥ 8.3.4 and all standalone CAST Dashboard Packages):

Code Block
languagexml
<Resource name="jdbc/domains/AAD" url="jdbc:postgresql://localhost:2280/postgres"
    initConnectionSqls="SET search_path TO CAST_MEASURE;"
    key="D228ED8B5E5690B3A75"
    factory="com.castsoftware.adg.webservice.security.BasicDataSourceFactory"

	auth="Container" type="javax.sql.DataSource" driverClassName="org.postgresql.Driver"
    validationQuery="select 1"
    initialSize="5" maxActive="20" maxIdle="10" maxWait="-1"/>

Save the file, reload the cache (see Reload the cache) and then reload your CAST Dashboard / RestAPI and ensure you can login and view the data you need to.

Info
You may need to repeat the above for each target CAST Storage Server/PostgreSQL instance resource you have configured in the context.xml file.


For CAST Dashboards 2.x

Expand
titleClick to expand

Open the following file with a text editor:

Code Block
languagetext
WAR ≥ 2.x
CATALINA_HOME\webapps\<dashboard>\WEB-INF\classes\application.properties
 
ZIP ≥ 2.0 - 2.4
<install_folder>\application.properties

JAR ≥ 2.5
Microsoft Windows: %PROGRAMDATA%\CAST\Dashboards\<dashboard>\application.properties
Linux: /root/CAST/Dashboards/<dashboard>/application.properties

Find the following sections of code (one is for the application schema CSS/PostgreSQL host and the other is for the user management schema host) and replace the lines "restapi.datasource[0].username" / "spring.datasource.username" and "restapi.datasource[0].password" / "spring.datasource.password" with one single line containing your generated "key":

Code Block
## DATASOURCE
# Resource1 is the datasource name used in domains.properties
# Adapt server name (localhost) and port (2282) if required
# You can add multiple datasources if you want to connect to multiple CSS Servers. Datasource name must be unique
# You have to configure your domains names and relative schema names in domains.properties
restapi.datasource[0].url=jdbc:postgresql://localhost:2282/postgres
restapi.datasource[0].username=operator
restapi.datasource[0].password=CastAIP
restapi.datasource[0].poolname=Resource1
restapi.datasource[0].minimumIdle=10
restapi.datasource[0].maximumPoolSize=20

#datasource configuration for user management
spring.datasource.url=jdbc:postgresql://localhost:2282/postgres?ApplicationName=DASHBOARDS&currentSchema=cast_dashboards
spring.datasource.platform=postgres
spring.datasource.username=operator
spring.datasource.password=CastAIP
spring.datasource.initialization-mode=always
spring.datasource.driver-class-name=org.postgresql.Driver
spring.liquibase.change-log=classpath:db/changelog/db.changelog-master.xml
spring.liquibase.default-schema=cast_dashboards
spring.liquibase.enabled=true

For example:

Code Block
## DATASOURCE
# Resource1 is the datasource name used in domains.properties
# Adapt server name (localhost) and port (2282) if required
# You can add multiple datasources if you want to connect to multiple CSS Servers. Datasource name must be unique
# You have to configure your domains names and relative schema names in domains.properties
restapi.datasource[0].url=jdbc:postgresql://localhost:2282/postgres
restapi.datasource[0].key=D228ED8B5E5690B3A75
restapi.datasource[0].poolname=Resource1
restapi.datasource[0].minimumIdle=10
restapi.datasource[0].maximumPoolSize=20

#datasource configuration for user management
spring.datasource.url=jdbc:postgresql://localhost:2282/postgres?ApplicationName=DASHBOARDS&currentSchema=cast_dashboards
spring.datasource.platform=postgres
spring.datasource.key=D228ED8B5E5690B3A75
spring.datasource.initialization-mode=always
spring.datasource.driver-class-name=org.postgresql.Driver
spring.liquibase.change-log=classpath:db/changelog/db.changelog-master.xml
spring.liquibase.default-schema=cast_dashboards
spring.liquibase.enabled=true

Save the file, reload the cache (see Reload the cache) and then reload your CAST Dashboard / RestAPI and ensure you can login and view the data you need to.

Info
You may need to repeat the above for each target CAST Storage Server/PostgreSQL instance resource you have configured in the application.properties file.


Either user or password (available in ≥ 2.5)

If you want to encrypt either the username OR the password (or BOTH) enter them in section 3.  In the example below, we have entered the default username (operator) for a CAST Storage Service/PostgreSQL instance (but you can alternatively enter the password (CastAIP for example):

Image Added

Now click the Encrypt button - CAST will then generate a key that relates to the credential you entered:

Image Added

You now need to copy this key to the clipboard or to a text file. Next open the following file with a text editor:

Code Block
languagetext
WAR ≥ 2.5
CATALINA_HOME\webapps\<dashboard>\WEB-INF\classes\application.properties
 
JAR ≥ 2.5
Microsoft Windows: %PROGRAMDATA%\CAST\Dashboards\<dashboard>\application.properties
Linux: /root/CAST/Dashboards/<dashboard>/application.properties

Find the following sections of code (one is for the application schema CSS/PostgreSQL host and the other is for the user management schema host) and replace the lines "restapi.datasource[0].username" / "spring.datasource.username" OR "restapi.datasource[0].password" / "spring.datasource.password" with a line containing your generated "key", depending on the item you have encrypted:

Code Block
## DATASOURCE
# Resource1 is the datasource name used in domains.properties
# Adapt server name (localhost) and port (2282) if required
# You can add multiple datasources if you want to connect to multiple CSS Servers. Datasource name must be unique
# You have to configure your domains names and relative schema names in domains.properties
restapi.datasource[0].url=jdbc:postgresql://localhost:2282/postgres
restapi.datasource[0].username=operator
restapi.datasource[0].password=CastAIP
restapi.datasource[0].poolname=Resource1
restapi.datasource[0].minimumIdle=10
restapi.datasource[0].maximumPoolSize=20

#datasource configuration for user management
spring.datasource.url=jdbc:postgresql://localhost:2282/postgres?ApplicationName=DASHBOARDS&currentSchema=cast_dashboards
spring.datasource.platform=postgres
spring.datasource.username=operator
spring.datasource.password=CastAIP
spring.datasource.initialization-mode=always
spring.datasource.driver-class-name=org.postgresql.Driver
spring.liquibase.change-log=classpath:db/changelog/db.changelog-master.xml
spring.liquibase.default-schema=cast_dashboards
spring.liquibase.enabled=true

For example, we have encrypted ONLY the operator username and replaced it with the generated encryption key:

Code Block
## DATASOURCE
# Resource1 is the datasource name used in domains.properties
# Adapt server name (localhost) and port (2282) if required
# You can add multiple datasources if you want to connect to multiple CSS Servers. Datasource name must be unique
# You have to configure your domains names and relative schema names in domains.properties
restapi.datasource[0].url=jdbc:postgresql://localhost:2282/postgres
restapi.datasource[0].username=CRYPTED2:A039A2CEC7EB3490D617DEE94B91A6CC
restapi.datasource[0].password=CastAIP
restapi.datasource[0].poolname=Resource1
restapi.datasource[0].minimumIdle=10
restapi.datasource[0].maximumPoolSize=20

#datasource configuration for user management
spring.datasource.url=jdbc:postgresql://localhost:2282/postgres?ApplicationName=DASHBOARDS&currentSchema=cast_dashboards
spring.datasource.platform=postgres
spring.datasource.username=CRYPTED2:A039A2CEC7EB3490D617DEE94B91A6CC
spring.datasource.password=CastAIP
spring.datasource.initialization-mode=always
spring.datasource.driver-class-name=org.postgresql.Driver
spring.liquibase.change-log=classpath:db/changelog/db.changelog-master.xml
spring.liquibase.default-schema=cast_dashboards
spring.liquibase.enabled=true


Info
  • You can also encrypt the password and replace it with an encrypted key, or both the username AND password and replace both with individual keys.
  • Save the file, reload the cache (see Reload the cache) and then reload your CAST Dashboard / RestAPI and ensure you can login and view the data you need to.

Encrypting access to an LDAP server

When configuring access to an LDAP server for authentication, an LDAP service account login and password must be specified in the.properties file in clear text as described in User authentication:

Code Block
languagetext
WAR 1.x
security.ldap.account.dn=cn=serviceaccount,dc=example,dc=com
security.ldap.account.password=password

WAR and ZIP ≥ 2.x
security.ldap.manager.dn=CN=serviceaccount,OU=RESOURCES,OU=FR,DC=example,DC=com
security.ldap.manager.password=password

To avoid the need to do this, browse to the following URL to access the built in login/password key generation page:

Code Block
languagetext
WAR file deployment: http://<server>:[<port>]/<dashboard>/static/key.html
ZIP/JAR file deployment: http://<server>:[<port>]/static/key.html

Login with a user (whether Default Authentication or LDAP) that has the ADMIN role - by default no users have this role in either mode - see User authentication for more information:

Image Added

When successfully authenticated, you now have a choice of method for encryption:

Both service account login and password combined (available in all releases)

If you want to encrypt both the service account login and the password, enter them in section 2.  In the example below, we have entered the required LDAP credentials:

Image Added

Info

Note that the encryption key combines the values assigned to the following lines in the .properties file:

Code Block
languagetext
WAR 1.x
security.ldap.account.dn=cn=serviceaccount,dc=example,dc=com
security.ldap.account.password=password

WAR/ZIP/JAR ≥ 2.x
security.ldap.manager.dn=CN=serviceaccount,OU=RESOURCES,OU=FR,DC=example,DC=com
security.ldap.manager.password=password

Therefore, you must enter in the "username" and "password" fields in the encryption tool, EXACTLY what is entered in the "dn=" and "password=" lines in the .properties file. For example, if the .properties file contains:

Code Block
WAR 1.x
security.ldap.account.dn=CN=myserviceaccount,DC=example,DC=com
security.ldap.account.password=mypassword

WAR and ZIP ≥ 2.x
security.ldap.manager.dn=CN=myserviceaccount,DC=example,DC=com
security.ldap.manager.password=mypassword

...then you need to enter exactly the same in the following fields:

Image Added

Now click the Encrypt button - CAST will then generate a key that relates to the credentials you entered:

Image Added

You now need to copy this key to the clipboard or to a text file and then open the following file with a text editor:

Code Block
languagetext
WAR 1.x
CATALINA_HOME\webapps\<dashboard>\WEB-INF\security.properties

WAR ≥ 2.x
CATALINA_HOME\webapps\<dashboard>\WEB-INF\classes\application.properties
 
ZIP ≥ 2.x
<unpacked_zip>\application.properties

JAR ≥ 2.5
Microsoft Windows: %PROGRAMDATA%\CAST\Dashboards\<dashboard>\application.properties
Linux: /root/CAST/Dashboards/<dashboard>/application.properties

Locate the following configuration in the file:

Code Block
languagetext
WAR 1.x
# 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}))

WAR/ ZIP / JAR ≥ 2.x

## SPRING SECURITY LDAP CONFIG
# LDAP url, in the form ldap://HOST:PORT
security.ldap.url=
# The ldap base where users and groups can be found
security.ldap.base=
# The DN for accessing the LDAP repository. You can encrypt this using the aip encryption tool
security.ldap.manager.dn=
# The associated password. You can encrypt this using the aip encryption tool
security.ldap.manager.password=

Now follow the instructions below for your specific dashboard release.

For CAST Dashboards 1.x

Expand

First remove the two lines with the security.ldap.account.dn and security.ldap.account.password parameters. Then enter the key generated previously into the line containing "key". This should give you the following:

Code Block
languagetext
# Parameters for ldap mode
# ------------------------
security.ldap.url=ldap://directory.example.com/
security.ldap.account.key=A9762B77F8A5B6C0A885BABD58DFA1438D77A51B94ECA09
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}))

Save the file, restart the web application and ensure you can login and view the data you need to.

For CAST Dashboards 2.x

Expand

First remove the two lines with the security.ldap.manager.dn and security.ldap.manager.password parameters. Then add a new line called security.ldap.manager.key and enter the key generated previous into this new line. This should give you the following:

Code Block
languagetext
## SPRING SECURITY LDAP CONFIG
# LDAP url, in the form ldap://HOST:PORT
security.ldap.url=
# The ldap base where users and groups can be found
security.ldap.base=
security.ldap.manager.key=A9762B77F8A5B6C0A885BABD58DFA1438D77A51B94ECA09

Save the file, restart the web application and ensure you can login and view the data you need to.

Either service account login or password (available in ≥ 2.5)

If you want to encrypt either the username OR the password (or BOTH) enter them in section 3.  In the example below, we have entered the service account login:

Image Added

Now click the Encrypt button - CAST will then generate a key that relates to the credentials you entered:

Image Added

You now need to copy this key to the clipboard or to a text file. Next open the following file with a text editor:

Code Block
languagetext
WAR ≥ 2.5
CATALINA_HOME\webapps\<dashboard>\WEB-INF\classes\application.properties
 
JAR ≥ 2.5
Microsoft Windows: %PROGRAMDATA%\CAST\Dashboards\<dashboard>\application.properties
Linux: /root/CAST/Dashboards/<dashboard>/application.properties

Locate the following configuration in the file:

Code Block
languagetext
## SPRING SECURITY LDAP CONFIG
# LDAP url, in the form ldap://HOST:PORT
security.ldap.url=
# The ldap base where users and groups can be found
security.ldap.base=
# The DN for accessing the LDAP repository. You can encrypt this using the aip encryption tool
security.ldap.manager.dn=
# The associated password. You can encrypt this using the aip encryption tool
security.ldap.manager.password=

Enter the encrypted key in place of the service account login or the password (or both if you have encrypted both individually). In the example below, we have replaced the service account login with the encrypted key:

Code Block
languagetext
## SPRING SECURITY LDAP CONFIG
# LDAP url, in the form ldap://HOST:PORT
security.ldap.url=
# The ldap base where users and groups can be found
security.ldap.base=
# The DN for accessing the LDAP repository. You can encrypt this using the aip encryption tool
security.ldap.manager.dn=CRYPTED2:6E600F59C2145C3674D18C4CD9D206CD812BB979955A23642747A4BDE1F4DBE24E98D3E82E198C0AA97375692A43F853
# The associated password. You can encrypt this using the aip encryption tool
security.ldap.manager.password=


Info
  • You can also encrypt the password and replace it with an encrypted key, or both the username AND password and replace both with individual keys.
  • Save the file, reload the cache (see Reload the cache) and then reload your CAST Dashboard / RestAPI and ensure you can login and view the data you need to.

What happens if the LDAP credentials change (new password)?

...

  • temporarily restoring access using a login and password, i.e. removing the security.ldap.account.key line from security.properties and re-adding the security.ldap.account.dn and security.ldap.account.password lines.accessing key.html and password in plain text by editing the .properties file.
  • accessing the key.html page and encrypting the new login/password into a key.
  • removing the security.ldap.account.dn and security.ldap.account.password lines from security.properties and re-adding the security.ldap.account.key line with the new keythe new encrypted keys by editing the .properties file.