SSO Sessions

A ticket-granting cookie is an HTTP cookie set by CAS upon the establishment of a single sign-on session. This cookie maintains login state for the client, and while it is valid, the client can present it to CAS in lieu of primary credentials. Services can opt out of single sign-on through the renew parameter or the CAS server may conditionally opt the service out based on the policies defined for the application in the service registry. See the CAS Protocol for more info.

The cookie value is linked to the active ticket-granting ticket, the remote IP address that initiated the request as well as the user agent that submitted the request. The final cookie value is then encrypted and signed.

These keys MUST be regenerated per your specific environment. Each key is a JSON Web Token with a defined length per the algorithm used for encryption and signing.

In the event that keys are not generated by the deployer, CAS will attempt to auto-generate keys and will output the result for each respected key. The deployer MUST attempt to copy the generated keys over to the appropriate settings in their CAS properties file, specially when running a multi-node CAS deployment. Failure to do so will prevent CAS to appropriate decrypt and encrypt the cookie value and will prevent successful single sign-on.

SSO Sessions

It is possible to review the current collection of active SSO sessions, and determine if CAS itself maintains an active SSO session via the CAS administration panels.

Administrative Endpoints

The following endpoints are provided by CAS:

Endpoint Description
ssoSessions Review the current single sign-on sessions established with CAS and manage each session remotely. A GET operation produces a list of current SSO sessions that are filtered by a provided type parameter with values ALL, PROXIED or DIRECT. A DELETE operation without specifying a ticket id will attempt to destroy all SSO sessions. Specifying a ticket-granting ticket identifier in the URL as a placeholder/selector will attempt to destroy the session controlled by that ticket. (i.e. ssoSessions/{ticket}).
sso Indicate the current status of the single sign-on session tied to the browser session and the SSO cookie.

Configuration

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

The cookie has the following properties:

  1. It is marked as secure.
  2. Depending on container support, the cookie would be marked as http-only automatically.
  3. The cookie value is encrypted and signed via secret keys that need to be generated upon deployment.

If keys are left undefined, on startup CAS will notice that no keys are defined and it will appropriately generate keys for you automatically. Your CAS logs will then show the following snippet:

1
2
3
4
WARN [...] - <Secret key for encryption is not defined. CAS will auto-generate the encryption key>
WARN [...] - <Generated encryption key ABC of size ... . The generated key MUST be added to CAS settings.>
WARN [...] - <Secret key for signing is not defined. CAS will auto-generate the signing key>
WARN [...] - <Generated signing key XYZ of size ... . The generated key MUST be added to CAS settings.>

You should then grab each generated key for encryption and signing, and put them inside your CAS properties for each setting. If you wish you manually generate keys, you may use the following tool.

By default, forced authentication requests that challenge the user for credentials either via the renew request parameter or via the service-specific setting of the CAS service registry will always generate the ticket-granting cookie nonetheless. What this means is, logging in to a non-SSO-participating application via CAS nonetheless creates a valid CAS single sign-on session that will be honored on a subsequent attempt to authenticate to a SSO-participating application.

Plausibly, a CAS adopter may want this behavior to be different, such that logging in to a non-SSO-participating application via CAS either does not create a CAS SSO session and the SSO session it creates is not honored for authenticating subsequently to an SSO-participating application. This might better match user expectations. This behavior can be altered either globally via CAS settings or on a per-service basis.

1
2
3
4
5
6
7
8
9
10
11
{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "...",
  "name" : "...",
  "id" : 1,
  "singleSignOnParticipationPolicy":
    {
      "@class": "org.apereo.cas.services.DefaultRegisteredServiceSingleSignOnParticipationPolicy",
      "createCookieOnRenewedAuthentication": "TRUE"
    }
}

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

Disable Service SSO Access

Participation in existing single signon sessions can be disabled on a per applications. For example, the following service will be challenged to present credentials every time, thereby not using SSO:

1
2
3
4
5
6
7
8
9
10
{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "...",
  "name" : "...",
  "id" : 1,
  "accessStrategy" : {
    "@class" : "org.apereo.cas.services.DefaultRegisteredServiceAccessStrategy",
    "ssoEnabled" : false
  }
}

SSO Participation Policies

Additional policies can be assigned to each service definition to control participation of an application in an existing single sign-on session. If conditions hold true, CAS shall honor the existing SSO session and will not challenge the user for credentials. If conditions fail, then user may be asked for credentials. Such policies can be chained together and executed in order.

Authentication Date

Honor the existing single sign-on session, if any, if the authentication date is at most 5 seconds old. Otherwise, challenge the user for credentials and ignore the existing session.

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" : "...",
  "name" : "...",
  "id" : 1,
  "singleSignOnParticipationPolicy":
    {
      "@class": "org.apereo.cas.services.ChainingRegisteredServiceSingleSignOnParticipationPolicy",
      "policies": [
        "java.util.ArrayList",
        [
          {
            "@class": "org.apereo.cas.services.AuthenticationDateRegisteredServiceSingleSignOnParticipationPolicy",
            "timeUnit": "SECONDS",
            "timeValue": 5,
            "order": 0
          }
        ]
      ]
    }
}

Last Used Time

Honor the existing single sign-on session, if any, if the last time an SSO session was used is at most 5 seconds old. Otherwise, challenge the user for credentials and ignore the existing session.

The policy calculation here typically includes evaluating the last-used-time of the ticket-granting ticket linked to the SSO session to check whether the ticket continues to actively issue service tickets, etc.

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" : "...",
  "name" : "...",
  "id" : 1,
  "singleSignOnParticipationPolicy":
    {
      "@class": "org.apereo.cas.services.ChainingRegisteredServiceSingleSignOnParticipationPolicy",
      "policies": [
        "java.util.ArrayList",
        [
          {
            "@class": "org.apereo.cas.services.LastUsedTimeRegisteredServiceSingleSignOnParticipationPolicy",
            "timeUnit": "SECONDS",
            "timeValue": 5,
            "order": 0
          }
        ]
      ]
    }
}

SSO Warning Session Cookie

A warning cookie set by CAS upon the establishment of the SSO session at the request of the user on the CAS login page. The cookie is used later to warn and prompt the user before a service ticket is generated and access to the service application is granted.

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

“I am at a public workstation” authentication

CAS has the ability to allow the user to opt-out of SSO, by indicating on the login page that the authentication is happening at a public workstation. By electing to do so, CAS will not honor the subsequent SSO session and will not generate the TGC that is designed to do so.

1
2
3
4
5
6
7
...
<input id="publicWorkstation"
       name="publicWorkstation"
       value="false" tabindex="4"
       type="checkbox" />
<label for="publicWorkstation" th:utext="#{screen.welcome.label.publicstation}"/>
...

Default Service

In the event that no service is submitted to CAS, you may specify a default service url to which CAS will redirect. Note that this default service, much like all other services, MUST be authorized and registered with CAS.

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

Required Service

CAS may be configured to require the user to authenticate from an application before access can be granted to all other registered services. Once CAS find a record for the required application as part of the single sign-on session records, it will permit authentication attempts by all other services until the single sign-on session is destroyed.

Such validation checks can be turned off and skipped on a per-application basis:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "@class": "org.apereo.cas.services.RegexRegisteredService",
  "serviceId": "^https://www.example.com",
  "name": "Example",
  "id": 1,
  "description": "Example",
  "properties" : {
    "@class" : "java.util.HashMap",
    "skipRequiredServiceCheck" : {
      "@class" : "org.apereo.cas.services.DefaultRegisteredServiceProperty",
      "values" : [ "java.util.HashSet", [ "true" ] ]
    }
  }
}

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