APEREO CASDocumentation

Enterprise Authentication for All Earthlings and Beyond

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

Quick Start

This recipe takes you from nothing to a working CAS server on your own machine: run it, configure it, register an application and log in. It is meant for learning and evaluation; Getting Started explains how to plan a real deployment.

:information_source: Settings Are Links

Click any setting on this page, such as cas.server.name, to see its description, default value, module and other formats right here, without leaving the page. Press ShiftShift anywhere in the documentation to search all settings.

1. Try It With Docker

If you only want to see CAS running, start the official image. Replace ${tag} with a CAS version listed on Docker Hub:



1
2
3



docker run --rm -p 8080:8080 \
  -e SERVER_SSL_ENABLED=false -e SERVER_PORT=8080 \
  apereo/cas:${tag}

Open http://localhost:8080/cas/login and log in as casuser with the password Mellon. The two variables are server.ssl.enabled and server.port written as environment variables; every setting can be passed this way. See Docker Installation for more.

2. Create an Overlay

A real deployment is built from a WAR overlay: a small Gradle project that pulls in CAS and holds only what you add or change. With a JDK installed (see Installation Requirements), generate one:



1
2



curl https://getcas.apereo.org/starter.tgz -d type=cas-overlay -d baseDir=cas | tar -xzvf -
cd cas

The CAS Initializr can also select the CAS version and modules for you.

3. Configure CAS

CAS reads its settings from /etc/cas/config/cas.properties; the directory can be changed with cas.standalone.configuration-directory. Create the directories once, owned by the account that runs CAS, and then the file:



1
2



sudo mkdir -p /etc/cas/config /etc/cas/services
sudo chown -R "$USER" /etc/cas





1
2
3
4



cas.server.name=http://localhost:8080
cas.server.prefix=${cas.server.name}/cas
server.port=8080
server.ssl.enabled=false

cas.server.name is the address users reach CAS at, and cas.server.prefix adds the /cas context path. Plain HTTP is only for trying CAS locally; a deployment must use HTTPS.

4. Register an Application

CAS only issues tickets to applications it knows. Add the JSON service registry to the dependencies block of build.gradle:

Show in CAS Initializr Generate CAS Server WAR Overlay 


1
2
3
4
5



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





1



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





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-json-service-registry"
}

Point it at the services directory in cas.properties:



1



cas.service-registry.json.location=file:/etc/cas/services

Then describe the application in /etc/cas/services/Example-1.json. The serviceId is a regular expression matched against the address the application sends to CAS:



1
2
3
4
5
6



{
  "@class": "org.apereo.cas.services.CasRegisteredService",
  "serviceId": "^https://app.example.org/.*",
  "name": "Example",
  "id": 1
}

See JSON Service Registry for file naming and reloading, and Service Management for the policies an application can carry.

5. Connect Your Directory

This step is optional. Out of the box, CAS accepts the single account set in cas.authn.accept.users. To log in with LDAP accounts instead, add the LDAP module:

Show in CAS Initializr Generate CAS Server WAR Overlay 


1
2
3
4
5



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





1



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





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

Then turn off the built-in account and describe your directory:



1
2
3
4
5
6
7



cas.authn.accept.enabled=false
cas.authn.ldap[0].type=AUTHENTICATED
cas.authn.ldap[0].ldap-url=ldaps://ldap.example.org:636
cas.authn.ldap[0].base-dn=ou=people,dc=example,dc=org
cas.authn.ldap[0].search-filter=uid={user}
cas.authn.ldap[0].bind-dn=cn=cas,ou=services,dc=example,dc=org
cas.authn.ldap[0].bind-credential=changeit

LDAP Authentication covers Active Directory, direct binds and attribute retrieval.

6. Build and Run



1
2



./gradlew clean build
java -jar build/libs/cas.war

CAS prints a READY banner when it has started.

7. Log In

Open http://localhost:8080/cas/login?service=https://app.example.org/ and log in. CAS sends the browser back to the application with a ticket parameter. The example application does not exist, so copy the ST-… ticket from the address bar and validate it the way an application would:



1



curl "http://localhost:8080/cas/p3/serviceValidate?service=https://app.example.org/&ticket=ST-…"

The response names the user in <cas:user>. A service ticket works once and only for a few seconds, as set by cas.ticket.st.time-to-kill-in-seconds; log in again if CAS reports it as invalid. The CAS Protocol describes this exchange in full.

8. Before Production

  • Set your own signing and encryption keys for the single sign-on cookie and the login flow: cas.tgc.crypto.encryption.key, cas.tgc.crypto.signing.key, cas.webflow.crypto.encryption.key and cas.webflow.crypto.signing.key. When they are missing, CAS generates them at startup and logs them; keep those values and use them on every node.
  • Serve CAS over HTTPS only, through the embedded or an external servlet container.
  • With more than one node, choose a shared ticket registry and keep the service definitions identical on every node.
  • Read the Security Guide.

Next Steps