8.1.1. Quick start

Note

As of Platform 4.3, custom extensions do not require a jar so the configuration is simpler. The old extensions with jar and war still work, you do not need to change them.

You should set up an "empty" directory for this practice. The directory should contain only the top DN, like:

dn: dc=example,dc=com
objectClass: top
objectClass: domain
dc: example

In this quick start, you configure Platform to write information of users and groups into LDAP. It might not match your need exactly, but after this start you have everything in an ldap-extension, then you can adapt it by following the next sections.

For example, one of the use cases is that you already have a populated directory. After this start, you will follow LDAP users mapped into Platform and LDAP groups mapped into Platform.

Another note: the ldap-extension is technically a portal extension that is described in Developer guide, but it does not require compilation, so administrators can create it without Maven. If you are a developer, you can create a Maven project for it like your other extensions.

  1. Create your ldap-extension directory:

    ldap-extension
    |__ META-INF
        |__ exo-conf
            |__ configuration.xml
    |__ WEB-INF
        |__ conf
            |__ configuration.xml
            |__ organization
                |__ idm-configuration.xml
                |__ picketlink-idm-ldap-config.xml
                |__ sync.xml
        |__ jboss-deployment-structure.xml
        |__ web.xml
  2. Edit WEB-INF/conf/configuration.xml:

    
    <?xml version="1.0" encoding="ISO-8859-1"?>
    <configuration
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.exoplatform.org/xml/ns/kernel_1_2.xsd http://www.exoplatform.org/xml/ns/kernel_1_2.xsd"
       xmlns="http://www.exoplatform.org/xml/ns/kernel_1_2.xsd">

        <import>war:/conf/organization/idm-configuration.xml</import>
    </configuration>
  3. Copy content of the portal.war!/WEB-INF/conf/organization/idm-configuration.xml file of eXo Platform to your idm-configuration.xml file, then edit your file to replace:

    
    <value>war:/conf/organization/picketlink-idm/picketlink-idm-config.xml</value>

    with the path to your picketlink-idm-ldap-config.xml file:

    
    <value>war:/conf/organization/picketlink-idm-ldap-config.xml</value>
  4. Copy content from one of PicketLink sample files to your picketlink-idm-ldap-config.xml file.

    The sample files are in portal.war!/WEB-INF/conf/organization/picketlink-idm/examples. You can also find them in the ldap-extension sample. Choose either of the following files:

    • picketlink-idm-msad-config.xml if you use MS Active Directory.

    • picketlink-idm-openldap-config.xml for OpenLDAP.

    • picketlink-idm-ldap-config.xml for others.

  5. Modify the picketlink-idm-ldap-config.xml file according to your LDAP setup. You often need to change the following parameters:

    • The suffix (dc=test,dc=domain, dc=my-domain,dc=com or dc=example,dc=com) should be replaced with your real suffix in the whole file.

    • providerURL

    • adminDN

    • adminPassword

  6. Do the following sub-steps which are specified for Microsoft Active Directory (MSAD) only:

    i. Prepare a truststore file containing the valid certificate for MSAD. It can be generated by the Linux command:

    keytool -import -file  certificate -keystore truststore

    ii. Edit the following parameters in the picketlink-idm-ldap-config.xml file:

    • providerURL: Should use SSL (ldaps://).

    • customSystemProperties: Give your truststore file path and password.

      
      <name>customSystemProperties</name>
      <value>javax.net.ssl.trustStore=/path/to/msad.truststore</value>
      <value>javax.net.ssl.trustStorePassword=password</value>
  7. Uncomment the following entries in the idm-configuration.xml file:

    • groupTypeMappings

      
      <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>
    • ignoreMappedMembershipTypeGroupList

      
      <value>
          <string>/platform/*</string>
      </value>
      <value>
          <string>/organization/*</string>
      </value> 

    This step enables mapping Platform groups (platform and organization - that are predefined groups) to LDAP. If you bypass this step, only user mapping is performed.

  8. Edit META-INF/exo-conf/configuration.xml:

    
    <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">
        <external-component-plugins>
            <target-component>org.exoplatform.container.definition.PortalContainerConfig</target-component>
            <component-plugin>
                <name>Add PortalContainer Definitions</name>
                <set-method>registerChangePlugin</set-method>
                <type>org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin</type>
                <priority>101</priority>
                <init-params>
                    <values-param>
                        <name>apply.specific</name>
                        <value>portal</value>
                    </values-param>
                    <object-param>
                        <name>addDependencies</name>
                        <object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependencies">
                            <field name="dependencies">
                                <collection type="java.util.ArrayList">
                                    <value><string>ldap-extension</string></value>
                                </collection>
                            </field>
                        </object>
                    </object-param>
                </init-params>
            </component-plugin>
        </external-component-plugins>
    </configuration>
  9. Edit WEB-INF/web.xml:

    
    <?xml version="1.0" encoding="UTF-8"?>
    <web-app version="3.0" metadata-complete="true"
        xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
        <display-name>ldap-extension</display-name>
        <listener>
            <listener-class>org.exoplatform.container.web.PortalContainerConfigOwner</listener-class>
        </listener>
    </web-app>

    Make sure the right directory name, ldap-extension, is configured in this step and the previous step.

  10. Edit WEB-INF/jboss-deployment-structure.xml:

    
    <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2">
        <deployment>
            <dependencies>
                <module name="deployment.platform.ear" export="true"/>
            </dependencies>
        </deployment>
    </jboss-deployment-structure>

    This file is needed only in Platform JBoss and you can exclude it for Tomcat, but it is alright if you include it anyway.

  11. Package and deploy your ldap-extension into Platform.

  12. Make sure the LDAP server is running, and start eXo Platform.

Packaging and deploying

It is the standard way that you package (simply compress) the directory into ldap-extension.war then copy it to:

To compress the directory into a .war (and decompress the .war for editing), you can use any archiver tool that supports .war extension. Because JDK is required to run eXo Platform, you should have it already. So you can use the JDK built-in tool jar, as follows:

Note

Do not include the ldap-extension folder itself into the .war. The .war should contain META-INF and WEB-INF folders on the top, it should not contain ldap-extension folder. That's why you need to go to inside the directory first.

Tip

You should have ldap-extension packaged in .war when deploying it to production. However when testing, if you feel uncomfortable having to edit a .war, you can skip compressing it. In Tomcat, just deploy the original folder ldap-extension. In JBoss, rename it to ldap-extension.war.

Testing

If the integration is successful, Platform users (like the predefined root) and groups (sub-groups of /platform and /organization) will be added to the LDAP tree. For example, assume the suffix is dc=example,dc=com and the directory is OpenLDAP, the root user entry will look like:

# root, People, portal, gatein, example.com
dn: uid=root,ou=People,o=portal,o=gatein,dc=example,dc=com
uid: root
objectClass: top
objectClass: inetOrgPerson
userPassword:: Z3Ru
mail: root@localhost
cn: Root
sn: Root

The /organization/executive-board group entry will look like:

# executive-board, Organization, portal, gatein, example.com
dn: cn=executive-board,ou=Organization,o=portal,o=gatein,dc=example,dc=com
objectClass: top
objectClass: groupOfNames
cn: executive-board
member: uid=root,ou=People,o=portal,o=gatein,dc=example,dc=com

The whole directory is:

# example.com
dn: dc=example,dc=com

# gatein, example.com
dn: o=gatein,dc=example,dc=com

# portal, gatein, example.com
dn: o=portal,o=gatein,dc=example,dc=com

# Platform, portal, gatein, example.com
dn: ou=Platform,o=portal,o=gatein,dc=example,dc=com

# Organization, portal, gatein, example.com
dn: ou=Organization,o=portal,o=gatein,dc=example,dc=com

# People, portal, gatein, example.com
dn: ou=People,o=portal,o=gatein,dc=example,dc=com

# administrators, Platform, portal, gatein, example.com
dn: cn=administrators,ou=Platform,o=portal,o=gatein,dc=example,dc=com

# users, Platform, portal, gatein, example.com
dn: cn=users,ou=Platform,o=portal,o=gatein,dc=example,dc=com

# guests, Platform, portal, gatein, example.com
dn: cn=guests,ou=Platform,o=portal,o=gatein,dc=example,dc=com

# web-contributors, Platform, portal, gatein, example.com
dn: cn=web-contributors,ou=Platform,o=portal,o=gatein,dc=example,dc=com

# management, Organization, portal, gatein, example.com
dn: cn=management,ou=Organization,o=portal,o=gatein,dc=example,dc=com

# executive-board, Organization, portal, gatein, example.com
dn: cn=executive-board,ou=Organization,o=portal,o=gatein,dc=example,dc=com

# employees, Organization, portal, gatein, example.com
dn: cn=employees,ou=Organization,o=portal,o=gatein,dc=example,dc=com

# root, People, portal, gatein, example.com
dn: uid=root,ou=People,o=portal,o=gatein,dc=example,dc=com
Copyright ©. All rights reserved. eXo Platform SAS
blog comments powered byDisqus