Configuring the SAML Extension Server

When the SAML extension server installs, a configuration file is generated and placed in the samlext/conf directory on the local drive of the server. This file is named samlextConfig.xml. The SAML extension server reads most of its configuration information from eDirectory. However, some basic information must be made available to the SAML extension server before a connection to the directory is established. Also, some sensitive information cannot be safely transferred or stored between eDirectory and the SAML Extension server. For this purpose, samlextConfig.xml contains several key pieces of information:

• Address(es) of the eDirectory server(s) containing user and configuration information
  • Proxy user and password
  • iChainServiceObject associated with the system

• Public Key Certificate of eDirectory server(s) if LDAP over SSL is to be used
• Key store containing the XML-Signature Key Pair
• Key store containing the SSL - Mutual client Key Pair
• Debug page enable flag

The following shows an example of what a typical samlextConfig.xml file looks like:

<authority name="SAMLExtDirectoryAuthority"> 
  <class>

<name>com.novell.wss.authority.saml.SAMLExtDirectoryAuthority</name> 
  </class> 
  <data>    <servers refresh="1"> 
      	<url>ldap://137.65.159.66:389</url> 
    </servers>    <proxyUser> 
      	<dn>cn=admin,o=novell</dn> 
      	<password>novell</password> 
      </proxyUser> 
 
    <initialCapacity>10</initialCapacity> 
    <maxCapacity>30</maxCapacity> 
 
    <isoDn>cn=iso_ichainsite,o=novell</isoDn>    <keypairs> 
      	<keypair usage="ssl" type="pkcs"> 
      	   <password>dude</password> 
       	  <file>ssl.pfx</file> 
      	</keypair> 
 
	      <keypair usage="signing" type="jks"> 
      	   <password>dude</password> 
         <file>sig.pfx</file> 
      	</keypair> 
 
    </keypairs>    <enableDebugPages>false</enableDebugPages>  </data></authority>

Configuration Elements

authority, class, name (required): These elements and associated attributes should not be modified.

data (required): The data element contains the basic configuration information for the SAML Extension server.

servers (required): This element allows the administrator to specify one or more eDirectory servers from which to read configuration and user attribute information. If more than one server is specified a "round-robin" approach is used to effect a type of load balancing between the servers. Also, a health check is performed on each of the servers at a specified time interval, and servers that are down are removed from the pool.

• refresh: The refresh attribute determines how often (in minutes) the health check thread will run on the LDAP server connection pools. If a server goes down, the health check monitor will deactivate it. If a server that was previously down becomes available, the health check will make those connections available again. The default value of 4 minutes will be used if no refresh attribute value is provided.
• url (required): This element specifies a single LDAP URL.

proxyUser,dn, password (required): These elements specify the user and password to use when making connections to eDirectory. The specified user must have read privileges to the iChainServiceObject.

initialCapacity (required): This is the number of connections to the specified directory to create and make available to the system at startup time.

maxCapacity (required): The maximum number of connections to create to a given directory. When requests are made to the system to obtain a LDAP connection and all are in use, new connections will be created and added to the available pool up until the maxCapacity value.

isoDn (required): This is the distinguished name of the iChainServiceObject associated with the iChain site. This setting allows the system to locate its configuration objects in the directory.

keypairs (optional): The keypairs element specifies public-private keypair objects to use for creating digital signatures on SAML data and creating outbound SSL connections. Applicable attributes are:

• usage (required): Two values are appropriate: SSL indicates that the keypair should be used to create outbound SSL connections. SIGNING indicates that the keypair should be used to create digital signatures on SAML data.
• type (optional): This is the type of keystore to open. Valid values are PKCS or PKCS12 for PKCS#12 formatted keystores or JKS for Java Key Store formatted keystores.
• alias (optional): Certain types of Keystores (JKS) can contain more than one public-private keypair. The alias attribute allows the administrator to specify which keypair to use. (This value is only used for the signature usage). If this value is absent, the first valid keypair found in the store is used.
• keyPassword (optional): Certain types of Keystores (JKS) can have a separate "key" password for each contained key. If this value is absent, the keystore password is used for this value.

file (required element): This is the file name of the keystore. The file name may be named relative to the location of the samlextConfig.xml file.

password (required element): This is the password used to load the keystore.

enableDebug (optional, default=false): This element allows the administrator to specify whether the SAML Extension debug pages will be available. It is generally a good idea to enable the pages when first deploying and debugging the system. However, as soon as the system is put into production or accessed by non-administrators, these pages should be disabled. There are three debug pages available:

• /samlext/status: This page displays the status of the system including the LDAP connection pools and currently loaded SAML configuration. Note that there is a possibility of a security issue since some sensitive information can be displayed.
• samlext/test: This page displays the attributes of the currently connected user. It shows all of the incoming headers and parameters included in the HTTP request as sent by iChain.
• samlext/saml/test: This page displays the SAML configuration as loaded by the system.

LDAP SSL Settings

In order to communicate with the LDAP server over SSL, you must apply additional settings. First, the LDAP SSL public key certificate for each directory you want to connect to via SSL must be copied onto the local drive of the SAML extension server. The samlextConfig.xml file must point to these certificates so that they can be added to the Java SSL TrustStore, enabling the system to make SSL connections to those servers. Second, a single directory server entry must be specified as the configuration server that the system can read initial configuration from before upgrading the connections to SSL. The following example shows the differences between the non-SSL and SSL configuration files:

<authority name="SAMLExtDirectoryAuthority"> 
  . . . 
 
    <configServers> 
      <url>ldap://137.65.159.66:389</url> 
    </configServers> 
 
    <servers> 
      <url secure="true">ldap://137.65.159.66:636</url> 
      <url secure="true">ldap://137.65.159.83:636</url> 
    </servers> 
 
    <ldapCertificates> 
      <ldapCertificate> 
        <file>dir_66.der</file> 
      </ldapCertificate> 
      <ldapCertificate> 
       <file>dir_83.der</file> 
      </ldapCertificate> 
    </ldapCertificates> 
 . . . 
 
  </data> 
</authority>

SSL-Enabled Configuration Elements

configServers (required): If secure LDAP connections are to be used, the configServers element must contain at least one LDAP server. The system uses this LDAP server to read its basic configuration information before transitioning to the SSL connections. After startup, the configServer connections are all closed.

servers (required): The servers listed here can have the secure attribute set to true. This causes the connections to be made using SSL.

ldapCertificates, ldapCertificate (required): The specified certificates will be added to the Java SSL truststore so that SSL connections can be made to the specified LDAP servers