⁠Chapter 17. LDAP Integration

17.1. Setting up LDAP
17.2. LDAP in Read only mode
17.2.1. Setting up LDAP Read-only Mode
17.2.2. Setting up Red Hat Directory Server or OpenDS
17.2.3. Setting up Microsoft Active Directory
17.2.4. Setting up OpenLDAP
17.3. LDAP as Default Store
17.3.1. Setting up LDAP as Default Identity Store
17.3.2. Setting up RHDS and OpenDS
17.3.3. Setting up Microsoft Active Directory
17.3.4. Setting up OpenLDAP
17.4. Integration Examples
17.4.1. Example 1 LDAP Configuration
17.4.2. Example 2 Read-only groupType Mappings
17.4.3. Example 3 Default groupType Mappings
Lightweight Directory Access Protocol (LDAP) is a set of open protocols used to access centrally stored information over a network. It is based on the X.500 standard for directory sharing, but is less complex and resource-intensive.
Using a client/server architecture, LDAP provides a reliable means to create a central information directory accessible from the network. When a client attempts to modify information within this directory, the server verifies the user has permission to make the change, and then adds or updates the entry as requested. To ensure the communication is secure, the Secure Sockets Layer (SSL) or Transport Layer Security (TLS) cryptographic protocols can be used to prevent an attacker from intercepting the transmission.
LDAP provides the protocols required to manage the data stored in a Directory Server. A Directory Server contains information about resources available (user accounts and printers for example) and their location on the network.
See https://access.redhat.com/knowledge/articles/119833 page for a list of supported directory servers.

Note

For ease of readability the following section uses the notational device ID_HOME to represent the file path JPP_HOME/gatein/gatein.ear/portal.war/WEB-INF/conf/organization/. This directory is the root of all portal identity-related configuration.
The portal includes several example LDAP configuration .xml files and .ldif (LDAP Data Interchange Format) data files. These examples are in the ID_HOME/picketlink-idm/examples directory and can be deployed in a testing environment to assist in configuring LDAP.
Report a bug

⁠17.1. Setting up LDAP

⁠

Procedure 17.1. LDAP Setup

  1. Install your LDAP server by following the installation instructions provided for the product you are using.
    See the Red Hat Directory Server Installation Guide, available from https://access.redhat.com/knowledge/docs/Red_Hat_Directory_Server/ for comprehensive installation guidance.
    If you are using a third-party directory server (OpenDS, OpenLDAP or Microsoft Active Directory), see the appropriate user documentation for that product.
    The following values provide an example of working configuration settings for the different Directory Servers:
    ⁠

    Table 17.1. Table Title

    Directory Server root user Distinguished Name(DN) Password Port Admin Port Base DN Database Population SSO/TLS
    RHDS and OpenDS MSAD OpenLDAP      
    cn=Directory manager CN=Users cn=Manager,dc=example,dc=com      
    password   secret      
    1389   1389      
    4444        
    dc=example,dc=com   dc=example,dc=com      
    "Only create the base entry"        
    no SSO, no TLS        
  2. Optionally, import an ldif file to populate the Directory Server.
  3. Start the Directory Server.
Report a bug

⁠17.2. LDAP in Read only mode

If LDAP is configured to operate in read-write mode, changes to user and group information made in the portal platform is written back to the directory server. If LDAP is operating in read-only mode, existing user and group information is consumed from the directory server, and all new user data entries created using the Portal User Interface are stored in the portal database. The only exception is that passwords updated through the user interface will also be propagated into the appropriate LDAP entry.
Report a bug

⁠17.2.1. Setting up LDAP Read-only Mode

⁠

Procedure 17.2. Set up LDAP Read-only Mode

  1. Open the ID_HOME/idm-configuration.xml file.
    The portal uses the PicketLink IDM framework as the underlying identity storage system, therefore the configuration uses dedicated PicketLink settings.
  2. Comment the default PicketLink config value: 
    ​<value>war:/conf/organization/picketlink-idm/picketlink-idm-config.xml</value>
  3. Uncomment the appropriate sample configuration values as described below, depending on which Directory Server you are implementing:
  4. To use a different LDAP server or directory data, edit the DS-specific.xml file you uncommented in the relevant sub-procedure (3a) above, and change the values to suit your requirements.
  5. Start the server.
  6. Navigate to the portal homepage (http://localhost:8080/portal) and log in as an administrator.
  7. Navigate to Group → Organization → Users and groups management.
  8. Create a new group called acme under the root node.
    • For RHDS, OpenDS and OpenLDAP:
      Create two sub-groups called roles and organization_units.
    • For MSAD:
      Create a subgroup called roles.
  9. By default, users mapped from LDAP will be members of LDAP groups, but will not be members of the /platform/users group. This means that mapped users will not be treated as full portal users. To fix this issue, one of the following approaches is required:
    1. Add LDAP users manually to /platform/users group
    2. Configure CustomMembershipLoginModule in the JAAS login modules stack. This is special login module, which will add every logged user into group /platform/users after successful login of this user. Two additional login modules (InitSharedStateLoginModule and SharedStateLoginModule) are required for this approach.
Users defined in LDAP must be visible in "Users and groups management" and groups from LDAP must be present as children of /acme/roles and /acme/organization_units.
More information about configuration can be found in the PicketLink IDM 1.x Community Documentation.

See Also:

Report a bug

⁠17.2.2. Setting up Red Hat Directory Server or OpenDS

⁠

Procedure 17.3. Red Hat Directory Server or Open Directory Server

  1. Uncomment the line under "Read Only "ACME" LDAP Example": 
    ​<!--Read Only "ACME" LDAP Example-->
​<value>war:/conf/organization/picketlink-idm/examples/picketlink-idm-LDAP-acme-config.xml</value>
  2. Uncomment the groupTypeMappings under "Uncomment for ACME LDAP example": 
    ​<!-- Uncomment for ACME LDAP example -->
​<entry>
​ <key><string>/acme/roles/*</string></key>
​ <value><string>acme_roles_type</string></value>
​</entry>
​<entry>
​ <key><string>/acme/organization_units/*</string></key>
​ <value><string>acme_ou_type</string></value>
​</entry>
  3. Return to Section 17.2.1, “Setting up LDAP Read-only Mode”.

See Also:

Report a bug

⁠17.2.3. Setting up Microsoft Active Directory

⁠

Procedure 17.4. Microsoft Active Directory

  1. Uncomment the line under "MSAD Read Only "ACME" LDAP Example": 
    ​ 
​	<!--MSAD Read Only "ACME" LDAP Example-->
​	<value>war:/conf/organization/picketlink-idm/examples/picketlink-idm-msad-readonly-config.xml</value>
  2. Uncomment the groupTypeMappings under "Uncomment for MSAD ReadOnly LDAP example": 
    ​
​<!-- Uncomment for MSAD ReadOnly LDAP example -->
​<entry>
​  <key><string>/acme/roles/*</string></key>
​  <value><string>msad_roles_type</string></value>
​</entry>
  3. Return to Section 17.2.1, “Setting up LDAP Read-only Mode”.

See Also:

Report a bug

⁠17.2.4. Setting up OpenLDAP

⁠

Procedure 17.5. configure OpenLDAP

  1. Install the LDAP server.
  2. Uncomment the line under "OpenLDAP ReadOnly "ACME" LDAP Example": 
    ​<!--OpenLDAP ReadOnly "ACME" LDAP Example-->
​<value>war:/conf/organization/picketlink-idm/examples/picketlink-idm-openLDAP-acme-config.xml</value>
  3. Uncomment the groupTypeMappings under "Uncomment for ACME LDAP example": 
    ​<!-- Uncomment for ACME LDAP example -->
​<entry>
​ <key><string>/acme/roles/*</string></key>
​ <value><string>acme_roles_type</string></value>
​</entry>
​<entry>
​ <key><string>/acme/organization_units/*</string></key>
​ <value><string>acme_ou_type</string></value>
​</entry>
  4. Return to Section 17.2.1, “Setting up LDAP Read-only Mode”

See Also:

Report a bug

⁠17.3. LDAP as Default Store

Follow the procedure below to set LDAP up as the default identity store for the portal. All default accounts and some of groups that come with the portal will be created in the LDAP store.
The LDAP server will be configured to store part of the portal group tree. This means that groups under specified part of the tree will be stored in directory server while all others will be stored in database.

See Also:

Report a bug

⁠17.3.1. Setting up LDAP as Default Identity Store

⁠

Procedure 17.6. Set up LDAP as Default Identity Store

  1. Install the LDAP server.
  2. Open the ID_HOME/idm-configuration.xml file.
    The portal uses the PicketLink IDM framework as the underlying identity storage system, therefore all the configurations use dedicated PicketLink settings.
  3. Comment out the default Picketlink config value: war:/conf/organization/picketlink-idm/picketlink-idm-config.xml
  4. Complete the steps in the procedure that relates to the chosen LDAP server:
  5. Uncomment the groupTypeMappings under "Uncomment for sample LDAP configuration": 
    ​<entry>
​ <key><string>/platform/*</string></key>
​ <value><string>platform_type</string></value>
​</entry>
​<entry>
​ <key><string>/organization/*</string></key>
​ <value><string>organization_type</string></value>
​</entry>
  6. Uncomment ignoreMappedMembershipTypeGroupList under Uncomment for sample LDAP config. 
    ​<value>
​  <string>/platform/*</string>
​</value>
​<value>
​  <string>/organization/*</string>
​</value>

    Important

    If this configuration is not uncommented, memberships will be used as both relationships and roles, which may cause duplicated records in the portal management interface.
    Normally, the same roles being used for LDAP mapping need to be uncommented. User memberships under the specified groups will be created in PicketLink IDM only as relationships, and not as roles.
  7. To use a different LDAP server or directory data, edit the DS-specific .xml file you uncommented in Step 4, and change the values to suit your requirements.

  8. Result

    All portal groups under /platform and /organization groups (for example /platform/users, /platform/administrators, /organization/management/executive-board) are mapped to the LDAP tree. The location of groups in the LDAP tree are configurable through the parameter ctxDNs in the PicketLink IDM configuration file.
Report a bug

⁠17.3.2. Setting up RHDS and OpenDS

⁠

Procedure 17.7. For RHDS and OpenDS

  1. Expose the entry under "Sample LDAP config": 
    ​<!--Sample LDAP config-->
​<value>war:/conf/organization/picketlink-idm/examples/picketlink-idm-LDAP-config.xml</value>
  2. Return to Section 17.3.1, “Setting up LDAP as Default Identity Store”
Report a bug

⁠17.3.3. Setting up Microsoft Active Directory

⁠

Procedure 17.8. For MSAD

  1. Expose the entry under "MSAD LDAP Example": 
    ​<!--MSAD LDAP Example-->
​<value>war:/conf/organization/picketlink-idm/examples/picketlink-idm-msad-config.xml</value>
  2. To enable SSL encryption, perform the following sub-steps:
    1. Open the ID_HOME/picketlink-idm/examples/picketlink-idm-msad-config.xml.
    2. Ensure the following entries are uncommented and that the path to the truststore file and password are correct: 
      <option>
  <name>customSystemProperties</name>
  <value>javax.net.ssl.trustStore=/path/to/truststore</value>
  <value>javax.net.ssl.trustStorePassword=password</value>
</option>
      You can import a custom certificate by replacing the certificate and truststore details in the following command: 
      keytool -import -file  certificate  -keystore  truststore
  3. Return to Section 17.3.1, “Setting up LDAP as Default Identity Store”.
Report a bug

⁠17.3.4. Setting up OpenLDAP

⁠

Procedure 17.9. For OpenLDAP

  1. Expose the entry under "OpenLDAP LDAP config": 
    ​<!--OpenLDAP LDAP config-->
​<value>war:/conf/organization/picketlink-idm/examples/picketlink-idm-openLDAP-config.xml</value>
  2. Return to Section 17.3.1, “Setting up LDAP as Default Identity Store”
Report a bug

⁠17.4. Integration Examples

⁠17.4.1. Example 1 LDAP Configuration

The following settings are stored in the PicketLink configuration file that is nominated in the idm-configuration.xml file of your deployment (under the config parameter of the PicketLinkIDMService component):
This file could be:
  • The default picketlink-idm-config.xml.
  • One of the three example configuration files discussed in Section 17.2.1, “Setting up LDAP Read-only Mode”:
    picketlink-idm-LDAP-acme-config.xml
    picketlink-idm-msad-readonly-config.xml
    picketlink-idm-openLDAP-acme-config.xml
  • A custom file created by modifying one of the above files.

Configuration Options

ctxDNs
This is the DN that will be used as context for IdentityObject searches. More than one value can be specified.
Some examples are:
  • ou=People,o=acme,dc=example,dc=com
  • ou=Roles,o=acme,dc=example,dc=com
  • ou=OrganizationUnits,o=acme,dc=example,dc=com
  • MSAD: CN=Users,DC=test,DC=domain (in two places).
providerURL
The LDAP server connection URL. Formatted as "ldap://<HOST>:<PORT>". The default setting is: ldap://localhost:1389.
MSAD: Should use SSL connection (ldaps://<HOST>:636) for password update or creation to work.
adminDN
The LDAP entry used to connect to the server.
Some possible values are:
  • RHDS or OpenDS: cn=Directory Manager
  • OpenLDAP: cn=Manager,dc=my-domain,dc=com
  • MSAD: TEST\Administrator
adminPassword
The password associated with the adminDN.
customSystemProperties
This option defines the values needed to use SSL encryption with LDAP.
Report a bug

⁠17.4.2. Example 2 Read-only groupType Mappings

The groupTypeMappings exposed in the idm-configuration.xml file correspond to identity-object-type values defined in the DS-specific configuration file (referenced in Sub-step 3a of the DS-specific procedure above).
For RHDS, OpenDS and OpenLDAP the picketlink-idm-LDAP-acme-config.xml and picketlink-idm-openLDAP-acme-config.xml files contain the following values: 
​
​	 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/readonly-opends.xml" parse="text"/>
Comment #1: The PicketLink IDM configuration file dictates that users and those two group types be stored in LDAP.
Comment #2: An additional option defines that nothing else (except password updates) should be written there.
All groups under /acme/roles will be stored in PicketLink IDM with the acme_roles_type group type name and groups under /acme/organization_units will be stored in PicketLink IDM with acme_ou_type group type name.
For MSAD, the identity-object-types values in picketlink-idm-msad-readonly-config.xml change to: 
​
​	 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/readonly-msad.xml" parse="text"/>
The difference is that this configuration maps only one group type and points to the same container in LDAP for both users and mapped groups.
Report a bug

⁠17.4.3. Example 3 Default groupType Mappings

The groupTypeMappings exposed in the idm-configuration.xml file correspond to identity-object-type values defined in the DS-specific configuration file (referenced in Sub-step 3a of the DS-specific procedure above).
All of the supported LDAP configurations use the following values when implemented as the default identity store: 
​
​	  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/default-ldap.xml" parse="text"/>
Comment #1: The groupTypeMappings define that all groups under /platform should be stored in PicketLink IDM with the platform_type group type name and groups under /organization should be stored in PicketLink IDM with organization_type group type name.
The PicketLink IDM configuration file repository maps users and those two group types as stored in LDAP.
Report a bug