|
|
|
|
|
This topic describes using LDAP authentication against an MS Active Directory tree.
Please do the following before contacting technical support on this provider:
The configuration file ldap.properties in the CDaily-x.x.x/WEB-INF folder contains detailed information on how you can configure the authentication system. Carefully look it over and in particular, read the theory of operation section for configuration information.
It's really important that you know up front you'll need someone who understands your AD implementation to configure connectDaily.
If your AD server does not already have the Certificate Authority software installed, read the article: http://social.technet.microsoft.com/wiki/contents/articles/2980.ldap-over-ssl-ldaps-certificate.aspx.
The default behavior of connectDaily is to trust the SSL certificate. This is not the most secure option but will be OK for most needs. If you want connectDaily to verify the LDAP over SSL certificate each time, perform these steps:
Export the CA certification from your certificate authority in DER format.
Import the CA certificate from your Certificate Authority installation into a new keystore file using the command:
keytool -import -file file.cer -keystore \ sslkey.keystore -alias "type=r.name=sslkey"
Once you've created the keystore file, change the SSLTrustStore path entry in the ldap.properties file to point to it.
If your Domain Controller/LDAP server is not the same server as the Certification Authority server, it may be necessary to go to the Issued Certificates section of the Certificate Authority program and locate the certificate issued to your domain controller. Once you locate that certificate, import it using the command shown above.
Important Tip - Make sure that the user account you're trying to authenticate to has logon permissions to the domain controllers FROM THE MACHINE CONNECTDAILY EXECUTES ON!
Follow the rest of the LDAP configuration instructions in the Configuring LDAP Authentication topic.
Debugging Notes
If it's not working, first try disabling SSL by editing the LDAP.properties file. Once you have authentication working without SSL, re-enable SSL and follow these steps: To debug the SSL connection sequence, define
-Djavax.net.debug=ssl:record
or
-Djavax.net.debug=ssl:handshake
On Windows, this is done by editing the value for:
HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Procrun 2.0\connectDaily\Parameters\Java\Options
This will send debug information to stdout. You should see the certificate exchange and certificate details. Make sure the matching certificate is in the keystore.
If you see a disconnect before the exchange of the certificate from the server, refer to MS KB Article 321051. This article contains information even if you are not using a 3rd party SSL certificate.
http://support.microsoft.com/kb/321051
See Also: Automatically Creating Users
This help topic documents the ldap.properties configuration file. This file is contained in the cdaily-x.x.x/WEB-INF directory and it controls operation of the LDAP authentication system. LDAP Configuration can be very complex, so you must read this topic completely and carefully.
The file cdaily-x.x.x/WEB-INF/misc/security/LDAP Authentication Flow Chart.pdf contains a flow chart that describes in detail how authentication is performed.
Broadly speaking there are two modes of operation.
In the first mode, a lookup account is used to turn the supplied user name into a distinguished name (DN). This distinguished name is then used for the authentication step. The one advantage to using this mode is that the user doesn't have to specify a qualified user name. Refer to the section on User Name Formats.
In the second mode, the program attempts to bind directly to the tree using the supplied user name and password. This mode can also support multiple domains/servers for authentication.
The important thing to note is that a bare user name cannot be used to bind to an LDAP tree. If you need to use a bare name (see below), you must provide for it's conversion to a format that can be used for binding to the directory.
Format |
Description |
Bare User Name. Example: user |
Bare user name only. If GuessDN=yes, then you must specify PrefixUserWith, and SuffixUserWith, and all users must reside in the same domain. For Example: GuessDN=Yes PrefixUserWith=cn\= SuffixUserWith=,cn\=users,dc\=test,dc\=mhsoftware,dc\=com If GuessDN=no, you must specify a lookup account. The lookup account will query for the DN. |
AD domain\username. Example: test\user |
Active Directory Only. Set searchField=SAMAccountName |
Distinguished Name. Example: CN=John Doe , CN=Users, DC=test, DC=mhsoftware, DC=com |
set searchField=DistinguishedName |
User Principal Name. Example: user@test.mhsoftware.com |
set searchField=userPrincipalName |
By default, connectDaily will strip out the user name portion of the login user ID, convert it to lower case, and use that to find the corresponding connectDaily user account. See ExtractUserNameExpression for additional information.
Tip
You can add an entry to WEB-INF/configuration.properties to prompt users on the correct name format. E.G.
UserID.placeholder=domain\\username
This placeholder prompt will be displayed on the login form's user id field (if the browser supports HTML 5 placeholder attributes).
ldap.properties is a Java properties file. The format of the file is
PropertyName=value
Property names are case sensitive. If value contains equal sign characters, they should be escaped using \. If value contains \ characters, they should be escaped as \\. If an entry is present multiple times, the last value in the file is used.
GuessDN
If yes, then the user's distinguished name will be guessed using the supplied user name and the values of PrefixUserWith and SuffixUserWith.
searchField
LDAP attribute name to query the directory for. Examples are SAMAccountName, DN, or userPrincipalName. Refer to the section above on User Name Formats.
lookupDN,lookupPassword
The username and password used for the lookup account. Required if GuessDN=no. This name needs to be qualified, so it should be a DN. For active directory, it can be a userPrincipalName or domain\username.
ServerName
Name of the LDAP server. You can specify either a host name or IP address. If you specify a host name, that host name must be resolvable from the server connectDaily is installed on. This can be a comma-delimited list of servers. If a list of servers is specified, the program will attempt to locate the user on the specified servers.
DefaultContext/Server.Name.DefaultContext
This is the context to search for the user account in. You must change this to the correct value for your directory.
Example: DefaultContext=dc\=test,dc\=mhsoftware,dc\=com
You can specify multiple contexts by specifying a delimited set of context names to search. Refer to ContextDelimiter.
If you are using multiple servers you must specify a unique set of contexts for each server. For example,
ServerName=server-a.domain.com,server-b.domain.com
server-a.domain.com.DefaultContext=dc\=a,dc\=domain,dc\=com
server-b.domain.com.DefaultContext=dc\=b,dc\=domain,dc\=com
Server.Name.AutoAddUserTemplate
This is the name of the connectDaily user to use as a template when creating a user who authenticated against Server.Name. For example:
ServerName=server-a.domain.com,server-b.domain.com
server-a.domain.com.AutoAddUserTemplate=domainauser
server-b.domain.com.AutoAddUserTemplate=domainbuser
This allows you to have different user defaults based on which server the user authenticates against. For example, a different default time zone for the user depending on which server they authenticate against.
ContextDelimiter
If multiple contexts are specified, this is the delimiter that separates the values. The code uses a regex split function, so the character should not be a special regex character. The default delimiter is ";".
CheckSSLCertificate
If this option is not present, or is set to no, the validity of the SSL certificate used to encrypt the LDAP session to the server is not verified. If this option is set to "yes", then the SSL certificate will be verified, and an error occur if the certificate is not trusted. Essentially, leaving this set to the default means you don't have to go through the steps to create a keystore for the certificate and mark it as trusted.
SSL_DISCLAIMER
Uncomment this configuration value to disable SSL. This is a security issue because LDAP sends the username/password across the network to the LDAP server as plain text.
TrustStorePath
Path to SSL trustStore containing the SSL Certificate for the LDAP server. Essentially putting the certificate in the keystore says you trust it.
If this value is not supplied, the default value of JRE/lib/security/cacerts will be used. If you use the default cacerts file in the JRE, and then upgrade your JRE, things will stop working.
TrustStorePassword
The password for the specified keystore. The default Java password for keystores is changeit.
fullName
LDAP Attribute Name for the user's Full name from the directory. When a user is created or logged in, their full name is set to this value.
emailAddress
The LDAP attribute that contains the user Email address. When a user is created or logged in, their Email address is set to this value.
GroupAttributeName
The attribute name for group memberships. When a user logs in, their connectDaily group memberships will be reconciled with their LDAP group memberships and they will be removed or added to connectDaily as required.
ExtractUserNameExpression
By default, connectDaily will extract the user name from the supplied user name. If searchField=SAMAccountName, then the domain name is stripped off. If searchField=UserPrincipalName, then the portion after the @ symbol is stripped. If searchField=DN, then the user name is the portion after the first CN=, up to the first comma. If you need to, you can specify your own regular expression to extract the user name.
If your user account names are not unique, for example, you have a user JSmith in a context, and another user JSmith in a different context, this may cause problems. To have connectDaily use the full user supplied user name, set this value to "disable".
debugMode
Sends detailed debugging information to the server log files. This will log passwords, so you should turn it off and erase the log files, once debugging is completed.