Skip Headers
Oracle® Beehive Installation Guide
Release 1 (1.4) for Linux x86

Part Number E13791-03
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

18 Integrating and Synchronizing LDAP with Oracle Beehive

Oracle Beehive user data may be mastered by the Oracle Beehive User Directory Service (UDS) or an external LDAP-based directory. "Mastered" means that a master source is used as the point of reference to determine the correct value for any user account attribute, and this source is used for making any changes to any account details.

This module describes how to integrate and synchronize UDS with an external LDAP-based directory, such as Oracle Internet Directory, so that all user data is mastered by the LDAP-based directory.

If UDS is synchronized with an external LDAP server, it will contact the LDAP server at regular intervals for all records that were changed. UDS will update its records accordingly. You may change the frequency that UDS contacts the LDAP server.

If you make a change in UDS, it will not update the LDAP server with which it is synchronized.

Note:

It is not necessary to master all user account attributes in an LDAP server; some attributes may be mastered in LDAP and others in UDS. However, all users that need to authenticate or login must be mastered in the same place.

The process of synchronizing an LDAP server with UDS involves creating the following files:

This module covers the following topics:

How Synchronization Works

An LDAP server maintains a change log in which it stores incremental changes made to directory objects. It stores these changes sequentially based on the change log number.

UDS contacts the LDAP server at regular intervals (whose duration is determined by the LDAP mapping profile) and requests the latest change log number and all records that were changed since the last stored change log number.

Note:

If any change is made to the LDAP server that alters the change log number, such as restoring the LDAP server from a backup or switching to a cloned instance, you must export all users and groups from LDAP and import them into UDS again as described in "Step 3: Loading Users and Groups".

Because any LDAP server may be synchronized with UDS, you must provide UDS with an LDAP mapping profile. This file specifies how to convert entries in your LDAP server to Oracle Beehive users and groups and which entries to synchronize.

Requirements

Oracle Beehive Release 1 supports Oracle Internet Directory, Microsoft Active Directory, IBM Tivoli Directory Server, Sun Directory Server, and OpenLDAP Directory.

Synchronizing LDAP with Oracle Beehive User Directory Service

Synchronizing LDAP with UDS consists of the following steps:

Notes:

You will need the user name and password of a user of your LDAP server who has access to the following:
  • Attributes in the Directory Information Tree (DIT)

  • Change logs

This user does not need write access to your LDAP server.

The steps in this module will use the user cn=orcladmin.

These steps use Oracle Internet Directory as the LDAP server to synchronize. For information specific to Active Directory, refer to the section "Active Directory Considerations".

This section also covers these topics:

Step 1: Creating an LDAP Mapping Profile

The LDAP mapping profile is an XML file that tells UDS the following information:

  • Which LDAP entries should be synchronized

  • How to treat entries with specific attributes or domain names (DNs) (for example, whether to map them as ENTERPRISE_USER, EXTENDED_ENTERPRISE_USER, or EXTERNAL_PERSON)

  • How to map the attributes of each user type to Oracle Beehive attributes.

Creating the LDAP mapping profile consists of the following steps:

Step A: Creating an LDAP Mapping Profile from a Template

Navigate to the directory <Oracle home>/beehive/templates/uds. It contains LDAP mapping profile templates for the following LDAP servers. These templates must be edited and customized depending on how your LDAP directory is configured and structured:

Table 18-1 LDAP Mapping Profile Templates

File Name Directory Type

adprofile_template.xml

Microsoft Active Directory

ibmprofile_template.xml

IBM Tivoli Directory Server

oidprofile_template.xml

Oracle Internet Directory

sunprofile_template.xml

Sun Directory Server

openldap_profile_template.xml

OpenLDAP Directory


Depending on your LDAP server, copy one of these files to another location, such as your home directory. Edit this file to create your LDAP mapping profile.

These steps use oidprofile_template.xml.

Step B: Renaming the Profile

Rename the profile in the <profile_name> tag. The following is an excerpt from an LDAP mapping profile:

<profile>
  <profile_name>my_profile</profile_name>
  <!-- ... -->
</profile>

Step C: Specifying LDAP Server Settings

Enter the LDAP server's host and port, administrator's username and password (which must be obfuscated), and the users and groups base search. The following is an excerpt from an LDAP mapping profile:

<ldap_server>
  <host>www.ldapserver.com</host>
  <port>389</port>
  <!-- <ssl_port>636</ssl_port> -->
  <connection_timeout>
    120
    <!-- This is the default value, in seconds -->
  </connection_timeout>
  <ldap_user_name>cn=orcladmin</ldap_user_name> 
  <!-- obfuscated password -->
  <ldap_user_password>
    fCgF4UPWg+Vm7IkSBSY07NOSkJ2XXTYRwGynrIM0mx/CHQF4W58Mab0izRX6Bxb6
  </ldap_user_password>
  <user_search_base>dc=oracle,dc=com</user_search_base>
  <group_search_base>
    cn=groups,dc=us,dc=oracle,dc=com
  </group_search_base>
  <primary_authentication_attribute>uid</primary_authentication_attribute>
  <!-- The primary authentication attribute is required only
       for DEFAULT profile -->
  <digest_authentication>
    <!-- Corresponds to the DigestAuthentication
         property of the component _CURRENT_SITE:LdapServer.
         This property can have multiple digest_authentication_attribute
         values -->
    <digest_authentication_attribute>
      <!-- An attribute from the user object (in the LDAP directory)
           that is required for digest authentication -->
    </digest_authentication_attribute>
  </digest_authentication>
</ldap_server>

In this excerpt, only users under dc=oracle,dc=com will be mapped to Oracle Beehive users. Similarly, only groups under cn=groups,dc=us,dc=oracle,dc=com will be mapped to Oracle Beehive groups.

The <connection_timeout> element is used by UDS to establish a connection to an external directory. If UDS cannot establish a connection within the number of seconds specified in this element, it aborts the connection attempt. The default value is 120 seconds. This element is available for Oracle Beehive Release 1 (1.3) and later.

For more information about the DigestAuthentication property, refer to "Configuring Digest Authentication".

Notes:

The LDAP user specified in <ldap_user_name> must have access to the change logs. If you later update the profile with a different LDAP user, then UDS will be synchronized with the state of the LDAP server corresponding to the latest change log number.

To obfuscate the LDAP administrator's password, use the beectl obfuscate command:

beectl obfuscate --expiration_time_in_minutes 0
Enter value for password:
Confirm value of password:
Successfully obfuscated the string.
fCgF4UPWg+Vm7IkSBSY07NOSkJ2XXTYRwGynrIM0mx/CHQF4W58Mab0izRX6Bxb6

Other beectl commands require obfuscated passwords. Use the same command to obfuscate them.

Step D: Providing Mapping Details for Each User Type and Static Group

Provide the mapping details for each user type and static group. The following is an excerpt from an LDAP mapping profile:

<user_type_map>
  <user_type_map_entry>
    <source_field_type>DN</source_field_type>
    <source_field_value>
      cn=users,dc=partners,dc=oracle,dc=com
    </source_field_value>
    <user_type>EXTENDED_ENTERPRISE_USER</user_type>
  </user_type_map_entry>
  <user_type_map_entry>
    <source_field_type>DN</source_field_type>
    <source_field_value>
      cn=users,dc=us,dc=oracle,dc=com
    </source_field_value>
    <user_type>ENTERPRISE_USER</user_type>
  </user_type_map_entry>
</user_type_map>

<group_type_map>
  <group_type_map_entry>
    <source_field_type>DN</source_field_type>
    <source_field_value>
      cn=groups,dc=us,dc=oracle,dc=com
    </source_field_value>
    <group_type>STATIC_GROUP</group_type>
  </group_type_map_entry>
</group_type_map>

This excerpt maps the following entries:

  • A user that is under the DN specified in <user_search_base> (in this example, it is dc=oracle,dc=com) and whose DN contains cn=users,dc=partners,dc=oracle,dc=com will be mapped to EXTENDED_ENTERPRISE_USER.

  • An entry that is under the DN specified <user_search_base> and whose DN contains cn=users,dc=us,dc=oracle,dc=com will be mapped to ENTERPRISE_USER.

Note:

Users of type EXTENDED_ENTERPRISE_USER must be specified before users of type ENTERPRISE_USER.

Once the users have been created in Oracle Beehive, they cannot be converted or updated to another type of user. For example, a user of type ENTERPRISE_USER cannot be converted to a user of type EXTENDED_ENTERPRISE_USER (and the other way around). Similarly, an EXTERNAL_PERSON cannot be converted to an ENTERPRISE_USER or EXTENDED_ENTERPRISE_USER.

Exclusion and Inclusion

Consider the following example:

<user_type_map>
  <user_type_map_entry>
    <source_field_name>UserStatus</source_field_name>
    <source_field_type>ATTRIBUTE</source_field_type>
    <source_field_value>true</source_field_value>
    <user_type>ENTERPRISE_USER</user_type>
  </user_type_map_entry>
</user_type_map>

In this example, a user (created in your LDAP directory) whose UserStatus attribute is set to true will be mapped to ENTERPRISE_USER.

However, if UserStatus is changed to any value other than true or nullified, then UDS synchronization will set the user's status as DISABLED in Oracle Beehive because the user no longer satisfies the condition specified in this <user_type_map>.

If UserStatus is changed back to true, then UDS synchronization will set the user's status as ENABLED in Oracle Beehive.

If a user in LDAP is deleted, UDS synchronization will set the user's status as MARKED_FOR_DELETE in Oracle Beehive.

Note:

The attribute specified in <source_field_name> (in the previous example, this would be UserStatus) must be of a string data type in your LDAP directory. UDS synchronization does not support any other LDAP data types.

Step E: Providing Scope and Membership Mapping Information

Provide community mapping information. Enter this information in an <scope_type_map> element. Users specified in a <scope_type_map> will be added to, or scoped within, the community (organization or enterprise) specified in the same element. A user may only be scoped within a single community.

You may optionally specify a <membership_type_map> element. Users specified in this element will be scoped within the community (organization or enterprise) specified by <scope_type_map>. In addition, users will become a member of the community specified in the <membership_type_map> element. A user may be a member of zero or more communities.

The following is an excerpt from an LDAP mapping profile.

<scope_type_map>
 
  <scope_type_map_entry>
    <source_field_name>OU</source_field_value>
    <source_field_type>ATTRIBUTE</source_field_type>
    <source_field_value>Alpha</source_field_value>
    <scope>
      <name>My_Organization</name>
      <identifier>orgn=My_Organization,enpr=My_Enterprise</identifier>
    </scope>
  </scope_type_map_entry>

  <scope_type_map_entry>
    <source_field_type>DN</source_field_type>
    <source_field_value>dc=us,dc=example,dc=com</source_field_value>
    <scope>
      <name>Entr1</name>
      <identifier>enpr=Oracle</identifier>
    </scope>
    <membership_type_map>
      <membership_type_map_entry>
        <source_field_type>DN</source_field_type>
        <source_field_value>
          dc=external,dc=us,dc=example,dc=com</source_field_value>
        <name>My_Organization</name>
        <identifier>orgn=My_Organization,enpr=My_Enterprise</identifier>
      </membership_type_map_entry>
    </membership_type_map>
  </scope_type_map_entry>
  <scope_type_map_entry>

</scope_type_map>

This excerpt maps the following entries:

  • A user that is under the attribute OU=Alpha will be scoped within the organization My_Organization.

  • A user that is under the DN dc=us,dc=oracle,dc=com will scoped within the enterprise My_Enterprise. A user that is under the DN dc=external,dc=us,dc=example,dc=com will scoped within the same enterprise (My_Enterprise). The same user will be a member of the organization My_Organization.

Tips:

To retrieve the identifier for an enterprise, call the following beectl command:
beectl list_enterprises
-----------------------------------------------
| Enterprise Name      | Identifier           |
-----------------------------------------------
| MyEnterprise         | enpr=My_Enterprise   |
-----------------------------------------------

To retrieve the identifier for an organization, call the following beectl command:

beectl list_organizations --scope enpr=My_Enterprose
 
Organization name:    My_Organization
Description:          Unknown
Identifier:           orgn=My_Organization,enpr=My_Enterprise
...

Step F: Providing Attribute Mapping for Each User Type and Static Group

Provide the attribute mapping for each user type and static group. The following is an excerpt from an LDAP mapping profile:

<directory_attribute_map>
  <directory_attribute_map_entry>
    <source_object>ENTERPRISE_USER</source_object>
    <AttributeMap>
      <Field>
        <source_attribute>givenname</source_attribute>
        <target_attribute>GIVENNAME</target_attribute>
        <target_attribute_type>ATTRIBUTE</target_attribute_type>
      </Field>
      <Field>
        <source_attribute>sn</source_attribute>
        <target_attribute>FAMILYNAME</target_attribute>
        <target_attribute_type>ATTRIBUTE</target_attribute_type>
      </Field>
    </AttributeMap>
  </directory_attribute_map_entry>
 
  <directory_attribute_map_entry>
    <source_object>EXTENDED_ENTERPRISE_USER</source_object>
    <AttributeMap>
      <Field>
        <source_attribute>givenname</source_attribute>
        <target_attribute>GIVENNAME</target_attribute>
        <target_attribute_type>ATTRIBUTE</target_attribute_type>
      </Field>
      <Field>
        <source_attribute>sn</source_attribute>
        <target_attribute>FAMILYNAME</target_attribute>
        <target_attribute_type>ATTRIBUTE</target_attribute_type>
      </Field>
    </AttributeMap>
  </directory_attribute_map_entry>
 
  <directory_attribute_map_entry>
    <source_object>STATIC_GROUP</source_object>
    <AttributeMap>
      <Field>
        <source_attribute>displayname</source_attribute>
        <target_attribute>NAME</target_attribute>
        <target_attribute_type>ATTRIBUTE</target_attribute_type>
      </Field>
    </AttributeMap>
  </directory_attribute_map_entry>
</directory_attribute_map>

In this excerpt, for each ENTERPRISE_USER, the givenname LDAP attribute will be mapped to the GIVENNAME attribute in Oracle Beehive. Similarly, for each STATIC_GROUP, the displayname LDAP attribute will be mapped to the NAME attribute in Oracle Beehive.

Mapping Postal Addresses

You may use the ORAPOSTAL user account address field scheme to map the postal address attributes of the users in your LDAP directory.

The ORAPOSTAL scheme contains the following fields:

  • l1: Address line 1

  • l2: Address line 2

  • box: Post box number

  • cy: City

  • st: State

  • code: Postal code

  • c: Country

Map your LDAP postal address attributes to these fields. The following excerpt demonstrates how to map to the fields of the ORAPOSTAL scheme:

<Field>
  <source_attribute>l1=street?cy=l?st=st?code=postalcode?c=c</source_attribute>
  <target_attribute>BUSINESS</target_attribute>
  <target_extended_attribute>ORAPOSTAL</target_extended_attribute>
  <target_attribute_type>ADDRESS</target_attribute_type>
</Field>

In this excerpt, LDAP postal address attributes will be mapped to ORAPOSTAL fields as follows:

  • street maps to l1

  • l maps to cy

  • st maps to st

  • postalcode maps to code

  • c maps to c

The entire postal address will be mapped to an address user account field (as specified by <target_attribute_type>) of type business (as specified by <target_attribute>).

Mapping Active Directory Proxy Addresses

An Active Directory user's entry contains an attribute named proxyAddresses that holds all the e-mail addresses of a particular user.

The following is an example of a proxyAddresses attribute:

proxyAddresses: smtp:rholmes@example.com ; SMTP:Robert.Holmes@example.com ; MBX:0 ; X400:c=US ; p=Example ; s=Holmes ; g=Robert ; RFAX: Holmes, Robert @

Consider the following example:

<Field> 
  <source_attribute>proxyAddresses</source_attribute> 
  <target_attribute>PROXY</target_attribute> 
  <target_extended_attribute>MAILTO</target_extended_attribute> 
  <target_attribute_type>ADDRESS</target_attribute_type> 
  <source_special_handling>PROXY</source_special_handling> 
</Field>

If the <source_special_handling> element is omitted, UDS synchronization will map the Active Directory proxyAddresses value of a user to the Oracle Beehive address type PROXY with the scheme MAILTO. This creates the following:

proxy1:mailto:smtp:rholmes@example.com
proxy2:mailto:smtp:robert.holmes@example.com
...
proxy8:mailto:RFAX: Holmes, Robert

If the <source_special_handling> element is included, Oracle Beehive will only synchronize values that start with smtp: and remove the text smtp:. As a result, the actual values in Oracle Beehive become the following:

proxy1:mailto:rholmes@example.com
proxy2:mailto:robert.holmes@example.com

Consequently, the <source_special_handling> element properly formats Active Directory e-mail addresses for Oracle Beehive and ignores values that start with MBX, RFAX, and other protocols not used by Oracle Beehive. This kind of mapping enables you to incorporate your legacy e-mail addresses into Oracle Beehive by synchronizing it with Active Directory's method of inbound mail lookup resolution.

Step G: Adding Profile to Oracle Beehive

A default directory profile is the one used by both authentication and UDS. This profile stores and reads LDAP server information from the site. For non-default directory profiles, the LdapServer object is stored within the profile itself.

For a default directory profile, the value of the <profile_flag> element (found in the <profile> element) is DEFAULT. For a non-default profile, the value is NON_DEFAULT.

Follow these steps to add a non-default directory profile:

  1. Add the profile with the following beectl command:

    beectl add_directory_profile --file oidprofile_template.xml
    

    The utility may return an error similar to the following:

    Failed to add directory profiles. See the log file.
    

    The log file is <Oracle home>/beehive/logs/oc4j/BEEMGMT/log.txt.

  2. Activate the configuration and commit changes.

    beectl activate_configuration
    beectl modify_local_configuration_files
    

To add a default directory profile, follow these steps:

  1. Add the profile with the following beectl command:

    beectl add_directory_profile --file oidprofile_template.xml
    
  2. Modify the AuthStoreType property of the Authentication Service to ldap with the beectl modify_property command. Refer to "Configuring Authentication Service to Use LDAP Server" for more information. (This is required so that the beectl modify_local_configuration_files works properly after you call beectl add_directory_profile to add the default profile.)

  3. Activate the configuration:

    beectl activate_configuration
    
Modifying Directory Profile

To modify a directory profile, you may use the beectl modify_directory_profile command, delete the existing directory profile and then add the updated profile, or modify one or more properties of the existing directory profile with the beectl modify_property command. In either case, you do not have to restart the LDAP server.

To modify a default profile to a non-default profile, modify the AuthStoreType property of the Authentication Service to db with the beectl modify_property command before activating the configuration and committing changes. Conversely, to modify a non-default profile to a default profile, modify the AuthStoreType property to ldap before activating the configuration and committing changes.

Directory Profile Validation

When you add a directory profile, Oracle Beehive validates the following in the XML file:

  1. LDAP credentials

  2. <poll_interval>, <profile_flag>, and <directory_type>

  3. The existence of <user_search_base> and <group_search_base> in your LDAP server

  4. For <scope_type_map> and <membership_type_map>, the following are validated:

    1. <source_field_type> (either DN or ATTRIBUTE)

    2. <source_field_value>: If <source_file_type> is DN (if <source_field_type> is ATTRIBUTE, then this validation is skipped)

    3. Values defined in <identifier> are validated for their existence; if you have specified an invalid enterprise or organization identifier, then an appropriate error message is returned

  5. For <user_type_map>, the following are validated:

    1. <source_field_type> (either DN or ATTRIBUTE)

    2. <source_field_value>: If <source_file_type> is DN (if <source_field_type> is ATTRIBUTE, then this validation is skipped)

    3. <user_type> (either ENTERPRISE_USER, EXTENDED_ENTERPRISE_USER, or EXTERNAL_PERSON)

  6. For <group_type_map> the following are validated:

    1. <source_field_type> (either DN or ATTRIBUTE)

    2. <source_field_value>: If <source_file_type> is DN (if <source_field_type> is ATTRIBUTE, then this validation is skipped)

    3. <group_type> (only valid value is STATIC_GROUP)

  7. For <directory_attribute_map> the following are validated:

    1. <target_attribute>: If <source_object> is ENTERPRISE_USER or EXTENDED_ENTERPRISE_USER, attribute mappings for the PRINCIPAL and FAMILYNAME target attributes must exist. If <source_object> is STATIC_GROUP, attribute mappings for the NAME target attribute must exist. If <source_object> is EXTERNAL_PERSON, attribute mappings for the FAMILYNAME target attribute must exist.

    2. <target_attribute_type>

    3. <target_extended_attribute>

Step 2: Enabling Synchronization

Enable the synchronization profile with the following commands: These commands enable a profile named oidldapdirectoryprofile:

beectl list_properties --component oidldapdirectoryprofile
beectl modify_property --component oidldapdirectoryprofile
                       --name ProfileState --value ENABLE
beectl activate_configuration

Note:

Your users will not be able to login yet, even though they are provisioned. Your users will able to login once you have completed the step described in "Configuring Authentication Service to Use LDAP Server".

Step 3: Loading Users and Groups

The following steps describe how to load all users and groups from the LDAP server to UDS:

  1. Generate an XML file from the LDAP server based on the mapping profile you loaded into Oracle Beehive in the previous step. The following command will create a file named UsersFromLDAP.xml in your home directory based on the profile named oidldapdirectoryprofile:

    beectl download_ldap_user_data
      --file UsersFromLDAP.xml
      --profile oidldapdirectoryprofile
    

    Note:

    You do not need administrator privileges to the LDAP server in order to extract data from it. Therefore a normal user may run the beectl download_ldap_user_data command.

    However, LDAP directories may impose a search limit for non-administrator users.

    For example, if your OID server has 500 records, OID may impose a search limit of 200 records for non-administrator users. If you are a normal user, the beectl download_ldap_user_data command will return only 200 records. As a result, you will not be able to synchronize all your users.

    Check your LDAP server documentation for maximum returned result limitations and how to manage them.

  2. In a text editor, open the file you generated (UsersFromLDAP.xml), and check for the following:

    • primary_principal is mapped to the attribute your LDAP server is configured for authentication, for example, sAMAccountName for Active Directory or uid (by default) for Oracle Internet Directory, otherwise authentication will fail

    • Enterprise and organization identifiers are correct for your Oracle Beehive deployment and all the organizations already exist in Oracle Beehive

    • The element familyname is defined and contains a value for each user

    Notes:

    If you receive many errors or inconsistencies in the generated XML file, delete it, correct the LDAP mapping profile, and recreate the generated XML file.
  3. Add the users in the generated XML file to Oracle Beehive with the beectl add_user command:

    beectl add_user --file UsersFromLDAP.xml
      --ldapbootstrap
    
  4. Make sure that the users were added successfully with the beectl list_users command:

    beectl list_users
    

Controlling How Often UDS Contacts the LDAP Server

By default, UDS contacts the LDAP server's change log every 30 seconds for updates. You may change this interval in either of the following ways:

  • In your LDAP mapping profile, change the value in the <poll_interval> tag.

    The following is an excerpt from an LDAP mapping profile with an interval set to 15 seconds:

    <profile>
      <profile_name>oidldapdirectoryprofile</profile_name>
      <poll_interval>15</poll_interval>
      <profile_state>DISABLE</profile_state>
      <profile_flag>DEFAULT</profile_flag>
      <directory_type>ORACLE_INTERNET_DIRECTORY</directory_type>
      <ldap_server>
      <!-- ... -->
    </profile>
    

    If you make any changes to your LDAP mapping profile, use the command modify_directory_profile to update the existing profile.

    Notes:

    The value of the <profile_flag> element may be DEFAULT or NON_DEFAULT.

    A DEFAULT profile is the one used by both authentication and UDS. This profile stores and reads LDAP server information from the site.

    For NON_DEFAULT profiles, the LdapServer object is stored within the profile itself.

    When adding a default profile, modify the AuthStoreType property of the Authentication Service to ldap with the beectl modify_property command. Refer to "Configuring Authentication Service to Use LDAP Server" for more information. (This is required so that the beectl modify_local_configuration_files works properly after you call beectl add_directory_profile to add the default profile.)

  • Use the beectl modify_property command. The following commands set the value of the property PollInterval to 15 seconds:

    beectl list_properties --component oidldapdirectoryprofile
    beectl modify_property
      --component oidldapdirectoryprofile
      --name PollInterval
      --value 15
    beectl activate_configuration
    

Note:

If the LDAP server's change log is cleaned up or purged more frequently than the UDS update frequency, data might be lost.

Retrieving Information About the LDAP Server

When you create a profile, Oracle Beehive creates an LdapServer configuration object. Use the beectl list_properties to get information about it:

beectl list_properties --component _CURRENT_SITE:LdapServer
-----------------------------------------------------------------------
| Property Name                    | Property Value                   |
-----------------------------------------------------------------------
| LdapServerHostName               | ldapserver.com                   |
| LdapServerPort                   | 389                              |
| LdapServerSslPort                | 636                              |
| SslEnabled                       | false                            |
| LdapServerUser                   | cn=orcladmin                     |
| LdapServerPassword               | [Protected Value]                |
| SSLMode                          | 0                                |
| UserSearchBase                   | cn=users,dc=us,dc=oracle,dc=com  |
| UserSearchBaseForSync            |                                  |
| GroupSearchBase                  | cn=groups,dc=us,dc=oracle,dc=com | 
| UserObjectClass                  |                                  |
| GroupObjectClass                 |                                  |
| PrimaryAuthenticationAttribute   | uid                              |
| PrimaryAuthenticationCredential  | not applicable                   |
| ProtocolAuthenticationAttribute  | not applicable                   | 
| ProtocolAuthenticationCredential | not applicable                   |
| VoiceAuthenticationAttribute     | not applicable                   |
| VoiceAuthenticationCredential    | not applicable                   |
| DirectoryType                    | ORACLE_INTERNET_DIRECTORY        | 
| Alias                            | OracleInternetDirectory          |
-----------------------------------------------------------------------

Notes:

You may have multiple LdapServer objects in an Oracle Beehive deployment if you have configured more than one LDAP mapping profile. The Authentication Service uses the LdapServer object set at the site level, which is created by the UDS mapping profile.

The site level LdapServer object may not have all required properties for authentication.

The following table describes the properties of the LdapServer object:

Table 18-2 LdapServer Properties

Property Name Required Description

LdapServerHostName

Required

LDAP server host name

LdapServerPort

Required

LDAP server port for non-SSL connections

LdapServerSslPort

Required

LDAP server port for SSL connections

SslEnabled

Required

If set to true, only SSL connections are used

LdapServerUser

Required

LDAP server user with bind and search privileges. This user must be able to look up attributes for all LDAP users provisioned to use Oracle Beehive

LdapServerPassword

Required

Password for LdapServerUser

SSLMode

Not used

Ignore this property

UserSearchBase

Required

User search base dn. The search scope is always subtree (recursive search).

GroupSearchBase

Required

Group search base dn. Search Scope is always subtree (recursive search).

UserObjectClass

Optional

Name of the user object class in the directory. This attribute is used to construct a search filter for the users.

If this value is not specified, a default value is used, described in "Default UserObjectClass and GroupObjectClass Values".

GroupObjectClass

Optional

Name of the group object class in the directory. This attribute is used to construct a search filter for the groups.

If this value is not specified, a default value is used, described in "Default UserObjectClass and GroupObjectClass Values".

PrimaryAuthenticationAttribute

Required

The name of the attribute the LDAP server uses to authenticate a user. For example, set this to uid for Oracle Internet Directory, or sAMAccountName for Active Directory.

PrimaryAuthenticationCredential

Not used

Ignore this property

ProtocolAuthenticationAttribute

Not used

Ignore this property

ProtocolAuthenticationCredential

Not used

Ignore this property

VoiceAuthenticationAttribute

Not used

Ignore this property

VoiceAuthenticationCredential

Not used

Ignore this property

DirectoryType

Required

Indicates which specific LDAP directory is being configured. Valid values are the following:

ORACLE_INTERNET_DIRECTORY
MICROSOFT_ACTIVE_DIRECTORY
IBM_TIVOLI_DIRECTORY
SUN_ONE_DIRECTORY
OPENLDAP_DIRECTORY

Alias

Optional

Alias for this LdapServer configuration object. Use this alias to refer to this LdapServer configuration object from beectl.


Default UserObjectClass and GroupObjectClass Values

Depending on the LDAP directory type, the values of UserObjectClass and GroupObjectClass are set to one of the values specified in the following table, if those properties have not been explicitly set:

Table 18-3 Default UserObjectClass and GroupObjectClass Values

Directory/Property UserObjectClass GroupObjectClass

IBM_TIVOLI_DIRECTORY

inetOrgPerson

groupOfNames

MICROSOFT_ACTIVE_DIRECTORY

user

group

ORACLE_INTERNET_DIRECTORY

orclUserV2

orclGroup

SUN_ONE_DIRECTORY

inetOrgPerson

groupOfUniqueNames

OPENLDAP_DIRECTORY

inetOrgPerson

groupOfNames


Configuring Authentication Service to Use LDAP Server

The following steps describe how to configure the Authentication Service so that it uses your LDAP server. These steps assume that you have already enabled a synchronization profile for your LDAP server.

Notes:

If you are using Active Directory as your LDAP server, refer to "Active Directory Considerations" before proceeding with these steps.

Before configuring the Authentication Service to use Active Directory, you must ensure that host names returned in an LDAP referral by Active Directory can be resolved by the Domain Name System (DNS) on the host on which you installed Oracle Beehive.

If you installed Oracle Beehive Integration for Zimbra in a separate Oracle home other than Oracle Beehive, then after configuring the Authentication Service to use your LDAP server, run the beectl modify_local_configuration_files command on both your Oracle Beehive Integration for Zimbra and Oracle Beehive homes.

  1. Modify the AuthStoreType property of the Authentication Service to ldap with the beectl modify_property command:

    beectl list_components --type AuthenticationService
    --------------------------------------------------
    | Component Type        | Component Identifier   |
    --------------------------------------------------
    | AuthenticationService | _AuthenticationService |
    --------------------------------------------------
    
    beectl modify_property --component _AuthenticationService
                           --name AuthStoreType --value ldap
    
    beectl activate_configuration
    
    beectl modify_local_configuration_files
    

    Note:

    The beectl modify_local_configuration_files command will ask you to run this command on all your other instances. Do not run this command on all your other instances at this time. For each instance, make your desired changes to the AuthStoreType property and run beectl activate_configuration before running the beectl modify_local_configuration_files command.
  2. To test the Authentication Service, log in with any user:

    beectl login
      --authuser newuser
      --authpassword <Password of newuser, obfuscated. To use non-obfuscated
      passwords, run beectl in shell mode>
    User newuser is successfully authenticated and logged in.
    

    To test connectivity with the LDAP server use either the commands ldapbind or ldapsearch. Refer to the documentation of your LDAP server for more information about these commands.

  3. Grant administration privileges to another LDAP user or group in your system.

    Note:

    Once you have changed AuthStoreType to ldap, you will not be able to login with the beeadmin account to administer your Oracle Beehive deployment.

    Therefore, you should assign administration privileges to another LDAP user or group or assign the appropriate privileges to particular users or groups depending on the security policy of your site.

    For more information about the beeadmin account, refer to the section "About Special and System-Reserved Accounts" in "Managing and Provisioning Oracle Beehive Users" in Oracle Beehive Administrator's Guide.

Configuring Digest Authentication

Digest authentication is an authentication method that involves using some known secrets (or passwords) from both the client and server to calculate a hash value. This hash value is transmitted instead of the actual secret (or password). One of the major benefits of digest authentication is that the password is not exposed while being transmitted.

To use digest authentication with a particular LDAP directory, the directory must be able to do one of the following:

Configuring digest authentication, using an LDAP directory as the authentication repository, involves the following steps:

For OpenLDAP Directory, refer to "Configuring Digest Authentication for OpenLDAP Directory".

Step A: Configure SSL for Oracle Beehive and LDAP Directory

Digest authentication requires that your Oracle Beehive instance and the corresponding LDAP server to be configured in SSL mode. Refer to "Configuring SSL" to configure your Oracle Beehive instance for SSL. Refer to the documentation of your LDAP directory to configure it in SSL mode.

Step B: Determine Digest Mechanism Depending on LDAP Directory

Determine the digest mechanism Oracle Beehive will use by referring to the following table. The digest mechanism used depends on the availability of a clear-text user password, reversible encrypted password, or a secure A1 hash value of the password. You may have to configure your LDAP directory to use certain digest mechanisms.

In the following table, each cell in the Digest Mechanism column specifies a digest mechanism and a list of password formats; the specified digest mechanism requires that your LDAP server is configured to store only one of these password formats.

Table 18-4 Supported Digest Authentication Mechanisms

Digest Mechanism Active Directory IBM Tivoli Directory Oracle Internet Directory Sun One Directory

SASL CRAM-MD5

  • Plain text

  • Reversible encryption

Not supported; Active directory does not allow any passwords to be read; the password attribute is write-only

Supported

Supported

Supported

SASL Digest-MD5

  • Plain text

  • Reversible encryption

  • A1 hash value

Supported; extend the schema to store the A1 hash value

Supported

Supported

Supported; extend the schema to store the A1 hash value

HTTP Digest

  • Plain text

  • Reversible encryption

  • A1 hash value

Supported; extend the schema to store the A1 hash value

Supported

Supported

Supported; extend the schema to store the A1 hash value

SyncML v1.0 Digest

  • Plain text

  • Reversible encryption

Not supported; Active directory does not allow any passwords to be read; the password attribute is write-only

Supported

Supported

Supported

Sync ML v1.1 Digest

  • Plain text

  • Reversible encryption

Not supported; Active directory does not allow any passwords to be read; the password attribute is write-only

Supported

Supported

Supported


Step C: Configure Oracle Beehive

These steps assume that you have already configured Oracle Beehive to authenticate with an LDAP directory.

  1. Set the properties UseSecureHash and AuthenticationRealm in the AuthenticationService component:

    • UseSecureHash: Set this property to true to use the A1 hash value. Set this property to false to use the plain or reversible encrypted password. This depends on which digest authentication method you are going to use. Refer to Table 18-4, "Supported Digest Authentication Mechanisms".

    • AuthenticationRealm: Default authentication realm. This value is returned to clients when digest authentication is initiated. For example, HTTP and SASL digest authentication requires that the realm value to be sent with the authentication challenge.

    The following beectl commands set UseSecureHash to true and AuthenticationRealm to myrealm@example.com:

    beectl modify_property
      --component _AuthenticationService
      --name UseSecureHash
      --value true
    
    beectl modify_property
      --component _AuthenticationService
      --name AuthenticationRealm
      --value myrealm@example.com
    
  2. Set the DigestAuthenticationAttribute property in the LdapServer configuration object. Refer to "Retrieving Information About the LDAP Server" for more information about this object.

    The DigestAuthentication property specifies which attributes from the user object (in the LDAP directory) are required for the digest authentication. This property can have multiple values. The format of the property value is <Mechanism Type>:<Attribute Name>. The following table lists the possible values for <Mechanism Type> and the type of attribute with which it is associated:

    Table 18-5 Valid Digest Mechanism Type Values

    <Mechanism Type> Value Type of Attribute to Specify

    DEFAULT

    Attribute name for reversible encrypted or plain password

    SASL.DIGEST_MD5

    Attribute name for SASL digest authentication

    HTTP.DIGEST

    Attribute name for HTTP digest authentication


    For example, suppose you are using Oracle Internet Directory as your LDAP server. Oracle Internet Directory stores the user password in reversible encrypted format in the attribute orclrevpwd. If you have also specified that Oracle Internet Directory stores the A1 hash value in the attribute authpassword;beehive, set DigestAuthenticationAttribute as follows:

    beectl modify_property
      --component <ID of LdapServer object>
      --name DigestAuthenticationAttribute
      --value DEFAULT:orclrevpwd
      --value SASL.DIGEST_MD5:authpassword;beehive
      --value HTTP.DIGEST:authpassword;beehive
    

    Note:

    To compute and set the A1 hash value, refer to the documentation of your LDAP server. You may also use a third-party tool to create this value or create this value yourself by using the information in RFC 2617, HTTP Authentication: Basic and Digest Access Authentication.
  3. Activate the configuration and commit changes.

    beectl activate_configuration
    beectl modify_local_configuration_files
    

Configuring Digest Authentication for OpenLDAP Directory

If you are using OpenLDAP Directory, follow these steps to configure digest authentication:

  1. Ensure your directory type is OPENLDAP_DIRECTORY, your Oracle Beehive instance is configured for SSL, and OpenLDAP Directory is in SSL mode.

  2. Add the value OPENLDAP_DIRECTORY:oracle.ocs.csi.authentication.handlers.impl.jaas.callback.impl.OcsLdapPasswordAccessor to the list of values in the PwdAccessorPlugin property of the _AuthenticationService component:

    beectl append_value
      --component _AuthenticationService
      --name PwdAccessorPlugin
      --value OPENLDAP_DIRECTORY:oracle.ocs.csi.authentication.handlers.
                impl.jaas.callback.impl.OcsLdapPasswordAccessor
    
  3. Ensure that you are storing user passwords as clear text (plain) in OpenLDAP. Simply use the ldapmodify command to add or modify a user's password.

  4. Activate the configuration and commit changes.

    beectl activate_configuration
    beectl modify_local_configuration_files
    

Changing LDAP Administrator's Password

To change the administrator's password of an LDAP server synchronized with Oracle Beehive, follow these steps:

  1. Stop Oracle Beehive with the beectl stop --all command.

  2. Change the password of the LDAP administrator in your LDAP server.

  3. Start Oracle Beehive with the beectl start command.

  4. Change the password for the LDAP administrator in Oracle Beehive with the following command (obfuscate the password with the beectl obfuscate command.)

    beectl modify_secure_property
      --component <LdapServer of the profile>
      --name LdapServerPassword
      --value <Password of LDAP administrator, obfuscated>
      --obfuscated
    
  5. Run the beectl modify_local_configuration_files command.

Oracle Internet Directory Considerations

This section covers the following topics:

Synchronizing with Directory Replication Group

A directory replication group (DRG) consists of the directory servers that participate in the replication of a given naming context. If you have synchronized Oracle Beehive with an Oracle Internet Directory server that belongs to a multimaster DRG, then ensure that the attribute orclDIPRepository is set to true.

This ensures changes made to any server in the multimaster DRG are synchronized with Oracle Beehive.

For more information about directory replication groups, refer to Chapter 29, "Oracle Internet Directory Replication Concepts" in Oracle Internet Directory Replication Concepts.

Migrating Oracle Internet Directory from One Server to Another

If you migrate an Oracle Internet Directory server (that is synchronized with Oracle Beehive) to another Oracle Internet Directory server, modify the LdapServer property in the _CURRENT_SITE component with the name of the new Oracle Internet Directory server:

beectl list_properties --component _CURRENT_SITE
 
...
 
| EventListenerDatabase    |                                      |
| SearchDatabase           |                                      |
| BusinessDatabase         |                                      |
| VirusScanEngineCluster   |                                      |
| SiteId                   | 17378                                |
| LdapServer               | OLD_OID_server_example.com           |
| LanguagePack             | byte array of size 656902            |
| ClusteringEnabled        | true                                 |
| DiagnosabilityProperties | 1f9fcf0e-7b46-427c-a6ef-636bcbb88f89 |
| DebugProperties          | 19804e92-9028-49b3-af36-be4ac4abb4f5 |
| BtiGlobalConfiguration   |                                      |
| Name                     | R1                                   |

beectl modify_property --component _CURRENT_SITE
  --name LdapServer
  --value <new Oracle Internet Directory server>
beectl modify_change_number
  --profile <name of your LDAP profile>
  --number <Changelog number of your new Oracle Internet Directory server>
beectl activate_configuration
beectl modify_local_configuration_files

Troubleshooting Synchronization between Oracle Beehive and Oracle Internet Directory

  • Check the files oidldapd.log and oidrepld.log from Oracle Internet Directory.

  • To retrieve change log information, the Oracle Directory Integration Server Control tool (odisrv) must be up and running. Refer to Chapter 2, "odisrv" in Oracle Identity Management User Reference.

  • Make sure that the orcldiprepository parameter is set to true. Refer to Chapter 9, "Oracle Identity Management Attribute Reference in Oracle Identity Management User Reference.

  • Make sure that the value of changeid from the bee_data.uds_sync_profile table is updated with the chg_no value from ods.ods_chg_log (which is a table from the Oracle Internet Directory schema). For more information about this table, see the section "LDAP-Based Replication" in Chapter 29, "Oracle Internet Directory Replication Concepts" in Oracle Internet Directory Administrator's Guide.

    Note: Take the chg_no value from Oracle Internet Directory used with the cloned system and not the information from the LDAP server used by the production system.

  • In Oracle Internet Directory, ensure that the attributes krbaPrincipalName and orclUserApplnProvStatus exist, otherwise create them. The bulkload bulk management tool might fail if these aren't defined.

    For more information about Oracle Internet Directory attributes, refer to Chapter 9, "Oracle Identity Management Attribute Reference in Oracle Identity Management User Reference.

    For more information about orclUserApplnProvStatus, refer to the section "Provisioning Status in Oracle Internet Directory" in Chapter 12, "Oracle Directory Integration Platform Service Concepts" in Oracle Identity Management Integration Guide.

    For more information about bulkload, refer to the section "bulkload" in Chapter 9, "Using Bulk Tools" in Oracle Internet Directory Administrator's Guide.

  • For more information about troubleshooting Oracle Internet Database, refer to Appendix J, "Troubleshooting Oracle Internet Directory" in Oracle Internet Directory Administrator's Guide.

Active Directory Considerations

During authentication, the Oracle Beehive Authentication Service may request Active Directory to perform an operation, such as a search. When Active Directory has referrals enabled, instead of the search results, Active Directory may respond with an LDAP referral. This referral may point to an Active Directory instance on another host.

Ensure that the host names returned in the referral can be resolved by the Domain Name System (DNS) on the host on which you installed Oracle Beehive.

For more information about LDAP referrals, refer to the Active Directory documentation.

Troubleshooting General LDAP Synchronization Issues

Call the command beectl validate_directory_entry to reconcile any LDAP directory entries that are not synchronized with Oracle Beehive.