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:
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 Section 2.1.1, "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 Section 2.5, "Using LDAP Server Profile"). Profiles are generally chosen from a set of predefined profile configurations (see Section 2.4, "Configuring Global LDAP Settings (login.properties)"), and contain technical details of the LDAP directory structure for the realms.
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 Section 2.6, "Configuring Individual Realm LDAP Settings" for details of the ldap.prof.defaultusergroup option.
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.
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:
Create a subdirectory called security in the local configuration directory (oedq_local_home/security).
Copy the login.properties file from the security directory of the base configuration directory (oedq_local_home/security) to oedq_local_home/security.
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.
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
Save the file.
Restart the application server to reload the configuration.
Once administrators can log in to EDQ, other group mappings should be configured through Launchpad administration.
To configure OPSS to use multiple LDAP servers (that is, for failover if one server is down), see Configuring Failover for LDAP Authentication Providers.
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 Section 2.3, "Integrating EDQ Directly with LDAP Servers" for details on the login.properties file.
To set up direct integration:
Navigate to the security directory in the EDQ local configuration directory (oedq_local_home/security).
Open the login.properties.template file with a text editor. This template contains sample settings that correspond to the supported LDAP providers.
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)
Save the file as login.properties in the same directory.
Restart the application server.
Other schemas can be supported by creating new profiles or extending existing profiles.
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 Section 2.6, "Configuring Individual Realm LDAP Settings".
Table 2-1 Global LDAP Settings
| Property | Description | Example Value | Mandatory? |
|---|---|---|---|
|
|
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 A realm configuration may be retained but disabled by removing it from this list. |
|
Yes. |
|
|
If set to If set to May be overridden at the realm level. |
|
No. If not set, the default value is |
|
|
Enables the use of x509 certificates for client authentication over SSL. There is a small performance cost associated with setting this to May be overridden at realm level. |
|
No If not set, the default is |
|
l |
Defines whether or not to use the primary group (for example the "Domain Users" group in AD). May be overridden at realm level |
|
No. This should be set to |
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.
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)
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 |
|---|---|---|
|
|
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 |
|
|
|
Filter to apply to users based on their primary group. Only used if useprimarygroup is set to true |
|
|
|
Canonical name of the default group that contains all EDQ users, used to determine users to display in issue, alert, and case assignment lists. |
|
|
|
Additional filter for groups; an LDAP search filter. |
This will include all groups with a canonical name beginning with edq. |
|
|
User identity regular expression, which is used to derive a filter to search the directory for the user |
|
|
|
Search filter to locate a specific user |
|
|
|
Attribute which stores the login name of a user |
|
|
|
Name of the attribute of a user which refers to groups they belong to |
|
|
|
Name of the attribute of a group which primaryuserattr refers to |
|
|
|
Name of the attribute of a group which identifies its members |
|
|
|
Name of the attribute of a user which memberattr refers to |
|
|
|
Search filter to locate members of a group |
|
|
|
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.
| Property | Description | Example Value | Mandatory? |
|---|---|---|---|
|
|
The LDAP (AD or Kerberos) domain name. |
|
Yes |
|
|
Specifies the LDAP profile name used to configure parameters using shipped built-in settings. See Section 2.4, "Configuring Global LDAP Settings (login.properties)" for details on LDAP profiles. |
|
Yes |
|
|
Specifies the user authentication method, if SSO is not used. Possible values are |
|
Yes |
|
|
If the |
|
No |
|
|
Specifies an alternative user-friendly label for the realm to display in the dialog when logging into user applications. |
|
No If not used, the |
|
|
Specifies whether or not the realm supports SSO using Kerberos/GSSAPI. Possible values are |
|
No If not set, defaults to |
|
|
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 |
|
No If not specified, a DNS lookup is used to look for LDAP servers. |
|
|
Distinguished name of the base entry of the LDAP hierarchy. |
|
No In many servers (including AD), this can be found from the RootDSE (the Root Directory Service Entry). |
|
|
Sets the security mode for LDAP connection. Possible values are |
|
No |
|
|
Sets the authentication mode for LDAP connection. Possible values are |
|
No If not specified, this defaults to |
|
|
The LDAP username used to authenticate EDQ with the LDAP server. This property must be set if |
|
Yes, if authentication mode is No, if the mode is |
|
|
The password associated with the LDAP username. |
|
Yes, if authentication mode is No, otherwise |
|
|
Specifies how the EDQ server connects to the LDAP server. If set, this parameter overrides the |
|
No. If not set, the default value is the one specified at the Global level. |
|
|
Canonical name of the default group that contains all EDQ users, used for display of users in issue, alert, and case assignment lists. |
|
Recommended If not set, this defaults to |
|
|
Additional filter for groups; an LDAP search filter. See Section 2.4, "Configuring Global LDAP Settings (login.properties)" for more information. |
This will include all groups with a name beginning with |
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.
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.
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:
Ifauth.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.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.
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.
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.
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.
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 Section 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.
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.
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.