Attribute Release Policies

The attribute release policy decides how attributes are selected and provided to a given application in the final CAS response. Additionally, each policy has the ability to apply an optional filter to weed out their attributes based on their values.

The following settings are shared by all attribute release policies:

CAS makes a distinction between attributes that convey metadata about the authentication event versus those that contain personally identifiable data for the authenticated principal.

Actuator Endpoints

The following endpoints are provided by CAS:

Authentication Attributes

During the authentication process, a number of attributes get captured and collected by CAS to describe metadata and additional properties about the nature of the authentication event itself. These typically include attributes that are documented and classified by the underlying protocol or attributes that are specific to CAS which may describe the type of credentials used, successfully-executed authentication handlers, date/time of the authentication, etc.

Releasing authentication attributes to service providers and applications can be controlled to some extent.

The following settings and properties are available from the CAS configuration catalog:

• Required
• Optional
• Signing & Encryption
• Hibernate & JDBC
• Email Servers
• LDAP & Active Directory
• Authentication
• Password Encoding
• Principal Transformation
• Password Policy
• Notes

Protocol/authentication attributes may also be released conditionally on a per-service basis.

Principal Attributes

Principal attributes typically convey personally identifiable data about the authenticated user, such as address, last name, etc. Release policies are available in CAS and documented below to explicitly control the collection of attributes that may be authorized for release to a given application.

Default

CAS provides the ability to release a bundle of principal attributes to all services by default. This bundle is not defined on a per-service basis and is always combined with attributes produced by the specific release policy of the service, such that for instance, you can devise rules to always release givenName and cn to every application, and additionally allow other specific principal attributes for only some applications per their attribute release policy.

The following settings and properties are available from the CAS configuration catalog:

• Required
• Optional
• Signing & Encryption
• Hibernate & JDBC
• Email Servers
• LDAP & Active Directory
• Authentication
• Password Encoding
• Principal Transformation
• Password Policy
• Notes

Return All

Return all resolved principal attributes to the service, and optionally exclude attributes from the final collection.

1
2
3
4
5
6
7
8
9
10
{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "sample",
  "name" : "sample",
  "id" : 100,
  "attributeReleasePolicy" : {
    "@class" : "org.apereo.cas.services.ReturnAllAttributeReleasePolicy",
    "excludedAttributes": ["java.util.LinkedHashSet", ["cn"]]
  }
}

Deny All

Never ever return principal attributes to applications. Note that this policy also skips and refuses to release default attributes, if any.

1
2
3
4
5
6
7
8
9
10
{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "sample",
  "name" : "sample",
  "id" : 100,
  "description" : "sample",
  "attributeReleasePolicy" : {
    "@class" : "org.apereo.cas.services.DenyAllAttributeReleasePolicy"
  }
}

Return Allowed

Only return the principal attributes that are explicitly allowed by the service definition.

1
2
3
4
5
6
7
8
9
10
{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "sample",
  "name" : "sample",
  "id" : 100,
  "attributeReleasePolicy" : {
    "@class" : "org.apereo.cas.services.ReturnAllowedAttributeReleasePolicy",
    "allowedAttributes" : [ "java.util.ArrayList", [ "cn", "mail", "sn" ] ]
  }
}

Attributes authorized and allowed for release by this policy may not necessarily be available as resolved principal attributes and can be resolved on the fly dynamically using the attribute definition store.

Return Encrypted

Encrypt and encode all all allowed attributes in base-64 using the assigned registered service public key.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "sample",
  "name" : "sample",
  "id" : 100,
  "attributeReleasePolicy" : {
    "@class" : "org.apereo.cas.services.ReturnEncryptedAttributeReleasePolicy",
    "allowedAttributes" : [ "java.util.ArrayList", [ "cn", "mail", "sn" ] ]
  },
  "publicKey" : {
    "@class" : "org.apereo.cas.services.RegisteredServicePublicKeyImpl",
    "location" : "classpath:public.key",
    "algorithm" : "RSA"
  }
}

The keys can be generated via the following commands:

1
2
3
openssl genrsa -out private.key 1024
openssl rsa -pubout -in private.key -out public.key -inform PEM -outform DER
openssl pkcs8 -topk8 -inform PER -outform DER -nocrypt -in private.key -out private.p8

Attributes authorized and allowed for release by this policy may not necessarily be available as resolved principal attributes and can be resolved on the fly dynamically using the attribute definition store.

REST

Only return the principal attributes that are explicitly allowed by contacting a REST endpoint. Endpoints must be designed to accept/process application/json. The expected response status code is 200 where the body of the response includes a Map of attributes linked to their values.

1
2
3
4
5
6
7
8
9
10
{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "sample",
  "name" : "sample",
  "id" : 100,
  "attributeReleasePolicy" : {
    "@class" : "org.apereo.cas.services.ReturnRestfulAttributeReleasePolicy",
    "endpoint" : "https://somewhere.example.org"
  }
}

The following parameters are passed to the endpoint:

The body of the submitted request may also include a Map of currently resolved attributes.

Return Mapped

Similar to above, this policy will return a collection of allowed principal attributes for the service, but also allows those principal attributes to be mapped and “renamed” at the more granular service level.

For example, the following configuration will recognize the resolved attributes eduPersonAffiliation and groupMembership and will then release affiliation and group to the web application configured.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "sample",
  "name" : "sample",
  "id" : 300,
  "description" : "sample",
  "attributeReleasePolicy" : {
    "@class" : "org.apereo.cas.services.ReturnMappedAttributeReleasePolicy",
    "allowedAttributes" : {
      "@class" : "java.util.TreeMap",
      "eduPersonAffiliation" : "affiliation",
      "groupMembership" : "group"
    }
  }
}

Attributes authorized and allowed for release by this policy may not necessarily be available as resolved principal attributes and can be resolved on the fly dynamically using the attribute definition store.

Return MultiMapped

The same policy may allow attribute definitions to be renamed and remapped to multiple attribute names, with duplicate attributes values mapped to different names.

For example, the following configuration will recognize the resolved attribute eduPersonAffiliation and will then release affiliation and personAffiliation whose values stem from the original eduPersonAffiliation attribute while groupMembership is released as group. In other words, the eduPersonAffiliation attribute is released twice under two different names each sharing the same value.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "sample",
  "name" : "sample",
  "id" : 300,
  "attributeReleasePolicy" : {
    "@class" : "org.apereo.cas.services.ReturnMappedAttributeReleasePolicy",
    "allowedAttributes" : {
      "@class" : "java.util.TreeMap",
      "eduPersonAffiliation" : [ "java.util.ArrayList", [ "affiliation", "personAffiliation" ] ],
      "groupMembership" : "group"
    }
  }
}

Attributes authorized and allowed for release by this policy may not necessarily be available as resolved principal attributes and can be resolved on the fly dynamically using the attribute definition store.

Inline Groovy Attributes

Principal attributes that are mapped may produce their values from an inline groovy script. As an example, if you currently have resolved a uid attribute with a value of piper, you could then consider the following:

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "sample",
  "name" : "sample",
  "id" : 300,
  "attributeReleasePolicy" : {
    "@class" : "org.apereo.cas.services.ReturnMappedAttributeReleasePolicy",
    "allowedAttributes" : {
      "@class" : "java.util.TreeMap",
      "uid" : "groovy { return attributes['uid'].get(0) + ' is great' }"
    }
  }
}

In the above snippet, the value of the uid attribute name is mapped to the result of the inline groovy script. Inline scripts always begin with the syntax groovy {...} and are passed the current collection of resolved attributes as an attributes binding variable. The result of the script can be a single/collection of value(s).

The above configuration will produce a uid attribute for the application whose value is a concatenation of the original value of uid plus the words “ is great”, so the final result would be “piper is great”.

File-based Groovy Attributes

Identical to inline groovy attribute definitions, except the groovy script can also be externalized to a .groovy file:

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "sample",
  "name" : "sample",
  "id" : 300,
  "attributeReleasePolicy" : {
    "@class" : "org.apereo.cas.services.ReturnMappedAttributeReleasePolicy",
    "allowedAttributes" : {
      "@class" : "java.util.TreeMap",
      "uid" : "file:/etc/cas/sample.groovy"
    }
  }
}

The sample.groovy script itself may have the following outline:

1
2
3
4
5
6
7
8
import java.util.*

def run(final Object... args) {
    def attributes = args[0]
    def logger = args[1]
    logger.debug("Current attributes are {}", attributes)
    return []
}

The configuration of this component qualifies to use the Spring Expression Language syntax.

Groovy Script

Let an external Groovy script decide how principal attributes should be released. The configuration of this component qualifies to use the Spring Expression Language syntax.

1
2
3
4
5
6
7
8
9
10
{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "sample",
  "name" : "sample",
  "id" : 300,
  "attributeReleasePolicy" : {
    "@class" : "org.apereo.cas.services.GroovyScriptAttributeReleasePolicy",
    "groovyScript" : "classpath:/script.groovy"
  }
}

The script itself may be designed in Groovy as:

1
2
3
4
5
6
7
8
9
10
11
import java.util.*

def Map<String, List<Object>> run(final Object... args) {
    def currentAttributes = args[0]
    def logger = args[1]
    def principal = args[2]
    def service = args[3]

    logger.debug("Current attributes received are {}", currentAttributes)
    return [username:["something"], likes:["cheese", "food"], id:[1234,2,3,4,5], another:"attribute"]
}

The following parameters are passed to the script:

Script Engines

Use alternative script engine implementations and other programming languages to configure attribute release policies. This approach takes advantage of scripting functionality built into the Java platform via additional libraries and drivers. While Groovy should be natively supported by CAS, the following module is required in the overlay to include support for additional languages such as Python, etc.

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

1
implementation "org.apereo.cas:cas-server-support-script-engines:${project.'cas.version'}"

1
2
3
4
5
6
7
8
9
dependencyManagement {
  imports {
    mavenBom "org.apereo.cas:cas-server-support-bom:${project.'cas.version'}"
  }
}

dependencies {  
  implementation "org.apereo.cas:cas-server-support-script-engines"
}

The service definition then may be designed as:

1
2
3
4
5
6
7
8
9
10
{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "sample",
  "name" : "sample",
  "id" : 300,
  "attributeReleasePolicy" : {
    "@class" : "org.apereo.cas.services.ScriptedRegisteredServiceAttributeReleasePolicy",
    "scriptFile" : "classpath:/script.[py|js|groovy]"
  }
}

The configuration of this component qualifies to use the Spring Expression Language syntax. The scripts need to design a run function that receives a list of parameters. The collection of current attributes in process as well as a logger object are passed to this function. The result must produce a map whose keys are attributes names and whose values are a list of attribute values.

As an example, the script itself may be designed in Groovy as:

1
2
3
4
5
6
7
8
9
import java.util.*

def Map<String, List<Object>> run(final Object... args) {
    def currentAttributes = args[0]
    def logger = args[1]

    logger.debug("Current attributes received are {}", currentAttributes)
    return[username:["something"], likes:["cheese", "food"], id:[1234,2,3,4,5], another:"attribute"]
}

Here’s the same script written in Python:

1
2
3
4
5
def run(*Params):
  Attributes = Params[0]
  Logger = Params[1]
  # Calculate attributes and return a new dictionary of attributes...
  return ...

You are also allowed to stuff inlined groovy scripts into the scriptFile attribute. The script has access to the collection of resolved attributes as well as a logger object.

1
2
3
4
5
6
7
8
9
10
{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "sample",
  "name" : "sample",
  "id" : 300,
  "attributeReleasePolicy" : {
    "@class" : "org.apereo.cas.services.ScriptedRegisteredServiceAttributeReleasePolicy",
    "scriptFile" : "groovy { return attributes }"
  }
}

Attribute Repository Filtering

Attribute release policies can be assigned a principalAttributesRepository to consult attribute sources defined and controlled by Person Directory attribute repositories to fetch, resolve, cache and release attributes. To learn more about this topic, please see this guide.

Chaining Policies

Attribute release policies can be chained together to process multiple rules. The order of policy invocation is the same as the definition order defined for the service itself.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "sample",
  "name" : "sample",
  "id" : 300,
  "attributeReleasePolicy": {
    "@class": "org.apereo.cas.services.ChainingAttributeReleasePolicy",
    "mergingPolicy": "replace",
    "policies": [ "java.util.ArrayList",
      [
          {"@class": "..."},
          {"@class": "..."}
      ]
    ]
  }
}

The following merging policies are supported:

Ordering Policies

Note that each policy in the chain can be assigned a numeric order that would determine its position in the chain before execution. This order may be important if you have attribute release policies that should calculate a value dynamically first before passing it onto the next policy in the chain.

For example, the policy chain below allows CAS to generate an attribute first using the GeneratesFancyAttributeReleasePolicy policy where the attribute is next passed onto the next policy in the chain, that is ReleaseFancyAttributeReleasePolicy, to decide whether or not the attribute should be released. Note the configuration of policy order determines the execution sequence.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "sample",
  "name" : "sample",
  "id" : 300,
  "attributeReleasePolicy": {
    "@class": "org.apereo.cas.services.ChainingAttributeReleasePolicy",
    "policies": [ "java.util.ArrayList",
      [
          {
            "@class": "org.apereo.cas.ReleaseFancyAttributeReleasePolicy",
            "order": 1
          },
          {
            "@class": "org.apereo.cas.GeneratesFancyAttributeReleasePolicy", 
            "order": 0
          }
      ]
    ]
  }
}

Attribute Value Filters

While each policy defines what principal attributes may be allowed for a given service, there are optional attribute filters that can be set per policy to further weed out attributes based on their values.

See this guide to learn more.