Previous Topic: CA SiteMinder® Federation Java SDK Programming InterfacesNext Topic: CA SiteMinder® Web Services Security Programming Guide for Java


Using the CA SiteMinder® Federation Java SDK

This section contains the following topics:

Program Flow at the Relying Party Using the Open Format Cookie

Delegated Authentication Using the Open Format Cookie

CA SiteMinder® Federation Java SDK Logging

Java SDK Sample Application Overview

Java SDK Sample Application Deployment

Java SDK Sample Application Execution

Java SDK Sample Application Customization

Customizing a SAML Assertion

Program Flow at the Relying Party Using the Open Format Cookie

A brief description of Java SDK program flow at the relying party is following.

  1. The Java Application creates an implementation class of the IFederationOpenIdentity interface using the IdentityFactory interface.
  2. The Java application calls the extractCookie() method to extract the cookie from the HttpServletRequest object. This method also decrypts the cookie and puts the identity attributes in the Storage Map.
  3. Alternatively, the Java application can also call the processCookie() method to extract all the attributes from a cookie object and set them in the Storage Map.
  4. The Java application can get values for all the attributes that are put in the Storage Map using the getAttributes(), getAttribute(), getAuthnContext(), getSessionID(), getNameID(), getNameIDFormat(), and getUserConsent() methods.
  5. The Java application can set values for attributes in the cookie using the setAuthnContext() and setUserConsent() methods.
  6. The Java application can determine whether the cookie is no longer valid by calling the isExpired() method, with or without specifying a skew time. The method compares the expiration time stamp on the cookie, adding in the optional skew time, with the current GMT time. If the GMT time is greater, the cookie has expired. The cookie's expiration time stamp is specified using setTimeToLive() method when the cookie is created.

See the Javadoc reference for detailed information about these methods.

Delegated Authentication Using the Open Format Cookie

Delegated authentication lets a third-party access management system authenticate a user and then share the user credentials with CA SiteMinder® deployed at the asserting party. These credentials are shared either through a cookie, or in a query string.

Note: This guide discusses delegated authentication using the cookie and the Java SDK. See the CA SiteMinder® Federation Partnership Federation Guide for information about delegated authentication using a query string.

If the third-party access manager and the asserting party intend to use a cookie to communicate the authenticated user ID, the access control application can follow these steps:

  1. Implement the CA SiteMinder® Federation Java SDK.
  2. Construct an implementation class for the IFederationOpenIdentity interface.
  3. Call the createCookie method.

To construct the implementation class, the access control manager must know the cookie zone and password configured in CA SiteMinder® Federation. These values are communicated out-of-band. The third-party access management system must be in the same cookie domain as the asserting party.

The constructor from the IdentityFactory.java class to use when creating a cookie for delegated authentication is listed following.

   /** 
    * Gets an implementation of the IFederationOpenIdentity interface.
    *
    * @param cryptoInstance A cryptographic string; supported values are
    *  listed in IdentityCrypto.java.
    * @param bUseHmac A Boolean value that indicates whether to use HMAC. 
    */
     public static IFederationOpenIdentity getInstance(cryptoInstance, bUseHmac)

The access control manager can encrypt the cookie itself using password-based encryption, or it can use one of the FIPS-compliant cryptographic strings. If you chose a FIPS-compliant string, use the encryption provided by the Java SDK.

Here is a code snippet example of the cookie creation:

IFederationOpernIdentity openID = IdentityFactory.getInstance(IdentityCrypto.AES128, false);
String domain = ".moon.com";
String zone = "FED";
String name = "CryptoID"
String password = "";

openID.initCookieInfo(domain, zone, name, password);

openID.setLoginID = "TomJones";

openID.createCookie(HttpResponse);

The createCookie method uses the login ID to create a cookie value that is encrypted and added to the HttpSevletResponse object. After the request is redirected, the servlet container automatically passes the cookie.

CA SiteMinder® Federation Java SDK Logging

The default Java SDK logger writes messages to the standard output stream. Logging is disabled by default.

To enable CA SiteMinder® Federation Java SDK logging

  1. Copy the sdkloggingconfig.properties file from the sdkroot\sample folder and place it in any desired folder. Be sure that the folder is in the CLASSPATH.
  2. Set the the value of the sdk.logging.enable parameter to Y in the sdkloggingconfig.properties file.

Logging is enabled.

Java SDK Sample Application Overview

The Java SDK sample application simulates a relying party Java application. The application consumes the cookie sent by the CA SiteMinder® Federation deployment running at the relying part of the federation partnership.

The sample application demonstrates how a Java application can get the cookie from the incoming request and extract user identity information and the assertion attributes that are sent to the relying party. The sample application requires that CA SiteMinder® Federation is installed at the relying party and is configured to redirect the user to the URL of the sample application servlet.

Java SDK Sample Application Deployment

Deployment of the Java SDK sample application requires installing Tomcat and CA SiteMinder® Federation at the relying party.

To deploy the Java SDK sample application

  1. Install the Java SDK package at any preferred location.
  2. Set the environment variable FEDSDKROOT to the installation Directory of Java SDK.

    Note: The value of FEDSDKROOT points to the location of the SDK directory. Example: C:\Program Files\CA\Federation Manager\sdk.

    This environment variable is set automatically on Windows, but must be exported manually on UNIX platforms.

  3. Install Tomcat 5.0 and set the TOMCAT_HOME environment variable to point to the Tomcat root folder.

    Note: Tomcat must be installed on a different system from the one CA SiteMinder® Federation is installed on.

  4. Deploy FEDSDKROOT\sample\javasdk/war to the Web server by copying it to the TOMCAT_HOME\webapps\ folder.
  5. Start the Tomcat server.
  6. Try accessing the link “http://<FQDN of Tomcat Host>:<port num>/” to determine whether Tomcat is up and running.
  7. When using the open format cookie, update fedsample.properties in the TOMCAT_HOME\webapps\javasdk\WEB-INF\classes folder as follows:
  8. The following parameters must be updated if you are testing light weight provisioning:
  9. Update the sdkloggingconfig.properties file to enable logging. Logging is disabled by default.
  10. Install CA SiteMinder® Federation at the relying party of a Federation partnership and define an asserting party-relying party partnership.
    1. Select appropriate Redirect mode.
    2. Specify the Target URL of the partnership. Enter one of the following:

The sample application is now deployed and ready to run.

Java SDK Sample Application Execution

After you have installed Tomcat and CA SiteMinder® Federation, you can run the Java SDK sample application.

To run the Java SDK sample application

  1. Start the Tomcat Server where the sample application is deployed:
  2. Run the configured federation transaction to redirect to the SDK Sample Application.

    The sample application decodes the legacy cookie and displays the user identity information contained in the cookie.

Java SDK Sample Application Customization

The sample application can be modified using build.bat or build.sh scripts to regenerate the fedsdksample.jar.

To customize the sample Java application

  1. Modify SpSideServlet or SpSideAttributeServlet.java as desired.
  2. Verify that the JDK is installed and JAVA_HOME is set appropriately for your JDK installation.
  3. Run build.bat (Windows) or build.sh (UNIX) to build the fedsdksample.jar file.

The customized version of the sample application is ready to run.

Customizing a SAML Assertion

Security domains exchange authentication and authorization using data packages named assertions. The Security Assertion Markup Language (SAML) is an open standard that specifies the format of an assertion. A federated partnership consists of an identity provider (producer of an assertion) and a service provider (consumer of an assertion).

An enterprise can modify the content of an assertion based on the business agreements between the federated partners. For example, one partner can require user-friendly name equivalents for the attributes in the assertion. Or, a partner can opt to include the XML-type designation for each attribute in the assertion.

CA SiteMinder® Federation creates SAML assertions with its implementation of the AssertionGeneratorPlugin.java interface. An Application Developer can enhance the contents of the SAML assertion by overwriting the existing implementation class.

The diagram shown following illustrates the process of creating a custom assertion generator plug-in.

Diagram showing the process of customizing a SAML assertion

The process of customizing a SAML assertion includes these steps:

  1. Implement the Java assertion generator plug-in interface.
  2. Deploy the new assertion generator plug-in .
  3. Configure the assertion generator plug-in in the CA SiteMinder® Federation UI.
Implement the Java Assertion Generator Plug-in Interface

You create a custom assertion generator plug-in by implementing the AssertionGeneratorPlugin.java interface. The minimum requirements for the implementation class are listed following.

Follow these steps:

  1. Provide a public default constructor method that contains no parameters.
  2. Provide code that helps ensure that the implementation is stateless, so that many threads can use a single plug-in class.
  3. Include a call to the customizeAssertion method.

    Example

    In this example, imagine that the application developer defines handler.updateNameID to create user-friendly name attributes.

    /**
         * <p>Performs Assertion Generator callout functionality to customize the
         * SAML assertion in the <code>AssertionGeneratorPlugin</code> object and
         * returns a result.</p>
         * @param apiContext     A context object that provides methods for sending
         *                       log, trace, and error messages to the Policy Server. Use the APIContext.getAttrMap() method to retrieve attributes posted by the application specified in the Application URL.
         * @param userContext    A context object that allows a custom object to set
         *                       and retrieve information about a user in a user
         *                       directory. The information includes user
         *                       attributes and directory attributes associated
         *                       with the user.
         * @param pluginParam    The string for Assertion plug-in parameters. 
         * @param inputAssertion    The current XML token representing the SAML Assertion.
         * @param outputAssertion   The final XML token representing the SAML Assertion.
         * @return  0 if assertion is customized successfully, or -1 if no customization or an error occurred.
         * If the method fails, the outputAssertion is ignored.
         * @throws java.lang.Exception For cases when the customization terminates unexpectedly.
         *
         **/
        public int customizeAssertion(APIContext apiContext, UserContext userContext,String pluginParam,
         String inputAssertion, final StringBuffer outputAssertion) throws Exception {
            if (inputAssertion == null || inputAssertion.equals("")) {
                // Indicates non-zero for an error.
                apiContext.trace(PLUGIN_TAG, "Received null or empty response for customization");
                return -1;
            }
            apiContext.trace(PLUGIN_TAG, "Entering customizeAssertion");
            StringBuffer newAssertion = new StringBuffer(inputAssertion);
    
            try
            {
                Saml1AssertionHandler handler =
                    initHandler(apiContext, userContext);
                handler.updateNameID(newAssertion);
                handler.addAttributes(pluginParam, newAssertion);
            }
            catch(Throwable th)
            {
                apiContext.error("SAML1AssertionSample: " + th.getMessage());
                StringWriter writer = new StringWriter();
                th.printStackTrace(new PrintWriter(writer));
                writer.flush();
                apiContext.trace(PLUGIN_TAG,
                                 "Error customizing Assertion:\n" + writer.toString());
                
                apiContext.trace(PLUGIN_TAG, "Done customizeAssertion");
                return -1;
            }
    
            outputAssertion.append(newAssertion);
    
            apiContext.trace(PLUGIN_TAG, "Done customizeAssertion");
    
            // return "success"
            return 0;
        }
    

    Note: The syntax requirements and use of the parameter string that is passed into the customizeAssertion method is the responsibility of the custom object.

Deploy the Assertion Generator Plug-in

After you have coded your implementation class for the AssertionGeneratoPlugin.java interface, compile it and verify that CA SiteMinder® can find your executable file.

Follow these steps:

  1. Compile the assertion generator plug-in code in one of the following ways:
  2. In the JVMOptions.txt file, modify the -Djava.class.path value so it includes the classpath for the plug-in. Locate the JVMOptions.txt file in the directory federation_mgr_home\siteminder\config.

    You can place the plug-in jar in any directory and have the JVMOptions.txt file point to it. To use the sample plug-in, modify the classpath to point to fedpluginsample.jar; however, do not modify the classpath for smapi.jar.

    Note: To use Apache Xerces or Xalan in your plug-in, use the Xerces or Xalan binary files installed with CA SiteMinder®. The binaries are not installed with the CA SiteMinder® Federation SDK. Using these files is necessary for compatibility reasons.

Configure the Assertion Generator Plug-in in the UI

To configure the assertion generator plug-in, you provide values for settings in the Administrative UI.

Note: Do not configure the plug-in settings until you deploy the plug-in.

Follow these steps:

  1. Log on to the Administrative UI.
  2. Navigate to the Assertion Configuration step of the Partnership wizard for the partnership you want to modify.
  3. Enter values for the following fields:
    Plug-in Class

    Specifies the Java class name of the plug-in. Enter a name. This plug-in is invoked at run time.

    Example: com.mycompany.assertiongenerator.AssertionSample

    The plug-in class can parse and modify the assertion, and then return the result to CA SiteMinder® for final processing. Specify an assertion generator plug-in for each relying party. A compiled sample plug-in is included in the directory federation_mgr_sdk_home/jar.

    Plug-in Parameter

    (Optional). Specifies the string that CA SiteMinder® passes to the plug-in as a parameter at run time. The string can contain any value; there is no specific syntax to follow.

    The plug-in interprets the parameters that it receives. For example, the parameter is the name of an attribute, or the string can contain an integer that instructs the plug-in to do something.

The assertion generator plug-in is coded, compiled, and in place. The CA SiteMinder® assertion generator creates enhanced assertions as defined by the federation partners.