Surrogate Authentication

Surrogate authentication (impersonation), sometimes known as sudo for the web, is the ability to authenticate on behalf of another user.

The two actors in this case are:

  1. The primary admin user whose credentials are verified upon authentication.
  2. The surrogate user, selected by the admin, to which CAS will switch after credential verification and is one that is linked to the single sign-on session.

Example use cases for impersonation include:

  1. Logging into an application on behalf of a user to execute and make changes.
  2. Troubleshoot a bothersome authentication experience with an application on behalf of another user.

Surrogate authentication is enabled by including the following dependencies in the WAR overlay:

1
2
3
4
5

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

1

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

1
2
3
4
5
6
7
8
9
10

dependencies {
    /*
    The following platform references should be included automatically and are listed here 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-surrogate-webflow"
}

Account Storage

The following account stores may be configured and used to locate surrogates authorized for a particular user.

Storage Description
Simple See this guide.
JSON See this guide.
LDAP See this guide.
JDBC See this guide.
REST See this guide.
Groovy See this guide.
Custom See this guide.

Note that multiple account stores may be combined and can function simultaneously together to locate accounts from different stores.

Account Selection

Please see this guide.

Session Expiration

Please see this guide.

Surrogate Attributes

Upon a successful surrogate authentication event, the following attributes are communicated back to the application in order to detect an impersonation session:

Attribute Instructions
surrogateEnabled Boolean to indicate whether session is impersonated.
surrogatePrincipal The admin user whose credentials are validated and acts as the impersonator.
surrogateUser The surrogate user that is impersonated.

Surrogate Access Strategy

Please see this guide.

Surrogate Audits

Please see this guide.

Surrogate Principal Resolution

Please see this guide.

REST Protocol

The feature extends the CAS REST API communication model to surrogate authentication, allowing REST credentials to specify a substitute and authenticate on behalf of another user. To activate surrogate authentication for the CAS REST API, you will need to choose one of the following options:

  • Format the credential username using the following syntax:
1

[surrogate-userid][separator][primary-userid]
  • Pass along a special request header X-Surrogate-Principal that contains the surrogate userid.