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:

Name Value
authorizedToReleaseCredentialPassword Boolean to define whether the service is authorized to release the credential as an attribute.
authorizedToReleaseProxyGrantingTicket Boolean to define whether the service is authorized to release the proxy-granting ticket id as an attribute.
excludeDefaultAttributes Boolean to define whether this policy should exclude the default global bundle of attributes for release.
authorizedToReleaseAuthenticationAttributes Boolean to define whether this policy should exclude the authentication/protocol attributes for release. Authentication attributes are considered those that are not tied to a specific principal and define extra supplementary metadata about the authentication event itself, such as the commencement date.
principalIdAttribute An attribute name of your own choosing that will be stuffed into the final bundle of attributes, carrying the CAS authenticated principal identifier.
canonicalizationMode Transform all attribute values to uppercase or lowercase. Allowed values are UPPER, LOWER or NONE.
:warning: Usage Warning!

Think VERY CAREFULLY before turning on the above settings. Blindly authorizing an application to receive a proxy-granting ticket or the user credential may produce an opportunity for security leaks and attacks. Make sure you actually need to enable those features and that you understand the why. Avoid where and when you can, specially when it comes to sharing the user credential.

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:

 Get collection of released attributes for the user and application.

 Get collection of released attributes for the user and application.


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:

The configuration settings listed below are tagged as Required in the CAS configuration metadata. This flag indicates that the presence of the setting may be needed to activate or affect the behavior of the CAS feature and generally should be reviewed, possibly owned and adjusted. If the setting is assigned a default value, you do not need to strictly put the setting in your copy of the configuration, but should review it nonetheless to make sure it matches your deployment expectations.

The configuration settings listed below are tagged as Optional in the CAS configuration metadata. This flag indicates that the presence of the setting is not immediately necessary in the end-user CAS configuration, because a default value is assigned or the activation of the feature is not conditionally controlled by the setting value. In other words, you should only include this field in your configuration if you need to modify the default value or if you need to turn on the feature controlled by the setting.

  • cas.authn.authentication-attribute-release.enabled=true

    • Whether authentication or protocol attributes should be released to clients. This flag specifically address non-principal attributes, or otherwise attributes that carry metadata about the authentication event itself that are not strictly tied to a principal or person data. The change here should consider such attributes regardless of the specific protocol or authentication flow (CAS, OIDC, etc).

    org.apereo.cas.configuration.model.core.authentication.AuthenticationAttributeReleaseProperties.

    How can I configure this property?

  • cas.authn.authentication-attribute-release.never-release=

    • List of authentication attributes that should never be released.

    org.apereo.cas.configuration.model.core.authentication.AuthenticationAttributeReleaseProperties.

    How can I configure this property?

  • cas.authn.authentication-attribute-release.only-release=

    • List of authentication attributes that should be the only ones released. An empty list indicates all attributes should be released.

    org.apereo.cas.configuration.model.core.authentication.AuthenticationAttributeReleaseProperties.

    How can I configure this property?

    Configuration Metadata

    The collection of configuration properties listed in this section are automatically generated from the CAS source and components that contain the actual field definitions, types, descriptions, modules, etc. This metadata may not always be 100% accurate, or could be lacking details and sufficient explanations.

    Be Selective

    This section is meant as a guide only. Do NOT copy/paste the entire collection of settings into your CAS configuration; rather pick only the properties that you need. Do NOT enable settings unless you are certain of their purpose and do NOT copy settings into your configuration only to keep them as reference. All these ideas lead to upgrade headaches, maintenance nightmares and premature aging.

    YAGNI

    Note that for nearly ALL use cases, declaring and configuring properties listed here is sufficient. You should NOT have to explicitly massage a CAS XML/Java/etc configuration file to design an authentication handler, create attribute release policies, etc. CAS at runtime will auto-configure all required changes for you. If you are unsure about the meaning of a given CAS setting, do NOT turn it on without hesitation. Review the codebase or better yet, ask questions to clarify the intended behavior.

    Naming Convention

    Property names can be specified in very relaxed terms. For instance cas.someProperty, cas.some-property, cas.some_property are all valid names. While all forms are accepted by CAS, there are certain components (in CAS and other frameworks used) whose activation at runtime is conditional on a property value, where this property is required to have been specified in CAS configuration using kebab case. This is both true for properties that are owned by CAS as well as those that might be presented to the system via an external library or framework such as Spring Boot, etc.

    :information_source: Note

    When possible, properties should be stored in lower-case kebab format, such as cas.property-name=value. The only possible exception to this rule is when naming actuator endpoints; The name of the actuator endpoints (i.e. ssoSessions) MUST remain in camelCase mode.

    Settings and properties that are controlled by the CAS platform directly always begin with the prefix cas. All other settings are controlled and provided to CAS via other underlying frameworks and may have their own schemas and syntax. BE CAREFUL with the distinction. Unrecognized properties are rejected by CAS and/or frameworks upon which CAS depends. This means if you somehow misspell a property definition or fail to adhere to the dot-notation syntax and such, your setting is entirely refused by CAS and likely the feature it controls will never be activated in the way you intend.

    Validation

    Configuration properties are automatically validated on CAS startup to report issues with configuration binding, specially if defined CAS settings cannot be recognized or validated by the configuration schema. Additional validation processes are also handled via Configuration Metadata and property migrations applied automatically on startup by Spring Boot and family.

    Indexed Settings

    CAS settings able to accept multiple values are typically documented with an index, such as cas.some.setting[0]=value. The index [0] is meant to be incremented by the adopter to allow for distinct multiple configuration blocks.

    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.

    :information_source: Remember

    Depending on the protocol used and the type/class of service (i.e. relying party) registered with CAS, additional release policies may become available that allow more fine-tuned control over attribute release, catering better to the needs of the particular authentication protocol at hand. Remember to verify attribute release capabilities of CAS by visiting and studies the appropriate documentation for each protocol.

    Policy Resource
    Default Bundle See this page.
    Deny All See this page.
    Return All See this page.
    Return Static See this page.
    Return Allowed See this page.
    Return Encrypted See this page.
    Return Mapped See this page.
    Return Linked See this page.
    Mapped Groovy File See this page.
    Mapped Inline Groovy See this page.
    Return MultiMapped See this page.
    Pattern Matching See this page.
    Groovy Script See this page.
    REST See this page.

    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. See this guide to learn more.

    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.