How to configure your web application to authenticate users with X509 Application Certificates

Quick Links to:

Using X509 Application Certificates with CSF Security version 2

Using X509 Applicaiton Certificates with CSF Security requires that the following be done:

• add three new beans to your application's applicationContext spring security xml,
• add one new bean to your application's applicationContext conf xml,
• create a new allowEntities.properties file.

Each of the above is described below.

1. Add the following 3 beans to your application's appicationContext spring security xml.
   
   You many already have a filterChainProxy already defined in your security XML.  If the filterChainProxy is already defined, then replace it with the filterChainProxy given below.
   
   The ssoX509SecurityContextPersistenceFilter and the ssoX509AuthenticationProcessingFilter are new beans.
   

       <bean id="filterChainProxy" class="org.springframework.security.web.FilterChainProxy">
           <security:filter-chain-map path-type="ant">
               <security:filter-chain pattern="/css/**" filters="logoutFilter" />
               <security:filter-chain pattern="/images/**" filters="logoutFilter" />
               <security:filter-chain pattern="/js/**" filters="logoutFilter" />
               <security:filter-chain pattern="/docs/**" filters="logoutFilter" />
               <security:filter-chain pattern="/**" filters="ssoX509SecurityContextPersistenceFilter,
              		logoutFilter,
              		ssoX509AuthenticationProcessingFilter,
              		basicAuthenticationProcessingFilter,
              		exceptionTranslationFilter,
              		filterSecurityInterceptor"
               />
           </security:filter-chain-map>
       </bean>
   
       <bean id="ssoX509SecurityContextPersistenceFilter" class="edu.mit.csf.security.spring.filter.SsoX509SecurityContextPersistenceFilter"/>
       
       <bean id="ssoX509AuthenticationProcessingFilter" class="edu.mit.csf.security.spring.filter.SsoX509AuthenticationProcessingFilter">
           <property name="authenticationManager" ref="authenticationManager"/>
           <property name="allowedEntities" ref="allowedEntities"/>
       </bean>
   

2. Add the following bean to your application's appicationContext conf xml.
   
   For Tomcat servers:

       <bean id="allowedEntities" class="edu.mit.csf.base.configuration.CompactApacheApplicationConfiguration" init-method="init">
           <property name="locations">
               <list>
                   <value>file:${user.dir}/<application identifier>/allowedEntities.properties</value>
               </list>
           </property>
       </bean>
   

   Notice that in the <value> line there is a <application identifier> entry.  You must replace the <application identifier> with your application identifier.  For example: if your application identifier is addDrop, then the <value> line would be:

   <value>file:${user.dir}/addDrop/allowedEntities.properties</value>
   

   
   For OC4J servers:

       <bean id="allowedEntities" class="edu.mit.csf.base.configuration.CompactApacheApplicationConfiguration" init-method="init">
           <property name="locations">
               <list>
                   <value>file:${user.home}/allowedEntities.properties</value>
               </list>
           </property>
       </bean>
   

3. Create a new allowedEntities.properties file and place it in either the ${user.dir}/<application identifier> directory for apache/tomcat servers or in the ${user.home} for OC4J servers.
   The entries for this propery file must be of the following syntax:
   
                  <application certificate CN>=yes
   
   Here are two entries for commonly used application certificates:

   # for the registrar application certificate
   registrar.app.mit.edu=yes
   # for the registrar-test application certificate
   registrar-test.app.mit.edu=yes
   

Things that you should be aware of

These notes pertain to the ssoX509SecurityContextPersistenceFilter and the ssoX509AuthenticationProcessingFilter.

1. These filters are designed to work with both Touchstone authentication and/or X509 Application Certificate authentication.
2. Touchstone authentication always takes presidency over X509 Application Certificate authentication.
3. For each http request based on X509 Application Certificate authentication, a new spring security context will be created when the request is received and destroyed when request has completed.
4. For each http request based on Touchstone authentication:
   1. A check is made to see if there is an existing security context for the request.
   2. If there is no existing security context, then a new security context is created and will be saved when the request has completed.
   3. If there is an existing security context, then existing security context is retrieve and a check is made to verify that the security context principal is identical to the Touchstone remote user.
   4. If the security context principal is different from the Touchstone remote user, then the existing security context is ignored, a new security context is created and will be destroyed when the request has completed.
   5. If the security context principal is identical to the Touchstone remote user, then the existing security context is used and will be saved when the request has completed.