12 Configuring LDAP Authentication Providers

Oracle WebLogic Server includes LDAP Authentication providers to give access to user information contained in several common LDAP identity stores.

This chapter includes the following sections:

• LDAP Authentication Providers Included in WebLogic Server

• Requirements for Using an LDAP Authentication Provider

• Configuring an LDAP Authentication Provider: Main Steps

• Accessing Other LDAP Servers

• Enabling an LDAP Authentication Provider for SSL

• Dynamic Groups and WebLogic Server

• Use of GUID and LDAP DN Data in WebLogic Principals

• Configuring Users and Groups in the Oracle Internet Directory and Oracle Virtual Directory Authentication Providers

• Example of Configuring the Oracle Internet Directory Authentication Provider

• Configuring Failover for LDAP Authentication Providers

• Configuring an Authentication Provider for Oracle Unified Directory

• Following Referrals in the Active Directory Authentication Provider

• Configuring Group Search in the LDAP Authentication Provider for Oracle Directory Server Enterprise Edition

• Improving the Performance of LDAP Authentication Providers

• Configuring an Administrator User from an External LDAP Server: an Example

LDAP Authentication Providers Included in WebLogic Server

WebLogic Server includes LDAP Authentication providers for identity stores such as Oracle Internet Directory, Oracle Virtual Directory, Oracle Unified Directory, and more. The full set of included LDAP Authentication providers are as follows:

• Oracle Internet Directory Authentication provider

• Oracle Virtual Directory Authentication provider

• Oracle Unified Directory Authentication provider

• iPlanet Authentication provider (for Oracle Directory Server Enterprise Edition)

• Active Directory Authentication provider

• Open LDAP Authentication provider

• Novell Authentication provider

• Generic LDAP Authentication provider

Each LDAP Authentication provider stores user and group information in an external LDAP server. They differ primarily in how they are configured by default to match typical directory schemas for their corresponding LDAP server. For information about configuring the Oracle Internet Directory and Oracle Virtual Directory Authentication providers to match the LDAP schema for user and group attributes, see Configuring Users and Groups in the Oracle Internet Directory and Oracle Virtual Directory Authentication Providers.

WebLogic Server does not support or certify any particular LDAP servers. Any LDAP v2 or v3 compliant LDAP server should work with WebLogic Server. The following LDAP directory servers have been tested:

• Oracle Internet Directory

• Oracle Virtual Directory

• Oracle Unified Directory

• Oracle Directory Server Enterprise Edition (formerly known as Sun iPlanet)

• Active Directory shipped as part of the Microsoft Windows platform

• Open LDAP

• Novell Directory Service (NDS)

An LDAP Authentication provider can also be used to access other LDAP servers. However, you must either use the LDAP Authentication provider (LDAPAuthenticator) or choose a pre-defined LDAP provider and customize it. See Accessing Other LDAP Servers.

Note:

The Active Directory Authentication provider also supports Microsoft Active Directory Application Mode (ADAM) as a standalone directory server.

Requirements for Using an LDAP Authentication Provider

If an LDAP Authentication provider is the only configured Authentication provider for a security realm, you must have the Admin role to boot WebLogic Server and use a user or group in the LDAP directory. Do one of the following in the LDAP directory:

• By default in WebLogic Server, the Admin role includes the Administrators group. Create an Administrators group in the LDAP directory, if one does not already exist. Make sure the LDAP user who will boot WebLogic Server is included in the group.

  The Active Directory LDAP directory has a default group called Administrators. Add the user who will be booting WebLogic Server to the Administrators group and define Group Base Distinguished Name (DN) so that the Administrators group is found.

• If you do not want to create an Administrators group in the LDAP directory (for example, because the LDAP directory uses the Administrators group for a different purpose), create a new group (or use an existing group) in the LDAP directory and include the user from which you want to boot WebLogic Server in that group. In the WebLogic Server Administration Console, assign that group the Admin role.

Note:

If the LDAP user who boots WebLogic Server is not properly added to a group that is assigned to the Admin role, and the LDAP authentication provider is the only authentication provider with which the security realm is configured, WebLogic Server cannot be booted.

Configuring an LDAP Authentication Provider: Main Steps

After you choose an LDAP Authentication provider that matches your LDAP server, you need to enable communication between the provider and the LDAP server, configure the way in which user and group information can be accessed in the LDAP server, and configure settings that optimize the performance of the LDAP Authentication provider.

To configure an LDAP Authentication provider, complete the following main steps:

1. Choose an LDAP Authentication provider that matches your LDAP server and create an instance of the provider in your security realm. See the following topics:

   • If you are using the WebLogic Server Administration Console, see Configure Authentication and Identity Assertion providers in the Oracle WebLogic Server Administration Console Online Help.

   • If you are using the WebLogic Scripting Tool (WLST), see Managing Security Data (WLST Online) in Understanding the WebLogic Scripting Tool. This section also explains how to use WLST to switch from one LDAP authentication provider to another.

2. Configure the provider-specific attributes of the LDAP Authentication provider, which you can do through the WebLogic Server Administration Console. For each LDAP Authentication provider, attributes are available to:

   1. Enable communication between the LDAP server and the LDAP Authentication provider. For a more secure deployment, Oracle recommends using the SSL protocol to protect communications between the LDAP server and WebLogic Server. Enable SSL with the SSLEnabled attribute.

   2. Configure options that control how the LDAP Authentication provider searches the LDAP directory.

      Note:

      The value you enter for principal must be an LDAP administrator who has the privilege to search users and groups in the corresponding LDAP server. If the LDAP administrator does not have privileges to search the LDAP server, an LDAP exception with error code 50 is generated.

   3. Specify where in the LDAP directory structure users are located.

   4. Specify where in the LDAP directory structure groups are located.

      Note:

      When specifying an LDAP search filter for users or groups using the following LDAPAuthenticatorMBean attributes, wildcards are accepted but they can have a negative performance impact on the LDAP server, particularly if you use a combination of them:

      • AllUsersFilter

      • UserFromNameFilter

      • AllGroupsFilter

      • GroupFromNameFilter

      For example, the following filter expression combines five wildcarded conditions, each condition using two asterisk wildcard characters:

      (|(cn=*wall*)(givenname=*wall*)(sn=*wall*)(cn=*wall*)(mail=*wall*))
      

      The preceding example filter would likely cause an unacceptable overhead on the corresponding LDAP server.

      Additionally, group names must not contain any trailing space characters.

   5. Define how members of a group are located.

   6. Set the name of the global universal identifier (GUID) attribute defined in the LDAP server.

      Note:

      If you are configuring either the Oracle Internet Directory or Oracle Virtual Directory Authentication provider, see Configuring Users and Groups in the Oracle Internet Directory and Oracle Virtual Directory Authentication Providers. This section explains how to match the authentication provider attributes for users and groups to the LDAP directory structure.

   7. Set timeout values for the connection to the LDAP server. You can specify two timeout values: a connection timeout, and a socket timeout.

      The connection timeout, specified in the LDAPServerMBean.ConnectTimeout attribute for all LDAP Authentication providers, has a default value of zero. This default setting specifies no timeout limit, and can result in a slowdown in WebLogic Server execution if the LDAP servers configured for an LDAP Authentication provider are unavailable. In addition, if WebLogic Server has multiple LDAP Authentication providers configured, the failure to connect to one LDAP server may block the use of the other LDAP Authentication providers.

      Oracle recommends that you set the LDAPServerMBean.ConnectTimeout attribute on the LDAP Authentication provider to a non-zero value; for example, 60 seconds. You can set this value via either the WebLogic Server Administration Console or WLST. You can also set this value in the config.xml file by adding the following configuration parameter for the LDAP Authentication provider:

      <wls:connect-time>60</wls:connect-time>
      

      Note:

      Oracle recommends that you do not edit the config.xml file directly.

      The socket timeout, specified in the -Dweblogic.security.providers.authentication.ldap.socketTimeout JVM configuration option, sets the timeout in seconds for connecting to any one LDAP server specified in the LDAPServerMBean.Host attribute. The default value of the socket timeout is 0, which sets no socket timeout on the connection.

      For information about the appropriate values to set for the connection timeout and socket timeout values for an LDAP Authentication provider, see Configuring Failover for LDAP Authentication Providers.

3. Configure performance options that control the cache for the LDAP server. Use the Configuration > Provider Specific and Performance pages for the provider in the WebLogic Server Administration Console to configure the cache. See Improving the Performance of LDAP Authentication Providers.

Note:

If the LDAP Authentication provider fails to connect to the LDAP server, or throws an exception, check the configuration of the LDAP Authentication provider to make sure it matches the corresponding settings in the LDAP server.

See the following topics:

• Accessing Other LDAP Servers

• Enabling an LDAP Authentication Provider for SSL

• Dynamic Groups and WebLogic Server

• Use of GUID and LDAP DN Data in WebLogic Principals

• Configuring Users and Groups in the Oracle Internet Directory and Oracle Virtual Directory Authentication Providers

• Example of Configuring the Oracle Internet Directory Authentication Provider

• Configuring Failover for LDAP Authentication Providers

• Configuring an Authentication Provider for Oracle Unified Directory

• Following Referrals in the Active Directory Authentication Provider

• Improving the Performance of LDAP Authentication Providers

Accessing Other LDAP Servers

The LDAP Authentication providers in this release of WebLogic Server are configured to work readily with the Oracle Internet Directory, Oracle Virtual Directory, Oracle Unified Directory, Oracle Directory Server Enterprise Edition (ODSEE), Active Directory, Open LDAP, and Novell NDS LDAP servers. You can use an LDAP Authentication provider to access other types of LDAP servers. Choose either the generic LDAP Authentication provider (LDAPAuthenticator) or the existing LDAP provider that most closely matches the new LDAP server and customize the existing configuration to match the directory schema and other attributes for your LDAP server.

If you are using Oracle Unified Directory, see Configuring an Authentication Provider for Oracle Unified Directory.

If you are using Active Directory, see Following Referrals in the Active Directory Authentication Provider.

Enabling an LDAP Authentication Provider for SSL

To configure SSL for an LDAP Authentication provider, you must create and configure a custom trust keystore for use with the LDAP server, and specify that the SSL protocol should be used by the LDAP Authentication provider when connecting to that LDAP server.

To do this, complete the following steps:

1. Configure the LDAP Authentication provider. Make sure you select SSLEnabled on the Configuration > Provider Specific page.
2. Obtain the root certificate authority (CA) certificate for the LDAP server.
3. Create a trust keystore using the preceding certificate. For example, the following example shows using the keytool command to create a JKS keystore named ldapTrustKS with the root CA certificate rootca.pem:
   keytool -importcert -keystore ./ldapTrustKS -trustcacerts -alias oidtrust -file rootca.pem -noprompt -storetype jks

   Note:

   When you enter the command as shown above, keytool prompts you to enter a password for the keystore.

   For more information about creating a trust keystore, see Configuring Keystores.

4. Copy the keystore to a location from which WebLogic Server has access.
5. Start the WebLogic Server Administration Console and navigate to the server-name > Configuration > Keystores page, where server-name is the WebLogic Server instance for which you are configuring this keystore.
6. If necessary, in the Keystores field, click Change to select the Custom Identity and Custom Trust configuration rules.
7. If the communication with the LDAP server uses 2-way SSL, configure the custom identity keystore, keystore type, and passphrase.
8. In Custom Trust Keystore, enter the path and file name of the trust keystore created in step 3.
9. In Custom Trust Keystore Type, enter jks. If you had created a PKCS12 keystore in step 3 (-storetype pkcs12), enter pkcs12 here.
10. In Custom Trust Keystore Passphrase, enter the password used when creating the keystore.
11. Reboot the WebLogic Server instance for changes to take effect.

See Configuring SSL. For more information about using the WebLogic Server Administration Console to configure keystores and enable SSL, see the following topics in the Oracle WebLogic Server Administration Console Online Help:

• Configure identity and trust

• Set up SSL

• Configure two-way SSL

Dynamic Groups and WebLogic Server

Many LDAP servers have a concept of dynamic groups or virtual groups. Many LDAP servers have a concept of dynamic groups or virtual groups. These are groups that, rather than consisting of a list of users and groups, contain some policy statements, queries, or code that define the set of users that belong to the group. Even if a group is marked dynamic, users must log out and log back in before any changes in their group memberships take effect. The term dynamic describes the means of defining the group and not any runtime semantics of the group within WebLogic Server.

Use of GUID and LDAP DN Data in WebLogic Principals

When a user is authenticated into WebLogic Server, an authentication provider creates a Subject with a set of user and group principals, which include the user and group names, respectively. The LDAP Authentication providers included in WebLogic Server also store the global universal identifier (GUID) and LDAP distinguished name (DN) data of users and groups as attributes of those principals. By default, WebLogic Server does not use the GUID or DN data in WebLogic principals. However, if the WebLogic domain is configured to use JAAS authorization, the GUID and DN data can be used in principal comparison operations that occur with Java policy decisions.

When configuring an LDAP Authentication provider, make sure that the name of the GUID attribute defined in the LDAP server is specified correctly for that provider. The default GUID attribute name for each LDAP Authentication provider included in WebLogic Server is listed in Table 12-1.

Table 12-1 Name of GUID Attribute for LDAP Authentication Providers in WebLogic Server

Provider	Default GUID Attribute Name
WebLogic Authentication provider	orclguidFoot 1
Oracle Internet Directory Authentication provider	orclguid
Oracle Virtual Directory Authentication provider	orclguidFoot 2
Active Directory Authentication provider	objectguidFoot 3
Oracle Unified Directory Authentication provider	entryuuid
iPlanet Authentication provider	nsuniqueid
Novell Authentication provider	guid
Open LDAP Authentication provider	entryuuid

^Footnote 1

Note that the GUID attribute name for the embedded LDAP server cannot be modified, so the WebLogic Authentication provider does not have a corresponding attribute that is configurable.

^Footnote 2

The GUID attribute name you configure for the Oracle Virtual Directory Authentication provider depends on whether Oracle Virtual Directory has a mapping of this attribute name. The mapping specifies a name for this attribute that is renamed from the one defined in the LDAP server with which Oracle Virtual Directory is connected. If a mapping exists, specify the name that is defined in the mapping. For example, if the GUID attribute is renamed in the mapping to OVDguid, configure the Oracle Virtual Directory Authentication provider to use OVDguid as the GUID attribute name. If a mapping does not exist, specify the name that is defined in the LDAP server. For example, if the LDAP server is Sun iPlanet Directory, and Sun iPlanet Directory defines the GUID attribute name as nsuniqueid, configure the Oracle Virtual Directory Authentication provider to use nsuniqueid.

^Footnote 3

The Active Directory Authentication provider also supports Microsoft Active Directory Application Mode (ADAM) as a standalone directory server.

For more information about how GUID and DN data in principal objects may be used, see Configuring a Domain to Use JAAS Authorization.

Configuring Users and Groups in the Oracle Internet Directory and Oracle Virtual Directory Authentication Providers

You can modify the default values in the Oracle Internet Directory and Oracle Virtual Directory Authentication providers that specify how users and groups are located in the LDAP server.

• Configuring User and Group Name Types

• Configuring Static Groups

Configuring User and Group Name Types

By default, the Oracle Internet Directory and Oracle Virtual Directory Authentication providers are configured to search users and groups in the LDAP directory using the class attribute types identified in the following table:

Table 12-2 Class Attribute Types Used for Searches

Class	Attribute	Type
User object class	user name	cn
Group object class	group name	cn

If the user name attribute type, or group name attribute type, defined in the LDAP directory structure differs from the default settings for the Authentication provider you are using, you must change those provider settings. The following sections explain how to make those changes.

Note:

Neither the Oracle Internet Directory Authentication provider nor Oracle Virtual Directory Authentication provider can read the name of a user or group from the LDAP server if the name contains an invalid character. Invalid characters are:

• Comma (,)

• Plus sign (+)

• Quotes (")

• Backslash (\)

• Angle brackets (< or >)

• Semicolon (;)

If either of these providers encounters a group or user name containing an invalid character, the name is ignored. (WebLogic Server in general does not support group names containing any of these invalid characters. See Create groups in the Oracle WebLogic Server Administration Console Online Help.)

This section includes the following topics:

• Changing the User Name Attribute Type

• Changing the Group Name Attribute Type

Changing the User Name Attribute Type

By default, the Oracle Internet Directory and Oracle Virtual Directory Authentication providers are configured with the user name attribute set to type cn. If the user name attribute type in the LDAP directory structure uses a different type — for example, uid — you must change the following Authentication provider attributes:

• AllUsersFilter

• UserFromNameFilter

• UserNameAttribute

For example, if the LDAP directory structure has the user name attribute type uid, the preceding Authentication provider attributes must be changed as shown in Table 12-3. The required changes are shown in bold.

Table 12-3 Changing the User Name Attribute Type for the User Object Class

Attribute Name	Default Setting	Required New Setting
UserNameAttribute	cn	uid
AllUsersFilterFoot 4	(&(cn=*)(objectclass=person))	(&(uid=*)(objectclass=person))
UserFromNameFilter	(&(cn=%u)(objectclass=person))	(&(uid=%u)(objectclass=person))

^Footnote 4

When specifying an LDAP search filter for users or groups, wildcards are accepted. However, using multiple asterisk wildcards, particularly for a user or group name attribute, have a negative performance impact on the LDAP server.

For information about configuring the user name attribute type, see the following topics in the Oracle WebLogic Server Administration Console Online Help:

• Configure the Oracle Internet Directory Authentication provider

• Configure the Oracle Virtual Directory Authentication provider

Changing the Group Name Attribute Type

By default, the Oracle Internet Directory and Oracle Virtual Directory Authentication providers are configured with the group name attribute type of cn for the static group object class and dynamic group object class. If the group name attribute type in the LDAP directory structure is different — for example, type uid is used — you must change the following Authentication provider attributes:

• AllGroupsFilter

• GroupFromNameFilter

• StaticGroupNameAttribute (for static groups)

• DynamicGroupNameAttribute (for dynamic groups)

For example, if the LDAP directory structure of the group object class uses a group name attribute of type uid, you must change the Authentication provider attributes as shown in Table 12-4. The required changes are shown in bold.

Table 12-4 Required Changes for the Group Name Attribute Type

Attribute Name	Default Setting	Required Changes
StaticGroupNameAttribute	cn	uid
DynamicGroupNameAttribute	cn	uid
AllGroupsFilterFoot 5	(&(cn=*)(|(objectclass=groupofUniqueNames)(objectclass=orcldynamicgroup)))	(&(uid=*)(|(objectclass=groupofUniqueNames)(objectclass=orcldynamicgroup)))
GroupFromNameFilterFoot 5	(|(&(cn=%g)(objectclass=groupofUniqueNames))(&(cn=%g)(objectclass=orcldynamicgroup)))	(|(&(uid=%g)(objectclass=groupofUniqueNames))(&(uid=%g)(objectclass=orcldynamicgroup)))

^Footnote 5

When specifying an LDAP search filter for users or groups, wildcards are accepted. However, using multiple asterisk wildcards, particularly for a user or group name attribute, have a negative performance impact on the LDAP server.

For more information about configuring group name attributes, see the following topics in the Oracle WebLogic Server Administration Console Online Help

• Configure the Oracle Internet Directory Authentication provider

• Configure the Oracle Virtual Directory Authentication provider

Configuring Static Groups

The Oracle Internet Directory and Oracle Virtual Directory Authentication providers are configured by default with the following settings for static groups:

• Static group object class name of groupofuniquenames

• Static member DN attribute of type uniquemember

However, the directory structure of the Oracle Internet Directory or Oracle Virtual Directory LDAP server with which you are configuring either of these Authentication providers may instead define the following for static groups:

• Static group object class name of groupofnames

• Static member DN attribute of type member

If the LDAP database schema contains the static group object class name of groupofnames, and the static member DN attribute of type member, you need to change the Oracle Internet Directory or Oracle Virtual Directory Authentication provider attribute settings as shown in Table 12-5. The required changes are shown in bold.

Table 12-5 Attribute Settings for Static Groups in the Oracle Internet Directory and Oracle Virtual Directory Authentication Providers

Attribute	Default Setting	Required Changes
StaticGroupObjectClass	groupofuniquenames	groupofnames
StaticMemberDNAttribute	uniquemember	member
AllGroupsFilterFoot 6	(&(cn=*)(|(objectclass=groupofUniqueNames)(objectclass=orcldynamicgroup)))	(&(cn=*)(|(objectclass=groupofnames)(objectclass=orcldynamicgroup)))
GroupFromNameFilterFoot 6	(|(&(cn=%g)(objectclass=groupofUniqueNames))(&(cn=%g)(objectclass=orcldynamicgroup)))	(|(&(cn=%g)(objectclass=groupofnames))(&(cn=%g)(objectclass=orcldynamicgroup)))

^Footnote 6

When specifying an LDAP search filter for users or groups, wildcards are accepted. However, using multiple asterisk wildcards, particularly for a user or group name attribute, have a negative performance impact on the LDAP server.

For more information about configuring static groups, see the following topics in the Oracle WebLogic Server Administration Console Online Help:

• Configure the Oracle Internet Directory Authentication provider

• Configure the Oracle Virtual Directory Authentication provider

Example of Configuring the Oracle Internet Directory Authentication Provider

Learn how to set up a sample Oracle Internet Directory Authentication provider and use a quick method to verify the configuration.

Perform the following steps to configure this provider:

1. Create a new Oracle Internet Directory Authentication provider from the WebLogic Server Administration Console:

   1. In the Console, navigate to the Security Realms > RealmName > Providers > Authentication page.

   2. Click New to add a new Authentication provider.

   3. Enter a name of your choice and choose OracleInternetDirectoryAuthenticator as the type.

   4. Click OK.

2. Configure the new Oracle Internet Directory Authentication provider:

   1. Click the name of the new provider you just created.

   2. On the Common page, set the Control Flag as needed (REQUIRED, REQUISITE, OPTIONAL or SUFFICIENT), as described in Setting the JAAS Control Flag Option.

   3. Navigate to the Provider Specific page.

   4. Configure the Connection section with the Oracle Internet Directory server values you want to use. The port must be the Oracle Internet Directory LDAP port. For the purpose of this example, assume the following values:

      Host: hostname.com
      Port: 3060
      Principal: cn=orcladmin
      Credential: password
      SSLEnabled is unchecked
      

   5. Configure the Users section as per your Oracle Internet Directory configuration.

      As described in Changing the User Name Attribute Type, pay particular attention to the fields All Users Filter and User From Name Filter. They must reflect the value of the User Name Attribute field.

      The default value for User Name Attribute is cn and therefore the default values for the filter fields include (&(cn=)...) and (&(*cn=%u)...), respectively. If you change the User Name Attribute value, you must replace it accordingly in the filter fields as well.

      Note:

      If there are any leading or trailing white spaces in these filter field values, the users list may not be properly fetched from Oracle Internet Directory and you may not be able to authenticate using the Oracle Internet Directory Authentication provider.

      For the purpose of example, assume the following values. Key changes are marked in bold.

      User Base DN: cn=Users,dc=us,dc=oracle,dc=com
      All Users Filter: (&(uid=*)(objectclass=person))
      User From Name Filter: (&(uid=%u)(objectclass=person))
      User Seearch Scope: subtree
      User Name Attribute: uid
      User Object Class: person
      

   6. Configure the Groups section as per your Oracle Internet Directory configuration.

      As described in Changing the Group Name Attribute Type, by default the Oracle Internet Directory Authentication provider is configured with the group name attribute type of cn for the static group object class and dynamic group object class. If the group name attribute type in the LDAP directory structure is different, you must change other Authentication provider attributes to match.

      In addition, as described in Configuring Static Groups, the Oracle Internet Directory Authentication provider is configured by default with a Static group object class name of groupofuniquenames and a Static member DN attribute of type uniquemember.

      If the LDAP database schema instead contains the static group object class name of groupofnames, and the static member DN attribute of type member, you need to change the attribute settings as shown in Table 12-5.

      For the purpose of example, assume the following values. Key values that must match are marked in bold.

      Group Base DN: cn=Groups,dc=us,dc=oracle,dc=com
      All Groups Filter: (&(cn=*)(objectclass=groupofUniqueNames))
      
      Static Group Name Attribute: cn
      Static Group Object Class: groupofuniquenames
      Static Member DN attribute: uniquemember
      Static Group DNs from Member DN Filter: (&(uniquemember=%M)(objectclass=groupofuniquenames))
      
      Dynamic Group Name Attribute: (empty)
      Dynamic Group Object Class:   (empty)
      Dynamic Member URL Attribute: (empty)
      User Dynamic Group DN Attribute:  (empty)
      

   7. Configure all other sections as needed, using Configuring an LDAP Authentication Provider: Main Steps for guidance. In this example, all of the default values are appropriate.

   8. Save your changes.

3. If needed, order the providers to make the Oracle Internet Directory Authentication provider first in the list.

4. Restart the WebLogic Server to complete the changes.

5. Verify the setup.

   In the WebLogic Server Administration Console, navigate to the Security Realms > RealmName > Users and Groups page. You should be able to see all users and groups that exist in the Oracle Internet Directory LDAP structure.

Configuring Failover for LDAP Authentication Providers

You can configure an LDAP provider to work with multiple LDAP servers and enable failover if one LDAP server is not available. Use the Host attribute (found in the WebLogic Server Administration Console on the Configuration > Provider Specific page for the LDAP Authentication provider) to specify the names of the additional LDAP servers. Each host name may include a trailing space character and a port number. In addition, set the Parallel Connect Delay and Connection Timeout attributes for the LDAP Authentication provider

• Parallel Connect Delay—Specifies the number of seconds to delay when making concurrent attempts to connect to multiple servers. An attempt is made to connect to the first server in the list. The next entry in the list is tried only if the attempt to connect to the current host fails. This setting might cause your application to block for an unacceptably long time if a host is down. If the value is greater than 0, another connection setup thread is started after the specified number of delay seconds has passed. If the value is 0, connection attempts are serialized.

• Connection Timeout—Specifies the maximum number of seconds to wait for the connection to the LDAP server(s) to be established. If the value is set to 0, the default, there is no maximum time limit and WebLogic Server waits until the TCP/IP layer times out to return a connection failure.

  If multiple hosts are set in the Host attribute, the connection timeout controls the total timeout value for attempts to connect to all the specified hosts.

  Oracle recommends setting the connection timeout to a value of at least 60 seconds, depending upon the configuration of TCP/IP.

• Socket Timeout—Specifies the maximum number of seconds to wait for the connection to any one host specified in the Host attribute. The socket timeout is specified only using the -Dweblogic.security.providers.authentication.ldap.socketTimeout=seconds security parameter for the JVM in which WebLogic Server runs. The default value of the socket timeout is 0, which sets no socket timeout.

  Note that setting the socket timeout is not available in the WebLogic Server Administration Console. For information about the options for configuring WebLogic Server security parameters, see Security in Command Reference for Oracle WebLogic Server.

The following examples present scenarios that occur when an LDAP Authentication provider is configured for LDAP failover:

LDAP Failover Example 1

In the following scenario, an LDAP Authentication provider is configured with three servers in its Host attribute: directory.knowledge.com:1050, people.catalog.com, and 199.254.1.2. The status of the LDAP servers is as follows:

• directory.knowledge.com:1050 is down

• people.catalog.com is up

• 199.254.1.2 is up

WebLogic Server attempts to connect to directory.knowledge.com. After three seconds, or the socket connection throws an exception, the connect attempt times out and WebLogic Server attempts to connect to the next specified host (people.catalog.com). WebLogic Server then uses people.catalog.com as the LDAP Server for this connection. Otherwise, after another three seconds, WebLogic Server tries to connect to 199.254.1.2. This process continues, but will fail if the overall LDAP server connection process exceeds 10 seconds.

Table 12-6 LDAP Configuration Example 1

LDAP Option	Value
Host	directory.knowledge.com:1050 people.catalog.com 199.254.1.2
Parallel Connect Delay	0
Connect Timeout	10
Socket Timeout	3

LDAP Failover Example 2

In the following scenario, WebLogic Server attempts to connect to directory.knowledge.com. After 1 second (specified by the Parallel Connect Delay attribute), the connect attempt times out and WebLogic Server tries to connect to the next specified host (people.catalog.com) and directory.knowledge.com at the same time. If the connection to people.catalog.com succeeds, WebLogic Server uses people.catalog.com as the LDAP Server for this connection. WebLogic Server cancels the connection to directory.knowledge.com after the connection to people.catalog.com succeeds.

Table 12-7 LDAP Configuration Example 2

LDAP Option	Value
Host	directory.knowledge.com:1050 people.catalog.com 199.254.1.2
Parallel Connect Delay	1
Connect Timeout	10
Socket Timeout	3

Configuring an Authentication Provider for Oracle Unified Directory

Use the WebLogic Server Administration Console to configure the Oracle Unified Directory Authentication provider. Complete the following steps:

1. In the WebLogic Server Administration Console, navigate to the Security Realms > RealmName > Providers > Authentication page.
2. Click New to add a new Authentication provider.
3. Enter a name for the Authentication provider and choose OracleUnifiedDirectoryAuthenticator as the type.
4. Click OK.
5. In the Security Realms > RealmName > Providers > Authentication page, click the name of the Oracle Unified Directory Authentication provider you created, and select the Configuration > Provider Specific page.
6. Configure the connection attributes for Oracle Unified Directory, as well as any other attributes as appropriate.
7. In the field labeled GUID Attribute, located at the bottom of the page, make sure entryuuidis displayed.
8. Click Save.

Note:

After you configure the Oracle Unified Directory Authentication provider and subsequently log in to WebCenter as the LDAP user configured for that provider, you might receive a WCS error stating that the user is not found in the identity store. You receive this error if the DefaultAuthenticator provider in your security realm is set to REQUIRED. As a workaround, change the JAAS Control Flag for the DefaultAuthenticator provider to SUFFICIENT. See Setting the JAAS Control Flag Option.

Following Referrals in the Active Directory Authentication Provider

If Active Directory uses LDAP referrals, you must configure the Active Directory Authentication provider to follow those referrals by making sure that the LDAPServerMBean.FollowReferrals attribute is enabled. This attribute is enabled by default, but Oracle recommends that you make sure it is specifically enabled.

You can enable this attribute using WLST or the WebLogic Server Administration Console. If you are using the WebLogic Server Administration Console, this attribute is available from the Configuration > Provider Specific page for the Active Directory Authentication provider.

Configuring Group Search in the LDAP Authentication Provider for Oracle Directory Server Enterprise Edition

You can set up a security realm to use Oracle Directory Server Enterprise Edition (ODSEE) as the identity store by configuring the iPlanet Authentication provider. However, note that this identity store has a user/group association that works differently from other LDAP servers that affects how groups can be searched for a given user. In particular, a group entry in Oracle Directory Server Enterprise Edition has an attribute of memberuid that point to a user's uid attribute. This is different from the typical LDAP static group, which uses the member or uniquemember attributes to point to a user entry DN.

The IPlanetAuthenticatorMBean includes the following attributes that you can set, using WLST or the WebLogic Server Administration Console, to search for the groups in which a given user is a member. This is an alternative to the member or uniqueMember attribute-based user-to-group membership search (that is, static group search).

• UseMemberuidForGroupSearch — When enabled, this attribute specifies that the memberuid attribute of the group entry is used for looking up the groups in which a user is a member. (By default, the UseMemberuidForGroupSearch attribute is disabled, which causes the member or uniqueMember attributes to be used for group lookups.

• GroupFromUserFilterForMemberuid — Can be used to specify an LDAP search filter for searching groups for a given username.

To use the WebLogic Server Administration Console to search for the groups in which a given user is a member:

1. Navigate to the Configuration > Provider Specific page for the iPlanet Authentication provider.
2. Select Use Memberuid For Group Search.
3. Specify the LDAP search filter in Group From User Filter For Memberuid. The default value is (&(memberuid=%M)(objectclass=groupofuniquenames)).

Improving the Performance of LDAP Authentication Providers

WebLogic Server supports the use of several ways to improve the performance of LDAP Authentication providers, such as optimizing settings for the group membership caches, connection pool size, and user cache.

To improve the performance of LDAP Authentication providers:

• Optimize the group membership caches used by the LDAP Authentication providers. See Optimizing the Group Membership Caches.

• Optimize the connection pool size and user cache. See Optimizing the Connection Pool Size and User Cache.

• Expose the Principal Validator cache for the security realm and increase its thresholds. See Optimizing the Principal Validator Cache.

• If you are using the Active Directory Authentication provider, configure it to perform group membership lookups using the tokenGroups option. The tokenGroups option holds the entire flattened group membership for a user as an array of system ID (SID) values. The SID values are specially indexed in the Active Directory and yield extremely fast lookup response. See Configuring the Active Directory Authentication Provider to Improve Performance.

• If you are using the generic LDAP Authentication provider, you can use the LDAPAuthenticatorMBean API to analyze hit/miss statistics collected from the group membership and user caches. See Analyzing the Generic LDAP Authenticator Cache Statistics.

• When you are configuring a new LDAP Authentication provider or making changes to an existing one, an API is invoked to test the connection between this provider and the corresponding LDAP server during the configuration. See Testing the LDAP Connection During Configuration.

Optimizing the Group Membership Caches

To optimize the group membership caches for an LDAP Authentication provider, set the following attributes (found in the WebLogic Server Administration Console on the LDAP Authentication provider's Configuration > Provider Specific and Performance pages):

• Group Membership Searching—Available from the Provider Specific page, this attribute controls whether group searches are limited or unlimited in depth. This option controls how deeply to search into nested groups. For configurations that use only the first level of nested group hierarchy, this option allows improved performance during user searches by limiting the search to the first level of the group.

  • If a limited search is defined, Max Group Membership Search Level must be defined.

  • If an unlimited search is defined, Max Group Membership Search Level is ignored.

• Max Group Membership Search Level—Available from the Provider Specific page, this attribute controls the depth of a group membership search if Group Membership Searching is defined. Possible values are:

  • 0—Indicates only direct groups will be found. That is, when searching for membership in Group A, only direct members of Group A will be found. If Group B is a member of Group A, the members will not be found by this search.

  • Any positive number—Indicates the number of levels to search. For example, if this option is set to 1, a search for membership in Group A will return direct members of Group A. If Group B is a member of Group A, the members of Group B will also be found by this search. However, if Group C is a member of Group B, the members of Group C will not be found by this search.

• Enable Group Membership Lookup Hierarchy Caching— Available from the Performance page, this attribute indicates whether group membership hierarchies found during recursive membership lookup are cached. Each subtree found will be cached. The cache holds the groups to which a group is a member. This setting only applies if Group Membership is enabled. By default, it is disabled.

• Max Group Hierarchies in Cache—Available from the Performance page, this attribute specifies the maximum size of the Least Recently Used (LRU) cache that holds group membership hierarchies. A value of 1024 is recommended. This setting only applies if Enable Group Membership Lookup Hierarchy Caching is enabled.

• Group Hierarchy Cache TTL—Available from the Performance page, this attribute specifies the number of seconds cached entries stay in the cache. The default is 60 seconds. A value of 6000 is recommended.

In planning your cache settings, bear in mind the following considerations:

• Enabling a cache involves a trade-off of performance and accuracy. Using a cache means that data is retrieved faster, but runs the risk that the data may not be the latest available.

• The time-to-live (TTL) setting how long you are willing to accept potentially stale data. This depends a lot on your particular business needs. If you frequently changes group memberships for users, then a long TTL could mean that group related changes won't show up for a while, and you may want a short TTL. If group memberships almost never change after a user is added, a longer TTL may be fine.

• The cache size is related to the amount of memory you have available, as well as the cache TTL. Consider the number of entries that might be loaded in the span of the TTL, and size the cache in relation to that number. A longer TTL will tend to require a larger cache size.

Optimizing the Connection Pool Size and User Cache

When configuring any of the LDAP Authentication providers, you can improve the performance of the connection between WebLogic Server and the LDAP server by optimizing the size of the LDAP connection pool and user cache. To make these optimizations, complete the following steps:

1. Set the LDAP connection pool size to 100 by using either of the following methods:

   • Define the following system property in the setDomainEnv script, which is located in the bin directory of the WebLogic domain:

     -Dweblogic.security.providers.authentication.LDAPDelegatePoolSize=100
     

   • In the WebLogic Server Administration Console, select the Provider Specific page for the LDAP authentication provider you are configuring (Security Realms > myrealm > Providers > Authentication > your LDAP Authentication provider > Provider Specific), and specify 100 in the field labeled Connection Pool Size.

2. Enable and enlarge the cache used with the LDAP server by completing the following steps in the WebLogic Server Administration Console:

   1. Select the Provider Specific page for the LDAP Authentication provider (Security Realms > myrealm > Providers > Authentication > your LDAP Authentication provider > Provider Specific).

   2. Scroll towards the bottom and make sure that Cache Enabled is checked.

   3. In the field labeled Cache Size, specify a value of 3200 KB.

   4. In the field labeled Cache TTL, specify a time-to-live value that matches the Group Hierarchy Cache TTL value (see Optimizing the Group Membership Caches). A value of 6000 is recommended).

   5. Set the results timeout value for the LDAP server. On the current Provider Specific configuration page, specify a value of 1000 ms in the field labeled Results Time Limit.

3. Restart WebLogic Server for the changes to take effect.

Configuring Dynamic Groups in the iPlanet Authentication Provider to Improve Performance

Dynamic groups do not list the names of their members. Instead, the membership of the dynamic group is constructed by matching user attributes. Because group membership needs to be computed dynamically for dynamic groups, there is a risk of performance problems for large groups. Configuring the iPlanet Authentication provider appropriately can improve performance where dynamic groups are involved.

In the iPlanet Authentication provider, the User Dynamic Group DN Attribute attribute specifies the attribute of an LDAP user object that specifies the distinguished names (DNs) of dynamic groups to which this user belongs. If such an attribute does not exist, WebLogic Server determines if a user is a member of a group by evaluating the URLs on the dynamic group. By default, User Dynamic Group DN Attribute is null. If you set User Dynamic Group DN Attribute to some other value, to improve performance set the following attributes for the iPlanet Authentication provider:

UserDynamicGroupDNAttribute="wlsMemberOf"
DynamicGroupNameAttribute="cn" 
DynamicGroupObjectClass=""
DynamicMemberURLAttribute="" 

To set these attributes in the WebLogic Server Administration Console:

1. Expand Security Realms > RealmName > Providers > Authentication.
2. On the Provider Specific tab for your iPlanet Authentication provider, set User Dynamic Group DN Attribute. Set Dynamic Group Object Class and Dynamic Member URL Attribute to null (delete anything in the fields) and leave Dynamic Group Name Attribute set to cn.

Optimizing the Principal Validator Cache

To improve the performance of an LDAP Authentication provider, the settings of the cache used by the WebLogic Principal Validation provider can be increased as appropriate. The Principal Validator cache used by the WebLogic Principal Validation provider caches signed WLSAbstractPrincipals. To optimize the performance of the Principal Validator cache, set these attributes for your security realm (found in the WebLogic Server Administration Console on the Configuration > Performance page for the security realm):

• Enable WebLogic Principal Validator Cache—Indicates whether the WebLogic Principal Validation provider uses a cache. This setting only applies if Authentication providers in the security realm use the WebLogic Principal Validation provider and WLSAbstractPrincipals. By default, it is enabled.

• Max WebLogic Principals In Cache—The maximum size of the Last Recently Used (LRU) cache used for validated WLSAbstractPrincipals. The default setting is 500. This setting only applies if Enable WebLogic Principal Validator Cache is enabled.

Configuring the Active Directory Authentication Provider to Improve Performance

To configure an Active Directory Authentication provider to use the tokenGroups option, set the following attributes (found in the WebLogic Server Administration Console on the Active Directory Authentication provider's Configuration > Provider Specific page):

• Use Token Groups for Group Membership Lookup—Indicates whether to use the Active Directory tokenGroups lookup algorithm instead of the standard recursive group membership lookup algorithm. By default, this option is not enabled.

  Note:

  Access to the tokenGroups option is required (meaning, the user accessing the LDAP directory must have privileges to read the tokenGroups option and the tokenGroups option must be in the schema for user objects).

• Enable SID to Group Lookup Caching—Indicates whether or not SID-to-group name lookup results are cached. This setting only applies if the Use Token Groups for Group Membership Lookup option is enabled.

• Max SID To Group Lookups In Cache—The maximum size of the Least Recently Used (LRU) cache for holding SID to group lookups. This setting applies only if both the Use Token Groups for Group Membership Lookup and Enable SID to Group Lookup Caching options are enabled.

Analyzing the Generic LDAP Authenticator Cache Statistics

If you are using the generic LDAP Authentication provider, then you can use the LDAPAuthenticatorMBean API to analyze hit/miss statistics collected from the group membership and user caches. To analyze cache statistics, you must enable cache collection and statistics of the cache. You can do this by using either the WebLogic Server Administration Console or the WebLogic Scripting Tool (WLST).

• Using the WebLogic Server Administration Console — To enable cache collection and statistics using the Administration Console, perform the following steps:

  1. Expand Security Realms > RealmName > Providers > Authentication.

  2. On the Provider Specific tab for your LDAP Authentication provider, select the check boxes for the Cache Enabled and Cache Statistics Enabled entries.

  3. Save the changes. If automatic realm restart is enabled, you do not need to restart the domain after activating your changes.

• Using the WebLogic Scripting Tool (WLST) — Cache statistics can be accessed through a runtime MBean, LdapAuthenticatorRuntimeMBean, using the WebLogic Scripting Tool (WLST). The following example demonstrates the use of WLST to retrieve cache statistics:

  connect('','','t3://host:port')
  Please enter your username :
  Please enter your password :
  ...
  serverRuntime()
  cd("ServerSecurityRuntime/")
  cd("$servername")
  cd("RealmRuntimes/myrealm/AuthenticatorRuntimes/OracleInternetDirectoryAuthenticator")
  ls()
   
  The cache statistics data:
  ----
  -r--   GroupCacheHits                               47
  -r--   GroupCacheQueries                            49
  -r--   GroupCacheSize                               1
  -r--   GroupCacheStatStartTimeStamp                 2015-07-15 19:24:02.702
  -r--   Name                                         OracleInternetDirectoryAuthenticator
  -r--   ProviderName                                 OracleInternetDirectoryAuthenticator
  -r--   Type                                         LdapAuthenticatorRuntime
  -r--   UserCacheHits                                296
  -r--   UserCacheQueries                             300
  -r--   UserCacheSize                                2
  -r--   UserCacheStatStartTimeStamp                  2015-07-15 19:24:01.64

Note:

Cache statistics is not supported for the DefaultAuthenticator Authentication provider.

Testing the LDAP Connection During Configuration

Similar to the JDBC connection testing, WebLogic Server tests the connection between the Authentication provider and the LDAP server.

On the Provider Specific page, after you configure a new LDAP Authentication provider or make changes to an existing one, when you save your configuration changes, WebLogic Server tests the connection between this provider and the corresponding LDAP server. If the test succeeds, the configuration settings are saved and you may activate them. If the test fails, an error message is displayed indicating a problem. No configuration settings are saved.

Configuring an Administrator User from an External LDAP Server: an Example

Learn an example of how to configure an administration user from an external LDAP server and perform a quick method of verifying the configuration. In this example, the user, orcladmin, is configured for Oracle Unified Directory Authentication provider. The goal is to configure WebLogic Server to allow orcladmin to log into the WebLogic Administration console as an administrator.

Perform the following tasks to configure an the user, orcladmin, from an external LDAP server:

1. Create and configure an LDAP Authentication provider.
   1. Before you configure the LDAP Authentication provider, you need to obtain the User Base DN and Groups Base DN details. To obtain these details from the LDAP server, you must download and install a third party browser tool. You can find JXplorer, an open source browser tool, at the following location:
      http://jxplorer.org/downloads/users.html

      This example assumes that you are using JXplorer LDAP browser tool; other LDAP browser tools may vary in detail.

   2. In the LDAP browser tool, configure a new connection and enter your host and port details along with the Base DN of the LDAP server.
   3. In the Security section, choose the User + Password level from the drop-down list, and enter your user credentials. Alternatively, you can log in as an anonymous user if permitted.
   4. Click OK to configure the connection. The LDAP tree should appear in the Explore tab on the left pane.
   5. Navigate to the hierarchy where your user is created, and right click the user to copy its DN in a text file, for example, ou=people, o=example.com. This DN will be used as the User Base DN for configuring the LDAP authentication provider.
      To obtain the Groups Base DN navigate to the groups hierarchy and copy the DN details in a text file. For example, ou=groups, o=example.com.
   6. With the LDAP host, port, Principal credentials, and User and Group base DN details, configure a new LDAP Authentication provider using the WebLogic Server Administration Console. In the Administration Console, navigate to the Security Realms > RealmName > Providers page and click New to add a new Authentication provider. Enter a name for the Authentication provider and choose OracleUnifiedDirectoryAuthenticator as the type. Click OK.
   7. Click the name of the Oracle Unified Directory Authentication provider you created, and select the Configuration > Provider Specific page.
   8. Configure the mandatory connection attributes, such as the Host, Port, Principal, Credential, for the user. Enter the User Base DN and the Group Base DN that you obtained from the third party LDAP browsing tool in the previous steps.
   9. Click Save. If automatic realm restart is enabled, you do not need to restart the domain after activating your changes.
2. Configure the default WebLogic Authentication provider.
   1. Navigate to Security Realms > RealmName >Providers > DefaultAuthenticator.
   2. On the Common Configuration page, set the Control Flag to SUFFICIENT.
   3. If automatic realm restart is enabled, you do not need to restart the domain after activating your changes.
3. Create and configure global security roles.
   1. Verify whether the LDAP user and/or group is successfully configured. Navigate to Security Realms > RealmName > Users and Groups, and ensure that you can see the name of the user or group you created.
   2. Click the Roles and Policies tab and expand Global Roles > Roles. On the Admin role row, click the View Role Conditions link, and click Add Conditions.
   3. On the Edit Global Role page, select Group or User from the Predicate List drop-down menu, and click Next.
   4. In the User Argument Name field, enter the LDAP User/Group name you created in the previous steps, and click Add followed by Finish.
   5. Click Save.
      For more information about creating and configuring global security roles, see Create global security roles in Oracle WebLogic Server Administration Console Online Help.
4. Verify your configuration.
   Log out from the WebLogic Administration Console and log back in with the LDAP user credentials that you created. You should be able to log in as the new LDAP user.