Using LDAP or Active Directory for Authentication

Spectrum™ Technology Platform can be configured to use an LDAP or Active Directory server for authentication. When a user logs in to Spectrum™ Technology Platform, the user's credentials are verified using LDAP or AD. The system then checks to see if there is a Spectrum™ Technology Platform user with the same name. If there is, the user is logged in. If there is not, then a Spectrum™ Technology Platform user account is automatically created for the user and given the role user.

The following diagram illustrates this process:

Before configuring Spectrum™ Technology Platform to use a directory service for authentication, confirm that your directory service meets these requirements:

For LDAP, the directory server must be LDAP Version 3 compliant.
There are no specific requirements for the Active Directory server.

Note: We recommend that you contact Pitney Bowes Technical Support or Professional Services to guide you through this process.

Note: When setting up Spectrum using LDAP or STS or SSO_STS , If the property is, by default, spectrum.security.account.createNonExisting=true, Active Directory users are created automatically in Spectrum™ Technology Platform after their first login to Spectrum. If you turn off the property spectrum.security.account.createNonExisting=false, LDAP/Active Directory users will not be authenticated to Spectrum™ Technology Platform until the administrator manually creates users.

If there are existing users configured in Management Console and you want to use them after you enable LDAP or Active Directory authentication, create those users in your LDAP or Active Directory system. Be sure to use the same user name as in Spectrum™ Technology Platform.

Note: You do not need to create the "admin" user in LDAP or Active Directory since this user will continue to use Spectrum™ Technology Platform for authentication after you enable LDAP or Active Directory authentication.
Stop the Spectrum™ Technology Platform server.
Turn on LDAP or Active Directory authentication:
1. Open this configuration file in a text editor:
  
  server\app\conf\spectrum-container.properties
2. Set the property spectrum.security.authentication.basic.authenticator to LDAP:
```
spectrum.security.authentication.basic.authenticator=LDAP
```
  The setting LDAP is used to enable Active Directory as well as LDAP.
3. Save and close the file.
Configure the connection properties:
1. Open this configuration file in a text editor:
  
  server\app\conf\spring\security\spectrum-config-ldap.properties
2. Modify these properties.
  spectrum.ldap.url
  The URL, including port, of the LDAP or Active Directory server. For example,
  spectrum.ldap.url=ldap://ldapserver.example.com:389/
  spectrum.ldap.dn.format
  The format to use to search for the user account in LDAP or Active Directory. Use the variable %s for the user name. For example,
  LDAP:
  spectrum.ldap.dn.format=uid=%s,ou=users,dc=example,dc=com
  Active Directory:
  spectrum.ldap.dn.format=%s@example.com
  spectrum.ldap.dn.base
  The distinguished name (dn) to search for user accounts in LDAP or Active Directory. For example,
  LDAP:
  spectrum.ldap.dn.base=ou=users,dc=example,dc=com
  Active Directory:
  spectrum.ldap.dn.base=cn=Users,dc=example,dc=com
  spectrum.ldap.search.filter
  A search filter to use when searching for attributes such as roles. The search filter can contain these variables:
  
  {user} is the user name logging into Spectrum™ Technology Platform
  
  {dn} is the distinguished name specified in spectrum.ldap.dn.base.
  
  For example:
  LDAP:
  spectrum.ldap.search.filter=uid={user}
  Active Directory:
  spectrum.ldap.search.filter=userPrincipalName={dn}
  spectrum.ldap.attribute.roles
  Optional. Specifies the LDAP or Active Directory attribute that contains the name of the Spectrum™ Technology Platform roles for the user. The role name you specify in the LDAP or Active Directory attribute must match the name of the role defined in Spectrum™ Technology Platform.
  For example, to apply the roles defined in the attribute spectrumroles you would specify:
  spectrum.ldap.attribute.roles=spectrumroles
  If this attribute contains a role named designer then the designer role would be granted to the user.
  You can only specify one attribute but the attribute may contain multiple roles. To specify multiple roles inside an attribute, separate each with a comma. You can also specify a multi-value attribute, with each instance of the attribute containing a different role. Only the roles specified in this one attribute are used in Spectrum™ Technology Platform. No other LDAP or Active Directory attributes will have any impact on Spectrum™ Technology Platform roles.
  If the user has roles assigned to it in Spectrum™ Technology Platform, the user's permissions are the union of the roles from LDAP or Active Directory and the roles from Spectrum™ Technology Platform.
  Note: When a user logs in for the first time, if the user does not have a Spectrum™ Technology Platform user account one is created automatically and given the role user. The effective permissions for the user are the union of the permissions in the user role and the roles specified in the attributes listed in the spectrum.ldap.attribute.roles property.
  Note: When you view the user's roles in Management Console you will not see the roles assigned to the user by the spectrum.ldap.attribute.roles property.
  spectrum.ldap.pool.min
  
  The minimum size of the connection pool for connections to the LDAP or Active Directory server.
  
  spectrum.ldap.pool.max
  
  The maximum number of simultaneous connections to the LDAP or Active Directory server.
  
  spectrum.ldap.timeout.connect
  
  Specifies how long to wait to establish a connection to the LDAP or Active Directory server, in milliseconds. The default is 1000 milliseconds.
  
  spectrum.ldap.timeout.response
  
  Specifies how long to wait for a response from the LDAP or Active Directory server after the connection is established, in milliseconds. The default is 5000 milliseconds.
  
  spectrum.ldap.retry.count
  
  The number of times the Spectrum™ Technology Platform server will try connecting to the LDAP or Active Directory server if the initial connection attempt fails. Set this to 0 if you want to allow only one connection attempt.
  Tip: If you cluster your LDAP or Active Directory servers, we recommend that you set this value to 1 or more to allow the LDAP or Active Directory load balancer to redirect the connection request to a different server if the one that is initially tried is unavailable.
  
  spectrum.ldap.retry.wait
  
  The number of milliseconds to wait between connection attempts.
  
  spectrum.ldap.retry.backoff
  The multiplication factor to use to increase the wait time after each failed retry attempt.
  For example,
  spectrum.ldap.timeout.connect=1000 ... spectrum.ldap.retry.count=5 spectrum.ldap.retry.wait=500 spectrum.ldap.backoff=2
  In this example, the wait for the initial connection attempt is 1,000 milliseconds, and the wait time for each of the five retry attempts is increased by a factor of two, resulting in these wait times for each retry attempt:
  Retry attempt 1: 500 milliseconds
  Retry attempt 2: 1,000 milliseconds
  Retry attempt 3: 2,000 milliseconds
  Retry attempt 4: 4,000 milliseconds
  Retry attempt 5: 8,000 milliseconds
3. Save and close the properties file.
Start the Spectrum™ Technology Platform server.

If you are running Spectrum™ Technology Platform in a cluster, you must modify the spectrum-container.properties file and the spectrum-config-ldap.properties file on each of the servers in the cluster. Stop the server before modifying the file, then start the server after you are done modifying the file. If you mapped an LDAP attribute value to a role, this mapping will replicate to all nodes in the cluster, so you do not need to repeat the mapping procedure in the JMX console.