This chapter will help you integrate eXo Platform 3.0 to your information system.
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 Single Sign On.
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, refer to here.
eXo Portal 3.0 supports 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.
To specify the initial Organization configuration, the content of your extension.war /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 type org.exoplatform.services.organization.OrganizationDatabaseInitializer is used to specify lists 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></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 the five components. For more details, take a look at the GateIn documentation .
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
ldap-configuration.xml
file, and this part will explain the numerous parameters which it contains.
Firstly, start by connection settings which will tell eXo how to connect to your directory server. These settings are very close to 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 PROVIDERURL ). For multiple LDAP servers, use comma separated list of host:port (Ex. 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 SECURITYPRINCIPAL ).
password: password for user rootdn (see SECURITYCREDENTIALS ).
authenticationType: type of authentication to be used (see SECURITYAUTHENTICATION ). 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.
referalMode: 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 file ldap-configuration.xml (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 can't be created by eXo and must exist in directory already.
ldapDescriptionAttr: Name of a common attribute that will be used as description for groups and membership types.
In Core, the ldapDesriptionAttr key is present but not consistently used everywhere in code. When using Core, consider that the description is always mapped to the 'description' attribute.
Other parameters are discussed in the following sections.
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
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 user creation.
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.
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: user name (login)
userPassword: password (used when portal authentication is done by eXo login module)
userFirstNameAttr: first name
userLastNameAttr: last name
userDisplayNameAttr: display name
userMailAttr: email address
Example: In the example above, 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 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. Example: Groups 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.
l attribute corresponds to the City property in OU property editor
Example: Adding the group human-resources 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: filter is used under 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. Example: Roles manager, user, admin and editor could by 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 separat list of classes for membership types creation.
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 Example: Adding 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
Example: If membershipTypeNameAttr is cn, then role name is 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. 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
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 rather complex filters. Example: Here is a filter used for a customer that needs to trigger a dynlist overlay on openldap.
(&amp;(objectClass=ExoMembership)(membershipURL=*))
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 to when creating user profiles
Here is an alternative configuration for active directory that you can find in activedirectory-configuration.xml
There is a Microsoft limitation: password can not be set in AD via unsecured connection you have to use the LDAPs protocol.
Here is how to use LDAPs protocol with the Active Directory:
1. setup AD to use SSL:
* add Active Directory Certificate Services role
* install right certificate for DC machine
2. enable Java VM to use certificate from AD:
* import root CA used in AD, to keystore, something like
keytool -importcert -file 2008.cer -keypass changeit -keystore /home/user/java/jdk1.6/jre/lib/security/cacerts
* set java options
JAVA_OPTS="${JAVA_OPTS} -Djavax.net.ssl.trustStorePassword=changeit -Djavax.net.ssl.trustStore=/home/user/java/jdk1.6/jre/lib/security/ca"
[...]
<component>
<key>org.exoplatform.services.ldap.LDAPService</key>
[..]
<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) -->
<!-- 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>
eXo Platform uses 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 identity management, there is a wrapper implementation that delegates to the PicketLink IDM framework. For futher information, look at here.
The email service can use any SMTP account configured in $JBOSSHOME/server/default/conf/gatein/configuration.properties or $TOMCATHOME/gatein/conf/configuration.properties if you are using Tomcat.
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 user name, 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.