Configuration Security

This document describes how to retrieve and secure CAS configuration and properties.

Standalone

If you are running CAS in standalone mode without the presence of the configuration server, you can take advantage of built-in Jasypt functionality to decrypt sensitive CAS settings.

Jasypt supplies command-line tools useful for performing encryption, decryption, etc. In order to use the tools, you should download the Jasypt distribution. Once unzipped, you will find a jasypt-$VERSION/bin directory a number of bat|sh scripts that you can use for encryption/decryption operations (encrypt|decrypt).(bat|sh).

Encrypted settings need to be placed into CAS configuration files as:

1
cas.something.sensitive={cipher}FKSAJDFGYOS8F7GLHAKERGFHLSAJ

You also need to instruct CAS to use the proper algorithm, decryption key and other relevant parameters when attempting to decrypt settings. To see the relevant list of CAS properties for this feature, please review this guide.

Spring Cloud

Securing CAS settings and decrypting them is entirely handled by the Spring Cloud project as described in this guide.

The CAS configuration server exposes /encrypt and /decrypt endpoints to support encrypting and decrypting values. Both endpoints accept a POST payload; you can use /encrypt to secure and encrypt settings and place them inside your CAS configuration. CAS will auto-decrypt at the appropriate moment.

To see the relevant list of CAS properties for this feature, please review this guide.

JCE Requirements

to use the encryption and decryption features you need the full-strength "Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files" installed in your JVM version (if it’s not there by default).

To encrypt a given setting, use:

1
curl https://config.server.endpoint/encrypt -d sensitiveValue

Then, copy the encrypted setting into your CAS configuration using the method specified below.

URL Encoding

Be careful with curl. You may have to use --data-urlencode or set an explicit Content-Type: text/plain to account for special characters such as +.

If you wish to manually encrypt and decrypt settings to ensure the functionality is sane, use:

1
2
3
export ENCRYPTED=`curl https://config.server.endpoint/encrypt -d sensitiveValue | python -c 'import sys,urllib;print urllib.quote(sys.stdin.read().strip())'`
echo $ENCRYPTED
curl https://config.server.endpoint/decrypt -d $ENCRYPTED | python -c 'import sys,urllib;print urllib.quote(sys.stdin.read().strip())'

Properties that are prefixed with {cipher} are automatically decrypted by the CAS configuration server at runtime, such as:

1
2
3
cas
    something
        sensitive: '{cipher}FKSAJDFGYOS8F7GLHAKERGFHLSAJ'

Or:

1
2
# Note that there are no quotes around the value!
cas.something.sensitive={cipher}FKSAJDFGYOS8F7GLHAKERGFHLSAJ

Vault

You can also store sensitive settings inside Vault. Vault can store your existing secrets, or it can dynamically generate new secrets to control access to third-party resources or provide time-limited credentials for your infrastructure. To lean more about Vault and its installation process, please visit the project website.

Once vault is accessible and configured inside CAS, support is provided via the following dependency:

1
2
3
4
5
<dependency>
     <groupId>org.apereo.cas</groupId>
     <artifactId>cas-server-core-configuration-cloud-vault</artifactId>
     <version>${cas.version}</version>
</dependency>

To see the relevant list of CAS properties for this feature, please review this guide.

With CAS, secrets are picked up at startup of the application server. CAS uses the data and settings from the application name (i.e. cas) and active profiles to determine contexts paths in which secrets should be stored and later fetched.

These context paths typically are:

1
2
/secret/{application}/{profile}
/secret/{application}

As an example, you may write the following CAS setting to Vault:

1
vault write secret/cas/native <setting-name>=<value>

CAS will execute the equivalent of the following command to read settings later when needed:

1
vault read secret/cas/native

All settings and secrets that are stored inside Vault may be reloaded at any given time. To lean more about CAS allows you to reload configuration changes, please review this guide. To lean more about how configuration is managed and profiled by CAS, please review this guide.

Troubleshooting

To enable additional logging, modify the logging configuration file to add the following:

1
2
3
4
<AsyncLogger name="org.springframework.cloud.vault" level="debug" additivity="false">
    <AppenderRef ref="console"/>
    <AppenderRef ref="file"/>
</AsyncLogger>