Configuring CAS for X509 User Certificates

Introduction

The follow settings were tested with CAS version 3.3.1. If any issues occur while doing this for newer versions, check the External Links section at the bottom of this page for the CAS documentation on setting up certification authentication.

Add the cas-server-support-x509-3.3.1.jar to CAS

• Copy thirdparty/cas-server-support-x509-3.3.1/target/cas-server-support-x509-3.3.1.jar to apache-tomecat-${version}/webapps/cas/WEB-INF/lib/cas-server-support-x509-3.3.1.jar

Configuring Web Flow

In apache-tomcat-${version}/webapps/cas/WEB-INF/login-workflow.xml make the following modifications:

• Remove the XML comments around the action-state stanza with id startAuthenticate.

  startAuthenticate

  <action-state id="startAuthenticate">
    <action bean="x509Check" />
    <transition on="success" to="sendTicketGrantingTicket" />
    <transition on="error" to="viewLoginForm" />
  </action-state>

• Modify the decision-state stanze with id renewRequestCheck as follows.

  renewRequestCheck

  <decision-state id="renewRequestCheck">
    <if test="${externalContext.requestParameterMap['renew'] != '' &amp;&amp; externalContext.requestParameterMap['renew'] != null}" then="startAuthenticate" else="generateServiceTicket" />
  </decision-state>

• Modify the decision-state stanze with id gatewayRequestCheck as follows.

  gatewayRequestCheck

  <decision-state id="gatewayRequestCheck">
    <if test="${externalContext.requestParameterMap['gateway'] != '' &amp;&amp; externalContext.requestParameterMap['gateway'] != null &amp;&amp; flowScope.service != null}" then="redirect" else="startAuthenticate" />
  </decision-state>

In apache-tomcat-${version}/webapps/cas/WEB-INF/cas-servlet.xml make the following modifications:

• Define the x509Check bean.
  
  

  x509Check

  <bean
     id="x509Check"
     p:centralAuthenticationService-ref="centralAuthenticationService"
     class="org.jasig.cas.adaptors.x509.web.flow.X509CertificateCredentialsNonInteractiveAction" >
     <property name="centralAuthenticationService" ref="centralAuthenticationService"/>
  </bean>

Configuring the Authentication Handler

In apache-tomcat-${version}/webapps/cas/WEB-INF/deployerConfigContext.xml make the following modifications:

• In the list stanza of the property stanza with name authenticationHandlers of the bean stanza with id authenticationManager, add the X509CredentialAuthenticationHander bean definition.

  X509CredentialAuthenticationHander

  <bean id="authenticationManager"
    class="org.jasig.cas.authentication.AuthenticationManagerImpl">
         
    <!-- Other property definitions -->
  
     <property name="authenticationHandlers">
       <list>
  
         <!-- Other bean definitions -->
  
         <bean
           class="org.jasig.cas.adaptors.x509.authentication.handler.support.X509CredentialsAuthenticationHandler">
           <property name="trustedIssuerDnPattern" value=".*" />
           <!--
             <property name="maxPathLength" value="3" />
             <property name="checkKeyUsage" value="true" />
             <property name="requireKeyUsage" value="true" />
           -->
         </bean>
      </list>   
    </property>
  </bean>

Configuring the Credentials to Principal Resolver

In apache-tomcat-${version}/webapps/cas/WEB-INF/deployerConfigContext.xml make the following modifications:

• In the list stanza of the property stanza with name credentialsToPrincipalReslover of the bean stanza with id authenticationManager, add the X509CertificateCredentialsToIdentifierPrincipalResolver bean definition.  The pattern in the value attribute on the property stanza can be modified to suit your needs.  This is a simple example that uses the first CN field in the DN as the Principal. 

  X509CertificateCredentialsToIdentifierPrincipalResolver

  <bean id="authenticationManager"
    class="org.jasig.cas.authentication.AuthenticationManagerImpl">
    <property name="credentialsToPrincipalResolvers">
      <list>
      
        <!-- Other bean definitions -->
  
        <bean
          class="org.jasig.cas.adaptors.x509.authentication.principal.X509CertificateCredentialsToIdentifierPrincipalResolver">
          <property name="identifier" value="$OU $CN" />
        </bean>
      </list>
    </property>
  
    <!-- Other property definitions -->
  
  </bean>

In addition to the PrincipalResolver mentioned above, CAS comes with other resolvers that can return different representations of the user identifier. This list was obtained from the official CAS Documentation site linked at the bottom of this page.

Different resolvers should be used depending on the use-case for the server. When performance external attribute lookup (example: Attribute lookup via DIAS) it is necessary to have CAS return the full DN as the identifier and the class X509CertificateCredentialsToDistinguishedNamePrincipalResolver should be used. When using a local LDAP, however, the X509CertificateCredentialsToIdentifierPrincipalResolver class can be used to only return the username that maps directly to the LDAP username.

Default Certificates

• To verify certificate authentication with the default CAS files you must make sure that the included testUser and testAdmin certificates are installed into your web browser. This has only been tested to work with Firefox. These certificates were provided in the Ozone Widget Framework and can be used in development environments.

1. • The sample certificate for testUser1 is ${ozone-widget-framework}/apache-tomcat-${version}/certs/testUser1.p12
     
     • password: password
   • The sample certificate for testAdmin1 is ${ozone-widget-framework}/apache-tomcat-${version}/certs/testAdmin1.p12
     
     • password: password

External Links

For more information on CAS configuration options and what each setting means, go to their documentation page: https://wiki.jasig.org/display/CASUM/X.509+Certificates