This chapter will show you how to integrate eXo Platform 3.5 into your system throughout the specific topics below:
The information which is related to the authentication, including:
The information which is related to the users integration, including:
Explanations of numerous parameters of the eXo LDAP organization service, including:
Ways to configure the email service.
When logging into the portal, you can gain access to many systems through portlets using a single identity. However, in many cases, the portal infrastructure must be integrated with other SSO-enabled systems. There are many different Identity Management solutions available. The GateIn documentation gives detailed configuration for different SSO implementation. For more details, see SSO - Single Sign On.
Central Authentication Service (CAS)
Central Authentication Service (CAS) is a Web Single-Sign-On (WebSSO), developed by JA-SIG as an open source project. CAS enables you to work on different applications to log in only once and to be recognized and authenticated by all applications. Details about CAS can be found here.
The CAS integration consists of two steps:
Installing or configuring the CAS server.
Setting up the portal to use the CAS server.
For more information on CAS configuration, see here.
Kerberos SSO on Active Directory
eXo Portal 3.5 supports the Kerberos authentication on a Microsoft Active Directory. You will need to configure both your Active Directory server and the application server.
The implementation makes possible to use SPNEGO or NTLM. The client will get two authentication headers, including Negotiate and NTLM and will use whichever supported by the browser. In Firefox, it is possible to manage authentication types, but it is not in Internet Explorer; therefore, SPNEGO will be used.
To learn more about how to configure Kerberos SSO, see here.
See also
To specify the initial Organization configuration, the content of your extension.war in /WEB-INF/conf/organization/organization-configuration.xml should be edited. This file uses the portal XML configuration schema. It lists several configuration plugins.
The plugin of org.exoplatform.services.organization.OrganizationDatabaseInitializer type is used to specify a list of membership types, groups and users to be created.
The predefined membership types are specified in the membershipType field of the OrganizationConfig plugin parameter.
<field name="membershipType">
<collection type="java.util.ArrayList">
<value>
<object type="org.exoplatform.services.organization.OrganizationConfig$MembershipType">
<field name="type">
<string>member</string>
</field>
<field name="description">
<string>member membership type</string>
</field>
</object>
</value>
<value>
<object type="org.exoplatform.services.organization.OrganizationConfig$MembershipType">
<field name="type">
<string>owner</string>
</field>
<field name="description">
<string>owner membership type</string>
</field>
</object>
</value>
</collection>
</field>
The predefined groups are specified in the group field of the OrganizationConfig plugin parameter.
<field name="group">
<collection type="java.util.ArrayList">
<value>
<object type="org.exoplatform.services.organization.OrganizationConfig$Group">
<field name="name">
<string>portal</string>
</field>
<field name="parentId">
<string/>
</field>
<field name="type">
<string>hierachy</string>
</field>
<field name="description">
<string>the /portal group</string>
</field>
</object>
</value>
<value>
<object type="org.exoplatform.services.organization.OrganizationConfig$Group">
<field name="name">
<string>community</string>
</field>
<field name="parentId">
<string>/portal</string>
</field>
<field name="type">
<string>hierachy</string>
</field>
<field name="description">
<string>the /portal/community group</string>
</field>
</object>
</value>
...
</collection>
</field>
The predefined users are specified in the membershipType field of the OrganizationConfig plugin parameter.
<field name="user">
<collection type="java.util.ArrayList">
<value>
<object type="org.exoplatform.services.organization.OrganizationConfig$User">
<field name="userName">
<string>root</string>
</field>
<field name="password">
<string>exo</string>
</field>
<field name="firstName">
<string>root</string>
</field>
<field name="lastName">
<string>root</string>
</field>
<field name="email">
<string>exoadmin@localhost</string>
</field>
<field name="groups">
<string>member:/admin,member:/user,owner:/portal/admin</string>
</field>
</object>
</value>
<value>
<object type="org.exoplatform.services.organization.OrganizationConfig$User">
<field name="userName">
<string>exo</string>
</field>
<field name="password">
<string>exo</string>
</field>
<field name="firstName">
<string>site</string>
</field>
<field name="lastName">
<string>site</string>
</field>
<field name="email">
<string>exo@localhost</string>
</field>
<field name="groups">
<string>member:/user</string>
</field>
</object>
</value>
...
</collection>
</field>
The exo.platform.services.organization package has five main components: user, user profile, group, membership type and membership. There is an additional component that serves as an entry point into Organization API - OrganizationService component which provides handling functionality for five components. For more details, see the Organization API section.
See also
Description of parameters used in the connection settings.
Organization Service Configuration
Required information for configuring Organization Service that shows how the directory is structured and how to interact with it.
Active Directory sample configuration
Introduction to an alternative configuration for active directory, and steps to use the LDAPs protocol with the Active Directory.
Information about the PicketLink IDM component which eXo Platform currently uses for keeping the necessary identity information, such as users, groups, memberships.
If you have an existing LDAP server, the eXo predefined settings will likely not match your directory structure. eXo LDAP organization service implementation was written with flexibility in mind and can certainly be configured to meet your requirements.
The configuration is done in the ldap-configuration.xml file which contains numerous parameters.
See also
First, start by connection settings which will tell eXo how to connect to your directory server. These settings are very close to the JNDI API context parameters. This configuration is activated by the init-param ldap.config of service LDAPServiceImpl.
<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">
<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="authenticationType"><string>simple</string></field -->
<field name="version">
<string>3</string>
</field>
<field name="referralMode">
<string>follow</string>
</field>
<!-- field name="serverName"><string>active.directory</string></field -->
</object>
</object-param>
</init-params>
</component>
providerURL: LDAP server URL (see PROVIDER URL). For multiple LDAP servers, use comma separated list of host:port (For example, ldap://127.0.0.1:389,10.0.0.1:389).
rootdn: distinguished name of user that will be used by the service to authenticate on the server (see SECURITY PRINCIPAL).
password: password for user rootdn (see SECURITY CREDENTIALS).
authenticationType: type of authentication to be used (see SECURITY AUTHENTICATION). Use one of none, simple, strong. Default is simple.
version: LDAP protocol version (see java.naming.ldap.version). Set to 3 if your server supports LDAP V3.
referralMode: one of follow, ignore, throw (see REFERRAL).
serverName: you will need to set this to active.directory to work with Active Directory servers. Any other value will be ignored and the service will act as on a standard LDAP.
Next, you need to configure the eXo OrganizationService to show how the directory is structured and how to interact with it. This is managed by a couple of init-params: ldap.userDN.key and ldap.attribute.mapping in the ldap-configuration.xml file (by default located at portal.war/WEB-INF/conf/organization)
<component>
<key>org.exoplatform.services.organization.OrganizationService</key>
<type>org.exoplatform.services.organization.ldap.OrganizationServiceImpl</type>
[...]
<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"/>
[...]
</object-param>
</init-params>
[...]
</component>
ldap.attribute.mapping maps your LDAP to eXo. At first, there are two main parameters to configure in it:
<field name="baseURL">
<string>dc=exoplatform,dc=org</string>
</field>
<field name="ldapDescriptionAttr">
<string>description</string>
</field>
baseURL: root dn for eXo organizational entities. This entry cannot be created by eXo and must have existed in the directory already.
ldapDescriptionAttr: Name of a common attribute that will be used as description for groups and membership types.
In Core, the ldapDescriptionAttr key is present but not consistently used everywhere in code. When using Core, consider that the description is always mapped to the 'description' attribute.
Here are the main parameters to map eXo users to your directory:
<field name="userURL">
<string>ou=users,ou=portal,dc=exoplatform,dc=org</string>
</field>
<field name="userObjectClassFilter">
<string>objectClass=person</string>
</field>
<field name="userLDAPClasses">
<string>top,person,organizationalPerson,inetOrgPerson</string>
</field>
userURL: base dn for users. Users are created in a flat structure under this base with a dn of the form: ldap.userDN.key=username,userURL.
For example:
uid=john,cn=People,o=MyCompany,c=com
However, if users exist deeply under userURL, eXo will be able to retrieve them.
Example:
uid=tom,ou=France,ou=EMEA,cn=People,o=MyCompany,c=com
userObjectClassFilter: Filter used under userURL branch to distinguish eXo user entries from others.
Example: john and tom will be recognized as valid eXo users but EMEA and France entries will be ignored in the following subtree:
uid=john,cn=People,o=MyCompany,c=com
objectClass: person
...
ou=EMEA,cn=People,o=MyCompany,c=com
objectClass: organizationalUnit
...
ou=France,ou=EMEA,cn=People,o=MyCompany,c=com
objectClass: organizationalUnit
...
uid=tom,ou=EMEA,cn=People,o=MyCompany,c=com
objectClass: person
...userLDAPClasses: commas are used to separate list of classes used for creating users. When a new user is created, an entry will be created with the given objectClass attributes. The classes must at least define cn and any attribute referenced in the user mapping.
For example, adding the user Marry Simons could produce:
uid=marry,cn=users,ou=portal,dc=exoplatform,dc=org objectclass: top objectClass: person objectClass: organizationalPerson objectClass: inetOrgPerson ...
The following parameters maps LDAP attributes to eXo User Java objects attributes.
<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>
userUsernameAttr: username (login)
userPassword: password (used when the portal authentication is done by eXo login module)
userFirstNameAttr: first name
userLastNameAttr: last name
userDisplayNameAttr: display name
userMailAttr: email address
In the example above, the user Marry Simons could produce:
uid=marry,cn=users,ou=portal,dc=exoplatform,dc=org userPassword: XXXX givenName: Marry sn: Simons displayName: Marry Simons mail: marry.simons@example.org uid: marry ...
eXo Platform groups can be mapped to organizational or applicative groups defined in your directory.
<field name="groupsURL">
<string>ou=groups,ou=portal,dc=exoplatform,dc=org</string>
</field>
<field name="groupLDAPClasses">
<string>top,organizationalUnit</string>
</field>
<field name="groupObjectClassFilter">
<string>objectClass=organizationalUnit</string>
</field>
groupsURL: base dn for eXo groups Groups can be structured hierarchically under groupsURL. For example, groups, including communication, communication/marketing and communication/press, would map to:
ou=communication,ou=groups,ou=portal,dc=exoplatform,dc=org ... ou=marketing,ou=communication,ou=groups,ou=portal,dc=exoplatform,dc=org ... ou=press,ou=communication,ou=groups,ou=portal,dc=exoplatform,dc=org ...
groupLDAPClasses: commas are used to separate list of classes used for group creation. When a new group is created, an entry will be also created with the given objectClass attributes. The classes must define at least the required attributes: ou, description and l.
The l attribute corresponds to the City property in OU property editor.
For example, adding the human-resources group could produce:
ou=human-resources,ou=groups,ou=portal,dc=exoplatform,dc=org objectclass: top objectClass: organizationalunit ou: human-resources description: The human resources department l: Human Resources ...
groupObjectClassFilter: This filter is used under the groupsURL branch to distinguish eXo groups from other entries. You can also use a complex filter if you need. Example: groups WebDesign, WebDesign/Graphists and sales could be retrieved in:
l=Paris,dc=sites,dc=mycompany,dc=com
...
ou=WebDesign,l=Paris,dc=sites,dc=mycompany,dc=com
...
ou=Graphists,WebDesign,l=Paris,dc=sites,dc=mycompany,dc=com
...
l=London,dc=sites,dc=mycompany,dc=com
...
ou=Sales,l=London,dc=sites,dc=mycompany,dc=com
...Membership types are the possible roles that can be assigned to users in groups.
<field name="membershipTypeURL">
<string>ou=memberships,ou=portal,dc=exoplatform,dc=org</string>
</field>
<field name="membershipTypeLDAPClasses">
<string>top,organizationalRole</string>
</field>
<field name="membershipTypeNameAttr">
<string>cn</string>
</field>
membershipTypeURL: base dn for membership types storage. eXo stores membership types in a flat structure under membershipTypeURL. For example, roles, including manager, user, admin and editor could be defined by the subtree:
ou=roles,ou=portal,dc=exoplatform,dc=org ... cn=manager,ou=roles,ou=portal,dc=exoplatform,dc=org ... cn=user,ou=roles,ou=portal,dc=exoplatform,dc=org ... cn=admin,ou=roles,ou=portal,dc=exoplatform,dc=org ... cn=editor,ou=roles,ou=portal,dc=exoplatform,dc=org ...
membershipTypeLDAPClasses: commas are used to separate list of classes for creating membership types. When a new membership type is created, an entry will be also created with the given objectClass attributes. The classes must define the required attributes: description, cn.
For example, adding the membership type validator would produce:
cn=validator,ou=roles,ou=portal,dc=exoplatform,dc=org objectclass: top objectClass: organizationalRole ...
membershipTypeNameAttr: Attribute will be used as the name of the role. For example, if membershipTypeNameAttr is cn, the role name will be manager for the following membership type entry:
cn=manager,ou=roles,ou=portal,dc=exoplatform,dc=org
Memberships are used to assign a role within a group. They are entries that are placed under the group entry of their scope group. Users in this role are defined as attributes of the membership entry.
For example, to designate tom as the manager of the group human-resources:
ou=human-resources,ou=groups,ou=portal,dc=exoplatform,dc=org
...
cn=manager,ou=human-resources,ou=groups,ou=portal,dc=exoplatform,dc=org
member: uid=tom,ou=users,ou=portal,dc=exoplatform,dc=org
...The parameters to configure memberships are:
<field name="membershipLDAPClasses">
<string>top,groupOfNames</string>
</field>
<field name="membershipTypeMemberValue">
<string>member</string>
</field>
<field name="membershipTypeRoleNameAttr">
<string>cn</string>
</field>
<field name="membershipTypeObjectClassFilter">
<string>objectClass=organizationalRole</string>
</field>
membershipLDAPClasses: the commas are used to separate the list of classes for creating memberships. When a new membership is created, an entry will be also created with the given objectClass attributes. The classes must at least define the attribute designated by membershipTypeMemberValue. Example: Adding membership validator would produce:
cn=validator,ou=human-resources,ou=groups,ou=portal,dc=exoplatform,dc=org objectclass: top objectClass: groupOfNames ...
membershipTypeMemberValue: Multi-valued attribute is used in memberships to reference users that have the role in the group. Values should be a user dn.
Example: james and root, who have admin role within the group human-resources, would give:
cn=admin,ou=human-resources,ou=groups,ou=portal,dc=exoplatform,dc=org member: cn=james,ou=users,ou=portal,dc=exoplatform,dc=org member: cn=root,ou=users,ou=portal,dc=exoplatform,dc=org ...
membershipTypeRoleNameAttr: Attribute of the membership entry whose value refers to the membership type. For example, in the following membership entry:
cn=manager,ou=human-resources,ou=groups,ou=portal,dc=exoplatform,dc=org
The cn attribute is used to designate the manager membership type. In other words, the name of role is given by the 'cn' attribute.
membershipTypeObjectClassFilter: Filter is used to distinguish membership entries under groups. You can use the more complex filters. For example, the following is a filter used for a customer that needs to trigger a dynlist overlay on OpenLDAP.
(&amp;(objectClass=ExoMembership)(membershipURL=*))
Please pay attention to the xml escaping of the '&' (and) operator.
eXo User profiles also have entries in the LDAP but the actual storage is still done with the hibernate service. You will need the following parameters:
<field name="profileURL">
<string>ou=profiles,ou=portal,dc=exoplatform,dc=org</string>
</field>
<field name="profileLDAPClasses">
<string>top,organizationalPerson</string>
</field>
profileURL: base dn to store user profiles.
profileLDAPClasses: Classes used for creating user profiles.
Here is an alternative configuration for active directory that you can find in activedirectory-configuration.xml.
[...]
<component>
<key>org.exoplatform.services.ldap.LDAPService</key>
[..]
<object type="org.exoplatform.services.ldap.impl.LDAPConnectionConfig">
<!-- for multiple ldap servers, use comma separated list of host:port (Ex. ldap://127.0.0.1:389,10.0.0.1:389) -->
<!-- whether or not to enable ssl, if ssl is used ensure that the javax.net.ssl.keyStore & java.net.ssl.keyStorePassword properties are set -->
<!-- exo portal default installed javax.net.ssl.trustStore with file is java.home/lib/security/cacerts-->
<!-- ldap service will check protocol, if protocol is ldaps, ssl is enable (Ex. for enable ssl: ldaps://10.0.0.3:636 ;for disable ssl: ldap://10.0.0.3:389 ) -->
<!-- when enable ssl, ensure server name is *.directory and port (Ex. active.directory) -->
<field name="providerURL"><string>ldaps://10.0.0.3:636</string></field>
<field name="rootdn"><string>CN=Administrator,CN=Users, DC=exoplatform,DC=org</string></field>
<field name="password"><string>site</string></field>
<field name="version"><string>3</string></field>
<field name="referralMode"><string>ignore</string></field>
<field name="serverName"><string>active.directory</string></field>
</object>
[..]
</component>
<component>
<key>org.exoplatform.services.organization.OrganizationService</key>
[...]
<object type="org.exoplatform.services.organization.ldap.LDAPAttributeMapping">
[...]
<field name="userAuthenticationAttr"><string>mail</string></field>
<field name="userUsernameAttr"><string>sAMAccountName</string></field>
<field name="userPassword"><string>unicodePwd</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="membershipTypeLDAPClasses"><string>top,group</string></field>
<field name="membershipTypeObjectClassFilter"><string>objectClass=group</string></field>
[..]
<field name="membershipLDAPClasses"><string>top,group</string></field>
<field name="membershipObjectClassFilter"><string>objectClass=group</string></field>
</object>
[...]
</component>
There is a Microsoft limitation: the password cannot be set in AD via unsecured connection, you have to use the LDAPs protocol.
Here is how to use the LDAPs protocol with the Active Directory:
1. Set up AD to use SSL:
i. Add the Active Directory Certificate Services role.
ii. Install the right certificate for the DC machine.
2. Enable Java VM to use the certificate from AD:
i. Import the root CA used in AD, to keystore, such as: keytool importcert file 2008.cer keypass changeit keystore /home/user/java/jdk1.6/jre/lib/security/cacerts.
ii. Set the Java options as below:
JAVA_OPTS="${JAVA_OPTS} -Djavax.net.ssl.trustStorePassword=changeit -Djavax.net.ssl.trustStore=/home/user/java/jdk1.6/jre/lib/security/ca"
eXo Platform uses the PicketLink IDM component to keep the necessary identity information, such as users, groups, memberships. While the legacy interfaces are still used (org.exoplatform.services.organization) for the identity management, there is a wrapper implementation that delegates to the PicketLink IDM framework. For further information, visit here.
The project exo.core defines the API for Organization Service and the eXo Platform implementation of API. For the Organization Service plugged in the eXo Platform product, you are flexible in switching between: eXo Organization Service, PicketLink and your own implementation. The configuration to switch between various Organization Service implementations can be found in portal.war/WEB-INF/conf/configuration.xml:
<!--PicketLink IDM integration -->
<import>war:/conf/organization/idm-configuration.xml</import>
<!--Former exo implementations -->
<!--<import>war:/conf/organization/exo/hibernate-configuration.xml</import> -->
<!-- <import>war:/conf/organization/exo/jdbc-configuration.xml</import> -->
<!--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/ldap-configuration.xml</import> -->
If you want to switch between different implementations, you just need to uncomment the corresponding <import> and leave others commented:
<!--PicketLink IDM integration -->
<import>war:/conf/ldap-configuration.xml</import>
<!-- <import>war:/conf/organization/idm-configuration.xml</import> -->
<!--Former exo implementations -->
<!--<import>war:/conf/organization/exo/hibernate-configuration.xml</import> -->
<!-- <import>war:/conf/organization/exo/jdbc-configuration.xml</import> -->
<!--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 -->
The email service can use any SMTP account configured in the configuration.properties file.
File location
| File | Tomcat | JBoss |
|---|---|---|
| configuration.properties | $PLATFOORM_TOMCAT_HOME/gatein/conf/configuration.properties | $PLATFORM_JBOSS_HOME/server/default/conf/gatein/configuration.properties |
The relevant section looks like:
# EMail gatein.email.smtp.username= gatein.email.smtp.password= gatein.email.smtp.host=smtp.gmail.com gatein.email.smtp.port=465 gatein.email.smtp.starttls.enable=true gatein.email.smtp.auth=true gatein.email.smtp.socketFactory.port=465 gatein.email.smtp.socketFactory.class=javax.net.ssl.SSLSocketFactory
It is pre-configured for Gmail, so any Gmail account can easily be used. You simply need to use the full Gmail address as username, and fill in the password.
In corporate environments, you will want to use your corporate SMTP gateway. When using it over SSL, like in the default configuration, you may need to configure a certificate trust-store, containing your SMTP server's public certificate. Depending on the key sizes, you might also need to install Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files for your Java Runtime Environment.
See also