Central Authentication Service v2.0 Protocol Specification
Author: Drew Mazurek <drew.mazurek@yale.edu>
Contributors: Susan Bramhall <susan.bramhall@yale.edu>,
Howard Gilbert <howard.gilbert@yale.edu>,
Andy Newman <newman-andy@yale.edu>,
Andrew Petro <andrew.petro@yale.edu>
Version: 1.0
Release Date: May 4, 2005
Copyright © 2005, Yale University
Table of Contents
1. Introduction
1.1. Conventions & Definitions
2. CAS URIs
2.1. /login as credential requestor
2.1.1. parameters
2.1.2. URL examples of /login
2.1.3. response for username/password authentication
2.1.4. response for trust authentication
2.1.5. response for single sign-on authentication
2.2. /login as credential acceptor
2.2.1. parameters common to all types of authentication
2.2.2. parameters for username/password authentication
2.2.3. parameters for trust authentication
2.2.4. response
2.3. /logout
2.3.1. parameters
2.3.2. response
2.4. /validate [CAS 1.0]
2.4.1. parameters
2.4.2. response
2.4.3. URL examples of /validate
2.5. /serviceValidate [CAS 2.0]
2.5.1. parameters
2.5.2. response
2.5.3. error codes
2.5.4. proxy callback
2.5.5. URL examples of /serviceValidate
2.6. /proxyValidate [CAS 2.0]
2.6.1. parameters
2.6.2. response
2.6.3. URL examples of /proxyvalidate
2.7. /proxy [CAS 2.0]
2.7.1. parameters
2.7.2. response
2.7.3. error codes
2.7.4. URL example of /proxy
3. CAS Entities
3.1. service ticket
3.1.1. service ticket properties
3.2. proxy ticket
3.2.1. proxy ticket properties
3.3. proxy-granting ticket
3.3.1. proxy-granting ticket properties
3.4. proxy-granting ticket IOU
2
3.4.1. proxy-granting ticket IOU properties
3.5. login ticket
3.5.1. login ticket properties
3.6. ticket-granting cookie
3.6.1. ticket-granting cookie properties
3.7. ticket and ticket-granting cookie character set
Appendix A. CAS response XML schema
Appendix B. Safe redirection
Appendix C. References
Appendix D. CAS License
Appendix E. Changes to this Document
3
1. Introduction
This is the official specification of the CAS 1.0 and 2.0 protocols. It is subject to change.
1.1. Conventions & Definitions
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”,
“SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this
document are to be interpreted as described in RFC 2119
[1]
.
“Client” refers to the end user and/or the web browser.
“Server” refers to the Central Authentication Service server.
“Service” refers to the application the client is trying to access.
“Back-end service” refers to the application a service is trying to access on behalf of a
client. This can also be referred to as the “target service.”
<LF> is a bare line feed (ASCII value 0x0a).
2. CAS URIs
CAS is an HTTP
[2,3]
-based protocol that requires each of its components to be accessible through
specific URIs. This section will discuss each of the URIs.
2.1. /login as credential requestor
The /login URI operates with two behaviors: as a credential requestor, and as a credential
acceptor. It responds to credentials by acting as a credential acceptor and otherwise acts as a
credential requestor.
If the client has already established a single sign-on session with CAS, the web browser presents
to CAS a secure cookie containing a string identifying a ticket-granting ticket. This cookie is
called the ticket-granting cookie. If the ticket-granting cookie keys to a valid ticket-granting
ticket, CAS may issue a service ticket provided all the other conditions in this specification are
met. See Section 3.6 for more information on ticket-granting cookies.
2.1.1. parameters
The following HTTP request parameters may be passed to /login while it is acting as a credential
requestor. They are all case-sensitive, and they all MUST be handled by /login.
service [OPTIONAL] – the identifier of the application the client is trying to access. In
almost all cases, this will be the URL of the application. Note that as an HTTP request
parameter, this URL value MUST be URL-encoded as described in Section 2.2 of RFC
1738
[4]
. If a service is not specified and a single sign-on session does not yet exist, CAS
SHOULD request credentials from the user to initiate a single sign-on session. If a
service is not specified and a single sign-on session already exists, CAS SHOULD
display a message notifying the client that it is already logged in.
4
renew [OPTIONAL] – if this parameter is set, single sign-on will be bypassed. In this
case, CAS will require the client to present credentials regardless of the existence of a
single sign-on session with CAS. This parameter is not compatible with the “gateway”
parameter. Services redirecting to the /login URI and login form views posting to the
/login URI SHOULD NOT set both the “renew” and “gateway” request parameters.
Behavior is undefined if both are set. It is RECOMMENDED that CAS implementations
ignore the “gateway” parameter if “renew” is set. It is RECOMMENDED that when the
renew parameter is set its value be “true”.
gateway [OPTIONAL] – if this parameter is set, CAS will not ask the client for
credentials. If the client has a pre-existing single sign-on session with CAS, or if a single
sign-on session can be established through non-interactive means (i.e. trust
authentication), CAS MAY redirect the client to the URL specified by the “service”
parameter, appending a valid service ticket. (CAS also MAY interpose an advisory page
informing the client that a CAS authentication has taken place.) If the client does not
have a single sign-on session with CAS, and a non-interactive authentication cannot be
established, CAS MUST redirect the client to the URL specified by the “service”
parameter with no “ticket” parameter appended to the URL. If the “service” parameter is
not specified and “gateway” is set, the behavior of CAS is undefined. It is
RECOMMENDED that in this case, CAS request credentials as if neither parameter was
specified. This parameter is not compatible with the “renew” parameter. Behavior is
undefined if both are set. It is RECOMMENDED that when the gateway parameter is set
its value be “true”.
2.1.2. URL examples of /login
Simple login example:
https://server/cas/login?service=http%3A%2F%2Fwww.service.com
Don’t prompt for username/password:
https://server/cas/login?service=http%3A%2F%2Fwww.service.com&gateway=true
Always prompt for username/password:
https://server/cas/login?service=http%3A%2F%2Fwww.service.com&renew=true
2.1.3. response for username/password authentication
When /login behaves as a credential requestor, the response will vary depending on the type of
credentials it is requesting. In most cases, CAS will respond by displaying a login screen
requesting a username and password. This page MUST include a form with the parameters,
“username”, “password”, and “lt”. The form MAY also include the parameter, “warn”. If
“service” was specified to /login, “service” MUST also be a parameter of the form, containing
the value originally passed to /login. These parameters are discussed in detail in Section 2.2.1.
The form MUST be submitted through the HTTP POST method to /login which will then act as a
credential acceptor, discussed in Section 2.2.
2.1.4. response for trust authentication
5
