YAML Service Registry

This registry reads services definitions from YAML configuration files at the application context initialization time. YAML files are expected to be found inside a configured directory location and this registry will recursively look through the directory structure to find relevant files.

Support is enabled by adding the following module into the Maven overlay:

1
2
3
4
5
<dependency>
    <groupId>org.apereo.cas</groupId>
    <artifactId>cas-server-support-yaml-service-registry</artifactId>
    <version>${cas.version}</version>
</dependency>

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

A sample YAML file follows:

1
2
3
4
5
6
7
8
9
--- !<org.apereo.cas.services.RegexRegisteredService>
serviceId: "testId"
name: "YAML"
id: 1000
description: "description"
attributeReleasePolicy: !<org.apereo.cas.services.ReturnAllAttributeReleasePolicy>
accessStrategy: !<org.apereo.cas.services.DefaultRegisteredServiceAccessStrategy>
  enabled: true
  ssoEnabled: true
Clustering Services

You MUST consider that if your CAS server deployment is clustered, each CAS node in the cluster must have access to the same set of configuration files as the other, or you may have to devise a strategy to keep changes synchronized from one node to the next.

The service registry is also able to auto detect changes to the specified directory. It will monitor changes to recognize file additions, removals and updates and will auto-refresh CAS so changes do happen instantly.

Escaping Characters

Please make sure all field values in the blob are correctly escaped, specially for the service id. If the service is defined as a regular expression, certain regex constructs such as "." and "\d" need to be doubly escaped.

The naming convention for new files is recommended to be the following:

1
YAML fileName = serviceName + "-" + serviceNumericId + ".yml"

Remember that because files are created based on the serviceName, you will need to make sure characters considered invalid for file names are not used as part of the name.

Duplicate Services

As you add more files to the directory, you need to be absolutely sure that no two service definitions will have the same id. If this happens, loading one definition will stop loading the other. While service ids can be chosen arbitrarily, make sure all service numeric identifiers are unique. CAS will also output warnings if duplicate data is found.