Skip to end of metadata
Go to start of metadata

For ease of readability the following section uses the notational device ID_HOME to represent the file path GATEIN_HOME/gatein/gatein.ear/portal.war/WEB-INF/conf/organization/, as this directory is the root of all GateIn Portal's identity-related configuration.

LDAP (Lightweight Directory Access Protocol) 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.

The following table is a list of Directory Servers that are supported and certified in GateIn Portal.

Supported and Certified Directory Servers
Directory Server Version
OpenDS 1.2 and 2.0
OpenLDAP 2.4
Red Hat Directory Server 7.1
Sun Java System Directory Server 6.1
Microsoft Active Directory Windows Server 2008
Examples
GateIn 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.
LDAP Set Up
  1. Install your LDAP server by following the installation instructions provided for the product you are using.
    If you are installing the Red Hat Directory Server, you should refer to the Installation Guide at http://docs.redhat.com/docs/en-US/Red_Hat_Directory_Server/index.html.
    If you are using a third party directory server (OpenDS, OpenLDAP or Microsoft Active Directory), refer the appropriate documentation for that product.
    The following values provide an example of working configuration settings for the different Directory Servers:
    Directory Server root user Distinguished Name (DN) Password Port Admin Port Base DN Database Population SSO/TLS
    RHDS and OpenDS cn=Directory Manager password 1389 4444 dc=example,dc=com "Only create the base entry" no SSO, no TLS
    MSAD CN=Users            
    OpenLDAP cn=Manager,dc=example,dc=com secret 1389   dc=example,dc=com    

    These, and other appropriate settings, should be adjusted to suit your circumstances.

  2. Optional: Import an ldif file and populate the Directory Server.
  3. Start the Directory Server.

LDAP in Read-only Mode

This section will show you how to add LDAP in read-only mode. This means that user data entries (both pre-existing, and newly added through the GateIn Portal User Interface) will be consumed though the Directory Server and LDAP services, but written to the underlying database. The only exception is that passwords updated via the UI will also be propagated into the appropriate LDAP entry.

Set up LDAP read-only Mode
  1. Open the ID_HOME/idm-configuration.xml file.
      GateIn Portal uses the PicketLink IDM framework as the underlying identity storage system, hence all the configurations use dedicated Picketlink settings.
  2. Comment out 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:
    • Red Hat Directory Server or OpenDS
      1. Uncomment the line under Read Only "ACME" LDAP Example:
      2. Uncomment the groupTypeMappings under Uncomment for ACME LDAP example:

        Refer to Read Only groupTypeMappings for more information about how these groupTypeMappings operate.

    • Microsoft Active Directory
      1. Uncomment the line under MSAD Read Only "ACME" LDAP Example:
      2. Uncomment the groupTypeMappings under Uncomment for MSAD ReadOnly LDAP example:

        Refer to Read Only groupTypeMappings for more information about how these groupTypeMappings operate.

    • OpenLDAP
      1. If you have not done so already, install your LDAP server. Refer to LDAP Set Up for some assistance.
      2. Uncomment the line under OpenLDAP ReadOnly "ACME" LDAP Example:
      3. Uncomment the groupTypeMappings under Uncomment for ACME LDAP example:

        Refer to Read Only groupTypeMappings for more information about how these groupTypeMappings operate.

  4. To use a different LDAP server or directory data, edit the DS-specific .xml file you uncommented in Substep 3a above and change the values to suit your requirements.
    Refer to the list in LDAP configuration for some examples or refer to the product-specific documentation for more information.
  5. Start the server.
  6. Navigate to the portal homepage (http://localhost:8080/portal) and log in as an administrator.
  7. Navigate to GroupOrganizationUsers and groups management.
    1. 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.

Users defined in LDAP should be visible in "Users and groups management" and groups from LDAP should be present as children of /acme/roles and /acme/organization_units.
More information about configuration can be found in PicketLink IDM integration and in the PicketLink project Reference Guide.

In read-only LDAP setup, your LDAP users are usually not member of group /platform/users by default. This means that they are not authorized to see non-public content of portal (like top address bar). To address this issue, we have special login module CustomMembershipLoginModule, which automatically adds each user to group /platform/users after his successful login. See Existing login modules for details about setup of this login module.

Another option is to use CoreOrganizationInitializer plugin which will enforce running OrganizationService listeners, as one of the listeners is automatically adding users into group /platform/users . See https://github.com/gatein/gatein-toolbox/tree/master/CoreOrganizationInitializer and especially it's README.txt file for more info.

LDAP as Default Store

Follow the procedure below to set LDAP up as the default identity store for GateIn Portal. All default accounts and some of groups that comes with GateIn Portal will be created in the LDAP store.

The LDAP server will be configured to store part of the GateIn 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.

Set up LDAP as Default Indentity Store
  1. If you have not done so already, install your LDAP server. Refer to LDAP Set Up for some assistance.
  2. Open the ID_HOME/idm-configuration.xml file.
    GateIn Portal uses the PicketLink IDM framework as the underlying identity storage system, hence 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. Uncomment the appropriate LDAP configuration entry depending on your LDAP server:
    • For RHDS and OpenDS
      1. Expose the entry under Sample LDAP config:
    • For MSAD
      1. Expose the entry under MSAD LDAP Example:
        • To use SSL encryption with MSAD:
        • Open the ID_HOME/picketlink-idm/examples/picketlink-idm-msad-config.xml
        • Ensure the following entries are uncommented and that the path to the truststore file and password are correct:

          You can import a custom certificate by replacing the certificate and truststore details in the following command:

    • For OpenLDAP
      1. Expose the entry under OpenLDAP LDAP config:
  5. Uncomment the groupTypeMappings under Uncomment for sample LDAP configuration:

    Refer to Default groupTypeMappings for more information about how these groupTypeMappings operate.

  6. Uncomment ignoreMappedMembershipTypeGroupList under Uncomment for sample LDAP config

    Usually you need to uncomment same roles, which you are using for LDAP mapping. The point is that user memberships under those groups will be created in Picketlink IDM only as relationships and not as roles. Without uncommenting, memberships will be used as both relationships and roles, which could cause that you may see some duplicated records in UI.

  7. To use a different LDAP server or directory data, edit the DS-specific .xml file you uncommented in Step 4 above and change the values to suit your requirements.
    Refer to the list in LDAP configuration for some examples or refer to the product-specific documentation for more information.

Now after server startup, all GateIn Portal groups under /platform and under /organization groups (for example /platform/users , /platform/administrators , /organization/management/executive-board etc.) will be mapped to LDAP tree. The location of groups in LDAP tree is configurable via parameter ctxDNs in Picketlink IDM configuration file as described below.

Examples

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 LDAP Set Up :
    • 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://localhost:<PORT>". The default setting is:LDAP://localhost:1389.
    MSAD: Should use SSL connection (LDAPs://xxx: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.
Read Only groupTypeMappings

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:

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:

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.

Default groupTypeMappings

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:

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.

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Jan 29, 2013

    Added the additional Step (6) from LDAP as Default Store to the enterprise Reference Guide section of the same name. Incorporated all changes up to Rev 27 in the Enterprise Guide.