OEDQ can be fully integrated with Active Directory (AD) environments. In such a scenario:
Assuming the users and (where required) user groups are configured on the AD server, the following steps must be taken to integrate OEDQ with AD:
The login.properties file must be created and stored in the following location (assuming a standard Windows installation):
[Install Path]\config\security\login.properties
login.properties defines the realms available when performing user authentication, and specifies various configuration settings for each realm. A special realm name - internal - refers to the users defined within OEDQ, instead of on AD. No details block is required for this realm.
The following example of a login.properties file illustrates the settings that might be used for a Windows network with a single domain:
|
clientcreds = true realms = internal, win # Realm details win.realm = EXAMPLE.COM win.auth = ldap win.auth.bindmethod = simple win.ldap.profile = adsldap |
Instructs the server to use the credentials of the local machine to connect to the LDAP servers.
Defines the list of realm names that will be used in the rest of the file.
There are two realms named in the example:
Maps the realm name to the Windows domain name, specified in the long form (in the example, this is EXAMPLE.COM).
Defines the method used to validate a username/password when single sign-on is not in use (or has failed).
In this example, username/password checking is done by attempting an LDAP bind to the server.
Defines the authentication method used for the LDAP bind.
The simple method is the most basic form, and is supported in all versions of ADS from Windows 2000 on. It sends the username and password to ADS in clear text.
For information on alternative methods, see Advanced Realm Settings.
Indicates the LDAP schema in use.
For standard AD integration, the adsldap profile is used. Other profiles are available non-AD installations. For further information, please contact Support.
The following properties are not required for most installations, but are included here for completeness. Each may be included in the realm details block, as required.
For Windows 2003 server and later, more secure methods are available, such as digest-md5. To use this method, replace the win.auth.bind line in the example with the following two lines:
win.auth.bindmethod = digest-md5
win.auth.binddn = search: sAMAccountName
The second line indicates that the plain account name should be used in the bind as opposed to the default user@EXAMPLE.COM which is used with simple binds.
The rfc2307ldap profile reflects a typical Unix schema using the definitions from RFC 2307. Users are assumed to have the posixAccount object class, and groups are assumed to have the posixGroup object class. User information is determined in the same way as for AD.
By default the system locates LDAP servers by doing a DNS SRV lookup for the ldap_tcp service. If the domain controller is also serving as a DNS server these values should be set up automatically. If not available, servers may be specified explicitly with the following realm setting:
win.ldap.server = host1 host2 ...
For Windows server 2003 and later, if a X.509 certificate has been installed on the domain controller, TLS may be used to encrypt connections from the OEDQ server. To enable this, add the line:
win.ldap.security = tls
Where the adsldap profile is used, the list of users available in OEDQ applications are selected from the 'Domain Users' group by default. This group typically contains many users who are not required in OEDQ, such as network administrators, backup users, and so on. Therefore it is normally recommended that the set of users visible in OEDQ be confined to a smaller group. To specify this group, add the line:
win.ldap.prof.defaultusergroup = groupname
The following line should also be added:
win.ldap.prof.useprimarygroup = false
This indicates that the primaryGroupID attribute in a user record need not be consulted to determine the groups that a user belongs to. This can improve performance when there is a large number of users.
In cases where the external group list is particularly large, an additional filter to restrict the number of LDAP groups returned is often required.
There is an optional extra filter, called groupsearchfilter, which can be used to reduce the number of groups returned. The format of the filter is:
win.ldap.prof.groupsearchfilter = (attribute=value)
Where the value searched for can be an exact match, or partial using a wild card search (*).
The values searched for can be modified using standard LDAP syntax. For example:
win.ldap.prof.groupsearchfilter = (|(cn=Director*)(cn=SVN))
searches for LDAP group names beginning with "Director" or exactly matching "SVN".
For further information on configuring filters, please refer to RFC4515 - LDAP: String Representation of Search Filters.
Most browsers do not support (or do not support by default) the NEGOTIATE authentication mechanism required for SSO. At the time of writing, the following issues are known.
SSO does not work if the client browser and server are on the same system. Windows uses NTLM instead of GSS and this cannot be completed in a single handshake.
The browser tries to get a Kerberos service ticket for HTTP/servername and most local machine accounts do not have a suitable servicePrincipalName in their ADS account. Network admins can use the setspn command to set this up.
Assuming the above issues can be overcome, the following line enables SSO in all browser contexts:
http.gss = true
To enable selectively for different contexts, use multiple lines such as:
http.gss.admin = true
http.gss.formws = true
http.gss.ws = true
http.gss.dashboard = true
where:
admin means the administration pages accessed from the OEDQ Launchpad;formws means form-based web services;ws means SOAP web services; andSSO will only work with other web clients if they also NEGOTIATE authentication. Check the relevant supporting documentation for each web client to ensure it supports NEGOTIATE authentication before attempting to integrate it with AD.
When OEDQ is running as the local system account on Windows, it simply uses the security settings of this account. However, when OEDQ is running on Unix, it must use an AD account to establish its credentials.
Additionally, it validates the request for access with the encrypted account password read from a Kerberos key table (keytab). Setting up a valid keytab is an essential step in configuring SSO on Unix.
This topic assumes the existence of a Kerberos keytab and provides information on configuring the settings of the login.properties file to correctly integrate with it.
For further information on creating and configuring a Kerberos keytab, please see the OEDQ Technical Note: Tips for generating Kerberos Keytabs for AD accounts.
To successfully integrate OEDQ on Unix with AD, the following changes must be made to the login.properties file:
clientcreds = false
keytab = /etc/krb5.keytab
realms = internal, ad
ldap.prof.useprimarygroup = false
# Realm details
ad.realm = DOMAIN
ad.auth = ldap
ad.auth.bindmethod = digest-md5
ad.auth.binddn = search: sAMAccountName
ad.ldap.security = tls
ad.ldap.profile = adsldap
ad.ldap.auth = simple
ad.ldap.user = user@DOMAIN
ad.ldap.pw = password
ad.ldap.prof.defaultusergroup = groupname
Where the user and pw settings are the credentials of an AD account to be used by OEDQ. It is recommended that this account be Read Only.
If the Service Principal Name (SPN) used for SSO between client and server is not the default for the machine (i.e. HOST/machinename.domain@DOMAIN) then an additional line in the following format is required:
spn = hello/firstname.lastname@EXAMPLE.COM
Note: The SPN must be listed in the keytab.
If the keytab contains an entry for the internal machine or user account name (i.e. without a service/ prefix), then it is possible to use SASL/GSSAPI authentication between OEDQ and the AD server. The realm details section in login.properties is amended to:
# Realm details
ad.realm = DOMAIN
ad.auth = ldap
ad.auth.bindmethod = digest-md5
ad.auth.binddn = search: sAMAccountName
ad.ldap.security = tls
ad.ldap.profile = adsldap
ad.ldap.spn = "accountname"
ad.ldap.prof.defaultusergroup = groupname
The account name is machinename$ for a machine account or the login name for a user account.
If the keytab contains HTTP service entries for the machine, then it is also possible to use SSO for browser based logins (admin pages, dashboard, etc). To enable this, add the line:
http.gss = true
Normally this should be done only if all the client machines will be part of the domain. If SSO is not possible, the behavior of browsers varies. For example, IE will show a login dialogue in a pop-up window, whilst Firefox will revert to the normal OEDQ login pages.