Skip Headers
Oracle® Beehive Integration Guide
Release 2 (2.0.1.8)

Part Number E16650-06
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
PDF · Mobi · ePub

4 Integrating an External User Directory with Oracle Beehive

This module provides an overview of integrating an external User Directory Service (UDS) with Oracle Beehive. 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.

This module includes the following sections:

Overview of Integrating an External User Directory with Oracle Beehive

Oracle Beehive provides flexible user account management and provisioning by supporting both native and system-external user directory options. With Oracle Beehive, administrators can manage user account data either natively in Oracle Beehive or externally through integration with a supported LDAP-based user directory server. Oracle Beehive provides this flexibility for user account management through the User Directory Service.

Currently, Oracle Beehive supports the following user directory servers:

  • Oracle Internet Directory

  • IBM Tivoli Directory Server

  • Microsoft Active Directory Server

  • OpenLDAP Directory Server

  • Oracle Directory Server Enterprise edition ( formerly Sun Directory Server)

Organizations can also leverage external user directories to manage user authentication attributes, such as usernames and passwords. This option requires Oracle Beehive administrators to configure the Authentication Service after installation using the beectl command-line utility. For more information regarding this option, see Oracle Beehive Administrator's Guide.

Oracle Beehive user data may be mastered by the Oracle Beehive User Directory Service (UDS) or an external LDAP-based directory. An LDAP-mastered user is authenticated against the LDAP server. Some identity attributes of this user are stored on the LDAP server, and the remaining attributes can be stored in Oracle Beehive. For example, if a user's givenname and familyname attributes are stored on the LDAP server, then they are only for display in Oracle Beehive. The phonenumber and middlename attributes of the same user may be stored on Oracle Beehive and can be modified in Beehive.

If UDS is synchronized with an external LDAP server, then 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, then 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.

If you choose to integrate Oracle Beehive with a supported external user directory, then you should consider the limitations of this option as well as the steps to prepare your deployment for this option. This topic is covered in the following section:

Limitations of Deploying Oracle Beehive with an External User Directory

Limitations of Deploying Oracle Beehive with an External User Directory

Despite the multiple options and benefits provided by Oracle Beehive's support of external user directories, there are certain limitations as follows:

  • Oracle Beehive does not support integration with multiple, unique user directories. Oracle Beehive can only integrate with a single user directory instance on a specific server.

  • User accounts can only be mastered in one place, either natively in Oracle Beehive or in an external user directory. Despite this requirement, administrators may choose to master most user account attributes in one directory even if the user accounts themselves are mastered in Oracle Beehive or in an external user directory. However, certain user account attributes that are specific to Oracle Beehive, such as voicemail passwords and instant messaging user names, can only be mastered in Oracle Beehive.

  • To manage user account attributes that are mastered in external LDAP directories, administrators can only use the tools provided with or for those directories. Administrators cannot use the tools provided with Oracle Beehive, such as beectl, to manage user account attributes that are mastered in external LDAP directories.

  • The synchronization process between the external user directory servers and Oracle Beehive is unidirectional. The changes in an external user directory are imported into Oracle Beehive only. Oracle Beehive does not promote the user account attributes that it manages to external user directories.

Prerequisites for Integrating an External User Directory with Oracle Beehive

This section describes the requirements for integrating an external user directory with Oracle Beehive. This section includes the following topics:

Creating XML Files for Integrating an LDAP server with UDS

After installing Oracle Beehive but before deploying the system with an external user directory, you must import user account data from your external user directory server instance to UDS. This process involves creating the following XML files:

  • LDAP mapping profile: An XML file that contains external user directory server settings and specifies how to convert those entries to Oracle Beehive users and groups. This involves specifying attribute mappings between those defined in an external directory server and those used by Oracle Beehive.

  • User file: An XML file that represents, in a format specified by Oracle Beehive, all the user accounts that need to be synchronized. To create this, administrators use the LDAP mapping profile and the beectl download_ldap_user_data command.

OpenLDAP Directory Requirements

If you choose to integrate Oracle Beehive with OpenLDAP, ensure that you have configured OpenLDAP Directory as follows to synchronize it with Oracle Beehive:

  • Do not use the option lastmod off in your slapd.conf configuration file. Either omit the option or use lastmod on instead.

  • Ensure that all OpenLDAP users have the following attributes set to a value other than null:

    • entryUUID

    • modifiersName

    • ModifyTimestamp

    Verify that these attributes are set with the ldapsearch command:

    ldapsearch -h <hostname> -p <port> -b "<user base>" <attribute names>
    

    For example, if the host and port of your OpenLDAP Directory is myldap.example.com:8888, and the base DN of your users is cn=Users,dc=example,dc=bee, then call the following command:

    ldapsearch -h myldap.example.com -p 8888 -b "cn=Users,dc-example,dc=bee" entryUUID modifiersName ModifyTimestamp
    
  • Ensure that you have configured the system time setting correctly on the OpenLDAP server. If the system time (as retrieved from the date command) is not configured correctly on the OpenLDAP server, then synchronization may not work.

    It is required that the time settings on OpenLDAP server must be the same as that of the Oracle Beehive database or must be ahead of the Oracle Beehive database time. Note that the time settings on OpenLDAP server must not be behind the Beehive database time settings.

For more information, including the steps to create these files, refer to "Step 1: Creating an LDAP Mapping Profile".

Procedure for Integrating an External User Directory with Oracle Beehive

Integrating 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. However, if you later integrate Microsoft Exchange or IBM Lotus Domino Coexistence Solution, then you would require write access to the 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.

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 (DN) (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 4-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 user name 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.

Note:

After configuring the LDAP Server configuration, set AuthStoreType on the _AuthenticationService configuration to ldap. Once this property is set, run activate_configuration followed by modify_local_configuration_files. If you do not perform these steps, then the LDAP entries would not be present in the system-jazn-data.xml file.

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, see "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.

If your LDAP server is Microsoft Active Directory, then the user specified in <ldap_user_name> must have the following privileges:

  • Read access on the directory objects being synchronized.

  • Viewing rights to the deleted objects container in Microsoft Active Directory. For more information, refer to "How to let non-administrators view the Active Directory deleted objects container in Windows Server 2003 and in Windows 2000 Server" at http://support.microsoft.com/kb/892806.

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>

Note:

In case of multiple user_type_map rules, ensure that you put the specific rule first, and then the generic rule. In this way, if the first rule does not get satisfied, then the subsequent rules are evaluated.

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 in <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, then 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. In addition, the values specified in <source_field_name> and <source_field_value> must exactly match an attribute and corresponding value (respectively) in your LDAP directory.

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_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 entry:

  • A user that is under the DN dc=us,dc=oracle,dc=com will be scoped within the enterprise My_Enterprise.

  • A user that is under the DN dc=external, dc=us, dc=example, dc=com will be 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, then 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, then 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 as follows:

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.

In addition, this kind of mapping maps the user's DEFAULT_ADDRESS_BY_SCHEME element for scheme MAILTO: to be that of the value of the proxyAddresses value marked with the uppercase SMTP:. For example, if the proxyAddresses value in Active Directory was: smtp:rholmes@example.com;SMTP:robert.holmes@example.com;smtp:rob.holmes@example.com, then the default_address_by_scheme for scheme MAILTO: (that is, the default e-mail address used in clients such as Webmail) will be robert.holmes@example.com as it was prefixed by the text SMTP:.

Mapping primary_principal Attribute

Ensure that you map primary_principal to the attribute your LDAP server is configured for authentication. Modify and map primary_principal to sAMAccountName for Active Directory or uid (by default) for Oracle Internet Directory, otherwise authentication will fail.

Consider the following example for Active Directory:

<Field> 
<source_attribute>sAMAccountName</source_attribute> 
<target_attribute>PRIMARY</target_attribute> 
<target_attribute_type>PRINCIPAL</target_attribute_type> 
</Field>
Mapping external_inbox Attribute

You may synchronize the value of the UDS attribute external_inbox with an arbitrary attribute in your LDAP directory. If the value of external_inbox is true, then that user's e-mail messages will be routed somewhere other than his or her Personal Workspace Inbox.

Suppose you have created the attribute orclBeehiveUserStatus in your LDAP directory. You have configured orclBeehiveUserStatus to have a value of either external-inbox or local-inbox. You want external_inbox to be true if orclBeehiveUserStatus has a value of external-inbox and external_inbox to be false if orclBeehiveUserStatus has a value of local-inbox or smtp. You would use the following XML excerpt to represent this mapping:

<Field>
  <source_attribute>orclBeehiveUserStatus</source_attribute>
  <target_attribute>is_external_inbox</target_attribute>
  <target_attribute_type>ATTRIBUTE</target_attribute_type>
  <source_target_value_mapping>
    <value_mapping>
      <source_field_value>external-inbox</source_field_value>
      <target_field_value>true</target_field_value>
    </value_mapping>

    <value_mapping>
      <source_field_value>local-inbox</source_field_value>
      <target_field_value>false</target_field_value>
    </value_mapping>

  </source_target_value_mapping>
</Field>

Note:

The <source_target_value_mapping> mechanism can also be used for mapping any LDAP attribute to any other Beehive attribute, except Beehive attributes such as LOCALE and TIMEZONE.

If is_external_inbox is false for a particular user (which is the default), any e-mail message addressed to that user that originates from Oracle Beehive's inbound virtual mail server (VMS) will be delivered to that user's inbox. Conversely, if is_external_inbox is true, then any e-mail messages addressed to that user will be redirected to Oracle Beehive's outbound VMS. See "Managing Oracle Beehive E-mail" in Oracle Beehive Administrator's Guide for more information about Oracle Beehive VMSes. See "Managing and Provisioning Oracle Beehive Users" for more information about is_external_inbox and other user properties.

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. Most customers will only require a single profile.

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/logs.

  2. Activate the configuration:

    beectl activate_configuration
    

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 and commit changes:

    beectl activate_configuration
    beectl modify_local_configuration_files
    
Changing Directory Profile to Default Profile or Non-Default Profile

Note:

An ENABLEd profile will synchronize, whereas a DISABLEd profile will not synchronize. Only a DEFAULT profile is used for authentication and not a NON-DEFAULT profile.

.Follow these steps to change a directory profile to a default or non-default profile:

Changing Default Profile to Non-Default Profile

  1. Download the existing LDAP mapping profile with the beectl list_directory_profiles command. The following example downloads the existing LDAP profile and saves it in the file existing_profile.xml:

    beectl list_directory_profiles --file existing_profile.xml
    

    These steps will use existing_profile.xml as the file name of your existing LDAP mapping profile.

  2. Edit the file existing_profile.xml and change the value of <profile_flag> from DEFAULT to NON_DEFAULT.

  3. Upload the LDAP mapping profile with the beectl modify_directory_profile command:

    beectl modify_directory_profile --file existing_profile.xml
    
  4. Modify the AuthStoreType property of the Authentication Service from ldap to db with the beectl modify_property command:

    beectl modify_property --component _AuthenticationService --name AuthStoreType --value db
    
  5. Activate the configuration and commit changes:

    beectl activate_configuration
    beectl modify_local_configuration_files
    

Changing Non-Default Profile to Default

  1. Download the existing LDAP mapping profile with the beectl list_directory_profiles command. The following example downloads the existing LDAP profile and saves it in the file existing_profile.xml:

    beectl list_directory_profiles --file existing_profile.xml
    

    These steps will use existing_profile.xml as the file name of your existing LDAP mapping profile.

  2. Edit the file existing_profile.xml and change the value of <profile_flag> from NON_DEFAULT to DEFAULT.

  3. Upload the LDAP mapping profile with the beectl modify_directory_profile command:

    beectl modify_directory_profile --file existing_profile.xml
    
  4. Modify the AuthStoreType property of the Authentication Service from db to ldap with the beectl modify_property command:

    beectl modify_property --component _AuthenticationService --name AuthStoreType --value ldap
    
  5. Activate the configuration:

    beectl activate_configuration
    
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: 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, then 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
    

    Note:

    • If users are created using the beectl add_user command with the file option by running the command multiple times with a different batch of users in each run, then the manager or assistant attribute of the users is set in Oracle Beehive only if one of the following conditions is met:

      • The manager or assistant is already present in Oracle Beehive.

      • The manager or assistant is being created in the same XML as the user.

      If the manager or assistant is created in a different XML at a later time, then it is not set by the add_user command. To resolve this issue, you must reconcile users created in multiple batches by running the validate_directory_command with the reference option.

    • The -ldapbootstrap parameter indicates to Oracle Beehive that the users to be added are mastered/synched from the LDAP server and will authenticate to the LDAP server.

  4. Ensure that the users were added successfully with the beectl list_users command:

    beectl list_users
    

Step 3: 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 log in yet, even though they are provisioned. Your users will able to log in once you have completed the step described in "Configuring Authentication Service to Use LDAP Server".

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 fifteen 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, then 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" and "Changing Directory Profile to Default Profile or Non-Default Profile" 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 fifteen 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, then the 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 4-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 and Custom Object Classes for Users and Groups

UDS uses the values specified in the properties UserObjectClass and GroupObjectClass to determine whether an entity in your LDAP directory is a user or a group, respectively. The default schema of your LDAP directory uses a particular object class for users and another for groups. Oracle Beehive automatically sets UserObjectClass and GroupObjectClass to the name of the default object class used by the users and groups of your LDAP directory. Refer to "Default UserObjectClass and GroupObjectClass Values" for these default values.

However, if you are using a custom schema in your LDAP directory and have defined your users and groups with object classes other than the default ones for your directory, follow the steps described in "Specifying Non-Default User and Group Object Classes"

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 4-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


Specifying Non-Default User and Group Object Classes

Modify your LDAP mapping profile as described in "Modifying Directory Profile". In your LDAP mapping profile, include the elements <user_objectclass> and <group_objectclass> in the <ldapserver> section of your LDAP mapping profile.

For example, if the schema of your LDAP directory defines its users with the object class BeehivePerson and its groups with BeehiveGroup, you would modify your LDAP mapping profile as follows:

<ldap_server>
  <!-- ... -->
  <user_objectclass>BeehivePerson</user_objectclass>
  <group_objectclass>BeehiveGroup</group_objectclass>
</ldap_server>

Administering Your External User Directory and Oracle Beehive Integration

This section describes how to administer your external user directory and Oracle Beehive integration. This section includes the following topics:

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, see "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_properties --component _AuthenticationService
    ---------------------------------------------------------------------------
    | Property Name                    | Property Value                        |
    ---------------------------------------------------------------------------
    | Alias                            | _AuthenticationService                |
    ---------------------------------------------------------------------------
    | AuthStoreType                    | db                                  |
    ---------------------------------------------------------------------------
    ...........................................................................
    ...........................................................................
    ............................................................................
    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, see 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:

  • Store the user password in clear text or reversible encrypted form

  • Store an A1 hash value of the password. An A1 hash value is an intermediate value used for the calculation of the authentication methods HTTP digest and SASL digest-MD5. The A1 hash value is created from a user's password, principal name (userid) and realm.

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

For OpenLDAP Directory, see "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. See "Configuring SSL" in the Oracle Beehive Installation Guide for Microsoft Windows to configure your Oracle Beehive instance for SSL. Refer to the documentation of your LDAP directory to configure it in SSL mode.

Note:

To log in to an LDAP directory in SSL mode, the jps-config.xml file must have ldaps instead of ldap in the URL value in both the following locations:
  • $BKPR_HOME/j2ee/home/application-deployments/javasso
    <property name="oracle.security.jaas.ldap.provider.url" value="ldaps://user1.us.oracle.com:6060"/>
    
  • $BKPR_HOME/j2ee/home/application-deployments/beekeeper <property name="oracle.security.jaas.ldap.provider.url" value="ldaps://user1.us.oracle.com:6060"/>
    

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 4-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 4-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. See "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 4-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, then 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, see 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, then 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 | 1f90e-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.

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

  • Ensure 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, see Chapter 9, "Oracle Identity Management Attribute Reference in Oracle Identity Management User Reference.

    For more information about orclUserApplnProvStatus, see 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, see the section "bulkload" in Chapter 9, "Using Bulk Tools" in Oracle Internet Directory Administrator's Guide.

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

Modifying Directory Profile

To modify a directory profile, follow these general steps:

  1. Make changes to the existing LDAP mapping profile, then modify the directory profile with the command beectl modify_directory_profile --file <file name of modified LDAP mapping profile>.

    Alternatively, you may modify the directory profile through Oracle Beekeeper or with the beectl modify_property command.

  2. Activate the modified profile with the command beectl activate_configuration.

  3. Run the command beectl validate_directory_entry to validate all your users and groups already synchronized with UDS:

    beectl validate_directory_entry --all --profile exampleProfile --delete
    

After modifying the directory profile, you do not have to restart the LDAP server.

Notes:

You may not delete a profile with which you have already loaded users and groups from your LDAP server to UDS.

Do not change the name of the profile. Oracle Beehive treats a renamed profile as a new profile.

For Validate_directory_entry to reconcile with --all, --all_users, and --all_groups, the attributes in the rule map of directory profile should be indexed on the LDAP.

Active Directory Considerations

This section covers the following topics:

Active Directory Administrator's Account

Ensure that the user that you specified as the Active Directory administrator is not used by other applications. This may affect Oracle Beehive authentication.

In particular, if you notice a significant number of invalid credential errors in your Active Directory log files, ensure that the Active Directory administrator's account is not locked out or disabled.

Note:

You must have the Active Directory profile validation check permissions to ensure that the user account is successfully deleted in the UDS when deletions occur in Active Directory.

LDAP Referrals

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 DNS on the host on which you installed Oracle Beehive.

For more information about LDAP referrals, see 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.

Note:

To retrieve the LDAP DN of a user, use the ldapsearch command or other similar utility from your LDAP directory. You cannot use beectl validate_directory_entry to retrieve the DN of a synchronized user. In particular, if you change the DN of a synchronized user, you must use the new DN to validate that user with beectl validate_directory_entry. Oracle Beehive does not synchronize a user's DN.

Oracle Beehive uniquely identifies users (and all other entities) by their Beehive Object Distinguished Name (BODN), which has no relation to a user's LDAP DN. When you run the command beectl list_users, a user's BODN is specified by User Identifier.