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 attributets 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.

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. To learn more and see the relevant list of CAS properties, please review this guide.

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.

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

Return All

Return all resolved principal attributes to the service.

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.ReturnAllAttributeReleasePolicy"
  }
}

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 configuration.

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

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"
    }
  }
}

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
14
{
  "@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",
      "uid" : "groovy { return attributes['uid'] + ' 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
14
{
  "@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",
      "uid" : "file:/etc/cas/uid-for-sample-service.groovy"
    }
  }
}

Groovy Script

Let an external Groovy script decide how principal attributes should be released.

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

Javascript/Python/Groovy Script

Let an external javascript, groovy or python script decide how principal attributes should be released. This approach takes advantage of scripting functionality built into the Java platform. While Javascript and Groovy should be natively supported by CAS, Python scripts may need to massage the CAS configuration to include the Python modules.

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

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.

The script itself may be designed in Groovy as:

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

class SampleGroovyPersonAttributeDao {
    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"]
    }
}

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
11
{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "sample",
  "name" : "sample",
  "id" : 300,
  "description" : "sample",
  "attributeReleasePolicy" : {
    "@class" : "org.apereo.cas.services.ScriptedRegisteredServiceAttributeReleasePolicy",
    "scriptFile" : "groovy { return attributes }"
  }
}

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
{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "sample",
  "name" : "sample",
  "id" : 300,
  "attributeReleasePolicy": {
    "@class": "org.apereo.cas.services.ChainingAttributeReleasePolicy",
    "policies": [ "java.util.ArrayList",
      [
          {"@class": "..."},
          {"@class": "..."}
      ]
    ]
  }
}

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.