Integrating with an existing LDAP store

Typically, while working on enterprise-class architectures, you have to integrate applications with a specific user store provider. LDAP is the widely adopted standard dedicated to manage users and groups in large environments.

We will discuss how we can configure an external LDAP server with GateIn to authenticate and get information about users and groups directly from an LDAP server.

Getting ready

Locate the configuration.xml file in the following path in your application server deployments folder:

portal/WEB-INF/conf/configuration.xml

How to do it...

Let's now see which steps are required to configure your LDAP with GateIn:

  1. Uncomment the section related to the LDAP configuration in the configuration.xml file and change the file location to the correct path conf/organization/exo that should be included by default in the portal application, as shown in the following snippet:
    ... 

   <!--for organization service used active directory which is user lookup server -->
   <!--
      <import>war:/conf/organization/exoactivedirectory-configuration.xml</import>
   -->
   <!--for organization service used ldap server which is user lookup server -->
   
     <import>war:/conf/organization/exo/ldap-configuration.xml</import>
  
   <!-- <import>war:/conf/security-configuration.xml</import> -->

   <import>war:/conf/organization/organization-configuration.xml</import>
   <import>war:/conf/jcr/component-plugins-configuration.xml</import>
   <import>war:/conf/mail/portal-mail-configuration.xml</import>

   <!-- Portal related services -->
   <import>war:/conf/portal/portal-configuration.xml</import>
   <import>war:/conf/portal/application-registry-configuration.xml</import>
   <import>war:/conf/portal/controller-configuration.xml</import>
   <import>war:/conf/portal/web-configuration.xml</import>
   <import>war:/conf/portal/gadget-configuration.xml</import>
</configuration>
  2. Locate the LDAP configuration file in the following path:

    portal/WEB-INF/conf/organization/exo/ldap-configuration.xml.

  3. First, we will identify the LDAPConnectionConfig component to set the endpoint properties for your LDAP server:
    <configuration
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_2.xsd http://www.exoplaform.org/xml/ns/kernel_1_2.xsd"
   xmlns="http://www.exoplaform.org/xml/ns/kernel_1_2.xsd">
   <component>
     <key>org.exoplatform.services.ldap.LDAPService</key>
      <type>org.exoplatform.services.ldap.impl.LDAPServiceImpl</type>
    <init-params>
      <object-param>
        <name>ldap.config</name>
        <description>Default ldap config</description>
        <object type="org.exoplatform.services.ldap.impl.LDAPConnectionConfig">         
        
              <!-- for multiple ldap servers, use comma seperated list of host:port (Ex. ldap://127.0.0.1:389,10.0.0.1:389) -->
            <field  name="providerURL"><string>ldap://127.0.0.1:389,10.0.0.1:389</string></field>
            
               <field  name="rootdn"><string>CN=Manager,DC=exoplatform,DC=org</string></field>
               
              <field  name="password"><string>secret</string></field>            
       
           <field  name="version"><string>3</string></field>
           
           <field  name="minConnection"><int>5</int></field>
           
           <field  name="maxConnection"><int>10</int></field>       
           
           <field  name="referralMode"><string>follow</string></field>  
           
<!--
               <field  name="referralMode"><string>ignore</string></field>  
-->  
           
           <field  name="serverName"><string>default</string></field>
  4. Set the following properties for configuring your LDAP server with GateIn:
    • providerURL: The LDAP endpoint (ldap://<IP ADDRESS>:<PORT>), can be multi-value; you can add more servers using commas.
    • rootdn: This is the principal account identified by the LDAP Distinguished Name (DN). This account will be used by GateIn for read-only access to the server to retrieve all the users' and groups' information.
    • password: This is the password value for the principal account.
    • minConnection: The minimum number of connections that GateIn must create against the LDAP server when it is running.
    • maxConnection: The maximum number of connections that GateIn can create against the LDAP server when it is running.
    • serverName: This defines the type of the LDAP server. GateIn supports the following LDAP servers: default, active-directory, open.ldap, netscape.directory, redhat.directory.
  5. Identify the OrganizationService, which is the second component in the configuration file that is dedicated to set all the LDAP attributes against the UserProfile attributes provided in GateIn, and check that the configuration is compliant with your LDAP server:
    <component>
    <key>org.exoplatform.services.organization.OrganizationService</key>
    <type>org.exoplatform.services.organization.ldap.OrganizationServiceImpl</type>
    <component-plugins>
       <component-plugin>
         <name>init.service.listener</name>
         <set-method>addListenerPlugin</set-method>
         <type>org.exoplatform.services.organization.ldap.OrganizationLdapInitializer</type>
         <description>this listener populate organization ldap service create default dn</description>      
       </component-plugin>  
    </component-plugins> 
    <init-params>           
      <value-param>
        <name>ldap.userDN.key</name>
        <description>The key used to compose user DN</description>
        <value>cn</value>
      </value-param>
      
      <object-param>
        <name>ldap.attribute.mapping</name>
        <description>ldap attribute mapping</description>
        <object type="org.exoplatform.services.organization.ldap.LDAPAttributeMapping">                
          <field  name="userLDAPClasses"><string>top,person,organizationalPerson,inetOrgPerson</string></field>
          <field  name="profileLDAPClasses"><string>top,organizationalPerson</string></field>
          <field  name="groupLDAPClasses"><string>top,organizationalUnit</string></field>
          <field  name="membershipTypeLDAPClasses"><string>top,organizationalRole</string></field>
          <field  name="membershipLDAPClasses"><string>top,groupOfNames</string></field>
          
          <field  name="baseURL"><string>dc=exoplatform,dc=org</string></field>
          <field  name="groupsURL"><string>ou=groups,ou=portal,dc=exoplatform,dc=org</string></field>
          <field  name="membershipTypeURL"><string>ou=memberships,ou=portal,dc=exoplatform,dc=org</string></field>
          <field  name="userURL"><string>ou=users,ou=portal,dc=exoplatform,dc=org</string></field>
          <field  name="profileURL"><string>ou=profiles,ou=portal,dc=exoplatform,dc=org</string></field>
          
          <field  name="userUsernameAttr"><string>uid</string></field>
          <field  name="userPassword"><string>userPassword</string></field>
          <field  name="userFirstNameAttr"><string>givenName</string></field>
          <field  name="userLastNameAttr"><string>sn</string></field>
          <field  name="userDisplayNameAttr"><string>displayName</string></field>
          <field  name="userMailAttr"><string>mail</string></field>
          <field  name="userObjectClassFilter"><string>objectClass=person</string></field>
          
          <field  name="membershipTypeMemberValue"><string>member</string></field>
          <field  name="membershipTypeRoleNameAttr"><string>cn</string></field>
          <field  name="membershipTypeNameAttr"><string>cn</string></field>
          <field  name="membershipTypeObjectClassFilter"><string>objectClass=organiz ationalRole</string></field>
          <field  name="membershiptypeObjectClass"><string>organizationalRole</string></field>
          
          <field  name="groupObjectClass"><string>organizationalUnit</string></field>
          <field  name="groupObjectClassFilter"><string>objectClass=organizational Unit</string></field>
          
          <field  name="membershipObjectClass"><string>groupOfNames</string></field>
          <field  name="membershipObjectClassFilter"><string>objectClass=group OfNames</string></field>

          <field  name="ldapCreatedTimeStampAttr"><string>createdTimeStamp</string></field>
          <field  name="ldapModifiedTimeStampAttr"><string>modifiedTimeStamp</string></field>
          <field  name="ldapDescriptionAttr"><string>description</string></field>
        </object>
      </object-param>
    </init-params>     
  </component>
  6. The parameters that you can configure are as follows:
    • userLDAPClasses: Sets all the accepted LDAP classes for the users
    • profileLDAPClasses: Sets all the accepted LDAP classes for profiles
    • groupLDAPClasses: Sets all the accepted LDAP classes for groups
    • membershipTypeLDAPClasses: Sets all the accepted LDAP classes for the membership types
    • membershipLDAPClasses: Sets all the accepted LDAP classes for the memberships
    • baseURL: The base root LDAP query
    • groupsURL: The base LDAP query to get all the groups
    • membershipTypeURL: The base LDAP query for getting memberships
    • userURL: The base LDAP query for getting all the users
    • profileURL: The base LDAP query to retrieve all the profiles information
    • userUsernameAttr: The LDAP attribute for retrieving the username
    • userPassword: The LDAP attribute used for authenticating users
    • userFirstNameAttr: The LDAP attribute used for storing the first name of users
    • userLastNameAttr: The LDAP attribute dedicated to the last name of users
    • userDisplayNameAttr: The LDAP attribute used for the display name of users
    • userMailAttr: The LDAP attribute for the e-mail address of the users
    • userObjectClassFilter: The LDAP query for identifying the user object
    • membershipTypeMemberValue: The attribute used by LDAP for assigning user to groups
    • membershipTypeRoleNameAttr: This is the value used by LDAP to identify the association of a user with a group
    • membershipTypeNameAttr: The name attribute used by LDAP for the association of an user
    • membershipTypeObjectClassFilter: The LDAP filter used to identify the type of membership
    • membershipTypeObjectClass: The LDAP object class used for membership types
    • groupObjectClass: The LDAP object class used to identify a group
    • groupObjectClassFilter: The LDAP filter to identify groups
    • membershipObjectClass: The LDAP object used for groups
    • membershipObjectClassFilter: The LDAP filter for groups
    • ldapCreatedTimeStampAttr: The LDAP attribute dedicated for the created timestamp
    • ldapModifiedTimeStampAttr: The LDAP attribute for the modified timestamp
    • ldapDescriptionAttr: The description attribute
  7. Save the file.
  8. Restart the portal.
  9. Log in as an administrator.
  10. Click on Group | Organization | Users and groups management.
  11. Finally, click on Group Management to navigate all the groups previously defined in the LDAP server

How it works...

The LDAP Service provided in GateIn is a sub service dedicated to identify and synchronize users' information. It is based on PicketLink IDM, which is the JBoss Identity Project. This module is used in the portal to manage users.

The advantage is that this allows the management of users, from an LDAP source without re-writing any specific lines of code.

There's more...

The latest improvements on GateIn now allow for the use of PicketLink as the identity manager of the portal.

Note

PicketLink is the identity manager implementation of the JBoss Community. It is an open source project and it can be easily embedded in any standard J2EE application. It allows for the managing of user identities, storing the information in a database. It also supports many ways to negotiate credentials and Single Sign On (SSO) mechanisms.

GateIn provides different examples of how to use PicketLink inside the portal configuration in the following folder:

<PORTAL_WAR_ROOT>/WEB-INF/conf/organization/picketlink-idm/examples

You will find the following example files for PicketLink:

  • picketlink-idm-ldap-config.xml: A generic LDAP example
  • picketlink-idm-openldap-config.xml: An example of using OpenLDAP
  • picketlink-idm-msad-config.xml: An example of using Active Directory
  • picketlink-idm-msad-readonly-config.xml: An example of using read-only constraints against an Active Directory store

To set a specific configuration, you have to modify the file idm-configuration.xml that you find in the path <PORTAL_WAR_ROOT>/WEB-INF/conf/organization and choose one of the previous example files, updating the file in this way:

  <component>
    <key>org.exoplatform.services.organization.idm.PicketLinkIDMService</key>
    <type>org.exoplatform.services.organization.idm.PicketLinkIDMServiceImpl</type>
    <init-params>
      <value-param>
        <name>config</name>
        <value>war:/conf/organization/picketlink-idm/picketlink-idm-ldap-config.xml</value>

Inside these configuration files you will set parameters that are very similar to the previous ones that you saw in this recipe. You will need to set the endpoint and all the necessary information for authenticating and selecting the correct tree in the store.

PicketLink manages different identity stores for the portal domain dedicated to users. Taking a look at the OpenLDAP example, in order to configure a user domain using PicketLink, you need to configure:

  • realms: Contains the definitions of the JAAS realms dedicated to authenticate users and for creating user sessions.
  • repositories: A repository manages the user profile information with the related store. For each portal must be defined only one repository.
  • stores: Defines all the identity objects required for the portal. GateIn supports these types of source for the store: JDBC, LDAP, and Hibernate.

By default, in the configuration file you will find two realms: idm_realm is defined for the standard portal and idm_realm_sample-portal is defined for the sample portal:

<realms>
    <realm>
      <id>idm_realm_sample-portal</id>
      <repository-id-ref>DefaultPortalRepository</repository-id-ref>
      <identity-type-mappings>
        <user-mapping>USER</user-mapping>
      </identity-type-mappings>
      <options>
        <option>
          <name>cache.providerRegistryName</name>
          <value>apiCacheProvider</value>
        </option>
      </options>
    </realm>
    <realm>
      <id>idm_realm</id>
      <repository-id-ref>PortalRepository</repository-id-ref>
      <identity-type-mappings>
        <user-mapping>USER</user-mapping>
      </identity-type-mappings>
      <options>
        <option>
          <name>template</name>
          <value>true</value>
        </option>
        <option>
          <name>cache.providerRegistryName</name>
          <value>apiCacheProvider</value>
        </option>
      </options>
    </realm>
  </realms>

As you can see, for each realm a repository is defined. The repository contains all the contents of the portal and it will be used to cooperate with the involved identity stores for managing different roles and access permissions.

In this configuration file, the PortalRepository is the repository related to the default portal application provided by GateIn that we now want to configure. For this repository you will find a specific store named PortalLDAPStore dedicated to provide information from an LDAP server:

<repository>
      <id>PortalRepository</id>
      <class>org.picketlink.idm.impl.repository.FallbackIdentityStoreRepository</class>
      <external-config/>
      <default-identity-store-id>HibernateStore</default-identity-store-id>
      <default-attribute-store-id>HibernateStore</default-attribute-store-id>
      <identity-store-mappings>
        <identity-store-mapping>
          <identity-store-id>PortalLDAPStore</identity-store-id>
          <identity-object-types>
            <identity-object-type>USER</identity-object-type>
            <identity-object-type>platform_type</identity-object-type>
            <identity-object-type>organization_type</identity-object-type>
          </identity-object-types>
          <options/>
        </identity-store-mapping>
      </identity-store-mappings>
      <options>
        <option>
          <name>allowNotDefinedAttributes</name>
          <value>true</value>
        </option>
      </options>
    </repository>

Notice that for this repository we have three identity objects defined: USER, platform_type (membership), and organization_type (membership). PortalLDAPStore is the identity store preconfigured for LDAP servers; look at its definition:

<identity-store>
        <id>PortalLDAPStore</id>
        <class>org.picketlink.idm.impl.store.ldap.LDAPIdentityStoreImpl</class>
        <external-config/>
        <supported-relationship-types>
          <relationship-type>JBOSS_IDENTITY_MEMBERSHIP</relationship-type>
        </supported-relationship-types>

In order to configure the endpoint address for this LDAP store you need to change the following options defined for PortalLDAPStore with references relating to your LDAP server:

<options>
          <option>
            <name>providerURL</name>
            <value>ldap://localhost:1389</value>
          </option>
          <option>
            <name>adminDN</name>
            <value>cn=Manager,dc=my-domain,dc=com</value>
          </option>
          <option>
            <name>adminPassword</name>
            <value>secret</value>
          </option>

This means that you need to configure at least the parameters shown above:

  • providerURL: This is the endpoint address of your LDAP server
  • adminDN: This is the Distinguished Name (DN) to identify the principal user that will be used to read all the store
  • adminPassword: This is the password value of the principal user

Each identity store can manage different identity objects; here you need to set some attributes for the USER object type to synchronize user profile information. By default, the USER object consists of these parameters: firstName, lastName, and email. In the configuration file you find the USER definition:

 <identity-object-type>
            <name>USER</name>
            <relationships/>
            <credentials>
              <credential-type>PASSWORD</credential-type>
            </credentials>
            <attributes>
              <attribute>
                <name>firstName</name>
                <mapping>cn</mapping>
                <type>text</type>
                <isRequired>false</isRequired>
                <isMultivalued>false</isMultivalued>
                <isReadOnly>false</isReadOnly>
              </attribute>
              <attribute>
                <name>lastName</name>
                <mapping>sn</mapping>
                <type>text</type>
                <isRequired>false</isRequired>
                <isMultivalued>false</isMultivalued>
                <isReadOnly>false</isReadOnly>
              </attribute>
              <attribute>
                <name>email</name>
                <mapping>mail</mapping>
                <type>text</type>
                <isRequired>false</isRequired>
                <isMultivalued>false</isMultivalued>
                <isReadOnly>false</isReadOnly>
                <isUnique>true</isUnique>
              </attribute>
            </attributes>

Moreover, for each attribute of the object you need to configure the specific mapping between the portal attribute (the name element) and the LDAP attribute value (the mapping element).

For example, in the preceding snippet we found the firstName attribute defined by default, meaning that that the firstName field will be synchronized with the value from the cn attribute in the LDAP store. Change these attributes for your own configuration making sure that you check your LDAP attributes.

For each attribute, you need to define some XML elements to add constraints for a specific field:

  • type: The base type for the field
  • isRequired: A Boolean value to set this attribute as required or not
  • isMultivalued: A Boolean value to set this attribute as multi-value or not
  • isReadOnly: A Boolean value to set this attribute to read-only mode or not
  • isUnique: A Boolean value to set this attribute as unique for the identity object or not (optional)

The next step shows you how to provide the options for allowing GateIn to correctly identify users in the LDAP tree:

            <options>
              <option>
                <name>idAttributeName</name>
                <value>uid</value>
              </option>
              <option>
                <name>passwordAttributeName</name>
                <value>userPassword</value>
              </option>
              <option>
                <name>ctxDNs</name>
                <value>ou=People,o=portal,o=gatein,dc=my-domain,dc=com</value>
              </option>
              <option>
                <name>allowCreateEntry</name>
                <value>true</value>
              </option>
              <option>
                <name>createEntryAttributeValues</name>
                <value>objectClass=top</value>
                <value>objectClass=inetOrgPerson</value>
                <value>sn= </value>
                <value>cn= </value>
              </option>
            </options>
          </identity-object-type>

By changing these settings, the portal will correctly find users in the LDAP store. Each user is identified by a uid and we need to correctly set attributes that contain values for authenticating users from the portal application against the store:

  • idAttributeName: This is the name of the attribute in the store that contains the value for the user identifier
  • passwordAttributeName: This is the name of the attribute in the store that contains the password value
  • ctxDNs: This is the DN related to the LDAP tree to select all the users involved in the portal
  • allowCreateEntry: This allows the management and configuration of the user creation, and specifies the objectClass defined in the LDAP store

The second identity object is platform_type and it contains two relationships and has no attributes, and so the definition should be the following:

<identity-object-type>
            <name>platform_type</name>
            <relationships>
              <relationship>
                <relationship-type-ref>JBOSS_IDENTITY_MEMBERSHIP</relationship-type-ref>
                <identity-object-type-ref>USER</identity-object-type-ref>
              </relationship>
              <relationship>
                <relationship-type-ref>JBOSS_IDENTITY_MEMBERSHIP</relationship-type-ref>
                <identity-object-type-ref>platform_type</identity-object-type-ref>
              </relationship>
            </relationships>
            <credentials/>
            <attributes/>

This object contains information about users membership and, by default, the member attribute is used for selecting groups for users:

<options>
              <option>
                <name>idAttributeName</name>
                <value>cn</value>
              </option>
              <option>
                <name>ctxDNs</name>
                <value>ou=Platform,o=portal,o=gatein,dc=my-domain,dc=com</value>
              </option>
              <!--<option>-->
              <!--<name>entrySearchFilter</name>-->
              <!--<value></value>-->
              <!--</option>-->
              <option>
                <name>allowCreateEntry</name>
                <value>true</value>
              </option>
              <option>
                <name>parentMembershipAttributeName</name>
                <value>member</value>
              </option>
              <option>
                <name>parentMembershipAttributePlaceholder</name>
                <value>ou=placeholder,o=portal,o=gatein,dc=my-domain,dc=com</value>
              </option>
              <option>
                <name>isParentMembershipAttributeDN</name>
                <value>true</value>
              </option>
              <option>
                <name>allowEmptyMemberships</name>
                <value>true</value>
              </option>
              <option>
                <name>createEntryAttributeValues</name>
                <value>objectClass=top</value>
                <value>objectClass=groupOfNames</value>
                <value>member=ou=placeholder,o=portal,o=gatein,dc=my-domain,dc=com</value>
              </option>

Here, we have some new attributes that are used to read or write memberships between the portal and the LDAP store; some of them are:

  • idAttributeName: This is the name of the attribute used as identifier for groups.
  • ctxDNs: This is the DN for finding this group in the LDAP store tree.
  • parentMembershipAttributeName: This is the name of the attribute that manages members for groups.
  • parentMembershipAttributePlaceholder: This is the name of the attribute used as placeholder in the case of read/write operation against the LDAP store. It is required only if you want to use GateIn to manage users in LDAP.
  • createEntryAttributeValues: This contains the necessary options that are dedicated to create new entries in the store. It is required only if you want to use GateIn to manage users in LDAP.

Note

For more details about all the parameters and configurations of PicketLink, please see http://www.jboss.org/picketlink.

In this way, GateIn will automatically synchronize user profiles to get information from your LDAP store. You can therefore now start your portal instance and check your user profile in GateIn.

See also

  • The Setting an automatic membership after user creation recipe
  • The Integrating with Web SSO recipe
  • The Integrating with SPNEGO for Desktop SSO recipe
..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
3.16.50.252