View on GitHub

Single Sign-On for the Web

Overview

Branding the CAS User Interface (UI) involves simply editing the CSS stylesheet and also a small collection of relatively simple JSP include files, also known as views. Optionally, you may also wish to modify the text displayed and/or add additional Javascript effects on these views.

All the files that we’ll be discussing in this section that concern the theme are located in and referenced from: /cas-server-webapp/src/main/webapp.

Browser Support

CAS user interface should properly and comfortably lend itself to all major browser vendors:

Note that certain older version of IE, particularly IE 9 and below may impose additional difficulty in getting the right UI configuration in place.

Getting Started

CSS

The default styles are all contained in a single file located in css/cas.css. This location is set in WEB-INF/classes/cas-theme-default.properties. If you would like to create your own css/custom.css file, for example, you will need to update standard.custom.css.file key in that file.

standard.custom.css.file=/css/cas.css
cas.javascript.file=/js/cas.js

CSS per Locale

Selecting CSS files per enabled locale would involve changing the top.jsp file to include the below sample code:

<%
    String cssFileName = "cas.css"; // default
    Locale locale = request.getLocale();
 
    if (locale != null && locale.getLanguage() != null){
       String languageCssFileName = "cas_" + locale.getLanguage() + ".css";
       cssFileName = languageCssFileName; //ensure this file exists
    }
 
%>
<link href="/path/to/css/<%=cssFileName%>" rel="stylesheet" type="text/css"/>

Responsive Design

CSS media queries bring responsive design features to CAS which would allow adopter to focus on one theme for all appropriate devices and platforms. These queries are defined in the same css/cas.css file. Below follows an example:

@media only screen and (max-width: 960px) { 
  footer { padding-left: 10px; }
}

@media only screen and (max-width: 799px) { 
  header h1 { font-size: 1em; }
  #login { float: none; width: 100%; }
  #fm1 .row input[type=text], 
  #fm1 .row input[type=password] { width: 100%; padding: 10px; box-sizing: border-box; -webkit-box-sizing: border-box; -moz-box-sizing: border-box; }
  #fm1 .row .btn-submit { outline: none; -webkit-appearance: none; -webkit-border-radius: 0; border: 0; background: #210F7A; color: white; font-weight: bold; width: 100%; padding: 10px 20px; -webkit-border-radius: 3px; -moz-border-radius: 3px; border-radius: 3px; }
  #fm1 .row .btn-reset { display: none; }
  #sidebar { margin-top: 20px; }
  #sidebar .sidebar-content { padding: 0; }
}

Javascript

If you need to add some JavaScript, feel free to append js/cas.js.

You can also create your own custom.js file, for example, and call it from within WEB-INF/view/jsp/default/ui/includes/bottom.jsp like so:

<script type="text/javascript" src="<c:url value="/js/custom.js" />"></script>

If you are developing themes per service, each theme also has the ability to specify a custom cas.js file under the cas.javascript.file setting.

The following Javascript libraries are utilized by CAS automatically:

Preserving Anchor Fragments

Anchors/fragments may be lost across redirects as the server-side handler of the form post ignores the client-side anchor, unless appended to the form POST url. This is needed if you want a CAS-authenticated application to be able to use anchors/fragments when bookmarking.

Changes to cas.js

/**
 * Prepares the login form for submission by appending any URI
 * fragment (hash) to the form action in order to propagate it
 * through the re-direct (i.e. store it client side).
 * @param form The login form object.
 * @returns true to allow the form to be submitted.
 */
function prepareSubmit(form) {
    // Extract the fragment from the browser's current location.
    var hash = decodeURIComponent(self.document.location.hash);
 
    // The fragment value may not contain a leading # symbol
    if (hash && hash.indexOf("#") === -1) {
        hash = "#" + hash;
    }
   
    // Append the fragment to the current action so that it persists to the redirected URL.
    form.action = form.action + hash;
    return true;
}

Changes to Login Form

<form:form method="post" id="fm1" cssClass="fm-v clearfix" 
        commandName="${commandName}" htmlEscape="true" 
        onsubmit="return prepareSubmit(this);">

JSP

The default views are found at WEB-INF/view/jsp/default/ui/.

Notice top.jsp and bottom.jsp include files located in the ../includes directory. These serve as the layout template for the other JSP files, which get injected in between during compilation to create a complete HTML page.

The location of these JSP files are configured in WEB-INF/classes/default_views.properties.

Tag Libraries

The following JSP tag libraries are used by the user interface:

<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<%@ taglib prefix="spring" uri="http://www.springframework.org/tags" %>
<%@ taglib prefix="form" uri="http://www.springframework.org/tags/form" %>
<%@ taglib prefix="fn" uri="http://java.sun.com/jsp/jstl/functions" %>

Glossary of Views

Localization

The CAS Web application includes a number of localized message files:

In order to “invoke” a specific language for the UI, the /login endpoint may be passed a locale parameter as such:

https://cas.server.edu/login?locale=it

Configuration

All message bundles are marked under messages_xx.properties files at WEB-INF/classes. The default language bundle is for the English language and is thus called messages.properties. If there any custom messages that need to be presented into views, they may also be formatted under custom_messages_xx.properties files.

Messages are parsed and loaded via the following configuration:

<bean id="messageSource" class="org.jasig.cas.web.view.CasReloadableMessageBundle"
          p:basenames-ref="basenames" p:fallbackToSystemLocale="false" p:defaultEncoding="UTF-8"
          p:cacheSeconds="180" p:useCodeAsDefaultMessage="true" />
    
<util:list id="basenames">
    <value>classpath:custom_messages</value>
    <value>classpath:messages</value>
</util:list>

Messages are then read on each JSP view via the following sample configuration:

<spring:message code="message.key" />

In the event that the code is not found in the activated resource bundle, the code itself will be used verbatim.

Themes

With the introduction of Service Management application, deployers are now able to switch the themes based on different services. For example, you may want to have different login screens (different styles) for staff applications and student applications. Or, you want to show two layouts for day time and night time. This document could help you go through the basic settings to achieve this.

Components

Configuration of service-specific themes is backed by the Spring framework and provided by the following component:

<bean id="themeResolver" class="org.jasig.cas.services.web.ServiceThemeResolver"
    p:defaultThemeName="${cas.themeResolver.defaultThemeName}"
    p:servicesManager-ref="servicesManager"
    p:argumentExtractors-ref="argumentExtractors" />

Furthermore, deployers may be able to use the functionality provided by the ThemeChangeInterceptor of Spring framework to provide theme configuration per each request.

Configuration