APEREO CASDocumentation

Enterprise Authentication for All Earthlings and Beyond

Identity, Single Sign-On and Access Management
View on GitHub

SSO Sessions

The SSO cookie, also known as the ticket-granting cookie (TGC) is an HTTP cookie set by CAS upon the establishment of a single sign-on session. To learn more about this cookie, please visit this guide.

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

cas.sso.mail.attribute-namePrincipal attribute names that indicates the destination email address for this message.
no default
RequiredSpEL

Principal attribute names that indicates the destination email address for this message. The attributes must already be resolved and available to the CAS principal. When multiple attributes are specified, each attribute is then examined against the available CAS principal to locate the email address value, which may result in multiple emails being sent.

Type
List<String>
Default
none
Defined by
EmailProperties
Supports
Spring Expression Language
cas.sso.mail.fromEmail from address.
no default
Required

Email from address.

Type
String
Default
none
Defined by
EmailProperties
cas.sso.mail.subjectEmail subject line.
no default
RequiredSpEL

Email subject line.

The subject can either be defined verbatim, or it may point to a message key in the language bundle using the syntax #{subject-language-key}. This key should point to a valid message defined in the appropriate language bundle that is then picked up via the active locale. In case where the language code cannot resolve the real subject, a default subject value would be used.

Type
String
Default
none
Defined by
EmailProperties
Supports
Spring Expression Language
cas.sso.sms.attribute-namePrincipal attribute names that indicates the destination phone number for this SMS message.
no default
RequiredSpEL

Principal attribute names that indicates the destination phone number for this SMS message. The attribute must already be resolved and available to the CAS principal.

Type
List<String>
Default
none
Defined by
SmsProperties
Supports
Spring Expression Language
cas.sso.sms.fromThe from address for the message.
no default
Required

The from address for the message.

Type
String
Default
none
Defined by
SmsProperties
cas.sso.sms.textThe body of the SMS message.
no default
Required

The body of the SMS message.

Type
String
Default
none
Defined by
SmsProperties
cas.sso.create-sso-cookie-on-renew-authnFlag that indicates whether to create SSO session on re-newed authentication event.
true

Flag that indicates whether to create SSO session on re-newed authentication event.

Type
Boolean
Default
true
Defined by
SingleSignOnProperties
cas.sso.mail.bccEmail BCC address, if any.
no default

Email BCC address, if any.

Type
List<String>
Default
none
Defined by
EmailProperties
cas.sso.mail.ccEmail CC address, if any.
no default

Email CC address, if any.

Type
List<String>
Default
none
Defined by
EmailProperties
cas.sso.mail.htmlIndicate whether the message body should be evaluated as HTML text.
false

Indicate whether the message body should be evaluated as HTML text. The application of this setting depends on the email provider implementation and may not be fully supported everywhere. This is typically relevant for the default org.springframework.mail.javamail.JavaMailSender.

Type
Boolean
Default
false
Defined by
EmailProperties
cas.sso.mail.prioritySet the priority ( X-Priority header) of the message.
1

Set the priority (X-Priority header) of the message. Values: 1 (Highest), 2 (High), 3 (Normal), 4 (Low), 5 (Lowest). The application of this setting depends on the email provider implementation and may not be fully supported everywhere. This is typically relevant for the default org.springframework.mail.javamail.JavaMailSender.

Type
Integer
Default
1
Defined by
EmailProperties
cas.sso.mail.reply-toEmail Reply-To address, if any.
no default

Email Reply-To address, if any.

Type
String
Default
none
Defined by
EmailProperties
cas.sso.mail.textEmail message body.
no default

Email message body. Could be plain text or a reference to an external file that would serve as a template.

If specified as a path to an external file with an extension .gtemplate, then the email message body would be processed using the Groovy template engine. The template engine uses JSP style <% %> script and <%= %> expression syntax or GString style expressions. The variable out is bound to the writer that the template is being written to.

If using plain text, the contents are processed for string substitution candidates using named variables. For example, you may refer to an expected url variable in the email text via ${url}, or use ${token} to locate the token variable. In certain cases, additional parameters are passed to the email body processor that might include authentication and/or principal attributes, the available locale, client http information, etc.

Type
String
Default
none
Defined by
EmailProperties
cas.sso.mail.validate-addressesSet whether to validate all addresses which get passed to this helper.
false

Set whether to validate all addresses which get passed to this helper. The application of this setting depends on the email provider implementation and may not be fully supported everywhere. This is typically relevant for the default org.springframework.mail.javamail.JavaMailSender.

Type
Boolean
Default
false
Defined by
EmailProperties
cas.sso.proxy-authn-enabledIndicates whether CAS proxy authentication/tickets are supported by this server implementation.
true

Indicates whether CAS proxy authentication/tickets are supported by this server implementation.

Type
Boolean
Default
true
Defined by
SingleSignOnProperties
cas.sso.renew-authn-enabledIndicates whether this server implementation should globally support CAS protocol authentication requests that are tagged with "renew=true".
true

Indicates whether this server implementation should globally support CAS protocol authentication requests that are tagged with "renew=true".

Type
Boolean
Default
true
Defined by
SingleSignOnProperties
cas.sso.revocation-attribute-nameAttribute name that represents a Unix epoch value in seconds.
no default

Attribute name that represents a Unix epoch value in seconds. This timestamp signifies the demarcation point such that any authentication attempts that were created prior to that time are treated as revoked and SSO will be ignored. Calculations are based on the UTC timezone. The attribute is only read and never modified/updated by CAS.

Type
String
Default
none
Defined by
SingleSignOnProperties
cas.sso.services.allow-missing-service-parameterFlag that indicates whether to allow SSO session with a missing target service.
true

Flag that indicates whether to allow SSO session with a missing target service.

By default, CAS will present a generic success page if the initial authentication request does not identify the target application. In some cases, the ability to login to CAS without logging in to a particular service may be considered a misfeature because in practice, too few users and institutions are prepared to understand, brand, and support what is at best a fringe use case of logging in to CAS for the sake of establishing an SSO session without logging in to any CAS-reliant service.

Type
Boolean
Default
true
Defined by
SingleSignOnServicesProperties
cas.sso.services.required-service-patternA regular expression pattern that represents an application which must have established a session with CAS already before access to other applications can be allowed by CAS.
no default
Regex

A regular expression pattern that represents an application which must have established a session with CAS already before access to other applications can be allowed by CAS. This is the initial mandatory/required application with which the user must start before going anywhere else. Services that establish a session with CAS typically do so by receiving a service ticket from CAS.

Type
String
Default
none
Defined by
SingleSignOnServicesProperties
cas.sso.sso-enabledIndicate whether single sign-on should be turned on and supported globally for the server.
true

Indicate whether single sign-on should be turned on and supported globally for the server.

Type
Boolean
Default
true
Defined by
SingleSignOnProperties

Required settings may be needed to activate or affect the feature; review them even when they have a default. Optional settings only need to be set to change a default or to turn on the behavior they control. Third party settings belong to libraries such as Spring Boot that CAS builds on; their own documentation may have more detail.

Email servers

The following settings may also need to be defined to describe the mail server settings:

spring.mail.default-encodingDefault MimeMessage encoding.
UTF-8
Third party

Default MimeMessage encoding.

Type
Charset
Default
UTF-8
Defined by
MailProperties
spring.mail.hostSMTP server host.
no default
Third party

SMTP server host. For instance, 'smtp.example.com'.

Type
String
Default
none
Defined by
MailProperties
spring.mail.jndi-nameSession JNDI name.
no default
Third party

Session JNDI name. When set, takes precedence over other Session settings.

Type
String
Default
none
Defined by
MailProperties
spring.mail.passwordLogin password of the SMTP server.
no default
Third party

Login password of the SMTP server.

Type
String
Default
none
Defined by
MailProperties
spring.mail.portSMTP server port.
no default
Third party

SMTP server port.

Type
Integer
Default
none
Defined by
MailProperties
spring.mail.propertiesAdditional JavaMail Session properties.
no default
Third party

Additional JavaMail Session properties.

Type
Map<String,String>
Default
none
Defined by
MailProperties
spring.mail.protocolProtocol used by the SMTP server.
smtp
Third party

Protocol used by the SMTP server.

Type
String
Default
smtp
Defined by
MailProperties
spring.mail.ssl.bundleSSL bundle name.
no default
Third party

SSL bundle name. If set, 'mail.(protocol).ssl.socketFactory' property is set to an SSLSocketFactory obtained from the corresponding SSL bundle.

Note that the STARTTLS command can use the corresponding SSLSocketFactory, even if the 'mail.(protocol).ssl.enable' property is not set.

Type
String
Default
none
Defined by
MailProperties$Ssl
spring.mail.ssl.enabledWhether to enable SSL support.
false
Third party

Whether to enable SSL support. If enabled, 'mail.(protocol).ssl.enable' property is set to 'true'.

Type
Boolean
Default
false
Defined by
MailProperties$Ssl
spring.mail.ssl.verify-hostnameWhether to enable hostname verification.
true
Third party

Whether to enable hostname verification.

Type
Boolean
Default
true
Defined by
MailProperties$Ssl
spring.mail.test-connectionWhether to test that the mail server is available on startup.
false
Third party

Whether to test that the mail server is available on startup.

Type
Boolean
Default
false
Defined by
MailSenderValidatorAutoConfiguration
spring.mail.usernameLogin user of the SMTP server.
no default
Third party

Login user of the SMTP server.

Type
String
Default
none
Defined by
MailProperties
Notes on configuration

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, especially 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.

Remember that the creation of an SSO session is entirely separate and has nothing to do with the authentication protocol used to establish said session. Regardless of the type exchange between the client application and the CAS server, an SSO session will be created, used, maintained and shared between all application types that are integrated with CAS, regardless of their type or requested protocol.

Actuator Endpoints

The following endpoints are provided by CAS:

ssoSessions
CAS endpoint5 operationsNot exposed by defaultcas-server-support-reports
base path /cas/actuator/
sso
CAS endpoint1 operationNot exposed by defaultcas-server-support-reports
1

Include the module that provides these endpoints in the WAR overlay:

Show in CAS Initializr Generate CAS Server WAR Overlay 


1
2
3
4
5



<dependency>
    <groupId>org.apereo.cas</groupId>
    <artifactId>cas-server-support-reports</artifactId>
    <version>${cas.version}</version>
</dependency>





1



implementation "org.apereo.cas:cas-server-support-reports:${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-reports"
}





1
2
3
4
5
6
7
8
9
10



dependencies {
    /*
        The following platform references are included automatically and are listed for reference only.

        implementation enforcedPlatform("org.apereo.cas:cas-server-support-bom:${project.'cas.version'}")
        implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)
        
    */
    implementation "org.apereo.cas:cas-server-support-reports"
}
2

Turn the endpoints on and expose them over the web. One entry covers every operation. By default only info, health and status are exposed.



1
2
3



management.endpoint.ssoSessions.access=UNRESTRICTED
management.endpoint.sso.access=UNRESTRICTED
management.endpoints.web.exposure.include=ssoSessions,sso

Endpoints may be mapped to other paths. For example, to serve health at healthcheck:



1



management.endpoints.web.path-mapping.health=healthcheck