Setup/Configuration

This page describes how to set up the LDAP Connector and configure it.

Installation of the LDAP Connector

Install the OpenCms as normally, including OCEE. Then edit the configuration files, located in the ${OPENCMS_HOME}/WEB-INF/config/ folder, as following:

opencms.xml

Add the ldap configuration class to the opencms.xml configuration file, adding it
under the <configuration> node, as follows

<configuration>
    ...
    <config class="org.opencms.ocee.ldap.CmsLdapConfiguration"/>
</configuration>

opencms.properties

Add the new driver sequence in the opencms.properties configuration file, adding it under the “Configuration of the driver manager” section, as follows:

#
# Configuration of the driver manager
###########################################################################
driver.vfs=\
db
driver.project=\
db
driver.user=\
ldap,\
db
driver.history=\
db

If you are also using the Alkacon OCEE Accelerator, the accelerator driver should remain the first in the sequence. And please note that the LDAP connector user driver cannot be used without the database driver or any other driver that stores the data and enables the assignment of an internal user id.

Add the driver class in the opencms.properties configuration file, adding it under the “Configuration of LDAP user driver” section (it could be that this section does not exists in your current configuration file), as follows:

#
# Configuration of LDAP user driver
###########################################################################
ldap.user.driver=org.opencms.ocee.ldap.CmsLdapUserDriver

ocee-ldap.xml

See the following sections.

LDAP Connector settings

The main node of the configuration file specifies the class of the OpenCms user driver for LDAP
support.

  • Element: /opencms/ldap
    Description: The main node of the configuration.
    • Attribute: class
      Description: Specifies the class of the OpenCms user driver for LDAP support.
      Default Value: org.opencms.ocee.ldap.CmsLdapUserDriver
  • Element: /opencms/ldap/ldap-group
    Description: The name of the virtual group of which all LDAP Users are automatic
    members of.
    • Attribute: enabled
      Description: Specifies if the LDAP virtual group is enabled or not.
      Default Value: true.
  • Element: /opencms/ldap/password
    Description: This node is the password handling configuration.
  • Element: /opencms/ldap/password/digest-encoding
    Description: Encoding used with passwords.
    Default Value: UTF-8
  • Element: /opencms/ldap/password/digest-type
    Description: Encryption method used for passwords.
    Default Value: SSHA
    Possible Values: SSHA, SHA, MD5, PLAIN.
  • Element: /opencms/ldap/password/editable
    Description: Flag to indicate if it is allowed to change the password of the users.
    Default Value: false
  • Element: /opencms/ldap/password/pwd-mapping
    Description: Indicates the name of the attribute used to store the user password. This is
    only needed if you set password/editable to true.
    Default Value: userPassword
  • Element: /opencms/ldap/enable-cmsusers
    Description: If set to false, only users specified within the LDAP server are accepted. Otherwise, users defined in the OpenCms user management are also accepted. This is useful to define the OpenCms system users like Guest, Admin, etc. within OpenCms only, and other users using LDAP.
    Default Value: true
  • Element: /opencms/ldap/lookup-defaultusers
    Description: Flag to control (if enable-cmsusers is set to true) if the default OpenCms users should be tried to be synchronized with the Ldap server, setting this to false could improve performance and prevent eventual problems with some Ldap servers having (default) users with the same name.
    Default Value: true
  • Element: /opencms/ldap/update-storage
    Description: Flag to control if during initialization old users created by pre-pre1.0
    versions of the driver are converted to the current version format.
    Default Value: false
  • Element: /opencms/ldap/group-consistency
    Description: Flag to control how the groups defined for a user in the LDAP repository are synchronized when updating a LDAP user.
    Default Value: all
    Possible Values:
    • none: No groups are synchronized at all.
    • membership: Just the membership of the user to already synchronized groups
      is assured.
    • all: The same as membership and all missing groups will be created.
  • Element: /opencms/ldap/sync-interval
    Description: This parameter should be a number representing the minimal time interval, in milliseconds, for lost entries removal. If the parameter is missing or does not parse to a number, the feature will be disabled.
    Default Value: disabled
  • Element: /opencms/ldap/cache-live
    Description: This parameter should be a number representing the time to live, in
    milliseconds, of cached LDAP data. If the parameter is missing or does not parse to a
    number, the feature will be disabled. Following data is cached: all users, all groups, all
    users of a given group, and all groups of a given user.
    Default Value: disabled
  • Element: /opencms/ldap/page-size
    Description: A number representing the size of a page that will be returned for search
    results. If the number is -1 then the paging is disabled. If the number is positive then
    paging is activated with the given size and a LdapContext instead of a DirContext will be
    used to bind to the server. For that feature Java Version 1.5 is required.
    Default Value: -1 (disabled)

LDAP Providers

Usually you would configure just one LDAP server (provider), but the Alkacon OCEE OpenCms LDAP connector also supports LDAP referrals. Referrals allow a directory tree to be partitioned and distributed between multiple LDAP servers. When you browse a directory, a LDAP server can refer you to another server (provider) by returning referrals. Referrals are internally handled by JNDI. You just need to add an additional provider node for each referral in order to be able to connect to the server returned in a referral.

In addition, if you configure multiple organizational units (OUs) in the LDAP configuration (see below), you can specify the provider to use for each one.

Each LDAP provider is specified in a provider node:

  •  Element: /opencms/ldap/providers
    Description: A list of all configured LDAP providers.
  • Element: /opencms/ldap/providers/provider
    Description: Specifies a LDAP provider.
    • Attribute: url
      Description: Specifies the URL to the LDAP server.
      Value: something like ldap://my.ldap.server:389
    • Attribute: default
      Description: Sets whether this provider is the default provider for lookups. If your
      LDAP directory includes referrals to other directories, you should have one
      provider with this attribute set to true for initial lookups, and for each referral a
      provider with this attribute set to false.
      Default Value: false

The provider parameters of the LDAP user driver are specified in a list of key/value parameter
nodes. 

  • Element: /opencms/ldap/providers/provider/param
    Description: Specifies a parameter value for a LDAP provider.
    Default Value: Dependent of the parameter name as explained below.
    • Attribute: name
      Description: Specifies the parameter to set with the given value.
      Default Value: One of the following parameter names.
      The following parameters are currently needed for a LDAP provider:
    • Parameter Name: com.sun.jndi.ldap.connect.pool
      Description: Flag to indicate if LDAP connection pooling is enabled.
      Default Value: true
    • Parameter Name: java.naming.factory.initial
      Description: Name of the JNDI context factory class used to obtain data from the LDAP
      server.
      Default Value: com.sun.jndi.ldap.LdapCtxFactory
    • Parameter Name: java.naming.referral
      Description: Sets how LDAP referrals are handled.
      Value: one of ignore or follow.
    • Parameter Name: java.naming.security.authentication
      Description: Specifies the authentication method, depending on the LDAP
      server/configuration.
      Default Value: simple for clear-text passwords
    • Parameter Name: java.naming.security.credentials
      Description: The password of the LDAP entity to access the LDAP server.
    • Parameter Name: java.naming.security.principal
      Description: The distinguished name of the LDAP entity to access the LDAP server.
      Value: something like:
      uid=ldapuser,cn=Users,ou=OpenCms,ou=Applications,o=alkacon.com.

LDAP Groups

How to access to the groups and how to map their attributes is specified in a group-
definition node:

  • Element: /opencms/ldap/group-definitions
    Description: A list of all configured LDAP group definitions.
  • Element: /opencms/ldap/group-definitions/group-definition
    Description: Specifies a LDAP group definition.
    • Attribute: membersformat
      Description: Specifies the type of the group members’ format.
      Default Value: fulldn
      Value: one of following:
      • userid, members are described only by their id,
      • fulldn, member are described by their distinguished name, or
      • mburl, members are described by an additional query
  • Element: /opencms/ldap/group-definitions/group-definition/editable
    Description: Specifies if the current LDAP group type is editable in OpenCms, this option
    will never change the LDAP data, it just allows to edit OpenCms specific data, like group
    flags, and so on.
    Default Value: false

Group search options

Please note: Element names in this section are implicitly prefixed with
/opencms/ldap/group-definitions/.

For each group type the access methods to search and find the groups have to be specified:

  • Element: group-definition/group-access
    Description: Defines the access methods for the given group type.
  • Element: group-definition/group-access/contexts/context
    Description: Defines distinguished names of LDAP entities used as starting points for
    group lookups. The subtrees below these entities are searched for the appropriate group
    entry.
    Value: An LDAP context, something like:
    ou=OpenCms,ou=Applications,o=alkacon.com.
  • Element: group-definition/group-access/group-filters
    Description: Filters specify how to qualify groups in the LDAP directory.
    Please note: Multiple search conditions are specified in the reverse LDAP syntax with a
    leading ampersand (&). Since the ampersand is a reserved character in XML, it must be
    written by using the ampersand entity &amp;.
  • Element: group-definition/group-access/group-filters/by-name
    Description: Filter to qualify a group object by its unique id.
    Value: (&amp;(objectclass=groupofuniquenames)(cn=?))
  • Element: group-definition/group-access/group-filters/by-member
    Description: Filter to retrieve all LDAP group objects for a given user as member. This
    filter is not required for dynamic groups (membersformat = mburl).
    Value: (&amp;(objectclass=groupofuniquenames)(uniquemember=?))
  • Element: group-definition/group-access/group-filters/all
    Description: Filter to retrieve all LDAP group objects.
    Value: (objectclass=groupofuniquenames)
  • Element: group-definition/group-access/group-filters/search
    Description: Optional. Filter to retrieve LDAP group objects while searching in the
    synchronization view.
    Value: (&amp;(objectclass=groupofuniquenames)(cn=*?*))

Group attribute mappings

Please note: Element names in this section are implicitly prefixed with
/opencms/ldap/group-definitions/.

The attribute mappings have to be specified for each group type:

  • Element: group-definition/group-mapping
    Description: Defines a list of attribute mappings for the given group type.
  • Element: group-definition/group-mapping/groupid
    Description: This attribute maps to the group unique id or name.
    Default Value: cn
  • Element: group-definition/group-mapping/groupname
    Description: This attribute maps to the group description.
    Default Value: description
  • Element: group-definition/group-mapping/member
    Description: This attribute maps to the member entries.
    Default Value: uniquemember

Group to role mappings

In this node you can specify one or more group to role mappings, this is useful if you want that every user of a LDAP Group (identified by its name, like TestGroup) has automatically a role (identified by its name, like WORKPLACE_USER).
Please note: Element names in this section are implicitly prefixed with
/opencms/ldap/group-role-mappings/.
The attribute mappings have to be specified for each user type:

  • Element: group-role-mapping
    Description: Defines a group to role mapping.
  • Element: group-role-mapping/group
    Description: Defines the group to map.
  • Element: group-role-mapping/role
    Description: Defines the role to be mapped.

LDAP Users

How to access to the users and how to map their attributes is specified in a user-definition
node:

  • Element: /opencms/ldap/user-definitions
    Description: A list of all configured LDAP user definitions.
  • Element: /opencms/ldap/user-definitions/user-definition
    Description: Specifies a LDAP user definition.
  • Element: /opencms/ldap/user-definitions/user-definition/editable
    Description: Specifies if the current LDAP user type is editable in OpenCms, this option
    will never change the LDAP data, it just allows to edit OpenCms specific data.
    Default Value: false

User search options

Please note: Element names in this section are implicitly prefixed with /opencms/ldap/user-
definitions/.
For each user type the access methods to search and find the users have to be specified:

  • Element: user-definition/user-access
    Description: Defines the access methods for the given user type.
  • Element: user-definition/user-access/contexts/context
    Description: Defines distinguished names of LDAP entities used as starting points for
    user lookups. The subtrees below these entities are searched for the appropriate user
    entry.
    Value: An LDAP context, something like:
    ou=OpenCms,ou=Applications,o=alkacon.com.
  •  Element: user-definition/user-access/user-filters
    Description: Filters specify how to qualify users in the LDAP directory.
    Please note: Multiple search conditions are specified in the reverse LDAP syntax with a
    leading ampersand (&). Since the ampersand is a reserved character in XML, it must be
    written by using the ampersand entity &amp;.
  • Element: user-definition/user-access/user-filters/by-name
    Description: Filter to qualify a user object by its unique id.
    Value: (&amp;(objectclass=organizationalPerson)(uid=?))
  • Element: user-definition/user-access/user-filters/all
    Description: Filter to retrieve all LDAP user objects.
    Value: (objectclass=organizationalPerson)
  • Element: user-definition/user-access/user-filters/search
    Description: Optional. Filter to retrieve LDAP user objects while searching in the
    synchronization view.
    Value: (&amp;(objectclass=organizationalPerson)(uid=*?*))

User attribute mappings

Please note: Element names in this section are implicitly prefixed with /opencms/ldap/user-
definitions/.
The attribute mappings have to be specified for each user type:

  • Element: user-definition/user-mapping
    Description: Defines a list of attribute mappings for the given user type.
    • Attribute: write-back-mode
      Description: Optional attribute used to determine how to handle writing values
      back to the LDAP directory. Possible values are as follows:
      • automatic : When an attribute is marked as write-back in the mapping
        configuration, the attribute will be automatically written to the LDAP
        directory when the corresponding user is saved.
      • manual : When an attribute is marked as write-back in the mapping
        configuration, this attribute will only be synced from the LDAP directory
        when using manual synchronization in the OpenCms administration. In
        addition, the value will only be written back to the LDAP directory when
        the CmsRequestContext of the CmsObject used to save the user has an
        attribute “LDAPWrite” with the value “true”. So to make proper use of this
        mode requires some custom programming.
  • Element: user-definition/user-mapping/userid
    Description: This attribute maps to the user’s unique id or name.
    Default Value: uid
  • Element: user-definition/user-mapping/firstname
    Description: This attribute maps to the user’s first name.
    Default Value: givenname
    • Attribute: default
      Description: This optional attribute defines a default value if the Ldap attribute is
      not defined or empty.
    • Attribute: write-back
      Description: If set to ‘true’, this attribute may be written back to the LDAP
      directory when the corresponding OpenCms user is written.
  • Element: user-definition/user-mapping/lastname
    Description: This attribute maps to the user’s last name.
    Default Value: sn
    • Attribute: default
      Description: This optional attribute defines a default value if the Ldap attribute is
      not defined or empty.
    • Attribute: write-back
      Description: If set to ‘true’, this attribute may be written back to the LDAP
      directory when the corresponding OpenCms user is written.
  • Element: user-definition/user-mapping/mail
    Description: This attribute maps to the user’s mail address.
    Default Value: mail
    • Attribute: default
      Description: This optional attribute defines a default value if the Ldap attribute is
      not defined or empty.
    • Attribute: write-back
      Description: If set to ‘true’, this attribute may be written back to the LDAP
      directory when the corresponding OpenCms user is written.
    • Attribute: validate
      Description: If set to ‘true’, the configured default value will also be used if the
      email address read from LDAP is not a valid email address according to the
      default OpenCms email address validation.
  • Element: user-definition/user-mapping/description
    Description: This attribute maps to the user’s description.
    Default Value: description
    • Attribute: default
      Description: This optional attribute defines a default value if the Ldap attribute is
      not defined or empty.
    • Attribute: write-back
      Description: If set to ‘true’, this attribute may be written back to the LDAP
      directory when the corresponding OpenCms user is written.
  • Element: user-definition/user-mapping/address
    Description: This attribute maps to the user’s address.
    Default Value: postalAddress
    • Attribute: default
      Description: This optional attribute defines a default value if the Ldap attribute is
      not defined or empty.
    • Attribute: write-back
      Description: If set to ‘true’, this attribute may be written back to the LDAP
      directory when the corresponding OpenCms user is written.
  • Element: /user-definition/user-mapping/additional-mappings
    Description: Defines additional attributes of LDAP user objects mapped to OpenCms
    user’s additional information field.
  • Element: /user-definition/user-mapping/additional-mappings/attribute
    Description: Attribute mappings define the name of attributes in the LDAP directory, for
    given user’s additional information attributes.
    Value: The LDAP (case insensitive) attribute name.
    • Attribute: name
      Description: Specifies the name of the attribute to map.
      Value: the Java (case sensitive) attribute name to use to store the value.
    • Attribute: default
      Description: This optional attribute defines a default value if the Ldap attribute is
      not defined or empty.
    • Attribute: write-back
      Description: When this attribute is set to “true”, the additional info item will be
      written back to the LDAP directory when the user is saved.

Organizational units

Despite there being no way to synchronize complete LDAP OUs into OpenCms, you can define that specific LDAP groups and users are mapped to an OpenCms organizational unit. For this, define your users and groups in the same way as described in the previous sections, but defined inside an ou-definition tag. The only new configuration nodes are following:

  • Element: /ou-definitions/ou-definition/ou-name
    Description: Describes the path of the target OpenCms organizational unit. In general, the
    groups and users described outside of the ou-definitions node are mapped to the root OU.
    Value: The path of the target OpenCms organizational unit, with leading and trailing slashes.
  • Element: /ou-definitions/ou-definition/preferred-provider
    Description: This optional element is used to assign a configured LDAP provider to this OU. For
    access to users and groups from this OU, the provider with the URL configured here will be
    used. If the provider has not been configured in the <providers> section of the configuration, this
    will cause an error at startup time.

Configuration example
The OpenCms LDAP Connector could be configured as follows (please realize that this
example mixes 2 different types of groups, this is possible but usually not required):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE opencms SYSTEM "http://www.alkacon.com/dtd/6.0/ocee-ldap.dtd">
<opencms>
  <ldap class="org.opencms.ocee.ldap.CmsLdapUserDriver">
    <ldap-group enabled="true">Ldap Group</ldap-group>
    <password>
      <digest-encoding>UTF-8</digest-encoding>
      <digest-type>SSHA</digest-type>
      <editable>false</editable>
      <pwd-mapping>userPassword</pwd-mapping>
    </password>
    <enabled-cmsusers>true</enabled-cmsusers>
    <lookup-defaultusers>true</lookup-defaultusers>
    <update-storage>false</update-storage>
    <group-consistency>all</group-consistency>
    <sync-interval>180000</sync-interval>
    <!--3mins-->
    <cache-live>300000</cache-live>
    <!--5mins-->
    <page-size>100</page-size>
    <providers>
      <provider url="ldap://my.ldap.server:389" default="true">
        <param name="com.sun.jndi.ldap.connect.pool">true</param>
        <param name="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory</param>
        <param name="java.naming.referral">follow</param>
        <param name="java.naming.security.authentication">simple</param>
        <param name="java.naming.security.credentials">password</param>
        <param name="java.naming.security.principal">uid=ldapuser,cn=Users,ou=OpenCms,ou=Applications,o=alkacon.com</param>
      </provider>
    </providers>
    <ou-definitions>
      <ou-definition>
        <ou-name>/test/</ou-name>
        <group-definitions>
          <group-definition membersformat="mburl">
            <group-access>
              <group-filters>
                <all>(objectclass=groupofurls)</all>
                <by-name>(&amp;(objectclass=groupofurls)(cn=?))</by-name>
              </group-filters>
              <contexts>
                <context>ou=OpenCms,ou=Applications,o=alkacon.com</context>
              </contexts>
            </group-access>
            <group-mappings>
              <groupid>cn</groupid>
              <groupname>description</groupname>
              <member>memberurl</member>
            </group-mappings>
            <editable>false</editable>
          </group-definition>
        </group-definitions>
        <user-definitions>
          <user-definition>
            <user-access>
              <user-filters>
                <all>(objectclass=organizationalPerson)</all>
                <by-name>(&amp;(objectclass=organizationalPerson)(uid=?))</by-name>
              </user-filters>
              <contexts>
                <context>ou=OpenCms,ou=Applications,o=alkacon.com</context>
              </contexts>
            </user-access>
            <user-mappings>
              <userid>uid</userid>
              <firstname>givenname</firstname>
              <lastname>sn</lastname>
              <mail>mail</mail>
              <description>description</description>
              <address>postalAddress</address>
              <additional-mappings>
                <attribute name="Zip">postalCode</attribute>
              </additional-mappings>
            </user-mappings>
            <editable>false</editable>
          </user-definition>
        </user-definitions>
      </ou-definition>
    </ou-definitions>
    <group-definitions>
      <group-definition membersformat="fulldn">
        <group-access>
          <group-filters>
            <all>(objectclass=groupofuniquenames)</all>
            <by-name>(&amp;(objectclass=groupofuniquenames)(cn=?))</by-name>
            <by-member>(&amp;(objectclass=groupofuniquenames)(uniquemember=?))</by-member>
          </group-filters>
          <contexts>
            <context>ou=Groups,o=alkacon.com</context>
          </contexts>
        </group-access>
        <group-mappings>
          <groupid>cn</groupid>
          <groupname>description</groupname>
          <member>uniquemember</member>
        </group-mappings>
        <editable>false</editable>
      </group-definition>
    </group-definitions>
    <group-role-mappings>
      <group-role-mapping>
        <group>TestGroup</group>
        <role>WORKPLACE_USER</role>
      </group-role-mapping>
    </group-role-mappings>
    <user-definitions>
      <user-definition>
        <user-access>
          <user-filters>
            <all>(objectclass=organizationalPerson)</all>
            <by-name>(&amp;(objectclass=organizationalPerson)(uid=?))</by-name>
          </user-filters>
          <contexts>
            <context>ou=People,o=alkacon.com</context>
          </contexts>
        </user-access>
        <user-mappings>
          <userid>uid</userid>
          <firstname>givenname</firstname>
          <lastname>sn</lastname>
          <mail default="defaultuser@mycompany.com">mail</mail>
          <description>description</description>
          <address>postalAddress</address>
          <additional-mappings>
            <attribute name="City" default="--missing city--">l</attribute>
            <attribute name="Street">street</attribute>
            <attribute name="Phone">telephonenumber</attribute>
            <attribute name="Zip">postalcode</attribute>
          </additional-mappings>
        </user-mappings>
        <editable>false</editable>
      </user-definition>
    </user-definitions>
  </ldap>
</opencms>

Setting the validation handler

The default implementation does not allow white-spaces in the user id, and requires a valid email address. You can use the provided org.opencms.ocee.ldap.CmsLdapValidationHandler class to allow white-spaces in the user id (Ldap attribute CN) and email is not validated at all.
To use this class (required in most cases for MS ActiveDirectory, for instance), just edit your opencms-system.xml configuration file, and edit/add the opencms/system/validationhandler node:

<validationhandler class="org.opencms.ocee.ldap.CmsLdapValidationHandler" />

You can also use your own account data validation/restriction methods by implementing the
interface.

Translating user/group names

In case the default user/group names in the opencms-system.xml configuration file are modified, a list of principal translations has to be specified. This is required in order to translate the default user/group names (e.g. ”Admin”, ”Administrators”) to the user and group names configured in the opencms-system.xml configuration file (e.g. ”cmsadmin”, ”cmsadministrators”) while OpenCms export data is imported.

The user and group translations are configured in the opencms-importexport.xml configuration file, look for the opencms/importexport/import/principaltranslations node, which should look like:

<principaltranslations>
    <principaltranslation type="USER" from="Admin" to="cmsadmin" />
    <principaltranslation type="GROUP" from="Users" to="cmsusers" />
</principaltranslations>
  • Element: /opencms/importexport/import/principaltranslations
    Description: Specifies a set of translations to be executed while importing data.
  • Element: /opencms/importexport/import/principaltranslations/principaltranslation
    Description: Specifies a single translation of a group or an user to be executed while importing data.
    • Attribute: type
      Description: Sets whether this is a translation rule for a user or group name.
      Value: one of USER or GROUP.
    • Attribute: from
      Description: Specifies the “source” user/group name for the translation.
      Value: a group or user name, like Admin.
    • Attribute: to
      Description: Specifies the “destination” user/group name for the translation.
      Value: the user/group name that is configured in the default user/group names in the opencms-system.xml configuration file, like cmsadmin.

Secure LDAP connection

The OCEE LDAP Connector uses the normal Java LDAP client functionality, so configuring a secure LDAP
connection should be possible by using one of these methods:

Using the SSL socket property

By default, Oracle's LDAP service provider uses plain sockets when communicating with the LDAP
server. To request that SSL sockets be use, set the try the following configuration in your WEB-
INF/config/ocee-ldap.xml configuration file:
java.naming.security.protocol property to "ssl".


In the following example, the LDAP server is offering SSL at port 636. To run this program, you must enable SSL on port 636 on your LDAP server. This procedure is typically carried out by the directory's administrator. Try the following configuration in your WEB-INF/config/ocee-ldap.xml configuration file:

<provider url="ldap://localhost:636/o=JNDITutorial" default="false">
    <param name="com.sun.jndi.ldap.connect.pool">true</param>
    <param name="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory</param>
    <param name="java.naming.referral">follow</param>
    <param name="java.naming.security.protocol">ssl</param>
    <param name="java.naming.security.authentication">simple</param>
    <param name="java.naming.security.credentials">mysecret</param>
    <param name="java.naming.security.principal">cn=S. User, ou=NewHires, o=JNDITutorial</param>
</provider>

Note: If you use SSL to connect to a server on a port that is not using SSL, then your program will hang. Similarly, if you use a plain socket to connect to a server's SSL socket, then your application will hang. This is a characteristic of the SSL protocol.

Using the LDAPS URL

Instead of requesting the use of SSL via the use of the Context.SECURITY_PROTOCOL property, you can also request the use of SSL via the use of LDAPS URLs. An LDAPS URL is similar to an LDAP URL except that the URL scheme is "ldaps" instead of "ldap". It specifies the use of SSL when communicating with the LDAP server.

In the following example, the LDAP server is offering SSL at port 636. To run this program, you must enable SSL on port 636 on your LDAP server.

Try the following configuration in your WEB-INF/config/ocee-ldap.xml configuration file:

<provider url="ldaps://localhost:636/o=JNDITutorial" default="false">
    <param name="com.sun.jndi.ldap.connect.pool">true</param>
    <param name="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory</param>
    <param name="java.naming.referral">follow</param>
    <param name="java.naming.security.authentication">simple</param>
    <param name="java.naming.security.credentials">mysecret</param>
    <param name="java.naming.security.principal">cn=S. User, ou=NewHires,o=JNDITutorial</param>
</provider>

LDAPS URLs are accepted anywhere LDAP URLs are accepted.

Client authentication: Using SSL with the external SASL mechanism

Server Requirements: This example requires the LDAP server to allow certificate-based client authentication. In addition, the LDAP server must trust the client certificates that it receives, and must be able to map the owner distinguished names in the client certificates to principals that it knows about. Follow the instructions from your directory vendor on how to perform these tasks.

Client Requirements: This example requires the client to have an X.509 SSL client certificate. Moreover, the certificate must be stored as the first key entry in a keystore file. If this entry is password-protected, it must have the same password as the keystore.

SSL provides authentication and other security services at a lower layer than the LDAP. If authentication has already been done at the SSL, the LDAP layer can use that authentication information from SSL by using the External SASL mechanism.

The following example is like the previous SSL example, except that instead of using simple authentication, it uses the External SASL authentication. By using External, you do not need to supply any principal or password information, because they get picked up from the SSL. Try the following configuration in your WEB-INF/config/ocee-ldap.xml configuration file:

<provider url="ldap://localhost:636/o=JNDITutorial" default="false">
    <param name="com.sun.jndi.ldap.connect.pool">true</param>
    <param name="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory</param>
    <param name="java.naming.referral">follow</param>
    <param name="java.naming.security.protocol">ssl</param>
    <param name="java.naming.security.authentication">EXTERNAL</param>
</provider>

To use this configuration so that the client's certificate is used for authentication, you must provide (as system properties) the location and password of the keystore containing the client's certificate. Here is an example of how to run the program (your servlet container).

java -Djavax.net.ssl.keyStore=MyKeystoreFile \
-Djavax.net.ssl.keyStorePassword=mysecret \
External

If you do not supply a keystore, the program will run using anonymous authentication because no client credential exists at the SSL.

For more details see
https://docs.oracle.com/javase/jndi/tutorial/ldap/security/ssl.html

MS Active Directory configuration

The following sections contain some hints on how to configure the LDAP connector for use with Active Directory.

Related to the group definition section

The object class is group and not groupofuniquenames, you could also use some parent object class, but let us just take this object class for now. So, everywhere replace groupofuniquenames by group.

The membership data is stored in attributes called 'member' and not 'uniquemember' so replace again all of them and since the member attribute of the group entries contains the full DN of the users, like here:

member: CN=Test User,OU=Users,DC=opencms,DC=org

You should use the 'fulldn' for the membersformat attribute.

For the groupid mapping, you can use one of name, cn or sAMAccountName, normally all have the same data. Here YOU have to decide which one to use, and be sure that it will be UNIQUE for all groups you want to use in OpenCms. So you can leave the default 'cn' or replace all by the attribute you want.

For the groupname mapping, you will most likely have no special attribute for a group description, so you may use one of attributes that can also be used as id.

To mix 2 or more different group types in a server is not common, so normally you have just to delete the second group-definition for groupofurls.

With respect to the context, you have to define the branches in the Ldap tree structure you want to use with OpenCms. Be careful to include too many users you do not really need in OpenCms, since you may slowdown OpenCms if you have thousands of groups and users. It is a good practice to keep the context as small as possible.

Related to the user definition section

Here the object class is 'user' so replace all 'organizationalPerson' by 'user'.

For the userid mapping there are several attributes that may come in question, like: cn, displayName, mailNickname, name, sAMAccountName or userPrincipalName.

There is just one condition: this attribute should be unique for all users you want to use in OpenCms.

After that, the real question is: Which one do you want to use as login name? We recommend using one that does not contain spaces. But if you want to allow spaces you can do so, for this you have just to configure the proper validation handler as explained in the documentation. If you do not have any attribute for the address mapping is not really relevant so just use a valid attribute like cn.
additional-mappings are all optional, so you can remove them all.
All other default attribute mappings are ok with AD.

Sample configuration

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE opencms SYSTEM "http://www.alkacon.com/dtd/6.0/ocee-ldap.dtd">
<opencms>
   <ldap class="org.opencms.ocee.ldap.CmsLdapUserDriver">
      <ldap-group enabled="true">Ldap Group</ldap-group>
      <password>
         <digest-encoding>UTF-8</digest-encoding>
         <digest-type>SSHA</digest-type>
         <editable>false</editable>
         <pwd-mapping>userPassword</pwd-mapping>
      </password>
      <enabled-cmsusers>true</enabled-cmsusers>
      <lookup-defaultusers>false</lookup-defaultusers>
      <update-storage>false</update-storage>
      <group-consistency>all</group-consistency>
      <sync-interval>180000</sync-interval>
      <!--3mins-->
      <cache-live>300000</cache-live>
      <!--5mins-->
      <page-size>100</page-size>
      <providers>
         <provider url="ldap://qdcws0007.us.qdx.com:389" default="true">
            <param name="com.sun.jndi.ldap.connect.pool">true</param>
            <param name="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory</param>
            <param name="java.naming.referral">follow</param>
            <param name="java.naming.security.authentication">simple</param>
            <param name="java.naming.security.credentials">password1234</param>
            <param name="java.naming.security.principal">cn=TestUser,ou=Users,dc=opencms,dc=org</param>
         </provider>
      </providers>
      <group-definitions>
         <group-definition membersformat="fulldn">
            <group-access>
               <group-filters>
                  <all>(objectclass=group)</all>
                  <by-name>(&amp;(objectclass=group)(cn=?))</by-name>
                  <by-member>(&amp;(objectclass=group)(member=?))</by-member>
               </group-filters>
               <contexts>
                  <context>OU=Users,DC=opencms,DC=org</context>
               </contexts>
            </group-access>
            <group-mappings>
               <groupid>cn</groupid>
               <groupname>name</groupname>
               <member>unique</member>
            </group-mappings>
            <editable>false</editable>
         </group-definition>
      </group-definitions>
      <group-role-mappings>
         <group-role-mapping>
            <group>TestGroup</group>
            <role>WORKPLACE_USER</role>
         </group-role-mapping>
      </group-role-mappings>
      <user-definitions>
         <user-definition>
            <user-access>
               <user-filters>
                  <all>(objectclass=user)</all>
                  <by-name>(&amp;(objectclass=user)(cn=?))</by-name>
               </user-filters>
               <contexts>
                  <context>OU=Users,DC=opencms,DC=org</context>
               </contexts>
            </user-access>
            <user-mappings>
               <userid>cn</userid>
               <firstname>givenname</firstname>
               <lastname>sn</lastname>
               <mail>mail</mail>
               <description>description</description>
               <address>mail</address>
               <additional-mappings />
            </user-mappings>
            <editable>false</editable>
         </user-definition>
      </user-definitions>
   </ldap>
</opencms>