2 Authenticating Using LDAP/AD Services

This chapter describes how EDQ can be integrated with external user management systems based on the LDAP standard, thus allowing Administrators to manage user accounts externally to EDQ.

This chapter includes the following sections:

2.1 Learning About LDAP Support

LDAP is a standard for accessing distributed directory services such as Active Directory, Novell eDirectory, OpenLDAP or Oracle Internet Directory. LDAP directories store entries (which may include people, groups, organizational units, and other items) in a hierarchical arrangement. EDQ is certified for integration with the following LDAP directories:

  • Oracle Internet Directory (OID) 11g

  • Microsoft Active Directory (AD) for Windows Server 2000, 2003 and 2008

  • Open LDAP 2.4

  • Novell eDirectory 8.8

In the case of integration with AD, EDQ can support Single Sign-On (SSO), so users who have signed-on to the AD domain can access EDQ without the need to log in separately to the EDQ client applications.EDQ can be configured to authenticate users against an LDAP directory using either Oracle Platform Security Services (OPSS) configured on Oracle WebLogic Server (see Import Filtering of Users and Groups), or connection settings specified within EDQ's own configuration files (for example when hosted by an Apache Tomcat server). LDAP configuration consists of three parts:

  • Global (security/login.properties)

  • Realm(s)

  • Profile for each realm

The security/login.properties file which contains global security configuration is located within the base configuration directory (that is, oedq_home/security/login.properties). Realms define the LDAP directory or directories to use for authenticating users, and can be defined within the login.properties or realm-specific files (see Using LDAP Server Profile). Profiles are generally chosen from a set of predefined profile configurations (see Configuring Global LDAP Settings (login.properties)), and contain technical details of the LDAP directory structure for the realms.

2.1.1 Import Filtering of Users and Groups

By default LDAP integration imports all users from the LDAP directory. This can be a very large number of records, and it is recommended that where feasible the configuration specifies a group of users to import. Without this, performance of EDQ can be significantly impacted and excessive load placed on the LDAP directory. To specify a group, use the ldap.prof.defaultusergroup option in the ldap.properties file, For example:

ldap.prof.defaultusergroup=edqusers

See Configuring Individual Realm LDAP Settings for details of the ldap.prof.defaultusergroup option.

2.2 Integrating LDAP Using Oracle Platform Security Services

In a default installation of EDQ on WebLogic Server, EDQ is integrated with Oracle Platform Security Services (OPSS). EDQ users and groups are managed by an OPSS identity store that is configured in WebLogic Server.

Properties in the login.properties file define the default mapping of the LDAP administrators group to the EDQ administrators group. The default configuration looks for a group called “Administrators" and maps it to the EDQ group of the same name, enabling users within that group to access the Administration application on the EDQ Launchpad.

2.2.1 Configuring LDAP Group Mappings

Where the naming of groups in WebLogic Server identity store or the configured LDAP server does not match their corresponding groups in EDQ, mappings can be defined to override the defaults. This can be done in two ways: in the login.properties configuration file or through the Launchpad administration. If the Administrators group requires mapping, create a local login.properties file to override the base login.properties file included with EDQ, and adjust the group mapping in the new file:

  1. Create a subdirectory called security in the local configuration directory (oedq_local_home/security).
  2. Copy the login.properties file from the security directory of the base configuration directory (oedq_local_home/security) to oedq_local_home/security.
  3. Look for the property opss.xgmap, for example:

    opss.xgmap = Administrators -> Administrators

    Here opss refers to the Oracle Platform Security Services realm, xgmap is short for external group map.

  4. Modify the property with the desired group name mappings. The property accepts a comma-delimited list of mappings from the external group name to the corresponding group in EDQ. For example to map two groups DQAdministrators and DQ Admins to Administrators, you would use:

    opss.xgmap = DQAdministrators -> Administrators, DQ Admins -> Administrators

  5. Save the file.
  6. Restart the application server to reload the configuration.

Once administrators can log in to EDQ, other group mappings should be configured through Launchpad administration.

2.2.2 Configuring Server Failover

To configure OPSS to use multiple LDAP servers (that is, for failover if one server is down), see Configuring Failover for LDAP Authentication Providers.

2.3 Integrating EDQ Directly with LDAP Servers

EDQ also supports direct integration with LDAP servers without using Oracle Platform Security Services. This would typically be used where EDQ is hosted within an Apache Tomcat server, although it can be used with any container. Direct integration is configured through the login.properties file in the local configuration directory. See Integrating EDQ Directly with LDAP Servers for details on the login.properties file.

To set up direct integration:

  1. Navigate to the security directory in the EDQ local configuration directory (oedq_local_home/security).
  2. Open the login.properties.template file with a text editor. This template contains sample settings that correspond to the supported LDAP providers.
  3. Uncomment and edit the parameters that correspond with the LDAP server in the EDQ installation environment. The profile associated with an LDAP configuration provides information about the schema in the LDAP server that represents users and groups. EDQ provides the following built-in profiles:
    • adsldap: Microsoft Active Directory

    • inetorgoidldap: Oracle Internet Directory (OID)

    • inetorgopenldap: OpenLDAP using inetOrgPerson style schemas

    • rfc2307ldap: RFC 2307 (that is, Solaris)

  4. Save the file as login.properties in the same directory.
  5. Restart the application server.

Other schemas can be supported by creating new profiles or extending existing profiles.

2.4 Configuring Global LDAP Settings (login.properties)

EDQ supports integration with multiple realms which can use different LDAP servers. For example, a single EDQ server may support external authentication from both a Microsoft Active Directory (AD) realm and an Oracle Internet Directory (OID) realm, if required.

These global settings can be specified in the security/login.properties configuration file. Properties are configured using the syntax property_name = value, for example:

realms = realm1, realm2

Where noted, you can override the global settings at the realm level. Realm-level settings are more specific and always override global settings. (See Configuring Individual Realm LDAP Settings.

Table 2-1 Global LDAP Settings

Property Description Example Value Mandatory?

realms

A comma-separated list of realm names, representing active realm configurations.

The specified name of each realm must correspond with the realm-specific properties later in the file, in the format realm_name.property_name = value.

A realm configuration may be retained but disabled by removing it from this list.

realm1, realm2

Yes.

clientcreds

If set to true, the server uses the credentials of the local machine to connect to the LDAP servers. This is used to enable SSO for AD integrations where the EDQ server is on the domain.

If set to false, and if SSO is enabled, the server uses the configured keytab.

May be overridden at the realm level.

true

No. If not set, the default value is false.

x509

Enables the use of x509 certificates for client authentication over SSL. There is a small performance cost associated with setting this to true.

May be overridden at realm level.

true

No

If not set, the default is false.

ldap.prof.useprimarygroup

Defines whether or not to use the primary group (for example the "Domain Users" group in AD).

May be overridden at realm level

false

No. This should be set to false for performance purposes unless the membership of the primary group has any relevance for EDQ.

2.5 Using LDAP Server Profile

The LDAP server profile specifies how users are stored in the LDAP directory, and is used by EDQ to determine how to look up users and display them.

2.5.1 Default Profiles

EDQ ships with a number of default profiles, which are selected using the ldap.profile property:

  • adsldap: Microsoft Active Directory

  • inetorgoidldap: Oracle Internet Directory (OID)

  • inetorgopenldap: OpenLDAP using inetOrgPerson style schemas

  • rfc2307ldap: RFC 2307 (that is, Solaris)

2.5.2 Properties

LDAP profile properties can be overridden at global or realm level. In almost all cases these can be left at the values specified in the provided profile, with the notable exception of defaultusergroup and groupsearchfilter, however the properties are documented below for reference.

For properties which take LDAP search filters, the syntax is defined in RFC 4515 Lightweight Directory Access Protocol (LDAP): String Representation of Search Filters. See https://docs.oracle.com/cd/E20295_01/html/821-1222/fnyth.html for an introduction to the filter syntax.

Table 2-2 LDAP Profile Properties

Property Description Example Value

useprimarygroup

Defines whether or not to use the primary group (for example the "Domain Users" group in AD) to filter for users.

May be overridden at realm level

false

primarygroupfilter

Filter to apply to users based on their primary group. Only used if useprimarygroup is set to true

 

defaultusergroup

Canonical name of the default group that contains all EDQ users, used to determine users to display in issue, alert, and case assignment lists.

edqusers

groupsearchfilter

Additional filter for groups; an LDAP search filter.

(cn=edq*)

This will include all groups with a canonical name beginning with edq.

idmatch

User identity regular expression, which is used to derive a filter to search the directory for the user

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

userfilter

Search filter to locate a specific user

+(uid={1})

username

Attribute which stores the login name of a user

uid

primaryuserattr

Name of the attribute of a user which refers to groups they belong to

 

primarygroupattr

Name of the attribute of a group which primaryuserattr refers to

 

memberattr

Name of the attribute of a group which identifies its members

uniquemember

membertarget

Name of the attribute of a user which memberattr refers to

dn

membersearch

Search filter to locate members of a group

 

userdisplayname

   

2.6 Configuring Individual Realm LDAP Settings

This section provides details of the properties that are normally set at the realm level. Realm settings may be specified with either of the following methods:

  • In the login.properties file by using the syntax realm_name.property_name = value. This format enables you to specify settings for different realms within a single file, each set of properties having a different realm_name prefix.

  • In a file named realm_name.properties in a realms subdirectory of the security directory. This method requires a separate realm_name.properties file for each realm that you want to configure. The realm_name prefix is not needed for properties in the realm_name.properties file.

In a similar manner, profile settings and overrides can be specified in the security/login.properties file by using the syntax profile_name.property_name = value or, alternatively, in separate files named profile_name.properties in the security/profiles folder.

Table 2-3 LDAP Settings

Property Description Example Value Mandatory?

realm

The LDAP (AD or Kerberos) domain name.

EXAMPLE.COM

Yes

ldap.profile

Specifies the LDAP profile name used to configure parameters using shipped built-in settings. See Configuring Global LDAP Settings (login.properties) for details on LDAP profiles.

adsldap

Yes

auth

Specifies the user authentication method, if SSO is not used. Possible values are ldap or jaas. All current certified configurations use ldap.

ldap

Yes

auth.method

If the auth property is set to ldap, the auth.method property specifies which method is used to validate user credentials. See Validating Credentials When Single Sign-On Is Not Used for further information.

bind

No

label

Specifies an alternative user-friendly label for the realm to display in the dialog when logging into user applications.

myrealm

No

If not used, the configured realm name from the realm property is used.

gss

Specifies whether or not the realm supports SSO using Kerberos/GSSAPI. Possible values are true or false.

false

No

If not set, defaults to true.

ldap.server

A comma or space separated list of LDAP servers (either names or IP addresses).

Each server listed can include a specific port using the syntax server:port.

192.168.1.0:389, server2

No

If not specified, a DNS lookup is used to look for LDAP servers.

ldap.basedn

Distinguished name of the base entry of the LDAP hierarchy.

dc=example, dc=com

No

In many servers (including AD), this can be found from the RootDSE (the Root Directory Service Entry).

ldap.security

Sets the security mode for LDAP connection. Possible values are ssl or tls. See Using LDAP Over SSL/TLS for details.

tls

No

ldap.auth

Sets the authentication mode for LDAP connection.

Possible values are simple, digest-md5 or gss.

digest-md5

No

If not specified, this defaults to gss.

ldap.user

The LDAP username used to authenticate EDQ with the LDAP server.

This property must be set if ldap.auth is not set to gss.

cn=user, ou=users, dc=example, dc=com

Yes, if authentication mode is simple.

No, if the mode is digest-md5.

ldap.pw

The password associated with the LDAP username.

password

Yes, if authentication mode is simple or digest-md5.

No, otherwise

ldap.clientcreds

Specifies how the EDQ server connects to the LDAP server. If set, this parameter overrides the clientcreds parameter in the login.properties file. See Configuring Global LDAP Settings (login.properties) for more information.

true

No. If not set, the default value is the one specified at the Global level.

ldap.prof.defaultusergroup

Canonical name of the default group that contains all EDQ users, used for display of users in issue, alert, and case assignment lists.

edqusers

Recommended

If not set, this defaults to Domain Users on AD, which may be too large and cause display and memory issues.

ldap.prof.groupsearchfilter

Additional filter for groups; an LDAP search filter. See Configuring Global LDAP Settings (login.properties) for more information.

(cn=edq*)

This will include all groups with a name beginning with edq.

Recommended

If not set, no filter is used and all groups will be displayed on the External Groups configuration page.

LDAP server profile settings can be overridden in the LDAP realm settings by specifying the property with the prefix ldap.prof, for example: ldap.prof.defaultusergroup= group=edqusers,ou=groups,dc=example,dc=com.

2.7 Validating Credentials When Single Sign-On Is Not Used

In installations where Single Sign-On (SSO) is not used and the auth realm property is set to ldap, it is necessary to set the auth.method realm property to specify how user credentials are validated. The possible values for this property are as follows. They are described in the following sections.

"auth.method = bind"

"auth.method = password"

"auth.method = compare"

auth.method = bind

This setting directs the EDQ server to connect to the LDAP server to verify the user credentials. This is the default setting. Where the bind method is used, the following additional properties must be set:

  • auth.binddn: Specifies the actual user name that is used in the connection attempt. If omitted, a value in the form username@realmname is submitted. Otherwise, the value should be in the form search: dn, which uses the distinguished name (DN) of the user for the login.

  • auth.bindmethod: Specifies the authentication method that is used to connect to the LDAP server. The possible values are simple or digest-md5. The digest-md5 value encrypts the password on the network and is the recommended setting.

Note:

If auth.bindmethod is set to digest-md5 for an EDQ installation that is integrated with Active Directory, the auth.binddn property must be set to search: sAMAccountName.

auth.method = password

This setting directs the EDQ server to look up the user record on the LDAP server and then compare the submitted password to the stored password.

Note:

This method cannot be used with Active Directory servers.

The LDAP attribute that stores the password must be specified with the following property:

auth.password = search: attr

where: attr is the LDAP attribute.

auth.method = compare

This setting uses the LDAP compare method to validate the password. This method is more secure than auth.method = bind because a session is not created in the LDAP server.

The LDAP attribute that stores the password is specified with the auth.attribute property, which has a default value of userPassword. This default is the correct value for Oracle Internet Directory LDAP integrations.

2.8 LDAP Security

The ldap.security option controls security of the connection to the LDAP server. It is a comma separated list of options, which can be:

  • ssl: Use LDAP connections over SSL/TLS

  • tls: Use Start TLS extension to upgrade LDAP connections to encryption

  • qop=none

  • qop=auth

  • qop=auth-int

  • qop=auth-conf

By default, traffic to and from the LDAP server is unencrypted. LDAP traffic can be encrypted either by sending it over a Secure Sockets Layer (SSL) connection (LDAPS), or by using the Start TLS extension.

2.8.1 Using LDAP Over SSL/TLS

LDAP over SSL/TLS (LDAPS) establishes a secure connection to the LDAP server, and then sends LDAP traffic over it. This requires that the remote server presents a valid X.509 certificate. Specifically, the certificate's canonical name must match the host name of the server, and must be trusted or signed by a certificate authority (CA) trusted by the Java Runtime Environment (JRE) that is running EDQ.

Where an LDAP server presents an X.509 certificate that is either self-signed or signed by a certificate authority which is not part of the trusted defaults, EDQ must be configured to recognise these certificates.

2.8.1.1 Extracting Certificate from Active Directory

To connect over SSL/TLS to an Active Directory server without a certificate signed by a known certificate authority (typically a self-signed certificate), the certificate must be extracted from Active Directory and then imported into the JRE trusted certificates key store. The certificate can be extracted using Certutil (see https://technet.microsoft.com/en-in/library/cc732443.aspx for details), for example:

certutil -ca.cert certificate.crt

The extracted certificate then needs to be imported into the cacerts keystore belonging to the JRE, by following the instructions in Importing Certificates into JRE (for Tomcat).

2.8.1.2 Importing Certificates into JRE (for Tomcat)

The JRE includes a trusted certificate keystore, which can be found at the path lib/security/cacerts within the JRE installation folder. The keytool utility (provided with the JRE, see https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html) can import new certificates to this file, for example:

keytool -import -keystore lib\security\cacerts -file certificate.crt

At the prompts, provide the password, change it (note that you should not actually change this password), and confirm that you wish to trust the imported certificate.

2.8.1.3 Importing Certificates into OPSS (for WebLogic)

For instructions on managing the key/certificate stores used by WebLogic, see Fusion Middleware Administrator's Guide. For instructions on importing certificates into WebLogic Server, see https://docs.oracle.com/middleware/1221/opss/JISEC/cfgauthr.htm#JISEC2293.

2.8.2 Starting TLS

Alternatively the Start TLS LDAP extension can be used, where an unencrypted LDAP connection is established and encryption then negotiated. In this case, "relaxed checks" are performed on the LDAP server certificate, meaning that the LDAP server certificate does not need to be trusted. However, this means that EDQ cannot verify that it is connecting to the correct server, and requires that the network layer is trusted.

2.9 Example LDAP Configurations

Note:

The settings shown in these examples are included in the login.properties.template file with an additional # character at the beginning of each line. Remove this character to uncomment each property to make it active.

This section provides the following example configurations for the following LDAP technologies:

2.9.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 (user.name@example3.com)
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.9.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.9.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/host2.example2.com@EXAMPLE2.COM
# 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.9.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.

2.9.4.1 Example Settings for login.properties

The following are typical settings for integrating EDQ with Novell eDirectory.

# 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

2.9.4.2 Creating a novell.properties File

The EDQ installation does not come with a preconfigured6 profile for integrating with Novell eDirectory LDAP. If required, a novell.properties file must be created and saved in the security/profiles directory in the local configuration directory (oedq_local_home). The following is an example of this file.

# 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.10 Customizing Password Expiry Settings

You can customize the message that is presented to users if their password expires or is about to expire. By default, a standard dialog is displayed. This feature is available for users of Active Directory and any other LDAP server that supports the standard LDAP password policy response control.

To customize the message, you add variables to the login.properties file in the security directory of the local configuration directory (oedq_local_home/security).

2.10.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.10.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.10.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.10.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.11 Configuring Parent and Child Active Directory Domains

Parent and child domains in Active Directory can be defined in the login.properties file by defining separate realms for each domain. However, if these domains have full trust relationships, it is possible to define only the parent domain as a realm, as shown in the following examples.

2.11.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 john.doe@EXAMPLE.COM. The updated version adds the optional child domain component and would also match names like jane.doe@CHILD.EXAMPLE.COM.

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 user@EXAMPLE.COM, 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.12 Kerberos Keytabs for Active Directory Accounts

When EDQ is installed on a UNIX (Solaris, Linux, AIX, or HP-UX) server, you can configure it to use AD for user authentication by making LDAP connections to the AD server and performing user lookups.

In a basic configuration, the connection to AD is made with a user name and password configured in login.properties. The connection can be protected using SSL or TLS if necessary. SSO, in which the user logs into Windows and then does not need to log again into EDQ, is not available in this configuration since the EDQ server is not on the AD domain.

To enable SSO, the EDQ server must be set up to enable Kerberos authentication from the client PC. This authentication is achieved using the standard GSSAPI token exchange mechanism (RFC 4121) as follows:

  1. The client contacts the Domain Controller (DC) to request access to a service provided by the server application.

  2. The response from the DC is encoded into a token sent to the server by the client.

  3. The server validates this token and generates another token to send to the client.

  4. The token exchange can continue until client and server have established a secure context.

In practice, this exchange never requires more than one token in either direction.

At startup the server application sets up accept credentials, which it uses to initialize its half of the security context. When the server is running as the local system account on Windows, these credentials are obtained from the account's login context.

If the server is running on UNIX, it must use an account in AD to set up these credentials. It validates the request using 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.

2.12.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/testserver.example.com@EXAMPLE.COM (DES cbc mode with CRC-32)
 2   host/testserver.example.com@EXAMPLE.COM (DES cbc mode with RSA-MD5)
 2   host/testserver.example.com@EXAMPLE.COM (ArcFour with HMAC/md5)
 2   host/testserver@EXAMPLE.COM (DES cbc mode with CRC-32)
 2   host/testserver@EXAMPLE.COM (DES cbc mode with RSA-MD5)
 2   host/testserver@EXAMPLE.COM (ArcFour with HMAC/md5)
 2   TESTSERVER$@EXAMPLE.COM (DES cbc mode with CRC-32)
 2   TESTSERVER$@EXAMPLE.COM (DES cbc mode with RSA-MD5)
 2   TESTSERVER$@EXAMPLE.COM (ArcFour with HMAC/md5)
 2   HTTP/testserver.example.com@EXAMPLE.COM (DES cbc mode with CRC-32)
 2   HTTP/testserver.example.com@EXAMPLE.COM (DES cbc mode with RSA-MD5)
 2   HTTP/testserver.example.com@EXAMPLE.COM (ArcFour with HMAC/md5)
 2   HTTP/testserver@EXAMPLE.COM (DES cbc mode with CRC-32)
 2   HTTP/testserver@EXAMPLE.COM (DES cbc mode with RSA-MD5)
 2   HTTP/testserver@EXAMPLE.COM (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 Apache Directory Studio.

2.12.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.12.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.12.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.12.4.1 Oracle Directory Services Manager

ODSM is bundled with OID. For further information on how to use this tool for managing LDAP accounts, refer to the OID server administrators.

2.12.4.2 Apache Directory Studio

The Apache Directory Studio LDAP browser is a useful tool for examining and updating LDAP accounts.

To create a new account, use the following procedure:

  1. Launch the browser and close the Welcome window.

  2. Select New Connection... in the LDAP menu to create a new connection.

  3. Enter a name for the connection and the host name of an AD server.

  4. If the server supports TLS, select Use StartTLS Extension under Encryption Method.

  5. In the Authentication window, enter an AD user name (in the format user@DOMAIN or SHORTDOMAIN\user) and password. The AD directory tree is then visible in the LDAP browser area

If connected as an account with Administrator-level privileges, other AD accounts can be updated. For example, to add an SPN to a normal user account, follow these steps:

  1. Locate the user in the directory tree and click to see the user's LDAP attributes. Perform a search to find the user if there are a large number of objects.
  2. Right-click the Attributes window and select New Attribute....
  3. Select servicePrincipalName as the Attribute type and click Finish.
  4. The new attribute will appear in the list. Enter the required SPN as the value and press Enter.

Note:

If this is attempted using an account that does not have Administrator privileges, it will fail at the final step when changes are committed to AD. Therefore, it is possible to practice this procedure using a normal user account without making changes.

2.12.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/john.smith@EXAMPLE.COM

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.