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 &.
Element: group-definition/group-access/group-filters/by-name
Description: Filter to qualify a group object by its unique id.
Value: (&(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: (&(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: (&(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 &.
Element: user-definition/user-access/user-filters/by-name
Description: Filter to qualify a user object by its unique id.
Value: (&(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: (&(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

Client authentication: Using SSL with the external SASL mechanism 3

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.

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.

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>