63 Introducing Customizable Single Sign-On Facility in WEM Framework

WEM Framework’s authentication includes a customization layer called the Oracle Customizable Single Sign-On (CSSO) facility. You can use the CSSO facility’s authentication extensions to create a custom SSO solution, without directly modifying the CAS configuration. When you implement the login behavior, the Spring configuration injects these extensions into the CAS configuration.

Topics:

63.1 About Customizing Login Behavior for the WEM Framework

You need to extend the CSSO facility’s pre-packaged classes to implement a custom SSO solution. The CSSO facility’s default Spring configuration file identifies the classes to Spring for instantiation.

When you customize WEM SSO, you can use a different login screen, add credentials other than a user name/password pair, or use an external authentication authority to authenticate WebCenter Sites users. A custom SSO implementation consists of:

Three Java classes (which extend the default classes)
A configuration file that exposes the new classes to the framework

The default CSSO classes defer all credential discovery and authentication to the standard WEM SSO implementation. These classes are instantiated by the customdefaultWEMSSObean.xml Spring configuration file. Extending the default CSSO classes enables you to define methods which specify the behavior of your custom SSO solution. For example, you can create a different authentication for browser access, REST, or thick client authentication or both. When you extend the default CSSO classes, you must create a custom Spring configuration file that identifies the custom classes and exposes them to the WEM Framework.

The CSSO facility provides a complete SSO sample (including Java source files) that replaces the default WEM login behavior with custom login behavior. The sample SSO implementation demonstrates two different types of authentication: user name/password pair (with an additional domain field) and external user identifier. The external identifier maps a user authenticated by an external authentication authority to a WebCenter Sites system user.

The rest of this chapter provides information about the default components of the CSSO facility and instructions on implementing a custom SSO solution. To see an example of a custom SSO solution, the end of this chapter provides information about the CSSO sample, and instructions for running the sample.

63.2 About Components of the Default CSSO Implementation

Your starting point for customizing your SSO implementation is the default components of the CSSO facility. These components are the default classes that you extend to create your SSO solution and a Spring configuration file that instantiates these classes.

The com.fatwire.wem.sso.cas.custom.basis package (shown in the table below) contains the default classes that are included in the CSSO facility. The default Spring configuration file (customdefaultWEMSSObeans.xml) instantiates these classes to implement the default WEM login behavior.

Note:

The CSSO facility provides a complete SSO sample that replaces the default WEM login behavior with custom login behavior. See Running the CSSO Sample Implementation.

Table 63-1 com.fatwire.wem.sso.cas.custom.basis

Class	Description
`CustomAuthenticator.java`	Implements the `CustomAuthentication` interface. This class controls the behavior of the login sequence and handles authentication requests. By default, it returns to the WEM Framework to complete the authentication by displaying the standard WEM login form.
`CustomConfiguration.java`	Provides access to the properties that are set in the default Spring configuration file. You can extend this class when additional properties are required for a custom SSO implementation.
`CustomCredentials.java`	Provides a standard set of credential values for custom authentication. You can extend this class when additional attributes are needed for a custom SSO implementation.

The com.fatwire.wem.sso.cas.custom.interfaces package (shown in the table below) defines the custom authentication interfaces.

Table 63-2 com.fatwire.wem.sso.cas.custom.interfaces

Class	Description
`CustomAuthenticator.java`	Defines the interfaces that must be implemented by any custom SSO solution.
`CustomRestCodec.java`	Defines the interfaces that must be implemented to encode and decode a custom REST authentication token that is not user name/password based.

63.3 Configuring and Deploying Custom SSO Behavior

You begin configuring and deploying your custom SSO by extending the CSSO facility’s default classes. Then, you identify the new Java classes to Spring by creating a custom Spring configuration file. This file instantiates the classes, exposing them to the CSSO framework.

To configure and deploy custom SSO behavior:

Extend the default CSSO classes: CustomAuthenticator.java, CustomConfiguration.java, and CustomCredentials.java (contained within the com.fatwire.wem.sso.cas.custom.basis package):
1. Create Java classes that extend the default CSSO classes.
2. Package the Java classes you created in a jar file, then place the jar file in the classpath of the CAS servlet (in cas/WEB-INF/lib).
For more information, see About Extending the Default CSSO Classes.
Set the username and password properties in the customResolverCredential.xml file, located in the spring-configuration folder (in cas/WEB-INF). For instructions, see Settings Resolver Credentials.
Identify your new Java classes to Spring for instantiation:
1. Create a Spring configuration file that contains all the custom class names and properties for your SSO implementation.
2. Place the custom Spring configuration file in the spring-configuration folder (in cas/WEB-INF/).
3. Remove the .xml extension from the default Spring configuration file (customDefaultWEMSSObeans.xml).
For more information, see About Identifying Your Java Classes to Spring for Instantiation.
If an external authentication authority is used to authenticate a user, map the external user identifier to the appropriate WebCenter Sites system user name, unique identifier, and ACLs. For instructions, see Mapping External User Identifiers to WebCenter Sites Credentials.
Restart the CAS web application. For more information, see Restarting the CAS Web Application.

The rest of this section provides detailed information for the steps outlined above.

63.3.1 About Extending the Default CSSO Classes

An SSO implementation is a set of called methods that are specified in the default CSSO classes CustomAuthenticator.java, CustomConfiguration.java, and CustomCredentials.java. To replace the default WEM login behavior with custom behavior, you must create Java classes that extend the default CSSO classes. By extending the CSSO classes, the methods specified in the default CSSO classes are replaced by the methods specified in the custom classes for the functionality you want to change.

The three classes (located in the com.fatwire.wem.sso.cas.custom.basis package) that must be extended to implement a custom SSO solution are:

CustomConfiguration.java: Provides access to the externally defined properties that are specified in the default Spring configuration file. By default, this class exists only as a placeholder for injecting properties into the SSO configuration from the Spring configuration file. Extend this class to include additional properties, such as URLs or other configuration information, that are specific to your custom SSO implementation.
CustomCredentials.java: Provides a standard set of credential values for custom authentication. This class is built and populated by the web-flow handler or the custom REST authenticator. By default, this class defines the standard UsernamePasswordCredentials object (provided by CAS), which collects all information required to complete user authentication in the following properties; username, userId, and currentACL. The values of these properties populate the attributes map used by the authenticator (CustomAuthenticator.java), to perform the actual user authentication.

Extend this class to require additional credentials for your custom SSO solution. For an example of how this class passes user information to the authenticator to complete user authentication, refer to the code of the sample CSSO class SampleCredentials.java (located in the Misc/Samples/WEM/Samples/CustomizableSSO/lib folder).

CustomAuthenticator.java: Implements the CustomAuthentication interface. This class controls the behavior of the login sequence and handles authentication requests. By default, it returns to the WEM Framework to complete the authentication by displaying the standard WEM login form.

Note:

The default CustomAuthenticator.java class is the most important class because it contains all the authentication methods for an SSO implementation.

All authentication decisions and CAS web-flow actions are directed to this class for action. CAS web-flow performs several steps, one of which invokes the performLoginAction method. This method displays a login form or communicates with an external authentication authority.

This class also defines the static method callCsResolverPage which maps an external user to a WebCenter Sites user. If your custom SSO implementation uses an external authentication authority to authenticate users, the callCsResolverPage method must define the unique name for the CSSO authenticator. For more information, see Mapping External User Identifiers to WebCenter Sites Credentials.

The following is a complete interface description of the methods this class implements:

static final int SUCCESS  = 0;
static final int GOTOWEM  = 1; 
static final int FAILURE  = 2; 
static final int REDIRECT = 3; 
static final int ERROR    = 4;
static final int REPEAT   = 5; 

/**
 * Called from UserAuthentication handler to check for alternate 
 * credentials and validate appropriately. 
 * @param userCredentials
 * @return
 */
public int authenticate(com.fatwire.wem.sso.cas.custom.basis.CustomCredentials userCredentials);

/**
 * Called from CSAuthenticationHandler to check for REST user
 * credentials and validate appropriately.
 */
public int authenticateRest(UsernamePasswordCredentials restCredentials);

/**
 * Called from CSAuthenticationHandler to check is username/password
 * combination is detected. 
 */
public boolean checkRestCredentials(String token);

/**
 * Called from CSAttributeDAO to check for encoded credentials and
 * if so then return the correct username for DAO processing.
 * @param username
 * @return
 */
public String resolveRestUsername(String username);

/**
 * Called from LoginViewAction to handle login view processing. This 
 * method allows the calling of internal CAS methods. 
 * @param context
 * @param userAuthentication
 * @param centralAuthenticationService
 * @return
 */
public int performLoginAction(RequestContext context,
CustomAuthentication userAuthentication,
CentralAuthenticationService centralAuthenticationService);

/**
 * Called from casLogoutView to perform sign in cleanup
 * @param request
 * @param response
 */
public void performLogoutAction(HttpServletRequest request, HttpServletResponse response);

63.3.2 Settings Resolver Credentials

The customResolverCredentials.xml file, located in the spring-configuration folder (in cas/WEB-INF), defines the resolver credentials externally, so the credentials are encrypted independent from the custom SSO bean definitions. If an external authentication authority is used to authenticate users, you must set the username and password properties in the customResolverCredential.xml file and then reference this file in the Spring configuration file. (See About Creating a Spring Configuration File.)

To set resolver credentials:

Open for editing the customResolverCredentials.xml file, located in the spring-configuration folder (in cas/WEB-INF). The file looks as follows:

<?xml version="1.0" encoding="UTF-8" ?> 
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:p="http://www.springframework.org/schema/p" xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd">
  <description>This defines the SitesCS username/password credentials needed for identity resolution</description> 
<bean id="resolverCredential" class="com.fatwire.security.common.SecurityCredential">
  <property name="username" value="theUsername" /> 
  <property name="password" value="theUserpassword" /> 
  <property name="csfKeyname" value="passwordkey" /> 
  </bean>
  </beans>

Set the username and password properties.
- username – If an external authentication authority is used to authenticate a user, this property must specify the user name of a WebCenter Sites user who has permissions to read the SystemAttr table. This user name is used when the customCsResolver page queries the WebCenter Sites database to resolve an external user identifier into a registered WebCenter Sites user.
- password – If an external authentication authority is used to authenticate a user, this property must specify the password of the user identified by the username property.
For example:
```
<property name="username" value="fwadmin" /> 
<property name="password" value="xceladmin" />
```

See Mapping External User Identifiers to WebCenter Sites Credentials.

63.3.3 About Identifying Your Java Classes to Spring for Instantiation

All customization settings for an SSO implementation are specified in a single Spring configuration file, located in the spring-configuration folder (in cas/WEB-INF).

This section includes the following topics:

63.3.3.1 About Creating a Spring Configuration File

The classes and properties for the default SSO implementation are defined by the Spring configuration file customDefaultWEMSSObeans.xml, which is located in the spring-configuration folder (in cas/WEB-INF). When customizing CSSO, either create a new Spring configuration file or customize the classes and properties referenced in the default Spring configuration file. The rest of this section focuses on the second option.

The default Spring configuration file contains several bean identifiers that reference the classes and properties required for the default SSO implementation. The customUserConfiguration bean references the CustomConfiguration.java class and the customUserAuthenticator bean references the CustomAuthenticator.java class. These classes are instantiated by the Spring configuration file, which uses them to create the persistent objects for the SSO implementation's authentication process. To create a custom SSO solution, you must reference your custom Java classes within these beans.

Note:

The CustomCredentials.java class is not referenced by the Spring configuration file. Instead, you provide the code that instantiates this object in the performLoginAction method, defined in the default CSSO CustomAuthenticator.java class. This method creates a custom credentials object for every login request and passes it into CAS for authentication.

The customUserConfiguration bean also identifies the configuration properties which supply system information to the default SSO implementation. These properties are set with values of the environment on which you are deploying the SSO implementation. When you customize the Spring configuration file, you must modify the values of the properties to match the custom SSO implementation's environment, or include additional properties required by the custom SSO implementation.

Extending the CustomConfiguration.java class enables you to define additional properties in the Spring configuration file's customUserConfiguration bean. For example, if you created a JSP file that provides a custom login form for your SSO implementation, create a property that specifies the location of the JSP file by extending the CustomConfiguration.java class.

The rest of this section analyzes the classes and properties that are referenced in the default Spring configuration file (customDefaultWEMSSObean.xml).

The Default Spring Configuration File

<?xml version="1.0" encoding="UTF-8" ?>
<beans xmlns="http://www.springframework.org/schema/beans"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:flow="http://www.springframework.org/schema/webflow-config"
                xmlns:p="http://www.springframework.org/schema/p"
                xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
                http://www.springframework.org/schema/webflow-config http://www.springframework.org/schema/webflow-config/spring-webflow-config-1.0.xsd">
<!--  Custom SSO Bean definitions. This file defines either the default CAS/SSO configuration or a special user implementation. No other CAS configuration files are modified for a custom implementation    -->
<!--  This file defines the resolver credentials externally so the credentials can be encrypted independent from the custom SSO bean definitions    -->
 <import resource="customResolverCredential.xml" /> 
 <!--  This bean is never modified. It defines the web-flow controller which always passes control into the custom authenticator    -->
 <bean id="customUserLoginAction"   class="com.fatwire.wem.sso.cas.web.CustomLoginViewAction"
p:centralAuthenticationService-ref="centralAuthenticationService"
p:customAuthentication-ref="customUserAuthenticator" />
 <!--  This bean is usually not modified. Override it when there needs to be a custom encoding for information passed between the web-flow and any external component    -->
 <bean id="customRestCoder" class="com.fatwire.wem.sso.cas.custom.basis.CustomRestTokenCoding" />
 <!--  Modify this bean with a custom configuration implementation class when additional parameters are needed for a custom implementation    -->
 <bean id="customUserConfiguration" class="com.fatwire.wem.sso.cas.custom.basis.CustomConfiguration"
p:casLoginUrl="@CSConnectPrefix@://@hostname@:@portnumber@/cas/login"
p:resolverUrl="@CSConnectPrefix@://@hostname@:@portnumber@/@context-path@/custom/customCsResolver.jsp" p:resolverCredential-ref="resolverCredential" p:traceFlag="false" />
 <!--  Modify this bean with a customAuthentication class for a custom implementation.   -->
 <bean id="customUserAuthenticator" class="com.fatwire.wem.sso.cas.custom.basis.CustomAuthenticator"
p:customConfiguration-ref="customUserConfiguration"
p:customRestCoder-ref="customRestCoder" />
</beans>

Analyzing the Default Spring Configuration File

The customResolverCredentials.xml file in which you specified the resolver credentials externally is imported. See Settings Resolver Credentials.
The customUserConfiguration bean, which references the default CSSO customConfiguration.java class. See About Extending the Default CSSO Classes.
The resolverURL property and the traceflag property are referenced.
- resolverURL: If an external authentication authority is used to authenticate a user, this property must specify the full URL to the customCsResolver page, located on WebCenter Sites. The customCsResolver page obtains a user's external identifier and queries the WebCenter Sites database to retrieve the user's WebCenter Sites credentials. The domain and port number specified in this property must be modified if the values specified are different from the WebCenter Sites installation.
  
  See Mapping External User Identifiers to WebCenter Sites Credentials.
- traceflag: This property specifies whether the trace log, which provides information about the custom SSO layer, is enabled. This property can be set to either true or false.
The customUserAuthenticator bean references the default CSSO CustomAuthenticator.java class. See About Extending the Default CSSO Classes.

63.3.3.2 About Placing Your Spring Configuration File

The default Spring configuration file, which specifies the classes and properties for the default WEM login behavior, is located in the spring-configuration folder (in cas/WEB-INF). Placing your own file into the same location requires deactivating the default file (by removing or changing the file's .xml extension). This is because Spring loads all Spring configuration files contained in the spring-configuration folder (in cas/WEB-INF) and merges those files into a single configuration. As both the custom and the default files specify the same bean identifiers, only one of the files can be recognized by the Spring configuration. Duplicate bean identifiers result in initialization failure.

Note:

Avoid deleting customDefaultWEMSSObeans.xml. Instead, remove or change the file's .xml extension. This way you can restore the file to return to using the default WEM login screen.

63.3.4 Mapping External User Identifiers to WebCenter Sites Credentials

The CSSO facility enables you to use an external authentication authority to authenticate WebCenter Sites users. When the external authentication authority validates the user's credentials, it associates a unique external identifier with that user. To complete WEM authentication, the user's external identifier must be mapped to the corresponding WebCenter Sites system user name, unique identifier, and ACLs by using the method callCsResolverPage (defined as a static method in the default CSSO class CustomAuthenticator.java).

To map an external identifier to a WebCenter Sites system user, ensure you have set the external authentication properties in the customResolverCredentials.xml file (see Settings Resolver Credentials). To implement mapping from an external identifier to the appropriate WebCenter Sites system credentials, do the following:

To implement mapping:

Define a unique CSSO authenticator name for the external authentication authority of your custom SSO implementation in the callCsResolverPage method (defined in your extended CustomAuthenticator.java class).

For example, the following callCsResolverPage method (defined in the Sample CSSO class SampleAutheticator.java) defines samplesso as the unique authenticator name:

Map<String,String>csTokens=callCsResolverPage(externalUserId, "samplesso")
Access the Admin interface as a general administrator (for example, fwadmin/xceladmin).
Under the Admin node, expand the User Access Management node and double-click User.
Select the user whose external identifier you want to map to WebCenter Sites credentials:
1. In the Enter User Name field, enter the name of the user.
2. In the Select Operation section, select the Modify User Attributes option.
3. Click OK.
  
  The Modify User form opens.
  
  Figure 63-1 Modify User Form
  
  Description of "Figure 63-1 Modify User Form"
In the User Name column, click the name of the user whose external identifier you want to map to WebCenter Sites credentials.

The User Attribute form opens.

Figure 63-2 User Attribute Form

Description of "Figure 63-2 User Attribute Form"
In the form, fill in the fields:
- In the Attribute Name field, enter the unique CSSO authenticator name (the name used to identify the external authentication authority). This name must match the unique name of the CSSO authenticator defined in the callCsResolverPage method (in step 1).
- In the Attribute Values field, enter the user's external identifier provided by the external authentication authority.
Click Modify to store the new attribute and value in the WebCenter Sites SystemUserAttr database table.
Repeat steps 3 through 7 for all users associated with an external identifier.

Analysis of the Mapping Process

When the callCsResolverPage method is called to map an external identifier to a WebCenter Sites system user, it defines the unique CSSO authenticator name for your custom SSO implementation. The method uses the external identifier and the unique CSSO authenticator name to map the external user to the WebCenter Sites system user. This map contains the following items, which are placed in the associated properties of the CustomCredentials object:

username: The user's WebCenter Sites user name.
currentUser: The user's WebCenter Sites unique identifier.
currentACL: The user's ACLs.

The CustomCredentials object passes the username, currentUser, and currentACL values to the authenticate method, defined in the CustomAuthenticator.java class. The authenticate method uses these values to build the response map, which identifies the WebCenter Sites user.

63.3.5 Restarting the CAS Web Application

To deploy your custom SSO implementation, restart the CAS web application.

Once CAS has been restarted, it uses the classes defined in the custom Spring configuration file, located in the spring-configuration folder (in cas/WEB-INF) to provide the custom login behavior.

63.4 Running the CSSO Sample Implementation

Try out CSSO’s sample SSO implementation (including Java source files) to replace the default WEM login behavior with custom login behavior. This sample includes the standard user name and password fields, an additional field for a user to specify a domain name, and a field for an external user identifier. You will find two different types of authentication in this implementation, user name/password pair (with an additional domain field) and user authentication through an external authentication authority.

Note:

The CSSO sample does not enforce any validation rules that apply to the fields on the login form. Fields are not checked for completeness and incorrect values are not reported. If authentication fails, the form is re-displayed without comment. When implementing this form in a production environment, ensure that all rules are enforced with suitable diagnostic messages if an error occurs.

For information about all the sample components included in the CSSO facility, see Sample CSSO Components.

To run the sample SSO implementation:

Deploy the customizable-sso-1.0.jar (Misc/Samples/WEM Samples/CustomizableSSO) by placing it in the CAS classpath (cas/WEB-INF/lib folder). This file contains the sample CSSO classes.

For more information about the sample classes, see Sample CSSO Classes.
Create a fatwire folder in the CAS web application context folder. Copy the SampleLoginform.jsp file into the fatwire folder.
Identify the classes contained in the customizable-sso-1.0.jar file to Spring for instantiation:
1. Copy the customSampleSSObeans.xml configuration file into the spring-configuration folder.
2. Modify the properties in the customSampleSSObeans.xml file to match your operation environment.
3. Remove the .xml extension from the customDefaultWEMSSObeans.xml configuration file's name, located in the spring-configuration folder.
For more information about the sample Spring configuration file, see Sample Spring Configuration File.
To use the external identifier credentials to validate users, define the mapping relationship between the external user identifier and the user's WebCenter Sites system credentials by adding the appropriate entry to the SystemUserAttr table.

For instructions, see Mapping External User Identifiers to WebCenter Sites Credentials.
Restart the CAS web application.

The sample login form opens, as shown in Figure 63-3.

Figure 63-3 Sample CAS Login Form

Description of "Figure 63-3 Sample CAS Login Form"

63.4.1 Sample CSSO Classes

The CSSO sample contains three Java classes which extend the default CSSO classes, providing the methods for the sample SSO implementation's login behavior:

SampleConfiguration.java: This class extends the default CSSO CustomConfiguration.java class to include a domain property (sampleDomain) which will be validated by an external authentication authority when a user provides a value for this field on the login form. The sampleDomain property is injected into the CSSO configuration by Spring.

This class also includes the sampleFormURL property which defines the sample login form that is called to retrieve a user's credentials. Standard and custom properties for this class are supplied through the sample Spring configuration file.
SampleCredentials.java: This class extends the default CSSO CustomCredentials.java class and collects all information required to complete user authentication. The SampleAuthenticator class uses the UsernamePasswordCredentials object when a user supplies a user name and password on the login form. If a user supplies an external identifier on the login form instead of user name and password credentials, the SampleCredentials object is created to provide that information to the authenticator (in this example, sample SSO class SampleAuthenticator.java).

In CAS, the type of credentials object that is created controls which authenticator is used (either standard or custom). If user name and password credentials are supplied on the login form, the standard WEM user name and password authenticator is used automatically. If an external identifier is supplied on the login form, the custom authenticator is called to authenticate the SampleCredentials object.
SampleAuthenticator.java: This class extends the default CSSO CustomAuthenticator.java class and contains all the authentication methods that are called by the CSSO framework. When the sample is deployed, all authentication decisions and web-flow actions, during CAS authentication, are directed to this class for action.

The performLoginAction method (extended by this class) displays the sample login form. When a user submits his credentials on the form, CAS returns to this method to process the input fields. Depending on the credentials that require verification, the method creates either a UsernamePasswordCredentials object or a SampleCredentials object, populated with the user's assigned credentials. The credentials object is then inserted into the CAS context (provided by CAS) and a TGT is requested. The TGT request triggers authentication of the credentials object. If authentication is denied, a ticket exception results in the login form being redisplayed. If the authentication is successful, the next action in the web-flow occurs. For example, acquire a ticket, append the ticket to the original service URL (the WebCenter Sites URL), and redirect back to the original service.

There are two authentication methods in this class. One handles authentication using SampleCredentials and the other authenticates REST requests, which are usually user name/password based. The sample introduces the sampleDomain value as a new value to be authenticated. In this case, the performLoginAction method encodes the user name, password, and sampleDomain values provided by the user and passes the encoded values to the UsernamePasswordCredentials object. The default WEM authentication handler detects the sampleDomain value and passes that credential to the authenticationRest method. This method decodes the sampleDomain value from the other values and verifies that the correct domain has been specified. Authentication fails if the value is incorrect. If the value is correct, this method encodes the user name and password back into the credentials object, and the default WEM authentication handler validates the user name and password.

63.4.2 Sample Spring Configuration File

The classes and properties for the sample SSO implementation are defined by the sample Spring configuration file customSampleSSObeans.xml (located in Misc/Samples/WEM Samples/CustomizableSSO/src/main/webapp/WEB-INF/spring-configuration).

This section includes the following topics:

63.4.2.1 Analysis of the Sample Spring Configuration File

The sample Spring configuration file contains the same bean identifiers as the default Spring configuration file. However, the property values are modified to implement the sample login behavior. For example, the customUserConfiguration bean references the SampleConfiguration.java class and the customUserAuthenticator bean references the SampleAuthenticator.java class.

The customUserConfiguration bean also identifies the configuration properties which supply system information to the sample SSO implementation. For example, since the SampleLoginForm.jsp file provides the browser form that is used by the sample to obtain a user's credentials, the SampleConfiguration.java class is extended to include the sampleFormURL property. This property specifies the full URL of the login page for the sample SSO implementation. The domain name and port number match the CAS server installation, and the path points to where this page was placed during set up.

The following is the sample Spring configuration file's code. For more information about the properties referenced by this file, see Analyzing the Default Spring Configuration File in About Creating a Spring Configuration File.

The Sample Spring Configuration File

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xmlns:flow="http://www.springframework.org/schema/webflow-config"
       xmlns:p="http://www.springframework.org/schema/p"       
       xsi:schemaLocation="http://www.springframework.org/schema/beans
       http://www.springframework.org/schema/beans/spring-beans-2.0.xsd        http://www.springframework.org/schema/webflow-config http://www.springframework.org/schema/webflow-config/spring-webflow-config-1.0.xsd">

<!-- Custom SSO Bean definitions. This file defines either the default CAS/SSO configuration or a special user implementation. No other CAS configuration files are modified for a custom implementation -->

<!-- This file defines the resolver credentials externally so the credentials can
    be encrypted independent from the custom SSO bean definitions -->
<import resource="customResolverCredential.xml" />

<!-- This bean is never modified. It defines the web-flow controller which always
    passes control into the custom authenticator -->
<bean id="customUserLoginAction" class="com.fatwire.wem.sso.cas.web.CustomLoginViewAction"
         p:centralAuthenticationService-ref="centralAuthenticationService"
         p:customAuthentication-ref="customUserAuthenticator"
         />
<!-- This bean is usually not modified. Override it when there needs to be a
    custom encoding for information passed between the web-flow and any external
    component -->
<bean id="customRestCoder" class="com.fatwire.wem.sso.cas.custom.basis.
        CustomRestTokenCoding"
        />
<!-- Modify this bean with a custom configuration class when additional parameters are needed for a custom implementation -->
<bean id="customUserConfiguration" class="com.fatwire.wem.sso.cas.sample.SampleConfiguration"
         p:casLoginUrl="http://localhost:8080/cas/login"
         p:resolverUrl="http://localhost:8080/cs/custom/customCsResolver.jsp"
         p:resolverCredential-ref="resolverCredential"
         p:traceFlag="false"
         p:sampleDomain="mydomain"
         p:sampleFormUrl="http://localhost:8080/cas/fatwire/SampleLoginForm.jsp"
         />
<!-- Modify this bean with a customAuthentication class for a custom implementation. -->
<bean id="customUserAuthenticator" class="com.fatwire.wem.sso.cas.sample.SampleAuthenticator"
         p:customConfiguration-ref="customUserConfiguration"
         p:customRestCoder-ref="customRestCoder"
         />

</beans>

63.4.2.2 Placing the Sample Spring Configuration File

To instantiate the sample classes, place the sample Spring configuration file in the spring-configuration folder (in cas/WEB-INF) and remove the .xml extension from the default Spring configuration file.

For more information, see About Placing Your Spring Configuration File.

63.4.3 Sample CSSO Components

The sample CSSO implementation's components are located in the /WEM Samples/CustomizableSSO folder. The folders described in the table below are included with the sample CSSO implementation.

Table 63-3 Sample CSSO Components

Folder	Description
`Misc/Samples/WEM Samples/CustomizableSSO`	Contains the `customizable-sso-1.0.jar` file. This `jar` file provides the classes of the executable code for the sample. To deploy the sample SSO implementation, place this `jar` file in the CAS classpath (`cas/WEB-INF/lib` folder).
`Misc/Samples/WEM Samples/CustomizableSSO/lib`	Contains all the third-party `jar` files required to compile the Java source files for the sample SSO implementation.
`Misc/Samples/WEM Samples/CustomizableSSO/src/main/dist`	Contains Word documents that explain the individual source components and operations of the sample implementation. Note: We recommend reviewing these documents before viewing the sample's source code.
`Misc/Samples/WEM Samples/CustomizableSSO/src/main/java`	The root folder for the Java source files.
`Misc/Samples/WEM Samples/CustomizableSSO/src/main/webapp/fatwire`	Contains `SampleLoginForm.jsp`. The JSP provides the browser form that is used by the sample to obtain a user's login credentials. Implementing the sample requires creating a `fatwire` folder in the CAS application context folder and copying the `SampleLoginForm.jsp` to that folder.
`Misc/Samples/WEM Samples/CustomizableSSO/src/main/webapp/WEB-INF/spring-configuration`	Contains the sample Spring configuration file `customSampleSSObeans.xml`, which defines the Spring bean definitions required by the sample SSO implementation. This file must be placed in the s`pring-configuration` folder (in `cas/WEB-INF`). The file that exists in the `spring-configuration` folder (`customDefaultWEMSSObeans.xml`) must be given an extension other than `.xml` or removed. Note: Save a copy of the `customDefaultWEMSSObeans.xml` file so it can be restored when you return to the standard WEM login screen.