Configuration Server

As your CAS deployment moves through the deployment pipeline from dev to test and into production you can manage the configuration between those environments and be certain that applications have everything they need to run when they migrate through the use of an external configuration server provided by the Spring Cloud project. As an alternative, you may decide to simply run CAS in a standalone mode removing the need for external configuration server deployment, though at the cost of losing features and capabilities relevant for a cloud deployment.

Configuration Profiles

The CAS server web application responds to the following strategies that dictate how settings should be consumed.

Standalone

This is the default configuration mode which indicates that CAS does NOT require connections to an external configuration server and will run in an embedded standalone mode. When this option is turned on, CAS by default will attempt to locate settings and properties inside a given directory indicated under the setting name cas.standalone.config and otherwise falls back to using /etc/cas/config as the configuration directory. You may instruct CAS to use this setting via the methods outlined here.

Similar to the Spring Cloud external configuration server, the contents of this directory include (cas|application).(yml|properties) files that can be used to control CAS behavior. Also note that this configuration directory can be monitored by CAS to auto-pick up changes and refresh the application context as needed. Please review this guide to learn more.

Note that by default, all CAS settings and configuration is controlled via the embedded application.properties file in the CAS server web application. There is also an embedded application.yml file that allows you to override all defaults if you wish to ship the configuration inside the main CAS web application and not rely on externalized configuration files.

Settings found in external configuration files are and will be able to override the defaults provide by CAS. The naming of the configuration files inside the CAS configuration directory follows the below pattern:

• An application.(properties|yml) file is always loaded, if found.
• Settings located inside properties|yml files whose name matches the value of spring.application.name are loaded (i.e cas.properties)
• Settings located inside properties|yml files whose name matches the value of spring.profiles.active are loaded (i.e ldap.properties).
• Profile-specific application properties outside of your packaged web application (application-{profile}.properties|yml) This allows you to, if needed, split your settings into multiple property files and then locate them by assigning their name to the list of active profiles (i.e. spring.profiles.active=standalone,testldap,stagingMfa)

Spring Cloud

CAS is able to use an external and central configuration server to obtain state and settings. The configuration server provides a very abstract way for CAS (and all of its other clients) to obtain settings from a variety of sources, such as file system, git or svn repositories, MongoDb databases, Vault, etc. The beauty of this solution is that to the CAS web application server, it matters not where settings come from and it has no knowledge of the underlying property sources. It simply talks to the configuration server to locate settings and move on.

A full comprehensive guide is provided by the Spring Cloud project.

Overlay

The configuration server itself, similar to CAS, can be deployed via the following module in it own WAR overlay:

1
2
3
4
5
<dependency>
  <groupId>org.apereo.cas</groupId>
  <artifactId>cas-server-webapp-config-server</artifactId>
  <version>${cas.version}</version>
</dependency>

In addition to the strategies outlined here, the configuration server may load CAS settings and properties via the following order and mechanics:

1. Profile-specific application properties outside of your packaged web application (application-{profile}.properties|yml)
2. Profile-specific application properties packaged inside your jar (application-{profile}.properties|yml)
3. Application properties outside of your packaged jar (application.properties|yml).
4. Application properties packaged inside your jar (application.properties|yml).

The configuration and behavior of the configuration server is also controlled by its own src/main/resources/bootstrap.properties file. By default, it runs under port 8888 at /casconfigserver inside an embedded Apache Tomcat server whose endpoints are protected with basic authentication where the default credentials are casuser and Mellon. Furthermore, by default it runs under a native profile described below.

The following endpoints are secured and exposed by the configuration server:

Once you have the configuration server deployed, you can observe the collection of settings via:

1
curl -u casuser:Mellon http://config.server.url:8888/casconfigserver/cas/native

You can also observe the collection of property sources that provide settings to the configuration server:

1
curl -u casuser:Mellon http://localhost:8888/casconfigserver/env

Clients and Consumers

To let the CAS server web application (or any other client for that matter) talk to the configuration server, the following settings need to be applied to CAS’ own src/main/resources/bootstrap.properties file. The properties to configure the CAS server web application as the client of the configuration server must necessarily be read in before the rest of the application’s configuration is read from the configuration server, during the bootstrap phase.

1
2
3
4
spring.cloud.config.uri=http://casuser:Mellon@localhost:8888/casconfigserver
spring.cloud.config.profile=native
spring.cloud.config.enabled=true
spring.profiles.active=default

Remember that configuration server serves property sources from /{name}/{profile}/{label} to applications, where the default bindings in the client app are the following:

1
2
3
"name" = ${spring.application.name}
"profile" = ${spring.profiles.active}
"label" = "master"

All of them can be overridden by setting spring.cloud.config.* (where * is “name”, “profile” or “label”). The “label” is useful for rolling back to previous versions of configuration; with the default Config Server implementation it can be a git label, branch name or commit id. Label can also be provided as a comma-separated list, in which case the items in the list are tried on-by-one until one succeeds. This can be useful when working on a feature branch, for instance, when you might want to align the config label with your branch, but make it optional (e.g. spring.cloud.config.label=myfeature,develop).

To lean more about CAS allows you to reload configuration changes, please review this guide.

Profiles

Various profiles exist to determine how configuration server should retrieve properties and settings.

Native

The server is configured by default to load cas.(properties|yml) files from an external location that is /etc/cas/config. This location is constantly monitored by the server to detect external changes. Note that this location simply needs to exist, and does not require any special permissions or structure. The name of the configuration file that goes inside this directory needs to match the spring.application.name (i.e. cas.properties).

If you want to use additional configuration files, they need to have the form application-<profile>.(properties|yml). A file named application.(properties|yml) will be included by default. The profile specific files can be activated by using the spring.profiles.include configuration option, controlled via the src/main/resources/bootstrap.properties file:

1
2
3
spring.profiles.active=native
spring.cloud.config.server.native.searchLocations=file:///etc/cas/config
spring.profiles.include=profile1,profile2

An example of an external .properties file hosted by an external location follows:

1
cas.server.name=...

You could have just as well used a cas.yml file to host the changes.

Default

The configuration server is also able to handle git or svn based repositories that host CAS configuration. Such repositories can either be local to the deployment, or they could be on the cloud in form of GitHub/BitBucket. Access to cloud-based repositories can either be in form of a username/password, or via SSH so as long the appropriate keys are configured in the CAS deployment environment which is really no different than how one would normally access a git repository via SSH.

1
2
3
4
5
6
7
8
9
10
11
# spring.profiles.active=default
# spring.cloud.config.server.git.uri=https://github.com/repoName/config
# spring.cloud.config.server.git.uri=file://${user.home}/config
# spring.cloud.config.server.git.username=
# spring.cloud.config.server.git.password=

# spring.cloud.config.server.svn.basedir=
# spring.cloud.config.server.svn.uri=
# spring.cloud.config.server.svn.username=
# spring.cloud.config.server.svn.password=
# spring.cloud.config.server.svn.default-label=trunk

Needless to say, the repositories could use both YAML and properties syntax to host configuration files.

MongoDb

The server is also able to locate properties entirely from a MongoDb instance.

Support is provided via the following dependency in the WAR overlay:

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

Note that to access and review the collection of CAS properties, you will need to use the CAS administrative interfaces, or you may also use your own native tooling for MongoDB to configure and inject settings.

MongoDb documents are required to be found in the collection MongoDbProperty, as the following document:

1
2
3
4
5
{
    "id": "kfhf945jegnsd45sdg93452",
    "name": "the-setting-name",
    "value": "the-setting-value"
}

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

HashiCorp Vault

CAS is also able to use Vault to locate properties and settings. Please review this guide.

Apache ZooKeeper

CAS is also able to use Apache ZooKeeper to locate properties and settings.

Support is provided via the following dependency in the WAR overlay:

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

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

You will need to map CAS settings to ZooKeeper’s nodes that contain values. The parent node for all settings should match the configuration root value provided to CAS. Under the root, you could have folders such as cas, cas,dev, cas,local, etc where dev and local are Spring profiles.

To create nodes and values in Apache ZooKeeper, try the following commands as a sample:

1
2
3
4
5
zookeeper-client -server zookeeper1:2181
create /cas cas
create /cas/config cas
create /cas/config/cas cas
create /cas/config/cas/settingName casuser::Test

Creating nodes and directories in Apache ZooKeeper may require providing a value. The above sample commands show that the value cas is provided when creating directories. Always check with the official Apache ZooKeeper guides. You may not need to do that step.

Finally in your CAS properties, the new settingName setting can be used as a reference.

1
cas.something.something=${settingName}

…where ${settingName} gets the value of the contents of the Apache ZooKeeper node cas/config/cas/settingName.

DynamoDb

CAS is also able to use DynamoDb to locate properties and settings.

Support is provided via the following dependency in the WAR overlay:

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

The DynamoDbCasProperties table is automatically created by CAS with the following structure:

1
2
3
4
5
{
    "id": "primary-key",
    "name": "the-setting-name",
    "value": "the-setting-value"
}

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

JDBC

CAS is also able to use a relational database to locate properties and settings.

Support is provided via the following dependency in the WAR overlay:

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

By default, settings are expected to be found under a CAS_SETTINGS_TABLE that contains the fields: id, name and value. To see the relevant list of CAS properties for this feature, please review this guide.

Composite Sources

In some scenarios you may wish to pull configuration data from multiple environment repositories. To do this just enable multiple profiles in your configuration server’s application properties or YAML file. If, for example, you want to pull configuration data from a Git repository as well as a SVN repository you would set the following properties for your configuration server.

1
2
3
4
5
6
7
8
9
10
11
12
spring:
  profiles:
    active: git, svn
  cloud:
    config:
      server:
        svn:
          uri: file:///path/to/svn/repo
          order: 2
        git:
          uri: file:///path/to/git/repo
          order: 1

In addition to each repo specifying a URI, you can also specify an order property. The order property allows you to specify the priority order for all your repositories. The lower the numerical value of the order property the higher priority it will have. The priority order of a repository will help resolve any potential conflicts between repositories that contain values for the same properties.

Property Overrides

The configuration server has an “overrides” feature that allows the operator to provide configuration properties to all applications that cannot be accidentally changed by the application using the normal change events and hooks. To declare overrides add a map of name-value pairs to spring.cloud.config.server.overrides. For example:

1
2
3
4
5
6
spring:
  cloud:
    config:
      server:
        overrides:
          foo: bar

This will cause the CAS server (as the client of the configuration server) to read foo=bar independent of its own configuration.

Securing Settings

To learn how sensitive CAS settings can be secured via encryption, please review this guide.

Reloading Changes

To lean more about CAS allows you to reload configuration changes, please review this guide.

Clustered Deployments

CAS uses the Spring Cloud Bus to manage configuration in a distributed deployment. Spring Cloud Bus links nodes of a distributed system with a lightweight message broker. This can then be used to broadcast state changes (e.g. configuration changes) or other management instructions.

To learn how sensitive CAS settings can be secured via encryption, please review this guide.