Configuring Cascading Authentication Methods

Configure Event Stream Processor to cascade through a list of authentication methods and use the first available method.

A single authentication method can be a single point of failure. If you are using only LDAP authentication, for example, and your LDAP server goes down, users will no longer be able to authenticate using LDAP—so no one can log in. Cascading through two or more authentication methods allows the ESP server to continue authenticating users without manual intervention.

As with systems using singularly-enabled authentication methods, the <node_name>.xml file references a csi_*.xml file that contains the authentication parameters. The difference with a system using cascading authentication is that this csi_*.xml file contains the <authenticationProvider> definitions for all the authentication methods you want to make available.

To configure your system for cascading authentication, use one of the csi_*.xml files provided in ESP_HOME/security, such as csi_kerberos.xml, as a basis for a new CSI file, called, for example, csi_all.xml. Into the new csi_all.xml file, copy the <authenticationProvider> definitions from each of the csi_*.xml files corresponding to the authentication methods you want to enable. For example, if you want to cascade through the Kerberos, RSA, and LDAP authentication methods, copy the <authenticationProvider> definition from each of the csi_kerberos.xml, csi_rsa_xml, and csi_ldap.xml files.

The ESP server iterates through the list of providers in order, starting with the first one in the file. Under normal circumstances, this will be the authentication method for your system. If that method becomes unavailable, the server tries to use the second method in the file, then the third, continuing down the list until it finds a working authentication provider. If any attempt is successful, users can continue authenticating (using the new authentication method) with no manual intervention required.

With each subsequent authentication request, the server returns to the top of the list of authentication providers and tries them in order. Therefore, when the preferred authentication method becomes available again, the server reverts to that method; there is no need to restart the server or the cluster managers.

To configure Event Stream Processor to use cascading authentication:

Open the desired csi_*.xml file and save it with a different name, such as csi_all.xml.
For each authentication method you want to make available, open the corresponding csi_*.xml file.
In each file, copy the <authenticationProvider> or <config:authenticationProvider> section and paste it into csi_all.xml. Arrange the sections in the order you want the server to try them.
Make sure each <authenticationProvider> or <config:authenticationProvider> includes controlFlag="sufficient", as in the first line of this LDAP example:
```
<config:authenticationProvider controlFlag="sufficient" name="com.sybase.security.ldap.LDAPLoginModule">
  <config:options name="ServerType" value="openldap"/>
  <config:options name="ProviderURL" value="ldap://your-open-ldap-host.your-domain.com:389"/>
  <config:options name="DefaultSearchBase" value="dc=your-domain,dc=com"/>
  <config:options name="RoleSearchBase" value="dc=your-domain,dc=com"/>
  <config:options name="AuthenticationScope" value="subtree"/>
  <config:options name="RoleScope" value="subtree"/>
</config:authenticationProvider>
```
When controlFlag="sufficient" is set on an authentication provider, you can log in once you have authenticated against that provider. Anyone who tries to log in using an authentication provider that lacks controlFlag="sufficient" must authenticate multiple times. Event Stream Processor cycles through the authentication providers in the order in which they appear in the file; you cannot log in until:
- You authenticate against a provider whose definition includes controlFlag="sufficient", or
- You authenticate against every provider in the CSI file.
Save and close csi_all.xml.
Use a text editor to open the cluster configuration file, ESP_HOME/cluster/nodes/<node-name>/<node-name>.xml.
Within the <Security> section of the cluster configuration file, in the <Csi> section, change the <File> value to csi_all.xml, as follows:
```
<Csi>
  <File>csi_all.xml</File>
<Csi>
```
Save and close the file.
Restart the server and all of the cluster managers.