CAS (Centrale Authentication Service): for developers

CAS (Centrale Authentication Service): for developers

Intro

CAS is the Central Authentication Service for UGent. CAS allows you to log on to secured UGent pages using your account.

If you develop web applications which require user authentication, you can make use of CAS. CAS provides single sign on and single sign out and can return extra parameters along with the authenticated login name.

Tip: on the CAS (Centrale Authentication Service): introduction-page you find the answers to questions as "What is CAS?/ What is Central Authentication?", "How long do I remain logged on?", "How do I log out?".

How CAS works

CAS follows the same principle as webauth. Your web application directs the user to the CAS login page.

e.g.

https://login.ugent.be/login?service=https://login.ugent.be/cas-java-demo

Following authentication, CAS redirects the user to the original web application, which was passed within the url as service parameter. If the user is logged on to another web application, no login page will be presented. (= Single Sign On)

For single sign out, CAS sends a POST request to all applications the user is logged on to.

CAS can be tested following the instructions below. Please send your remarks about CAS or the webauth compatibility module to login@UGent.be.

Webauth compatibility

We provide a webauth compatibility module to allow enough time for you to migrate your web applications to CAS. You can test it in your applications, replacing "https://webauth.ugent.be/" by "https://webauthx.ugent.be/". As a result, the user will get to see the CAS login page.

Shortly, the current webauth implementation will be suspended; "https://webauth.ugent.be/" will then refer to the compatibility module. According to plan, the compatibility module will be turned off by the beginning of july 2009. By then your web applications must be migrated to CAS.

Setting up a CAS client

Registration is required. Enter the following:

  1. your web application url
  2. a short descriptionof your web application
  3. the attributes you wish to use

URL

CAS uses your web application url to compare the service parameter with the registered web applications. If a CAS redirect occurs in several pages of an application, you can enter the main url, followed by 2 *s (= wildcards). Be careful if you have other web applications in the same domain.

https://foo.UGent.be/bar/**

Attributes (optional)

By default, the login name (uid) is returned. Following LDAP attributes are available on demand:

  • mail
  • department
  • givenname
  • surname
  • objectClass
  • lastenrolled
  • jobcategory
  • addressingtitle
  • extcategory
  • ugentID
  • faculty

In this way, you can request LDAP attributes without having to resort to adressing the UGent LDAP from within your application. Based on the requirements of your applications, the above attribute list may be adapted.

Use CAS for authentication only, not for session management. You should provide session management in your application. Make sure that the authenticated login name is stored after succesful authentication.

Examples for users

Php examples

  1. The general example applies to most situations but NOT to webpages.ugent.be (= sites on webshares).
    Test the example: http://login.ugent.be/cas-php-demo.
  2. UGCAS_Simple is a client module with restricted functionality.
    Is is meant specifically for webpages.ugent.be (= sites on webshares) but can be used in other environments.

Requirements

PHP 4.2.2+

  • −with-curl
  • −with-openssl
  • −with-dom
  • −with-zlib

General example (NOT on webpages.ugent.be)

A php CAS library is available at: http://www.ja-sig.org/wiki/display/CASC/phpCAS. This library is CAS3 compatible, but lacks a number of CAS3 specific features.

We developed an adapted version, based on phpCAS. It can be downloaded from cas-ugent-php.zip. As long as phpCAS does not offer CAS version 3 support, we advise you to use this library.

The example below illustrates the use of the library:

Please adapt the certificate path to the actual certificate location! When the certificate path is incorrect, it will produce an infinite redirect loop error.

<?php

include_once('CAS.php');

//phpCAS::setDebug('/tmp/phpCAS.log'); // Schrijft debug informatie naar een log-file

// Parameters: CAS version, CAS server url, CAS server port, CAS server URI (same as host), 
// boolean indicating session start, communication protocol (SAML) between application and CAS server
phpCAS::client(SAML_VERSION_1_1,'login.ugent.be',443,'', true, 'saml');

// Server from which logout requests are sent
phpCAS::handleLogoutRequests(true, array('cas1.ugent.be','cas2.ugent.be','cas3.ugent.be','cas4.ugent.be','cas5.ugent.be','cas6.ugent.be'));

// Path to the "trusted certificate authorities" file:
phpCAS::setCasServerCACert('/etc/ssl/certs/ca-certificates.crt');
// No server verification (less safe!):
//phpCAS::setNoCasServerValidation();
// The actual user authentication
phpCAS::forceAuthentication(); 

// Handle logout requests
if (isset($_REQUEST['logout'])) {
        phpCAS::logout();
}


?>

<html>
  <head>
    <title>phpCAS simple client</title>
  </head>
  <body>
    <h1>Successfull Authentication!</h1>

    <p>the user's login is <b><?php echo phpCAS::getUser(); ?></b>.</p>
    <p>the attributes are:
    <?php
    echo '<ul>';
    $attr = phpCAS::getAttributes();
    foreach ($attr as $key => $value)
    {
        if(!is_array($value))
        {
                echo '<li>' . $key . ' => ' . $value . '</li>';
        }
        else
        {
                echo '<li>' . $key . '</li>';
                echo '<ul>';
                foreach($value as $v)
                {
                        echo '<li>' . $v . '</li>';
                }
                echo '</ul>';
        }
    }
    echo '</ul>';
    ?>

    </p>
    <p>phpCAS version is <b><?php echo phpCAS::getVersion(); ?></b>.</p>
    <p><a href="?logout=">Logout</a></p>

  </body>
</html>

UGCAS_Simple example (specifically for webpages.ugent.be)

UGCAS_Simple is a CAS client module with the same functionality as UGent Webauth: the username of the person is returned. No extra attributes nor logout are supported.

UGCAS_Simple can be downloaded from UGCAS_Simple-0.1.zip and contains:

  • UGCAS_Simple.php: php cas module. Place it where php can find it.
  • hello.php: simple example
  • hello2.php: slightly extended example

Java example

Test the example: https://login.ugent.be/cas-java-demo

You can download an example from cas-java-demo.zip

For a Java web application you only have to use a number of filters provided by the CAS developers.

Important: instructions below are for CAS client version 3.1.3 specifically

1. Add the following libraries to WEB-INF/lib (or use Maven):

cas-client-core-3.1.3.jar
commons-logging-1.1.jar
log4j-1.2.5.jar
opensaml-1.1.jar
xmlsec-1.3.0.jar

Download them here: java_servlet_filter_libs.zip

2. add the required filters to WEB-INF/web.xml.


	<context-param>
		<param-name>serverName</param-name>
		<param-value>https://mijnserver.ugent.be</param-value>
	</context-param>

	<filter>
		<filter-name>CAS Single Sign Out Filter</filter-name>
		<filter-class>org.jasig.cas.client.session.SingleSignOutFilter</filter-class>
	</filter>
	<filter-mapping>

		<filter-name>CAS Single Sign Out Filter</filter-name>
		<url-pattern>/*</url-pattern>
	</filter-mapping>
	<listener>
		<listener-class>org.jasig.cas.client.session.SingleSignOutHttpSessionListener</listener-class>

	</listener>
	<filter>
		<filter-name>CAS Authentication Filter</filter-name>
		<filter-class>org.jasig.cas.client.authentication.AuthenticationFilter</filter-class>
		<init-param>

			<param-name>casServerLoginUrl</param-name>
			<param-value>https://login.ugent.be/</param-value>
		</init-param>
		<init-param>
			<param-name>renew</param-name>

			<param-value>false</param-value>
		</init-param>
		<init-param>
			<param-name>gateway</param-name>
			<param-value>false</param-value>

		</init-param>
	</filter>
	<filter>
		<filter-name>CAS Validation Filter</filter-name>
		<filter-class>org.jasig.cas.client.validation.Saml11TicketValidationFilter</filter-class>

		<init-param>
			<param-name>casServerUrlPrefix</param-name>
			<param-value>https://login.ugent.be/</param-value>
		</init-param>
		<init-param>

			<param-name>tolerance</param-name>
			<param-value>300000</param-value>
		</init-param>
	</filter>
	<filter>

		<filter-name>CAS HttpServletRequest Wrapper Filter</filter-name>
		<filter-class>org.jasig.cas.client.util.HttpServletRequestWrapperFilter</filter-class>
	</filter>
	<filter-mapping>
		<filter-name>CAS Authentication Filter</filter-name>

		<url-pattern>/*</url-pattern>
	</filter-mapping>
	<filter-mapping>
		<filter-name>CAS Validation Filter</filter-name>
		<url-pattern>/*</url-pattern>

	</filter-mapping>
	<filter-mapping>
		<filter-name>CAS HttpServletRequest Wrapper Filter</filter-name>
		<url-pattern>/*</url-pattern>
	</filter-mapping>

	<servlet>
		<description>DemoServlet</description>
		<display-name>DemoServlet</display-name>
		<servlet-name>DemoServlet</servlet-name>

		<servlet-class>be.ugent.dict.ugentssoauth.demo.servlet.DemoServlet</servlet-class>
	</servlet>
	<servlet-mapping>
		<servlet-name>DemoServlet</servlet-name>
		<url-pattern>/*</url-pattern>

	</servlet-mapping>
</web-app>

Short explanation:

  • mijnserver.ugent.be: host on which the application runs
  • tolerance: the tolerance (in ms) for drifting clocks when validating SAML tickets
  • redirectAfterValidation: if false, the ticket parameter remains in the url, if true it does not.

3. You can then request the user using request.getRemoteUser(). Attributes can be retrieved from request.getUserPrincipal()

Below an example of how you can retrieve the remote user and its attributes.

import org.jasig.cas.client.authentication.AttributePrincipal;

...

                out.println("You are succesfully logged in as user <b>"	+ request.getRemoteUser() + "</b><br/><br/>");

		AttributePrincipal principal = (AttributePrincipal) request.getUserPrincipal();
		Map attributes = principal.getAttributes();

		if (attributes.size() > 0) {

			out.println("You have " + attributes.size() + " attributes : <br/>");
			Iterator keyIterator = attributes.keySet().iterator();

			while (keyIterator.hasNext()) {

				Object key = keyIterator.next();
				Object value = attributes.get(key);
				out.println("<b>" + key + "</b>" + " : " + value);
		        }
		} else {
			out.println("You have no attributes set");
		}

Spring security

The Spring framework is used in the EDO framework. CAS authentication can be integrated in a Spring based application, using Spring Security.

Spring Security offers out-of-the-box support for CAS 3. Cf. http://static.springframework.org/spring-security/site/reference/html/cas.html for the excellent Spring Security online documentation.

You can download an example from CasSpringsecurityExample.zip. Developers must reconfigure the UserDetailService bean for their environment.

Maven

The Java CAS client can easily be integrated into a Maven-based build system:

<dependency>
    <groupId>org.jasig.cas</groupId>
    <artifactId>cas-client-core</artifactId>
    <version>3.1.4</version>

</dependency> 
<dependency>
    <groupId>opensaml</groupId>
    <artifactId>opensaml</artifactId>
    <version>1.1b</version>

</dependency>

SSL

Service tickets are validated over an SSL connection with the CAS server. It is therefore necessary that the CAS server certificate is installed into the JVM on which te Java application will run.

sudo $JAVA_HOME/bin/keytool -import -alias login.ugent.be -file CERTIFICATE_FILE 
     -keystore $JAVA_HOME/jre/lib/security/cacerts
                            

.NET example

You can download an example from cas-NET-demo.zip.
Below you find the required code to implement the .NET client in your project.

Step 1: add properties in Web.config

	<appSettings>
		<add key="casLoginURL" value="https://login.ugent.be/login"/>
		<add key="casValidateURL" value="https://login.ugent.be/serviceValidate"/>
		<add key="casSamlValidateURL" value="https://login.ugent.be/samlValidate"/>
		<add key="serviceURL" value="jouw geregistreerde cas url"/>
	</appSettings>

Step 2: add the classes "DotNetCasClient" and "DotNetCasAttributePrincipal" to your project. Step 3: add the code below to your main page.

    protected void Page_Load(object sender, EventArgs e)
    {
        DotNetCasAttributePrincipal principal= null;
        String userId = (String)Session["userId"];
        if (userId == null)
        {
            DotNetCASClientServiceValidate client = new DotNetCASClientServiceValidate();

            principal = client.AuthenticatePrincipal(Request, Response);
        }
        if (principal != null && principal.isAutheniticated)
        {
            Session["userId"] = principal.userName;
            Session["userAttributeTable"] = principal.attributes;
        }
    }

From now on your application uses CAS.
Remark: The attributes are stored in a HashTable, each attribute is an arraylist of Strings. The Single Sign Out is not implemented. If you wish to use it, you will have to take care of it.
More information on Single Sign Out can be found on the cas help pages.