CAS

Configuring uPortal to use CAS

uPortal 3.2 is shipped with a default CAS authentication configuration that uses a bundled CAS server. This CAS server is included in the uPortal build and is deployed to the same servlet container as uPortal.

The required CAS configuration is contained in two filters and filter mappings in the portal's web.xml and in the security.properties file. When any of the following configuration elements changes, the CAS configuration will need to change as well:

server hostname
server port
SSL/non-SSL
application context name change

To update the CAS authentication configuration, look for all values of "localhost" in the "CAS Validate Filter" element of web.xml. Each URL will need to be sensibly updated to match either the CAS or uPortal installation. The "logoutRedirect.root" and "org.jasig.portal.channels.CLogin.CasLoginUrl" properties of security.properties will also need modification. More information on the configuration filter parameters can be found in the CAS documentation.

It's important to remember that moving to SSL will also require adopters to import the SSL of the CAS server into the JVM's keystore. This step must be performed even if the bundled CAS server is used. (See SSL Configuration)

Configuration Options

Option 1: Using the uPortal Bundled CAS Server
Option 2: Using an External CAS Server

Option 1: Using the uPortal Bundled CAS Server

The code below provides an example of changing the default "http://localhost:8080" installation to a real domain, mapped by Apache over SSL at "https://portal.school.edu".

Step 1: Edit uportal-war/src/main/webapp/WEB-INF/web.xml

uportal-war/src/main/webapp/WEB-INF/web.xml

<filter>
        <filter-name>CAS Validate Filter</filter-name>
        <filter-class>org.jasig.cas.client.validation.Cas20ProxyReceivingTicketValidationFilter</filter-class>
        <init-param>
          <param-name>casServerUrlPrefix</param-name>
          <param-value>https://portal.school.edu/cas</param-value>
        </init-param>
        <init-param>
          <param-name>serverName</param-name>
          <param-value>https://portal.school.edu</param-value>
        </init-param>
        <init-param>
            <param-name>proxyCallbackUrl</param-name>
            <param-value>https://portal.school.edu/uPortal/CasProxyServlet</param-value>
        </init-param>
        <init-param>
            <param-name>proxyReceptorUrl</param-name>
            <param-value>/CasProxyServlet</param-value>
        </init-param>
        <init-param>
            <param-name>acceptAnyProxy</param-name>
            <param-value>true</param-value>
        </init-param>
    </filter>

    <filter>
        <filter-name>CAS Assertion ThreadLocal Filter</filter-name>
        <filter-class>org.jasig.cas.client.util.AssertionThreadLocalFilter</filter-class>
    </filter>

    . . .

    <filter-mapping>
        <filter-name>CAS Validate Filter</filter-name>
        <url-pattern>/Login</url-pattern>
    </filter-mapping>

    <filter-mapping>
        <filter-name>CAS Validate Filter</filter-name>
        <url-pattern>/CasProxyServlet</url-pattern>
    </filter-mapping>

    <filter-mapping>
        <filter-name>CAS Assertion ThreadLocal Filter</filter-name>
        <url-pattern>/Login</url-pattern>
    </filter-mapping>

Step 2: Edit uportal-impl/src/main/resources/properties/security.properties

uportal-impl/src/main/resources/properties/security.properties

## This is the factory that supplies the concrete authentication class
root=org.jasig.portal.security.provider.UnionSecurityContextFactory
root.cas=org.jasig.portal.security.provider.cas.CasAssertionSecurityContextFactory
root.simple=org.jasig.portal.security.provider.SimpleSecurityContextFactory

## Answers what tokens are examined in the request for each context during authentication.
## A subcontext only needs to set its tokens if it differs from those of the root context.
principalToken.root=userName
credentialToken.root=password
credentialToken.root.cas=ticket

## Answers where the user will be redirected when log out occurs. Each security context can have one.
## (See comments in the LogoutServlet class)
## It would be better to escape the value of the url parameter, but since there are no parameters on the
## unescaped URL and since there are no further parameters on the logout URL, this does work.
logoutRedirect.root=https://portal.school.edu/cas/logout?url=https://portal.school.edu/uPortal/Login

## This is the factory that supplies the concrete authorization class
authorizationProvider=org.jasig.portal.security.provider.AuthorizationServiceFactoryImpl

## Login URL, if specified the CLogin channel will display a Login link with
## this URL instead of the standard userName/password form.
org.jasig.portal.channels.CLogin.CasLoginUrl=https://portal.school.edu/cas/login?service=https://portal.school.edu/uPortal/Login

Option 2: Using an External CAS Server

Configuring uPortal for an external CAS service is essentially the same. Once the portal is configured against an external CAS server, you may wish to remove the bundled CAS installation.

Steps 1 and 2: As Above

Configuration uPortal to authenticate to an external CAS server will require modifying the web.xml and security.properties files shown above to match the new CAS URL.

Step 3: Remove Bundled CAS Dependencies from Maven POM Files

To prevent CAS from being deployed by the ant deploy-ear task, perform the following changes:

Remove the line <module>cas</module> from uportal-portlets-overlay/pom.xml.
Remove the CAS dependency and webModule elements from uportal-ear/pom.xml.

Additional References

SSL Configuration

Having problems with these instructions?

Please send us feedback at uportal-user@lists.ja-sig.org