2 Integrating with LDAP

2.8.1 Example of Oracle Internet Directory LDAP Configuration

This section describes typical login.properties settings required to integrate EDQ with an Oracle Internet Directory LDAP server.

In this example, the LDAP user and password are transmitted in the clear (unencrypted) over the network. Oracle recommends the use of SSL (example3.ldap.security = ssl) or TLS (example3.ldap.security.tls) to encrypt LDAP traffic.

# Oracle Internet Directory Example
realms = example3
# Map the realm to a domain name
example3.realm                      = EXAMPLE3.COM 
# Disable GSS
example3.gss                        = false
# Authorize user by using LDAP bind to server 
example3.auth                       = ldap
 # Use distinguished name for authentication
example3.auth.binddn                = search: dn
# The LDAP server
example3.ldap.server                = server3
example3.ldap.auth                  = simple 
# The OID user credentials to be used by EDQ ([email protected])
example3.ldap.user                  = cn=intuser,cn=users,dc=example3,dc=com
example3.ldap.pw                    = password
# The base distinguished name is example3.com
example3.ldap.basedn                = dc=example3,dc=com 
# Use InetOrgPerson Style LDAP schema
example3.ldap.profile               = inetorgoidldap
# The name of the user group containing all EDQ users
example3.ldap.prof.defaultusergroup = group3
example3.ldap.security = ssl

2.8.2 Example of Microsoft Active Directory LDAP Configuration

This section describes typical login.properties settings required to integrate EDQ with a Microsoft Active Directory LDAP server.

In an AD environment, EDQ can be configured to permit SSO by users in the same domain. This example does not configure SSO, because it does not include the clientcreds=true property and setting.

# Active Directory Example
realms = example1
# Map the realm to a domain name
example1.realm                      = EXAMPLE1.COM 
# Authorize user by using LDAP bind to server;
# for Active Directory it must be ldap
example1.auth                       = ldap
# The authentication to use, in this case digest-md5 using
# the plain account name (example1.auth.binddn).
example1.auth.bindmethod            = digest-md5
example1.auth.binddn                = search: sAMAccountName
# Use Transport Layer Security. Requires a X.509 certificate to be
# installed on the domain controller.
example1.ldap.security              = tls
# The LDAP Schema to use.  For Active Directory adsldap is the
# standard schema to use
example1.ldap.profile               = adsldap
# The name of the user group containing all EDQ users.
example1.ldap.prof.defaultusergroup = group1

2.8.3 Example of Open LDAP Configuration

This section describes typical login.properties settings required to integrate EDQ with an Open LDAP server.

The path to the keytab (specified by the example2.keytab property in the example) can either be an absolute path or simply the file name. If the file name is provided, the system assumes the file is found in the security directory in the base configuration directory (oedq_home/security).

If the inetOrgPerson schema is used, the example2.ldap.profile property in the example should be set to inetorgopenldap.

# OpenLDAP Example
realms = example 2
# Map the realm to a domain name
example2.realm                      = EXAMPLE2.COM
# Do not use local machine credentials to connect to the LDAP server
example2.clientcreds                = false
# Specify the Service Principal Name to use
example2.spn                        = host/[email protected]
# The keytab where the SPN can be found.
example2.keytab                     = kerberos.ktab
# Authorize user by using LDAP bind to server 
example2.auth                       = ldap
# Use simple authentication, using the distinguished name
example2.auth.bindmethod            = simple
example2.auth.binddn                = search: dn
# Specify the LDAP server
example2.ldap.server                = ldapserver.example2.com
# Specify the base distinguished name.
example2.ldap.basedn                = dc=example2,dc=com
# Use the LDAP schema based on RFC2307, user are assumed to have
# the posixAccount object class
example2.ldap.profile               = rfc2307ldap
# Use Transport Layer Security
example2.ldap.security              = tls
# The name of the user group containing all EDQ users
example2.ldap.prof.defaultusergroup = group2

2.8.4 Example of Novell eDirectory LDAP Configuration

This section describes typical login.properties settings required to integrate EDQ with a Novell eDirectory LDAP server and what to do if a novell.properties file is required.

Section 2.8.4.1, "Example Settings for login.properties"

Section 2.8.4.2, "Creating a novell.properties File"

# Novell eDirectory Example
# Map the realm to a domain name
example4.realm                      = EXAMPLE4.COM
# The base distinguished name is example4.com
example4.ldap.basedn                = o=example4
# Authorize user by using LDAP bind to server 
example4.auth                       = ldap
# Use distinguished name for authentication
example4.auth.binddn                = search: dn
# The LDAP server
example4.ldap.server                = server4
example4.ldap.auth                  = simple
# Use Novell Style LDAP schema
example4.ldap.profile               = novell
# The name of the user group containing all EDQ users
example4.ldap.prof.defaultusergroup = group4
# Use Transport Layer Security
example4.ldap.security              = tls
# The eDirectory user credentials to be used by EDQ
example4.ldap.user                  = cn=intuser,ou=users,o=example4
example4.ldap.pw                    = password

# Simple LDAP profile for the Novell eDirectory server 
# ----------------------------------------------------

idmatch          = (.*)@${realm:.*}

userattributes   = uid givenName sn mail telephoneNumber
usersearch       = (objectClass=inetOrgPerson)
userfilter       = +(uid={1})
userkey          = GUID
userfind         = +(GUID={0})
username         = uid

# group lookup
 
groupsearch      = (&(objectClass=groupOfNames)(cn=*))
groupkey         = GUID
groupfind        = +(GUID={0})
groupnamefind    = +(cn={0})
 
# secondary user/group relationships
 
memberattr       = member
membertarget     = dn
 
# certificate support
 
certuserfilter   = +(userCertificate={der})
 
# vcard
 
vcard.fn         = fullName cn
vcard.org        = o
vcard.tel.work   = telephoneNumber
vcard.email.pref = mail
 
# support attributes
 
binaryattrs      = GUID

2.9.1 Overview of the Variables

The following variables can be used in the password messages:

• {0} - The standard pre-configured Password Expired message.

• {1} - The name of the user.

• {2} - The number of days left before the password expires.

The realm name for each value is also displayed using the standard global realms property. The displayed realm name may be overridden using the realm_name.label property.

2.9.2 Customizing the Password Expired Message

Do either of the following to configure the Password Expired message.

• To use the standard Password Expired message, enter the following value in the login.properties file:

  realm_name.extra.pwexpired.message = {0}

• To enter a custom Password Expired message, with a link to a specific URL for changing the password, use the following code in the login.properties file. The message text, formatting and URL in this code are included as examples for you to edit as required. The HTML formatting is optional.

  realm name.extra.pwexpired.message = <html><font size="+1">Dear <em>{1}</em><p>Your password has expired. Click <a href="[URL]">here</a> to set a new password.</p></font></html>

2.9.3 Customizing the Password Expiring Message

Use the following property in the login.properties file to create a custom Password Expiring message. Substitute the correct realm name and message text. The HTML formatting is optional.

realm_name.extra.pwexpiring.message = <html><font size="+1">Dear <em>{1}</em><p>Your password will expire {2,choice,0#today|1#tomorrow|1<in {2} days}.<p>Click <a href="[URL]">here</a> to manage your password settings.</p></font></html>

If you do not set a Password Expiring message, users will see the normal login screen if their password is about to expire.

2.9.4 Customizing the Expiry Time

By default, EDQ inherits the password expiry time from the LDAP server. By default, the number of days before the expiry time that users see the Password Expiring message is set to seven days. If required, you can set a custom expiry time and warning threshold in the login.properties file to override the settings in the LDAP server.

• To set a custom password expiry time, add the following value to the login.properties file:

  realm_name.ldap.prof.passwordhandler.passwordage = Number_of_days/hours/seconds

• To set a custom warning threshold, add the following value:

  realm_name.ldap.prof.passwordhandler.passwordwarning = Number_of_days/hours/seconds

  For each value, you can specify a number of days, hours or seconds. For example:

  • For 30 days set the value to 30 or 30d.

  • For 240 hours enter 240h.

  • For 3000 seconds enter 3000s.

2.10.1 Example Settings for Parent and Child Domains

The following example assumes there is a parent domain EXAMPLE.COM and a child domain CHILD.EXAMPLE.COM. It provides example settings that illustrate how to configure login.properties for parent and child domains with only the parent domain configured as a realm. An explanation of this example follows the code segment.

# Global settings
clientcreds = true       
realms = internal, parent
ldap.prof.useprimarygroup = false        
# Realm settings
# Update match pattern to allow child domain components  
child.ldap.prof.idmatch = (?i)(.*)@(?:.*\\.)?${realm:.*}  
parent.realm = EXAMPLE.COM
parent.auth = ldap
parent.auth.bindmethod = simple
parent.auth.binddn = search: dn  
parent.ldap.security = tls
parent.ldap.profile = adsldap    
parent.ldap.prof.defaultusergroup = edqusers     
parent.ldap.referral = follow

The settings for the parent domain are mostly the same as for a single AD domain. The significant differences are the following entries in the code.

parent.ldap.referral = follow

This property and its follow setting enable LDAP referrals. In a referral, when a search completes on the parent domain, it issues a referral reply that causes the search to continue in the child domain(s). For example, a single search can return all the groups in the parent and child domains.

parent.ldap.prof.idmatch = (?i)(.*)@(?:.*\\.)?${realm:.*}

This setting uses the idmatch property to select the realm based on the identity of a user. After a Kerberos/SSO handshake, the server obtains the identity of the client from the handshake and then determines which realm is associated with the user. The property is a regular expression, where ${realm_name:.*} is replaced with the realm_name from login.properties. The default value for single-domain AD is:

(?i)(.*)@${realm_name:.*}

In this case, the value expands to:

(?i)(.*)@EXAMPLE.COM

The value will match any user in the domain, such as [email protected]. The updated version adds the optional child domain component and would also match names like [email protected].

parent.auth.bindmethod = simple

parent.auth.binddn = search: dn

A username and password are authenticated against AD by attempting a bind as that user. With parent and child domains, a user from the child domain can connect to the parent domain controller. However, the common DIGEST-MD5 bind method does not work across domains, so set the bind method to simple and specify that the bind user name is the Distinguished Name (DN) of the user. For example:

CN=John Doe,OU=testusers,DC=parent,DC=com or CN=Jane Doe,OU=localusers,DC=child,DC=parent,DC=com

parent.ldap.prof.defaultusergroup = edqusers

The default user group is used to find all the users who may need to use the EDQ applications. Users in this group appear in issue and case assignment lists, among other places in the EDQ user interface. The default group can be in either domain but must have Universal Scope, allowing it to contain members from both domains.

Groups that are used to assign EDQ permissions can be created as Universal and contain members from both domains, or they can be created as Global in each domain and contain users from the same domain.

The list shown on the Administration > External Groups configuration page contains groups from both domains. If no filter was set up, the page displays two of each of the standard groups (two Domain Users, two Backup Operators, and so forth). If you create EDQ-related groups in both domains, give them different names in each domain so that you can distinguish them in the list.

When only the parent domain is configured as a specific realm, EDQ treats both parent and child domains as a single realm. In EDQ the identity of a user is user@REALM. Given an identity of [email protected], for example, users from both domains will appear with @EXAMPLE.COM in assignment lists and in the user lists from the System Information Data Store.

The format of the display name of the user is configurable. You can set it to the userPrincipalName attribute of each user, for example, by using the following line:

parent.ldap.prof.userdisplayname = userPrincipalName

2.11.1 What is a Keytab?

A Kerberos key table, or keytab, contains encrypted passwords for one or more Kerberos principals. The DC normally supports a number of different encryption algorithms (DES3, AES, RC4 etc) and the entry for a principal will include keys for each of these algorithms. The client will pick the best algorithm available for communication with the DC.

The service requested using GSSAPI is identified by a Service Principal Name (SPN). Normally this will be a reference to a particular service type at a machine hostname. Examples of service types are HOST (for general access, such as SSH), HTTP (for SSO from browsers) and LDAP (for LDAP servers such as AD domain controllers). An SPN is usually displayed in the format service/hostname; for example:

HOST/testserver.example.com

Each entry in a keytab also includes a Key Version Number (KVNO). This is incremented whenever the password for the principal is changed in the DC. The keytab must contain the correct KVNO for authentication to succeed.

On most UNIX systems, the default location of the system keytab is:

/etc/krb5.keytab

In the EDQ login.properties configuration file, the location of the keytab may be set by the following property:

keytab = Path to keytab

If the path is not absolute, it is relative to the security folder containing login.properties.

The klist command can be used to list the contents of a keytab:

klist -k [file]

klist -ke [file]

klist -keK [file]

A file name can be provided if the keytab is not in the default location. The first form only lists the principals; the second also includes the encryption algorithms, and the third also includes the key values in hexadecimal.

Following is sample output using klist:

Keytab name: WRFILE:/etc/krb5.keytab
KVNO Principal
 --------------------------------------------------------------------------
 2   host/[email protected] (DES cbc mode with CRC-32)
 2   host/[email protected] (DES cbc mode with RSA-MD5)
 2   host/[email protected] (ArcFour with HMAC/md5)
 2   host/[email protected] (DES cbc mode with CRC-32)
 2   host/[email protected] (DES cbc mode with RSA-MD5)
 2   host/[email protected] (ArcFour with HMAC/md5)
 2   [email protected] (DES cbc mode with CRC-32)
 2   [email protected] (DES cbc mode with RSA-MD5)
 2   [email protected] (ArcFour with HMAC/md5)
 2   HTTP/[email protected] (DES cbc mode with CRC-32)
 2   HTTP/[email protected] (DES cbc mode with RSA-MD5)
 2   HTTP/[email protected] (ArcFour with HMAC/md5)
 2   HTTP/[email protected] (DES cbc mode with CRC-32)
 2   HTTP/[email protected] (DES cbc mode with RSA-MD5)
 2   HTTP/[email protected] (ArcFour with HMAC/md5)

GSSAPI requires that an SPN has a service component (before the /), though there is no requirement that the rest is a valid host name or that the service is meaningful. An SPN in the following form is equally valid:

hello/alpha.beta

In a normal Kerberos system using a standard Kerberos Domain Controller (KDC) each SPN is a separate principal with a different password. In AD, SPNs are essentially aliases of a single account, stored as values of the AD servicePrincipalName LDAP attribute. When a computer account is created in AD, SPNs for the HOST service are created automatically. If additional services such as IIS or SQLserver are installed on the server, additional SPNs will be added to the account.

The Windows setspn command can be run on an AD server to manage the SPNs for an account. For example:

setspn -A HTTP/testserver.example.com testserver$

setspn -A hello/alpha.beta alpha.beta

The first command adds an HTTP SPN to the machine account for testserver; the second adds an SPN to a normal user account.

The Apache Directory Studio LDAP browser can be used to check on the SPNs associated with an account. If a connection to AD can be made with administrator privileges, it can also be used to add servicePrincipalName values. For more information, see Section 2.11.4.2, "Apache Directory Studio."

2.11.2 Creating Keytabs Using Existing Tools

In a normal Kerberos system, keytab entries are created using the ktadd subcommand of the Kerberos administration tool, kadmin. AD does not provide a Kerberos administration server so other approaches are required.

The keytab contains the encrypted password for the account so for each method either the password for the account must be known in advance, or it must be run with privileges to change the account password.

The method to use depends on the system configuration. Existing options include:

• Samba: If the system has been registered with AD using the Samba suite, the net ads keytab command can be used to create and update the keytab. This works because Samba has set the password for the account and stored it in a secret location.

• ktpass: The Windows ktpass command can run by an AD administrator to generate keytab entries. Unless there is no other alternative, do not use this command. It is complex and very difficult to use reliably. It will update the password of the account, thus rendering any previous keytab useless.

• msktutil: This is an open source application for UNIX which can be used to manage keytabs.

2.11.3 UNIX Kerberos Configuration

The Kerberos configuration (as used by commands such as kinit and the JRE) is read from a global configuration file, normally stored in the /etc/krb5.conf directory. This contains references to the Domain Controllers and mappings between DNS and Kerberos domains.

This is a simple example of such a configuration file for the domain EXAMPLE.COM:

[logging]
default = FILE:/var/log/krb5libs.log
kdc = FILE:/var/log/krb5kdc.log
admin_server = FILE:/var/log/kadmind.log

[libdefaults]
default_realm = EXAMPLE.COM
dns_lookup_realm =false
dns_lookup_kdc = false
ticket_lifetime = 24h
renew_lifetime = 7d
forwardable = yes

[realms]
EXAMPLE.COM = {
kdc = adsrvr01.example.com:88
kdc = adsrvr02.example.com:88
}

[domain_realm]
.example.com = EXAMPLE.COM
example.com = EXAMPLE.COM

The [realms] section lists the KDCs by host or IP for each domain; the [domain_realm] section maps DNS host names to Kerberos domains.

The krb5.conf file must be checked and adjusted for the configuration of the target domain. If it is not possible to update a file in /etc, the file can be stored elsewhere and a system property can be used to inform the JRE where it is. To do this, edit (or create, if it does not yet exist) the jvm.properties file in the EDQ configuration directory and add the line:

java.security.krb5.conf = absolute path to modified krb5.conf file

2.11.4 Managing LDAP Accounts

There are two tools that can be used to examine and update LDAP accounts: Oracle Directory Services Manager (ODSM) and Apache Directory Studio.

2.11.5 Configuring SSO

For a EDQ server configured for SSO integration with AD, a typical basic configuration of login.properties is as follows:

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

If the SPN used for SSO between client and server is not the default for the machine (HOST/machinename.domain@DOMAIN) then add a line like:

spn = hello/[email protected]

The SPN must be listed in the keytab.

If the keytab contains an entry for the internal machine or user account name (for example, without a service or prefix), then it is possible to use SASL and GSSAPI authentication between EDQ and the AD server. You would amend the realm details section in login.properties to:

# Realm details
ad.realm = DOMAIN
ad.auth = ldapad.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 (administration application, dashboard, etc). To enable this, add the line:

http.gss = true

Typically, you this should set this only if all the client machines will be part of the domain. If SSO is not possible, the behavior of browsers varies. For example, Internet Explorer will show a login dialog in a pop-up window while Firefox will revert to the normal EDQ login pages.