Chapter 3 Customizing Federation Manager

This chapter contains procedures to customize the default installation of Sun Java™ System Federation Manager. It includes procedures on how to change the default data store, enable Secure Sockets Layer (SSL), and work with Sun Java System Policy Agents.

This chapter contains the following topics:

• General Customizations

• Using an LDAPv3–compliant Directory

• Configuring Federation Manager for Sun Java System Policy Agents

General Customizations

Federation Manager deploys as a single web archive (WAR) making it easy to install, integrate and customize. If there is a need to customize Federation Manager, you can go to the staging directory, make changes to the relevant files, archive the WAR again, and redeploy the new WAR file to your web container. The default staging directory is /var/opt/SUNWam/fm/war_staging. See Detailing the fmwar Syntax for information on regenerating a WAR.

In addition to the customizations described in this chapter, 8 Authentication contains a section on customizing the Authentication component of Federation Manager. For information, see Customizing Authentication.

Using an LDAPv3–compliant Directory

When Federation Manager is deployed, all server configuration and user data is stored in a flat file. After installation, Federation Manager can be reconfigured to retrieve this data from an LDAPv3–compliant directory. This section contains information on how this is done as well as information about the serverconfig.xml file which provides configuration information regarding the directory.

• Changing the Default Data Store for Configuration Data to an LDAPv3–compliant Directory

• Changing the Default Data Store for User Data to an LDAPv3–compliant Directory

• The serverconfig.xml File

Changing the Default Data Store for Configuration Data to an LDAPv3–compliant Directory

When Federation Manager is deployed, the server configuration data is stored in a flat file. After installation, Federation Manager can be reconfigured to retrieve this data from an LDAPv3–compliant directory. To proceed, you must follow this sequence:

1. Set up your LDAPv3–compliant directory.

   See Setting Up Your LDAPv3–Compliant Directory.

2. Install your instance of Federation Manager.

   See Chapter 2, Installing and Deploying Federation Manager.

3. Reconfigure the Federation Manager configuration data.

   See Modifying Federation Manager Configuration Data to Recognize an LDAPv3–compliant Directory.

4. Migrate the new data to the directory.

   See Building and Loading LDIF Configuration Data Using fmff2ds.

Setting Up Your LDAPv3–Compliant Directory

The following sections contain procedures for setting up the supported LDAPv3–compliant directories.

Although Federation Manager has only been tested on supported LDAPv3–compliant directories, it should work with any LDAPv3-compliant directory server.

This section contains the following procedures:

• To Set Up Sun Java System Directory Server as a Configuration Data Store

• To Set Up Microsoft Active Directory as a Configuration Data Store

To Set Up Sun Java System Directory Server as a Configuration Data Store

In order to change the Federation Manager data store for configuration data to Sun Java System Directory Server, follow the procedure described below in To Set Up Sun Java System Directory Server as a Configuration Data Store.

1. Install Directory Server based on the instructions in the Sun Java Enterprise System 2005Q4 Installation Guide for UNIX.

2. Install Federation Manager based on the instructions in Chapter 2, Installing and Deploying Federation Manager.

3. Configure Federation Manager to communicate with Directory Server based on the instructions in Modifying Federation Manager Configuration Data to Recognize an LDAPv3–compliant Directory.

4. Build the new LDAP-based configuration data from the flat file data, and load the data and accompanying schema into Directory Server based on the instructions in Building and Loading LDIF Configuration Data Using fmff2ds.

To Set Up Microsoft Active Directory as a Configuration Data Store

In order to change the Federation Manager data store for configuration data to Microsoft Active Directory, you must set up the directory and load the Federation Manager LDIF schema. The procedure is described in To Set Up Microsoft Active Directory as a Configuration Data Store.

When the Active Directory installation wizard asks you to type a new domain, you may type a non-existent domain as in xyz.com. In this example, the root suffix will be dc=xyz,dc=com.

1. Install Microsoft Active Directory in either a Microsoft Windows 2000 Advanced Server or a Microsoft Windows 2003 Advanced Server.

   The procedures for these installations can be found in your Active Directory documentation or on the Microsoft web site.

2. Install the Active Directory Schema Snap-in.

   Instructions for installing the Active Directory Schema Snap-in can also be found on the Microsoft web site

3. Open the Microsoft Management Console (MMC).

   Using this console you can load the LDIF schema into Active Directory.

4. Point your cursor to Active Directory Schema and hold the right mouse button down.

5. Select Operations Master... from the drop-down menu.

6. Check The Schema may be modified on this Domain Controller from the Change Schema Master" window and click OK.

   This enables schema modification. The administrator DN is cn=administator,cn=users,ROOT-SUFFIX.

7. Install and configure Federation Manager according to the information in Modifying Federation Manager Configuration Data to Recognize an LDAPv3–compliant Directory.

Modifying Federation Manager Configuration Data to Recognize an LDAPv3–compliant Directory

After installing your LDAPv3–compliant directory you must reconfigure certain of the Federation Manager configuration data before migrating it to the directory. If the Federation Manager WAR is exploded, you must restart the web container after making these changes. If the Federation Manager WAR is not exploded, make your changes in the staging directory (located by default in the IS_INSTALL_VARDIR/war_staging directory where IS_INSTALL_VARDIR is defined in the silent installation file detailed in The Silent Installation File), regenerate the WAR, and deploy the modified WAR. The following instructions assume that the WAR has been exploded.

• To Set Up Federation Manager for an LDAPv3–compliant Directory

• To Add a Second Instance of Federation Manager to the Server List

To Set Up Federation Manager for an LDAPv3–compliant Directory

Before You Begin

If Federation Manager is working solely against an LDAPv3–compliant directory, you must create two users in the directory with the correct read and write privileges to the ou=services tree: amadmin and dsameuser. See serverconfig.xml Users.

1. Install Federation Manager according to the instructions in Chapter 2, Installing and Deploying Federation Manager.

2. Edit the default ServerGroup in the serverconfig.xml file as follows:

   • Change the host, port, and type attributes of the Server tag to reflect your directory's installation.

   • Change the DirDN and DirPassword attributes of the User tag in both the proxy and admin entries to reflect an existing user DN and password (encrypted using ampassword). Alternately, you can  create a new administrator in the directory. This new user must have read, search, write and delete permission on the ou=services subtree of the directory information tree (DIT) containing the Federation Manager configuration data once the data store has been changed to Open LDAP.

     ---

     Note –

     Ensure the proper user permissions have been allocated. This should be done after running fmff2ds.

     ---

   • Change the values of the BaseDN to that of the parent DN containing the configuration data. For example, dc=sun,dc=com.

   See

3. Edit the AMConfig.properties file as follows:

   • Change the value of the com.sun.identity.sm.sms_object_class_name property to com.sun.identity.sm.ldap.SMSLdapObject.

   • If the DirDN specified in the step above is different from the default amadmin, you need to modify the com.sun.identity.authentication.special.users property by adding (or replacing) the specified DN of the directory's super user. This property may contain a pipe-separated list of user DNs as in: com.sun.identity.authentication.special.users=cn=dsameuser,ou=DSAME Users,dc=sun,dc=com|cn=administrator,cn=users,dc=sun,dc=com.

   AMConfig.properties is located in the /exploded-FM-WAR-directory/WEB-INF/classes directory where exploded-FM-WAR-directory is the directory to which the Federation Manager WAR was deployed.

4. Run fmff2ds according to the information in Building and Loading LDIF Configuration Data Using fmff2ds.

5. Restart the web container.

   Federation Manager is now communicating with Directory Server.

To Add a Second Instance of Federation Manager to the Server List

This procedure is useful when an LDAPv3–compliant directory is used for storing configuration data. If creating a second instance of Federation Manager by running fmwar, you will need to add the new instance to the Server List attribute of the original instance of Federation Manager before starting the new instance. The following procedure describes how to do this.

1. Login to the console of the original instance of Federation Manager as administrator.

2. Select the Configuration tab.

3. Select Platform under System Properties.

4. Enter the new instance in the Server List global attribute and click Add.

   The value is entered in the form protocol://host-name:port|instance-name. For example, http://host2.sun.com:81|02.

Building and Loading LDIF Configuration Data Using fmff2ds

fmff2ds is a command-line utility used to convert service configuration data from a flat file to an LDIF file. This utility does not work with user data. fmff2ds performs the following functions:

• Builds and loads an LDAP schema for your directory based on included templates.

• Builds an LDIF file from a configuration data flat file and loads it into the directory.

The syntax for fmff2ds is:

fmff2ds [-a]  -h  directory-server-host -p directory-server-port -r root-suffix -f flat-file 
-u userDN [-w userPW] -j Java-directory

fmff2ds -V

fmff2ds -?

where:

Changing the Default Data Store for User Data to an LDAPv3–compliant Directory

After installing Federation Manager, its components are configured to work with user data that is stored in flat files. Following are the steps to change the default data store for user data from a flat file to an LDAPv3–compliant directory. User data can then be migrated to the directory based on the loaded LDIF schema. The following schemas are included with Federation Manager for this purpose.

Federation Manager does not contain scripts to migrate existing user data. Transferring any existing user data is outside the scope of this guide.

To Change the Default Data Store for User Data

If the Federation Manager WAR is exploded, you must restart the web container after making these changes. If the Federation Manager WAR is not exploded, make your changes in the staging directory, regenerate the WAR, and deploy the modified WAR. The following instructions assume that the WAR has been exploded.

1. Install your LDAPv3–compliant directory according to the product's documentation.

2. Locate the LDIF schema file for your directory server under /FederationManager-base/SUNWam/fm/ldif/.

   • Use fm_liberty_sds_schema.ldif if migrating data to Sun Java System Directory Server.

   • Use fm_liberty_ad_schema.ldif if migrating data to Microsoft Active Directory.

     You will need to replace the value of the ORG_ROOT_SUFFIX property with the appropriate root suffix before loading.

   • For all other LDAPv3–compliant directories, create an LDIF schema file accordingly.

3. Load the appropriate LDIF schema file into your directory by typing:

   ldapmodify -a -c -h host -p port -D bindDN -w bindpwd -f ldif-file

4. Enable the equality index for the iplanet-am-user-federation-info-key property in your directory server.

   If using Active Directory, indexing is already enabled through the attribute schema definition.

5. Edit the AMConfig.properties file by changing the value of the com.sun.identity.common.datastore.provider.default property from com.sun.identity.common.FileDataStoreProvider to com.sun.identity.common.LDAPDataStoreProvider

   AMConfig.properties is located in the /FederationManager-base/fmwar/web-src/WEB-INF/classes directory.

6. Modify the userdefault ServerGroup in the serverconfig.xml file as follows:

   • Change the host, port, and type attributes of the Server tag to reflect your directory's configuration.

   • Change the DirDN and DirPassword attributes in both the proxy and admin User tags to reflect an existing user DN and password (encrypted using ampassword). Alternately, you can  create a new administrator in the directory. This new user must have read, search, write and delete permission on all users to be managed.

   • Change the value of the BaseDN to that of the people container of your directory. For example, ou=People,dc=sun,dc=com.

   serverconfig.xml is located in the /exploded-FM-WAR-directory/WEB-INF/config directory where exploded-FM-WAR-directory is the directory to which the Federation Manager WAR was deployed.

7. Restart the web container.

The serverconfig.xml File

The serverconfig.xml file provides configuration information to Federation Manager regarding the LDAPv3–compliant directory being used as its data store. serverconfig.xml is located in the /exploded-FM-WAR-directory/WEB-INF/config directory where exploded-FM-WAR-directory is the directory to which the Federation Manager WAR was deployed. It contains the parameters used to establish the LDAP connection pool to the LDAPv3–compliant directory.

Example 3–1 serverconfig.xml

<?xml version="1.0" encoding="XML_ENCODING" standalone="yes"?>
<!--
    Copyright (c) 2004 Sun Microsystems, Inc. All rights reserved
    Use is subject to license terms.
-->

<iPlanetDataAccessLayer>
	<ServerGroup name="default" minConnPool="1" maxConnPool="10">
		<Server name="Server1" host="DIRECTORY_SERVER" port="DIRECTORY_PORT" type="SIMPLE" />
		<User name="User1" type="proxy">
			<DirDN>
				uid=amadmin,ou=people,NORMALIZED_ORGBASE
			</DirDN>
			<DirPassword>
				ENCADMINPASSWD
			</DirPassword>
		</User>
		<User name="User2" type="admin">
			<DirDN>
				uid=amadmin,ou=people,NORMALIZED_ORGBASE
			</DirDN>
			<DirPassword>
				ENCADMINPASSWD
			</DirPassword>
		</User>
		<BaseDN>
			NORMALIZED_RS
		</BaseDN>		
	</ServerGroup>
	<ServerGroup name="internalauthentication" minConnPool="1" maxConnPool="10">
		<Server name="Server1" host="DIRECTORY_SERVER" port="DIRECTORY_PORT" type="SIMPLE" />
		<User name="User1" type="proxy">
			<DirDN>
				uid=amadmin,ou=people,NORMALIZED_ORGBASE
			</DirDN>
			<DirPassword>
				ENCADMINPASSWD
			</DirPassword>
		</User>
		<User name="User2" type="admin">
			<DirDN>
				uid=amadmin,ou=people,NORMALIZED_ORGBASE
			</DirDN>
			<DirPassword>
				ENCADMINPASSWD
			</DirPassword>
		</User>
		<BaseDN>
			NORMALIZED_RS
		</BaseDN>		
	</ServerGroup>
	<!--
	Modify this ServerGroup to point to your LDAP server for user data.
	If your component needs to use a different LDAP server, add a
	ServerGroup for that component. Some of the possible ServerGroup names
	you can use are: saml, federation, disco, idpp, and authnsvc.

	Make sure user dn in your LDAP server uses the same naming attribute as
	your "admin" user; and baseDN is the people container LDAP server uses.
	-->
	<ServerGroup name="userdefault" minConnPool="1" maxConnPool="10">
		<Server name="Server1" host="DIRECTORY_SERVER" port="DIRECTORY_PORT" type="SIMPLE" />
		<User name="User1" type="proxy">
			<DirDN>
				uid=amadmin,ou=people,NORMALIZED_ORGBASE
			</DirDN>
			<DirPassword>
				ENCADMINPASSWD
			</DirPassword>
		</User>
		<User name="User2" type="admin">
			<DirDN>
				uid=amadmin,ou=people,NORMALIZED_ORGBASE
			</DirDN>
			<DirPassword>
				ENCADMINPASSWD
			</DirPassword>
		</User>
		<BaseDN>
			ou=people,NORMALIZED_RS
		</BaseDN>		
	</ServerGroup>
</iPlanetDataAccessLayer>

This section contains information on the following:

• server-config.dtd Definition Type Document

• serverconfig.xml Users

server-config.dtd Definition Type Document

The server-config.dtd defines the structure for serverconfig.xml. It is located in /FederationManager-base/XXXXXXXX.

Example 3–2 server-config.dtd

<?xml version="1.0" encoding="ISO-8859-1"?>

<--
    Copyright (c) 2002 Sun Microsystems, Inc. All rights reserved. 

    Use is subject to license terms.
-->

<!-- The root.-->
<!ELEMENT iPlanetDataAccessLayer (ServerGroup+) >


<!ELEMENT ServerGroup Server+ User+ BaseDN MiscConfig*>
<!ATTLIST ServerGroup
    name	ID		#REQUIRED
    minConnPool	NMTOKEN		"1"
    maxConnPool	NMTOKEN		"10"
>


<!ELEMENT BaseDN (#PCDATA) >

<!-- An Server contains an id, host name and port. -->
<!ELEMENT Server>
<!ATTLIST Server
          name    ID    #REQUIRED
          host    CDATA    #REQUIRED
          port    NMTOKEN    "389"
          type    (SIMPLE|SSL)    "SIMPLE"
>

<!--An User contains an ID, the type of privileges the DN and Password
provides. The type of connection of a DirInstance is realized from the type
of User it is associated with or it contains.-->
<!ELEMENT User (DirDN, DirPassword)>
<!ATTLIST User
          name    ID    #REQUIRED
          type    (auth|proxy|rebind|admin)    "auth"
>

<!ELEMENT DirDN (#PCDATA)>
<!ELEMENT DirPassword (#PCDATA)>
<!ELEMENT MiscConfig EMPTY>
<!ATTLIST MiscConfig
          name    CDATA   #REQUIRED
          value    CDATA   #IMPLIED
>

This section defines the main elements of the DTD.

• iPlanetDataAccessLayer Element

• ServerGroup Element

• Server Element

• User Element

• DirDN Element

• DirPassword Element

• BaseDN Element

• MiscConfig Element

iPlanetDataAccessLayer Element

iPlanetDataAccessLayer is the root element. It allows for the definition of multiple server groups per XML file. Its immediate sub-element is the ServerGroup. It contains no attributes.

ServerGroup Element

ServerGroup defines a pointer to one or more LDAPv3–compliant directories. They can be master or replica servers. The sub-elements that qualify ServerGroup include:

• Server

• User

• BaseDN

• MiscConfig

The ServerGroup attributes are the name of the server group, and values for minConnPool and maxConnPool which define the minimum (1) and maximum (10) connections that can be opened for the LDAP connection pool respectively. More than one defined ServerGroup element is not supported.

Federation Manager uses a connection pool to access the LDAPv3–compliant directory. All connections are opened when Federation Manager starts and are not closed. They are reused.

Server Element

Server defines a specific LDAPv3–compliant directory instance. It contains no sub-elements. The required XML attributes are a user-friendly name for the server, the host name, the port number on which the LDAPv3–compliant directory runs, and the type of LDAP connection that must be opened (either simple or SSL).

User Element

User contains sub-elements that define the user configured for the instance of the LDAPv3–compliant directory. The User sub-elements are DirDN and DirPassword. It's required XML attributes are the name of the user, and the type of user. The values for type identify the user's privileges and the type of connection that will be opened to the directory instance. Options include:

• auth defines a user authenticated to the LDAPv3–compliant directory.

• proxy defines a proxy user for the LDAPv3–compliant directory. See Proxy User.

• rebind defines a user with credentials that can be used to rebind to the LDAPv3–compliant directory.

• admin defines a user with administrative privileges for the LDAPv3–compliant directory. See Admin User.

DirDN Element

DirDN contains the LDAP Distinguished Name (DN) of the defined user.

DirPassword Element

DirPassword contains the defined user's encrypted password.

It is important that passwords and encryption keys are kept consistent throughout the deployment. For example, the passwords defined in this element are stored in the LDAPv3–compliant directory. If the password is changed in one place, it must be updated in all places where it is defined. Additionally, this password is encrypted. If the encryption key defined in the am.encryption.pwd property is changed, all passwords in serverconfig.xml must be re-encrypted using ampassword.

BaseDN Element

BaseDN defines the base DN for the server group. It contains no sub-elements and no XML attributes.

MiscConfig Element

MiscConfig is a placeholder for defining any LDAP JDK features like cache size. It contains no sub-elements. It's required XML attributes are the name of the feature and its defined value.

serverconfig.xml Users

Two users are defined in serverconfig.xml:

• Proxy User

• Admin User

Proxy User

serverconfig.xml

The Proxy User can take on any user's privileges (for example, the organization administrator or an end user). The connection pool is created with connections bound to the proxy user. Federation Manager creates a proxy user with the DN of cn=puser,ou=DSAME Users,dc=example,dc=com. This user is used for all queries made to the LDAPv3–compliant directory. It benefits from a proxy user ACI already configured in the LDAPv3–compliant directory and, therefore, can perform actions on behalf of a user, when necessary. It maintains an open connection through which all queries are passed (retrieval of service configurations, organization information, etc.). The proxy user password is always encrypted.

Admin User

dsameuser, the administrator user, is used for binding purposes when the Federation Manager SDK performs operations on the LDAPv3–compliant directory that are not linked to a particular user (for example, retrieving service configuration information). The Proxy User performs these operations on behalf of the dsameuser, but a bind must first validate the dsameuser credentials. During installation, Federation Manager creates cn=dsameuser,ou=DSAME Users,dc=example,dc=com.

Configuring Federation Manager for Sun Java System Policy Agents

Federation Manager supports both types of Sun Java System Policy Agents 2.2: web agents and J2EE agents. They can be deployed to work with Federation Manager in any web container on which the agents are supported although they will only work in SSO only mode. No policy or access control is supported.

With respect to passing attributes to an application using agents, there are some limitations. Agents can not retrieve user attributes stored directly in Federation Manager as the user management functionality is not enabled. Either of the following options will alleviate this issue.

1. User attributes can be passed from identity providers and delivered to service providers (using Federation Manager) in SAML assertions. Federation Manager can mark the attributes as session attributes that policy agents will consume and pass to the applications.

2. Implement a post authentication and/or federation adapter SPI for the service provider (using Federation Manager) to read user attributes and set them as session attributes. The policy agent will consume the session attributes and pass them to the applications.

The following steps must be taken in order for Sun Java System Policy Agents 2.2 to work correctly with Federation Manager. On the agent side, you must do the following:

1. When installing the agent, specify /fm for the following URI: Primary Server Deployment URI [/amserver] = /fm

2. After installation, modify the following values in the AMAgents.properties file:

   • com.sun.am.policy.agents.config.do_sso_only = true

   • com.sun.am.policy.agents.config.profile.attribute.fetch.mode=NONE

   • com.sun.am.policy.agents.config.response.attribute.fetch.mode=NONE

3. Restart the agent.

On the Federation Manager side, you must do the following:

1. Encrypt the shared secret password using the ampassword utility.

2. Modify the com.iplanet.am.service.secret property in AMConfig.properties by specifying the encrypted password as the value for the property.

3. Restart Federation Manager.