SourceForge.net Logo

libcas - CAS Specification
 
Home | Documentation | Support | Download | Get Involved | Related Sites

libcas - CAS Specification

    CAS Specification
    CAS Introduction
    API Documentation
    Tutorials
    Examples
    FAQ

Status of this Memo

This document specifies a proposed Internet track protocol for the Internet community, and requests discussion and suggestions for improvements. Distribution of this memo is unlimited.

Copyright

Copyright (C) by Ralph Schuster (2004). All rights reserved.

Abstract

The Common Authorization Service (CAS) protocol is an application-level protocol for distributed, collaborated authenticating and authorizing systems. It is a generic, stateless protocol which can be used to remotely authenticate and authorize users. A feature of CAS is its generic use of XML as presentation layer. Clients and servers can easily ignore XML tags they do not understand or vice versa send data through without violating the protocol as long they represent its data by XML.

This specification defines the protocol referred to as "CAS/1.0".

There is an introduction available where you can learn how CAS works.

Table of Contents

Top

1. Introduction

1.1. Purpose

The Common Authorization Service (CAS) protocol is an application-level protocol for distributed, collaborated authenticating and authorizing systems. It is a generic, stateless protocol which can be used to remotely authenticate and authorize users. A feature of CAS is its generic use of XML as presentation layer. Clients and servers can easily ignore XML tags they do not understand or vice versa send data through without violating the protocol as long they represent its data by XML.

This specification defines the protocol referred to as "CAS/1.0".

Practical information systems require more functionality than simple authentication and authorization. CAS allows additional structured data to be sent in either way to assure client and server have enough information for any authorization to succeed.

Top

1.2. Requirements

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 [??].

An implementation is not compliant if it fails to satisfy one or more of the MUST or REQUIRED level requirements for the protocols it implements. An implementation that satisfies all the MUST or REQUIRED level and all the SHOULD level requirements for its protocols is said to be "unconditionally compliant"; one that satisfies all the MUST level requirements but not all the SHOULD level requirements for its protocols is said to be "conditionally compliant."

Top

1.3. Terminology

This specification uses a number of terms to refer to the roles played by participants in, and objects of, the CAS communication.
connection
A transport layer virtual circuit established between two programs for the purpose of communication.
message
The basic unit of CAS communication, consisting of a structured sequence of octets matching the syntax defined in section 4 and transmitted via the connection.
request
A CAS request message, as defined in section 4.
response
A CAS response message, as defined in section 5.
scheme
A network data object or service that can be identified by a name as defined in section 3.2.
client
A program that establishes connections for the purpose of sending requests.
user agent
The client which initiates a request. These are often webservers, service daemons or other back end tools.
server
An application program that accepts connections in order to service requests by sending back responses. Any given program may be capable of being both a client and a server; our use of these terms refers only to the role being performed by the program for a particular connection, rather than to the program's capabilities in general.
tunnel
An intermediary program which is acting as a blind relay between two connections. Once active, a tunnel is not considered a party to the CAS communication. The tunnel ceases to exist when both ends of the relayed connections are closed.
cache
A program's local store of response messages and the subsystem that controls its message storage, retrieval, and deletion. A cache stores cacheable responses in order to reduce the response time and network bandwidth consumption on future, equivalent requests. Any client or server may include a cache, though a cache cannot be used by a server that is acting as a tunnel.
cacheable
A response is cacheable if a cache is allowed to store a copy of the response message for use in answering subsequent requests. The rules for determining the cacheability of CAS responses are defined in section ??. Even if a resource is cacheable, there may be additional constraints on whether a cache can use the cached copy for a particular request.
upstream/downstream
Upstream and downstream describe the flow of a message: all messages flow from upstream to downstream.
inbound/outbound
Inbound and outbound refer to the request and response paths for messages: "inbound" means "traveling toward the origin server", and "outbound" means "traveling toward the user agent"
Top

1.4. Overall Operation

The CAS protocol is a request/response protocol. A client sends a request to the server in the form of a XML document containing user information and requested authorization schemei over a connection with a server. The server responds with a XML document including a success or error code as well as server information, and possible error messages.

Most CAS communication is initiated by a server application and consists of a authorization request to be applied to a resource on some CAS server. In the simplest case, this may be accomplished via a single connection (v) between the server application (C) and the CAS server (S). 

          request chain ------------------------>
        C -------------------v------------------- S
          <----------------------- response chain
CAS communication usually takes place over TCP/IP connections. The default port is TCP 4466, but other ports can be used. This does not preclude CAS from being implemented on top of any other protocol on the Internet, or on other networks. CAS only presumes a reliable transport; any protocol that provides such guarantees can be used; the mapping of the CAS/1.0 request and response structures onto the transport data units of the protocol in question is outside the scope of this specification.

In CAS/1.0, a connection may be used for one or more request/response exchanges, although connections may be closed for a variety of reasons (see section ??).

Top

2. Protocol Parameters

2.1. CAS Version

CAS uses a "." numbering scheme to indicate versions of the protocol. The protocol versioning policy is intended to allow the sender to indicate the format of a message and its capacity for understanding further CAS communication, rather than the features obtained via that communication. No change is made to the version number for the addition of message components which do not affect communication behavior or which only add to extensible field values. The number is incremented when the changes made to the protocol add features which do not change the general message parsing algorithm, but which may add to the message semantics and imply additional capabilities of the sender. The number is incremented when the format of a message within the protocol is changed.

The version of a CAS message is indicated by version attribute of the XML root tag. 

		CAS-Version   = "CAS" "/" 1*DIGIT "." 1*DIGIT
Note that the major and minor numbers MUST be treated as separate integers and that each MAY be incremented higher than a single digit. Thus, CAS/3.8 is a lower version than CAS/3.33, which in turn is lower than CAS/10.2. Leading zeros MUST be ignored by recipients and MUST NOT be sent.

An application that sends a request or response message that includes CAS-Version of "CAS/1.0" MUST be at least conditionally compliant with this specification. Applications that are at least conditionally compliant with this specification MUST use a CAS-Version of "CAS/1.0" in their messages.

The CAS version of an application is the highest CAS version for which the application is at least conditionally compliant.

Note: Converting between versions of CAS may involve modification of tags required or forbidden by the versions involved.

Top

2.2. Scheme Identifiers

Schemes in CAS are symbolic names for pre-defined authentication and authorization procedures. Clients do not need to know how authentication and authorization are performed by CAS servers. These procedures are transparent to clients.

Servers SHOULD not indicate how the authorization process is implemented but return success or error codes instead.

Scheme names can consist of any character even spaces. Users are encouraged to use letters, digits and a few extra characters (e.g. underscores, dashes) only. Scheme names might need to be encoded when transmitted via XML according to XML encoding standards.

Top

2.3. Product Tokens

Product tokens are used to allow communicating applications to identify themselves by software name and version. Most fields using product tokens also allow sub-products which form a significant part of the application to be listed, separated by white space. By convention, the products are listed in order of their significance for identifying the application. 
       product         = token ["/" product-version]
       product-version = token
Examples: 
       <Agent>Apache/1.3.19 mod_cas/1.0</Agent>
       <Server>JCas/0.8.4</Server>
Product tokens SHOULD be short and to the point. They MUST NOT be used for advertising or other non-essential information. Although any token character MAY appear in a product-version, this token SHOULD only be used for a version identifier (i.e., successive versions of the same product SHOULD only differ in the product-version portion of the product value).

Top

3. CAS Message

CAS messages consist of requests from client to server and responses from server to client. 
       CAS-message   = Request | Response     ; CAS/1.0 messages
Request (section 4) and Response (section 5) messages use the generic XML format of ??? [??] for transferring information. Both message types use distinct Document Type Definitions (DTD). DTDs need not to be included in CAS messages.

In the interest of robustness, servers SHOULD ignore any spaces or any empty lin(s) received where a XML document is expected. In other words, if the server is reading the protocol stream and receives a CRLF first, it should ignore the CRLF.

Furthermore, servers SHOULD ignore any tag(s) received that are not part of the corresponding DTD.

Top

4. CAS Request

Two types of request messages exist: Authorization Requests and Administration Requests either use a different DTD. Both request types MUST be implemented by servers. Clients MAY implement Administration Requests but are not required to do so. However, clients MUST implement Authorization Requests.

4.1. Authorization Request

4.1.1. Document Type Definition

       <!DOCTYPE Request PUBLIC "-//GPL//DTD//CAS//REQ//AUTH//1-0" 
                                "http://libcas.sourceforge.net/dtd/casreq.dtd">

       <?xml version="1.0"?>
       <!ELEMENT Request (User, Password, Scheme, Cookie?, Agent?, ClientIP?, CloseConnection?)>
       <!ATTLIST Request version CDATA "CAS/1.0">
       <!ELEMENT User (#PCDATA)>
       <!ELEMENT Password (#PCDATA)>
       <!ELEMENT Scheme (#PCDATA)>
       <!ELEMENT Cookie (#PCDATA)>
       <!ELEMENT Agent (#PCDATA)>
       <!ELEMENT ClientIP (#PCDATA)>
       <!ELEMENT CloseConnection ("true"|"false")>

4.1.2. CAS Version

The CAS version used by the request is specified by attribute version of the root element (Request). CAS versions are specified in section 2.1.

4.1.3. User Tag

The content of this element specifies the user to be authenticated. This tag MUST be present. Only one User tag MUST be present.

4.1.4. Password Tag

The content of this element specifies the password of the user to be authenticated. Passwords MUST be transmitted without any encryption applied. CAS applies security by encrypting connections by default. The Password tag MUST be present. Only one Password tag MUST be present.

4.1.5. Scheme Tag

The content of this element specifies the authorization scheme to be applied for this request. Schemes are symbolic names that are defined by CAS servers. Schemes are transparent to clients and allow changing authorization method without affecting clients. The tag MUST be present. Only one Scheme tag MUST be present.

4.1.6. Cookie Tag

If a former CAS authorization request returned a cookie value (see Response message) this value MAY be included in a subsequent CAS Request. Servers SHOULD double-check cookie value against users, passwords, schemes, extra client information and expiration before authorization is based on such values. Cookies sent by a client MAY be ignored if the CAS server wishes so or is not able to handle it. Servers MUST use User, Password and Scheme tags to authenticate and authorize the user.

Only one Cookie tag MAY be present.

4.1.7. Agent Tag

The content of this element names the client product requesting authorization. Only one Agent tag MAY be present.

4.1.8. ClientIP Tag

If the requesting client is acting on behalf of another client this element can contain additional information about the client. CAS clients such as webservers may include the IP address of the HTTP user agent requesting the authorization. This element SHOULD be unique for different end users.

Only one ClientIP tag MAY be present.

4.1.9. CloseConnection Tag

If present, the content of this element specifies whether CAS connection should be closed after receiving the CAS response. Only "true" and "false" are allowed. Both client and server MAY shutdown the connection afterwards if "true" was sent.

If "false" was given or the tag is not present, both client and server SHOULD keep the connection established.

If either side wants to close the connection (Response messages contain a similar tag) the other side MUST accept the wish. In other words: If the client sent "true" servers MUST respond with correspondig tag set to "true". On the other hand, if the server sent "true" clients MUST be prepared to close the connection.

Only one CloseConnection tag MAY be present.

Top

4.2. Administration Request

Administration Request are defined to enable remote control of the CAS server application. CAS servers MUST implement the request but MAY return an error code indicating that they are not willing to execute it.

4.2.1. Document Type Definition

       <!DOCTYPE AdminRequest PUBLIC "-//GPL//DTD//CAS//REQ//AUTH//1-0" 
                                     "http://libcas.sourceforge.net/dtd/casadminreq.dtd">

       <?xml version="1.0"?>
       <!ELEMENT AdminRequest (User, Password, Command, Agent?, ClientIP?, CloseConnection?)>
       <!ATTLIST AdminRequest version CDATA "CAS/1.0">
       <!ELEMENT User (#PCDATA)>
       <!ELEMENT Password (#PCDATA)>
       <!ELEMENT Command (#PCDATA)>
       <!ELEMENT Agent (#PCDATA)>
       <!ELEMENT ClientIP (#PCDATA)>
       <!ELEMENT CloseConnection ("true"|"false")>

4.2.2. CAS Version

see Section 4.1.2 for definition.

4.2.3. User Tag

see Section 4.1.3 for definition.

4.2.4. Password Tag

see Section 4.1.4 for definition.

4.2.5. Command Tag

The content of this element specifies the command to be executed on the CAS server application. Commands are specific to server implementations and thus, not restricted. The tag MUST be present. Only one Command tag MUST be present.

The server MUST return success message only if the command was understood and executed successfully.

4.2.6. Agent Tag

see Section 4.1.7 for definition.

4.2.7. ClientIP Tag

see Section 4.1.8 for definition.

4.2.8. CloseConnection Tag

see Section 4.1.9 for definition.

Top

5. CAS Response

After receiving and interpreting a request message, a server responds with a CAS response message.

5.1. Document Type Definition

       <!DOCTYPE Response PUBLIC "-//GPL//DTD//CAS//REQ//AUTH//1-0" 
                                 "http://libcas.sourceforge.net/dtd/casresp.dtd">

       <?xml version="1.0"?>
       <!ELEMENT Response (RC, Cookie?, ErrorCode?, ErrorMessage?, Server?, CloseConnection?)>
       <!ATTLIST Response version CDATA "CAS/1.0">
       <!ELEMENT RC ("true"|"false")>
       <!ELEMENT Cookie (#PCDATA)>
       <!ELEMENT ErrorCode (#PCDATA)>
       <!ELEMENT ErrorMessage (#PCDATA)>
       <!ELEMENT Server (#PCDATA)>
       <!ELEMENT CloseConnection ("true"|"false")>

5.2. CAS Version

The CAS version used by the response is specified by attribute version of the root element (Response). CAS versions are specified in section 2.1.

5.3. RC Tag

If the user could be authorized successfully, the server MUST respond with "true". Reponses to Administration Requests MUST send "true" only if the specified command was executed successfully.

The RC tag MUST be present. Only one RC tag MUST be present. Valid values are "true" and "false".

5.4. Cookie Tag

If the user was authorized successfully, servers MAY create a string that the client MAY use in subsequent requests to accelerate authorizations. However, servers are not required to create these cookies or accept them in subsequent requests. They can invalidate them at any point in time without further notice.

Only one Cookie tag MAY be present.

5.5. ErrorCode Tag

If the request failed for any reason, this tag MUST be present, otherwise it MUST NOT. Servers will give error codes according to defined codes (see section 6) why the request failed. Additionally, servers should give details as Error Message (see next section).

Only one ErrorCode tag MAY be present.

5.6. ErrorMessage

If the request failed for any reason, this tag MAY be present, otherwise it MUST NOT. Servers will give readable error messages why the request failed.

Only one ErrorMessage tag MAY be present.

5.7. Server Tag

The content of this element names the server product handling the request. Only one Server tag MAY be present.

5.8. CloseConnection Tag

If present, the content of this element specifies whether CAS connection should be closed after CAS response was sent. Only "true" and "false" are allowed. Servers MUST shutdown the connection afterwards if "true" was sent. Clients MAY do so.

If "false" was given or the tag is not present, both client and server SHOULD keep the connection established.

If either side wants to close the connection (Request messages contain a similar tag) the other side MUST accept the wish. In other words: If the client sent "true" in corresponding tag, servers MUST respond with "true". On the other hand, if the server sent "true" clients MUST be prepared to close the connection.

Only one CloseConnection tag MAY be present.

Top

6. Error Codes

In case the server could not authorize the client it will respond with an arbitrary error code.

6.1. 1xx Client Errors

1xx error codes indicate protocol violations by clients.

Error Code Description
100 XML document not well-formed
101 Invalid XML document
102 Unknown Scheme
103 Admin Command not supported

6.2. 2xx Server Errors

If authorization fails due to internal server errors following error codes are defined.

Error Code Description
200 Internal Server Error
201 Backend error

6.3. 3xx Authorization errors

If authorization fails due to invalid credentials provided by a client the server responds with following error codes:

Error Code Description
300 Invalid user ID/password
301 Access denied
302 User locked
Top

7. Connections

CAS connection are subject to be closed at any time either side feels to do so. Connections SHOULD be closed by either partner if the XML document received is invalid (Conformity, Validity, Content, etc.). Thus, client and server MUST be prepared at any time that their counterpart closes the connection. Clients and servers MAY draw conclusions when the connection aborts.

Standard TCP/IP port of CAS is 4466.

Top

8. Security Considerations

CAS connections are SSL encrypted by default. Implementations should use plain TCP/IP only if vulnerability can be assumed to be zero (e.g. if only local connections are made by clients and servers do accept only connections from local host or by local pipes).

This procedure is required due to fact that plain passwords are transmitted by CAS. By doing so security is left to be subject of SSL/TLS.

Top

9. Appendices

Top

10. Index

Top

11. Full Copyright Statement

Copyright (C) Ralph Schuster (2004). All Rights Reserved.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by the author or his successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and THE AUTHOR DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Top