28 Managing the Embedded LDAP Server

Learn how to configure and manage the embedded LDAP server included in WebLogic Server which is the data store for the default Authentication, Authorization, Credential Mapping, and Role Mapping providers.

Configuring the Embedded LDAP Server

The embedded LDAP server contains user, group, group membership, security role, security policy, and credential map information. By default, each WebLogic domain has an embedded LDAP server configured with the default values set for each type of information.

The Default Authentication, Authorization, Credential Mapping, and Role Mapping providers use the embedded LDAP server as their data store. If you use any of these providers in a new security realm, you may want to change the default values for the embedded LDAP server to optimize its use in your environment.

Note:

The performance of the embedded LDAP server is best with fewer than 10,000 users. If you have more users, consider using a different LDAP server and Authentication provider.

See Configure the embedded LDAP server in the Oracle WebLogic Server Administration Console Online Help.

The data file and change log file used by the embedded LDAP server can potentially grow quite large. You can configure maximum sizes for these files with the following weblogic.Server command line arguments:

  • -Dweblogic.security.ldap.maxSize=<max bytes>, which limits the size of the data file used by the embedded LDAP server. When the data file exceeds the specified size, WebLogic Server eliminates from the data file space occupied by deleted entries.

  • -Dweblogic.security.ldap.changeLogThreshold=<number of entries>, which limits the size of the change log file used by the embedded LDAP server. When the change log file exceeds the specified number of entries, WebLogic Server truncates the change log by removing all entries that have been sent to all Managed Servers.

Embedded LDAP Server Replication

The embedded LDAP server for a domain consists of a primary LDAP server, maintained in the domain's Administration Server, and a replicated LDAP server maintained in each Managed Server in the domain. You can manage the behavior of the embedded LDAP server on the Administration Server and Managed Servers using the WebLogic Server Administration Console.

When changes are made using a Managed Server, updates are sent to the embedded LDAP server on the Administration Server. The embedded LDAP server on the Administration Server maintains a log of all changes. The embedded LDAP server on the Administration Server also maintains a list of Managed Servers and the current change status for each one. The embedded LDAP server on the Administration Server sends appropriate changes to each Managed Server and updates the change status for each server. This process occurs when an update is made to the embedded LDAP server on the Administration Server. However, depending on the number of updates, it may take several seconds or more for the change to be replicated to the Managed Server.

By selecting the Domain > Security > Embedded LDAP page in the WebLogic Server Administration Console, you can configure the behavior of the embedded LDAP server on the Administration Server and the Managed Servers in a domain. You can set these attributes:

  • Refresh Replica At Startup — Specifies whether the embedded LDAP server in a Managed Server should refresh all replicated data at boot time. This setting is useful if you have made many changes when the Managed Server was not active, and you want to download the entire replica instead of having the Administration Server push each change to the Managed Server.

  • Master First — Specifies whether a Managed Server should always connect to the primary embedded LDAP server on the Administration Server, instead of connecting to the local replicated LDAP server.

See Configure the embedded LDAP server in the Oracle WebLogic Server Administration Console Online Help.

Note:

Deleting and modifying the configured security providers through the WebLogic Server Administration Console may require manual clean up of the embedded LDAP server. Use an external LDAP browser to delete unnecessary information.

Viewing the Contents of the Embedded LDAP Server from an LDAP Browser

To view the contents of the embedded LDAP server through an LDAP browser, you must download and install an external LDAP browser, change the credential for the embedded LDAP server, and configure a new connection in the LDAP browser.

The steps for viewing the contents of the embedded LDAP server through an LDAP browser are described in detail:

  1. Download and install an external LDAP browser. You can find one LDAP browser at the following location:

    http://www.openldap.org/

    In this procedure, it is assumed that you are using this LDAP browser; other LDAP browsers may differ in detail.

  2. In the WebLogic Server Administration Console, change the credential for the embedded LDAP server:

    1. Expand Domain > Security > Embedded LDAP.

    2. In the Credential field, enter the new credential.

    3. In the Confirm Credential field, enter the new credential again.

    4. Click Save.

    5. Reboot WebLogic Server.

      Note:

      Changing the credential can affect the operation of the domain. Do not perform this step on a production server.

  3. Start the LDAP browser. To start the LDAP Browser/Editor mentioned in step 1, use the following command:

    lbe.sh
    
  4. In the LDAP browser, configure a new connection in the LDAP browser:

    1. Select the QuickConnect tab.

    2. Set the host field to localhost.

    3. Set the port field to 7001 (7002 if SSL is being used).

    4. Set the Base DN field to dc=mydomain where mydomain is the name of the WebLogic domain you are using.

    5. Uncheck the Anonymous Bind option.

    6. Set the User DN field to cn=Admin.

    7. Set the Password field to the credential you specified in Step 2.

  5. Click the new connection.

    Use the LDAP browser to navigate the hierarchy of the embedded LDAP server.

    Note:

    You can also view the contents of the embedded LDAP server by exporting its data and reviewing the exported file. See Exporting and Importing Information in the Embedded LDAP Server.

Exporting and Importing Information in the Embedded LDAP Server

Learn how to export and import data from the embedded LDAP server using either the WebLogic Server Administration Console or an LDAP browser.

To export and import data with the Console, use the Migration page of each security provider. See Export data from a security provider and Import data into a security provider in the Oracle WebLogic Server Administration Console Online Help.

Note:

When you use the WebLogic Server Administration Console Migration tab to export security data, the export process deletes any existing files in the target directory with the .dat extension. Always export security data to an empty directory.

This section describes how to use an LDAP browser to export and import data stored in the embedded LDAP server. Table 28-1 summarizes where data is stored in the hierarchy of the embedded LDAP server.

Table 28-1 Location of Security Data in the Embedded LDAP Server

Security Data Embedded LDAP Server DN

Users

ou=people,ou=myrealm,dc=mydomain 

Groups

ou=groups,ou=myrealm,dc=mydomain 

Security roles

ou=ERole,ou=myrealm,dc=mydomain 

Security policies

ou=EResource,ou=myrealm,dc=mydomain 

To export security data from the embedded LDAP server using the LDAP Browser/Editor:

  1. Enter the following command at a command prompt to start the LDAP Browser/Editor:

    lbe.sh
    
  2. Specify the data to be exported (for example, to export users specify ou=people,ou=myrealm,dc=mydomain).

  3. Select the LDIF > Export option.

  4. Select Export all children.

  5. Specify the name of the file into which the data will be exported.

To import security data into the embedded LDAP server using the LDAP Browser/Editor:

  1. Enter the following command at a command prompt to start the LDAP browser:
    lbe.sh
    
  2. Specify the data to be imported (for example, to import users, specify ou=people,ou=myrealm,dc=mydomain).
  3. In the LDAP Browser/Editor, select the LDIF > Import option.
  4. Select Update/Add.
  5. Specify the name of the file from which the data will be imported.

LDAP Access Control Syntax

The embedded LDAP server supports the IETF LDAP Access Control Model for LDAPv3. Learn how that access control is implemented within the embedded LDAP server. Apply these rules directly to entries within the directory as intended by the standard or configure and maintain them by editing the access control file (acls.prop).

Note:

The default behavior of the embedded LDAP server is to allow access only from the Administrator account in WebLogic Server. The WebLogic security providers use only the Administrator account to access the embedded LDAP server. If you are not planning to access the embedded LDAP server from an external LDAP browser or if you are planning only to use the Administrator account, you do not need to edit the acls.prop file and can ignore the information in this section.

The Access Control File

The access control file (acls.prop) maintained by the embedded LDAP server contains the complete list of access control lists (ACLs) for an entire LDAP directory. Each line in the access control file contains a single access control rule. An access control rule is made up of the following components:

Example 28-1 shows a sample access control file.

Example 28-1 Sample acl.props File

[root]|entry#grant:r,b,t#[all]#public

ou=Employees,dc=octetstring,dc=com|subtree#grant:r,c#[all]#public:
ou=Employees,dc=octetstring,dc=com|subtree#grant:b,t#[entry]#public:
ou=Employees,dc=octetstring,dc=com|subtree#deny:r,c#userpassword#public:
ou=Employees,dc=octetstring,dc=com|subtree#grant:r#userpassword#this:
ou=Employees,dc=octetstring,dc=com|subtree#grant:w,o#userpassword,title,
description,
postaladdress,telephonenumber#this:
cn=schema|entry#grant:r#[all]#public:

Access Control Location

Each access control rule is applied to a given location in the LDAP directory. The location is normally a distinguished name (DN) but the special location [root] can be specified in the acls.prop file if the access control rule applies to the entire directory.

If an entry being accessed or modified on the LDAP server does not equal or reside below the location of the access control rule, the given access control rule is not evaluated further.

Access Control Scope

The following access control scopes are defined:

  • Entry—An ACL with a scope of Entry is only evaluated if the entry in the LDAP directory shares the same DN as the location of the access control rule. Such rules are useful when a single entry contains more sensitive information than parallel or subentries entries.

  • Subtree—A scope of Subtree is evaluated if the entry in the LDAP directory equals or ends with the location of this access control. This scope protects means the location entry and all subentries.

If an entry in the directory is covered by conflicting access control rules (for example, where one rule is an Entry rule and the other is a Subtree rule), the Entry rule takes precedence over rules that apply because of the Subtree rule.

Access Rights

Access rights apply to an entire object or to attributes of the object. Access can be granted or denied. Either of the actions grant or deny may be used when you create or update the access control rule.

Each LDAP access right is discrete. One right does not imply another right. The rights specify the type of LDAP operations that can be performed.

This section includes the following topics:

Attribute Permissions

The permissions shown in Table 28-2 apply to actions involving attributes.

Table 28-2 Attribute Permissions

Permission Description

r Read

Read attributes. If granted, permits attributes and values to be returned in a Read or Search operation.

w Write

Modify or add attributes. If granted, permits attributes and values to be added in a Modify operation.

o Obliterate

Modify and delete attributes. If granted, permits attributes and values to be deleted in a Modify operation.

s Search

Search entries with specified attributes. If granted, permits attributes and values to be included in a Search operation.

c Compare

Compare attribute values. If granted, permits attributes and values to be included in a Compare operation.

m Make

Make attributes on a new LDAP entry below this entry.

The m permission is required for all attributes placed on an object when it is created. Just as the w and o permissions are used in the Modify operation, the m permission is used in the Add operation. The w and o permissions have no bearing on the Add operation and m has no bearing on the Modify operation. Since a new object does not yet exist, the a and m permissions needed to create it must be granted to the parent of the new object. This requirement differs from w and o permissions which must be granted on the object being modified. The m permission is distinct and separate from the w and o permissions so that there is no conflict between the permissions needed to add new children to an entry and the permissions needed to modify existing children of the same entry. In order to replace values with the Modify operation, a user must have both the w and o permissions.

Entry Permissions

The permissions shown in Table 28-3 apply to entire LDAP entries.

Table 28-3 Entry Permissions

Permission Description

a Add

Add an entry below this LDAP entry. If granted, permits creation of an entry in the DIT subject to control on all attributes and values placed on the new entry at the time of creation. In order to add an entry, permission must also be granted to add at least the mandatory attributes.

d Delete

Delete this entry. If granted, permits the entry to be removed from the DIT regardless of controls on attributes within the entry.

e Export

Export entry and all subentries to new location.

If granted, permits an entry and its subentries (if any) to be exported; that is, removed from the current location and placed in a new location subject to the granting of suitable permission at the destination.

If the last RDN is changed, Rename permission is also required at the current location.

In order to export an entry or its subentries, there are no prerequisite permissions to the contained attributes, including the RDN attribute. This is true even when the operation causes new attribute values to be added or removed as the result of the changes to the RDN.

i Import

Import entry and subentries from specified location.

If granted, permits an entry and its subentries (if any) to be imported; that is, removed from one location and placed at the specified location (if suitable permissions for the new location are granted).

When you import an entry or its subentries, the contained attributes, including the RDN attributes, have no prerequisite permissions. This is true even when the operation causes new attribute values to be added or removed as the result of the changes to RDN.

n RenameDN

Change the DN of an LDAP entry. Granting the Rename permission is necessary for an entry to be renamed with a new RDN, taking into account consequential changes to the DN of subentries. If the name of the superior entry is unchanged, the grant is sufficient.

When you rename an entry, there are no prerequisite permissions for the contained attributes, including the RDN attributes. This is true even when the operation causes new attribute values to be added or removed as the result of the changes of RDN.

b BrowseDN

Browse the DN of an entry. If granted, this permission permits entries to be accessed using directory operations that do not explicitly provide the name of the entry.

t ReturnDN

Allows DN of entry to be disclosed in an operation result. If granted, this permission allows the distinguished name of the entry to be disclosed in the operation result.

Attributes Types

The attribute types to which an access control rule applies should be listed in the ACL where necessary. The following keywords are available:

  • [entry] indicates the permissions apply to the entire object. This could mean actions such as delete the object, or add a child object.

  • [all] indicates the permissions apply to all attributes of the entry.

If the keyword [all] and another attribute are both specified within an ACL, the more specific permission for the attribute overrides the less specific permission specified by the [all] keyword.

Subject Types

Access control rules can be associated with a number of subject types. The subject of an access control rule determines whether the access control rule applies to the currently connected session.

The following subject types are defined:

  • authzID—Applies to a single user that can be specified as part of the subject definition. The identity of that user in the LDAP directory is typically defined as a DN.

  • Group—Applies to a group of users specified by one of the following object classes:

    • groupOfUniqueNames

    • groupOfNames

    • groupOfUniqueURLs

    The first two types of groups contain lists of users, and the third type allows users to be included in the group automatically based on defined criteria.

  • Subtree—Applies to the DN specified as part of the subject and all subentries in the LDAP directory tree.

  • IP Address—Applies to a particular Internet address. This subject type is useful when all access must come through a proxy or other server. Applies only to a particular host, not to a range or subnet.

  • Public—Applies to anyone connected to the directory, whether they are authenticated or not.

  • This—Applies to the user whose DN matches that of the entry being accessed.

Grant/Deny Evaluation Rules

The decision whether to grant or deny a client access to the information in an entry is based on many factors related to the access control rules and the entry being protected. Throughout the decision making process, these guiding principles apply:

  • More specific rules override less specific ones (for example, individual user entries in an ACL take precedence over a group entry).

  • If a conflict still exists in spite of the specificity of the rule, the subject of the rule determines which rule will be applied. Rules based on an IP Address subject are given the highest precedence, followed by rules that are applied to a specific AuthzID or This subject. Next in priority are rules that apply to Group subjects. Last priority is given to rules that apply to Subtree and Public subjects.

  • When there are conflicting ACL values, Deny takes precedence over Grant.

  • Deny is the default when there is no access control information. Additionally, an entry scope takes precedence over a subtree scope.

Backup and Recovery

Weblogic Server provides support to recover from a corrupt embedded LDAP server file.

If any of your security realms use the Default Authentication, Authorization, Credential Mapping, or Role Mapping providers, you should maintain an up-to-date backup of the following directory tree:

domain_name/servers/adminServer/data/ldap

In the preceding directory, domain_name is the domain root directory and adminServer is the directory in which the Administration Server stores run-time and security data.

Note:

In WebLogic Server 12.2.1.3.0 and later, users are removed from the Default Authenticator LDIF templates after the users are loaded during realm initialization. Therefore, you should not delete the contents of the domain_name/servers directory because the data cannot be recovered. If desired, you can disable this feature by setting the system property weblogic.security.doNotRemoveUsersFromLDIFT to true. The default is false.

For more information about backing up the embedded LDAP server data, see the following topics:

If the embedded LDAP server file becomes corrupt or unusable, the Administration Server will generate a NumberFormatException and fail to start. This situation is rare but can occur if the disk becomes full and causes the embedded LDAP file to enter into an invalid state.

To recover from an unusable embedded LDAP server file, complete the following steps:

  1. Change to the following directory:
    domain_name/servers/adminServer/data
    
  2. Rename the embedded LDAP server file, as in the following example:
    mv ldap ldap.old
    

    By renaming the file, and not deleting it completely, it remains available to you for analysis and potential data recovery.

  3. Start the Administration Server.

    When the Administration Server starts, a new embedded LDAP server file is created.

  4. Restore any data to the new embedded LDAP server that was added since the time the WebLogic domain was created.

    If you have configured a backup of the embedded LDAP server, you can restore the backed up data by importing it. See Exporting and Importing Information in the Embedded LDAP Server.