Illustration 63: Message Boards permissions. Global Server Settings
Now that you have navigated in the Enterprise Admin portlet, you know that there are more tabs in it than it initially shows. While the first four tabs focus on the maintenance of users and portal security, the remaining tabs focus on various portal settings which cover how the portal operates and integrates with other systems you may have.
Password policies can help to enhance the security of your portal. Using password policies, you can set password rules such as password strength, frequency of password expiration, and more. Additionally, you can apply different rule sets to different sets of portal users.
If you are viewing the Enterprise Admin portlet in its Restored state (i.e., not maximized), click the tab with the two arrows on it (>>). This will expand the portlet so you can see the rest of the tabs. Next, click on the Password Policies tab. You will see that there is already a default password policy in the system. You can edit this in the same manner as you edit other resources in the portal: click Actions and then click Edit.
You will then see the Password Policy settings form:
Changeable: Selects whether a user can change his or her password.
Change Required: Selects whether a user must change his or her password upon first log in.
Minimum Age: You can choose how long a password must remain in effect before it can be changed.
Syntax Checking: Allows you to choose whether dictionary words can be in passwords as well as the minimum password length.
Password History: Keeps a history (with a defined length) of passwords and won't allow users to change their passwords to one that was previously used.
Password Expiration: Lets you choose an interval where passwords can be active before they expire. You can select the age, the warning time, and a grace limit.
Lockout: Allows you to set the number of failed log in attempts before a user's account becomes locked. You can choose whether an administrator needs to unlock the account or if it becomes unlocked after a specific duration.
From the list of password policies, you can perform several other actions.
Edit: Brings you to the form above and allows you to modify the password policy.
Permissions: This allows you to define which Users, User Groups, or Roles have permissions to edit the Password Policy.
Assign Members: Takes you to a screen where you can search and select users in the portal to be assigned to this password policy. The password policy will be enforced for any users who are added here.
Delete: This shows up for any password policies that you add beyond the default policy. You cannot delete the default policy.
The Settings tab is where most of the global portal settings are:
General: This lets you configure global settings, such as the company name, domain, the virtual host, a global portal logo, and more.
Authentication: Allows you to configure login IDs, connection to LDAP, and Single Sign-On.
Default User Associations: Lets you configure default membership to Roles, User Groups, and Communities for new users.
Reserved Screen Names: Lets you reserve screen names and email addresses so that users cannot register using them. You might use this to prevent users from registering with the portal with user names that contain profanity or that sound official, such as admin or president.
Mail Host Names: You can add a list of other mail servers besides your main one here.
Email Notifications: Liferay sends email notifications for certain events, such as user registrations, password changes, etc. You can customize those messages here.
We will go over these settings in detail below.
The General tab allows you to set the name of the company / organization / site which is running the portal. You can also set the default domain name, virtual host, language and time zone, as well as a number of other data about the organization.
You can also set the portal-wide logo which appears in the top left corner of themes that are configured to display it. Be careful when using this option to choose an image file that fits the space. If you pick something that is too big, it will mess up the navigation.
Authentication: General Settings
The Authentication tab has several tabs under it. All of these are used for configuring how users will authenticate to Liferay. Because Liferay supports a number of authentication methods, there are settings for each.
The general settings affect only Liferay functionality, and don't have anything to do with any of the integration options on the other tabs. This tab allows you to customize Liferay's out-of-box behavior regarding authentication. Specifically, the General tab allows you to select from several global authentication settings:
Authenticate via email address (default), screen name, or user ID (a numerical ID auto-generated in the database—not recommended).
Enable / Disable Forgot Password functionality.
Enable / Disable account creation by strangers. If you are running an Internet site, you will probably want to leave this on so that visitors can create accounts on your site.
Enable / Disable account creation by those using an email address in the domain of the company running the site (which you just set on the General tab).
Enable / Disable email address verification. If you enable this, Liferay, will send users a verification email with a link back to the portal to verify the email address they entered is a valid one they can access.
By default, all settings except for the last are enabled by default. One default that is important is that users will authenticate by their email address. Liferay defaults to this for several reasons:
An email address is, by definition, unique to the user who owns it.
People can generally remember their email addresses. If you have a user who hasn't logged into the portal for a while, it is possible that he or she will forget his or her screen name, especially if the user was not allowed to use his or her screen name of choice (because somebody else already used it).
If a user changes his or her email address, if it is not used to authenticate, it is more likely that the user will forget to update his or her email address in his or her profile. If the user's email address is not updated, all notifications sent by the portal will fail to reach the user. So it is important to keep the email address at the forefront of a user's mind when he or she logs in to help the user keep it up to date.
For these reasons, Liferay defaults to using the email address as a user name.
Connecting Liferay to an LDAP directory has become much easier and is now a straightforward process through the Enterprise Admin portlet. There are still, however, two places in which you can configure the LDAP settings: the portal-ext.properties file (which will be covered in the next chapter) and the Enterprise Admin portlet—where the settings will get stored in the database. Note that if you use both, the settings in the database will override the settings in portal-ext.properties. For this reason, we recommend for most users that you use the Enterprise Admin portlet to configure the LDAP settings—it's easier and does not require a restart of Liferay. The only compelling reason to use the portal-ext.properties file is if you have many Liferay nodes which will be configured to run against the same LDAP directory. In that case, for your initial deployment, it may be easier to copy the portal-ext.properties file to all of the nodes so that the first time they start up, the settings are correct. Regardless of which method you use, the settings are the same.
The LDAP settings screen is very detailed, so we will look at it in chunks.
There are two global LDAP settings.
Enabled: Check this box to enable LDAP Authentication.
Required: Check this box if LDAP authentication is required. Liferay will then not allow a user to log in unless he or she can successfully bind to the LDAP directory first. Uncheck this box if you want to allow users that have Liferay accounts but no LDAP accounts to log in to the portal.
Several leading directory servers are listed here. If you are using one of these, select it and the rest of the form will be populated with the proper default values for that directory.
These settings cover the basic connection to LDAP.
Base Provider URL: This tells the portal where the LDAP server is located. Make sure that the machine on which Liferay is installed can communicate with the LDAP server. If there is a firewall between the two systems, check to make sure that the appropriate ports are opened.
Base DN: This is the Base Distinguished Name for your LDAP directory. It is usually modeled after your organization. For a commercial organization, it may look something like: dc=companynamehere,dc=com.
Principal: By default, the administrator ID is populated here. If you have removed the default LDAP administrator, you will need to use the fully qualified name of the administrative credential you do use. You need an administrative credential because Liferay will be using this ID to synchronize user accounts to and from LDAP.
Credentials: This is the password for the administrative user.
This is all you need in order to make a regular connection to an LDAP directory. The rest of the configuration is optional: generally, the default attribute mappings are sufficient data to synchronize back to the Liferay database when a user attempts to log in. To test the connection to your LDAP server, click the Test LDAP Connection button.
If you are running your LDAP directory in SSL mode to prevent credential information from passing through the network unencrypted, you will have to perform extra steps to share the encryption key and certificate between the two systems.
For example, assuming your LDAP directory happens to be Microsoft Active Directory on Windows Server 2003, you would take the following steps to share the certificate:
On the Windows 2003 Domain Controller, open the Certificates MMC snapin. Export the Root Certificate Authority certificate by selecting Certificates (Local Computer) mmc snapin -> Trusted Root Certification Authorities -> MyRootCACertificateName. Right click this certificate and select All Tasks -> export -> select DER encoded binary X.509 .CER. Copy the exported .cer file to your Liferay Portal server.
As with the CAS install (see the below section entitled Single Sign-On), you will need to import the certificate into the cacerts keystore. The import is handled by a command like the following:
keytool -import -trustcacerts -keystore /some/path/jdk1.5.0_11/jre/lib/security/cacerts -storepass changeit -noprompt
-alias MyRootCA -file /some/path/MyRootCA.cer
Once this is done, go back to the LDAP page in the Enterprise Admin portlet by selecting Settings -> Authentication -> LDAP. Modify the LDAP URL in the Base DN field to the secure version by changing the protocol to https and the port to 636 like the following:
Save the changes. Your Liferay Portal will now use LDAP in secure mode for authentication.
This section contains settings for finding users in your LDAP directory.
Authentication Search Filter: The search filter box can be used to determine the search criteria for user logins. By default, Liferay uses the email address as a user login name. If you have changed this setting—which can be done on the General tab that's next to the LDAP tab in the Enterprise Admin portlet—you will need to modify the search filter here, which has by default been configured to use the email address attribute from LDAP as search criteria. For example, if you changed Liferay's authentication method to use the screen name instead of the email address, you would modify the search filter so that it can match the entered login name:
Import Search Filter: Depending on the LDAP server, there are different ways to identify the user. Generally, the default setting (objectClass=inetOrgPerson) is fine, but if you want to search for only a subset of users or users that have different object classes, you can change this.
User Mapping: The next series of fields allows you to define mappings from LDAP attributes to Liferay fields. Though your LDAP user attributes may be different from LDAP server to LDAP server, there are five fields that Liferay requires to be mapped in order for the user to be recognized. You must define a mapping to the corresponding attributes in LDAP for the following Liferay fields:
The Enterprise Admin portlet provides default mappings for commonly used LDAP attributes. You can also add your own mappings if you wish.
Test LDAP Users: Once you have your attribute mappings set up (see above), click the Test LDAP Users button, and Liferay will attempt to pull LDAP users and match them up with their mappings as a preview.
Illustration 64: Testing LDAP UsersGroups
This section contains settings for mapping LDAP groups to Liferay.
Import Search Filter: This is the filter for finding LDAP groups that you want to map to Liferay. Enter the LDAP group attributes that you want retrieved for this mapping. The following attributes can be mapped:
Test LDAP Groups: Click the Test LDAP Groups to display a list of the groups returned by your search filter.
Illustration 65: Mapping LDAP Groups. Import/Export
Import Enabled: Check this box to cause Liferay to do a mass import from your LDAP directory. If you want Liferay to only synchronize users when they log in, leave this box unchecked. Definitely leave this unchecked if you are working in a clustered environment.
If you check the box, several other options will become available.
Import on Startup Enabled: Check this box to have Liferay run the import when it starts up.
Import Interval: The import runs on a schedule. Select how often you want the import to run.
Export Enabled: Check this box to enable Liferay to export user accounts from the database to LDAP. Liferay uses a listener to track any changes made to the User object and will push these changes out to the LDAP server whenever the User object is updated. Note that on every login, fields such as LastLoginDate are updated. When export is enabled, this has the effect of causing a user export every time the user logs in.
Users DN: Enter the location in your LDAP tree where the users will be stored. When Liferay does an export, it will export the users to this location.
User Default Object Classes: When a user is exported, the user is created with the listed default object classes. To find out what your default object classes are, use an LDAP browser tool such as JXplorer to locate a user and view the Object Class attributes that are stored in LDAP for that user.
Groups DN: Enter the location in your LDAP tree where the groups will be stored. When Liferay does an export, it will export the groups to this location.
Use LDAP Password Policy: Liferay uses its own password policy by default. This can be configured on the Password Policies tab of the Enterprise Admin portlet. If you want to use the password policies defined by your LDAP directory, check this box. Once this is enabled, the Password Policies tab will display a message stating that you are not using a local password policy. You will now have to use your LDAP directory's mechanism for setting password policies. Liferay does this by parsing the messages in the LDAP controls that are returned by your LDAP server. By default, the messages in the LDAP controls that Liferay is looking for are the messages that are returned by the Fedora Directory Server. If you are using a different LDAP server, you will need to customize the messages in Liferay's portal-ext.properties file, as there is not yet a GUI for setting this. See below for instructions describing how to do this.
Once you have completed configuring LDAP, click the Save button.
LDAP Options Not Available in the GUI
Though most of the LDAP configuration can be done from the Enterprise Admin portlet, there are several configuration parameters that are only available by editing portal-ext.properties. These options will be available in the GUI in future versions of Liferay Portal, but for now they can only be configured by editing the properties file.
If you need to change any of these options, copy the LDAP section from the portal.properties file into your portal-ext.properties file. Note that since you have already configured LDAP from the GUI, any settings from the properties file that match settings already configured in the GUI will be ignored. The GUI, which stores the settings in the database, always takes precedence over the properties file.
If you set this to user, Liferay will import all users from the specified portion of the LDAP tree. If you set this to group, Liferay will search all the groups and import the users in each group. If you have users who do not belong to any groups, they will not be imported.
ldap.error.password.not.changeable=not allowed to change
These properties are a list of phrases from error messages which can possibly be returned by the LDAP server. When a user binds to LDAP, the server can return controls with its response of success or failure. These controls contain a message describing the error or the information that is coming back with the response. Though the controls are the same across LDAP servers, the messages can be different. The properties described here contain snippets of words from those messages, and will work with Red Hat's Fedora Directory Server. If you are not using that server, the word snippets may not work with your LDAP server. If they don't, you can replace the values of these properties with phrases from your server's error messages. This will enable Liferay to recognize them.
Single Sign-On solutions allow you to provide a single log in credential for multiple systems. This allows you to have people authenticate to the Single Sign-On product and they will be automatically logged in to Liferay and to other products as well.
Liferay at the time of this writing supports several single sign-on solutions. Of course if your product is not yet supported, you may choose to implement support for it yourself by use of the extension environment—or your organization can choose to sponsor support for it. Please contact email@example.com for more information about this.
Authentication: Central Authentication Service (CAS)
CAS is an authentication system that was originally created at Yale University. It is a widely-used open source single sign-on solution, and was the first SSO product to be supported by Liferay.
Please follow the documentation for CAS to install it on your application server of choice. You can use the version that Liferay provides on our web site or the official version from the JA-SIG web site. The reason for the difference is simply that newer versions require JDK 5 and above only. We provide the older ones for use with Liferay 4.4.2 and below, so that users can have a full environment that runs on JDK 1.4.
Tip: If you are using Liferay 5.x, use the newer versions of CAS from the JA-SIG web site. If you are using Liferay 4.x, use the older Yale versions of CAS from Liferay's Sourceforge archives.
Your first step will be to copy the CAS client .jar file to Liferay's library folder. On Tomcat, this is in <Tomcat Home>/webapps/ROOT/WEB-INF/lib. Once you've done this, the CAS client will be available to Liferay the next time you start it.
The CAS Server application requires a properly configured Secure Socket Layer certificate on your server in order to work. If you wish to generate one yourself, you will need to use the keytool utility that comes with the JDK. Your first step is to generate the key. Next, you export the key into a file. Finally, you import the key into your local Java key store. For public, Internet-based production environments, you will need to either purchase a signed key from a recognized certificate authority (such as Thawte or Verisign) or have your key signed by a recognized certificate authority. For Intranets, you should have your IT department pre-configure users' browsers to accept the certificate so that they don't get warning messages about the certificate.
To generate a key, use the following command:
keytool -genkey -alias tomcat -keypass changeit -keyalg RSA
Instead of the password in the example (changeit), use a password that you will be able to remember. If you are not using Tomcat, you may want to use a different alias as well. For First and Last name, enter localhost, or the host name of your server. It cannot be an IP address.
To export the key to a file, use the following command:
keytool -export -alias tomcat -keypass changeit -file server.cert
Finally, to import the key into your Java key store, use the following command:
keytool -import -alias tomcat -file %FILE_NAME% -keypass changeit -keystore $JAVA_HOME/jre/lib/security/cacerts
If you are on a Windows system, replace $JAVA_HOME above with %JAVA_HOME%. Of course, all of this needs to be done on the system on which CAS will be running.
Once your CAS server is up and running, you can configure Liferay to use it. This is a simple matter of navigating to the Settings -> Authentication -> CAS tab in the Enterprise Admin portlet. Enable CAS authentication, and then modify the URL properties to point to your CAS server.
Enabled: Set this to true to enable CAS single sign-on.
Import from LDAP: A user may be authenticated from CAS and not yet exist in the portal. Select this to automatically import users from LDAP if they do not exist in the portal.
The rest of the settings are various URLs, with defaults included. Change localhost in the default values to point to your CAS server. When you are finished, click Save. After this, when users click the Sign In link from the Dock, they will be directed to the CAS server to sign in to Liferay.
NTLM is a Microsoft protocol that can be used for authentication through Microsoft Internet Explorer. Though Microsoft has adopted Kerberos in modern versions of Windows server, NTLM is still used when authenticating to a workgroup.
Enabled: Check the box to enable NTLM authentication.
Domain Controller: Enter the IP address of your domain controller. This is the server that contains the user accounts you want to use with Liferay.
Domain: Enter the domain / workgroup name.
OpenID is a new single sign-on standard which is implemented by multiple vendors. The idea is that multiple vendors can implement the standard, and then users can register for an ID with the vendor they trust. The credential issued by that vendor can be used by all the web sites that support OpenID. Some high profile OpenID vendors are AOL (http://openid.aol.com/screenname), LiveDoor (http://profile.livedoor.com/username), and LiveJournal (http://username.livejournal.com). Please see the OpenID site (http://www.openid.net) for a more complete list.
The obvious main benefit of OpenID for the user is that he or she no longer has to register for a new account on every site in which he or she wants to participate. Users can register on one site (the OpenID provider's site) and then use those credentials to authenticate to many web sites which support OpenID. Many web site owners often struggle to build communities because end users are reluctant to register for so many different accounts. Supporting OpenID makes it easier for site owners to build their communities because the barriers to participating (i.e., the effort it takes to register for and keep track of many accounts) are removed. All of the account information is kept with the OpenID provider, making it much easier to manage this information and keep it up to date.
Liferay Portal can act as an OpenID consumer, allowing users to automatically register and sign in with their OpenID accounts. Internally, the product uses OpenID4Java (http://code.google.com/p/openid4java/) to implement the feature.
OpenID is enabled by default in Liferay, but can be disabled on this tab.
Atlassian Crowd is a web-based Single Sign-On product similar to CAS. Crowd can be used to manage authentication to many different web applications and directory servers.
Because Atlassian Crowd implements an OpenID producer, Liferay works and has been tested with it. Simply use the OpenID authentication feature in Liferay to log in using Crowd.
OpenSSO is an open source single sign-on solution that comes from the code base of Sun's System Access Manager product. Liferay integrates with OpenSSO, allowing you to use OpenSSO to integrate Liferay into an infrastructure that contains a multitude of different authentication schemes against different repositories of identities.
You can set up OpenSSO on the same server as Liferay or a different box. Follow the instructions at the OpenSSO site (http://opensso.dev.java.net) to install OpenSSO. Once you have it installed, create the Liferay administrative user in it. Users are mapped back and forth by screen names. By default, the Liferay administrative user has a screen name of test, so in OpenSSO, you would register the user with the ID of test and an email address of firstname.lastname@example.org. Once you have the user set up, log in to Open SSO using this user.
In the same browser window, go to the URL for your server running Liferay and log in as the same user, using the email address email@example.com. Go to the Enterprise Admin portlet and the Settings -> Authentication -> OpenSSO tabs. Modify the three URL fields (Login URL, Logout URL, and Service URL) so that they point to your OpenSSO server (i.e., only modify the host name portion of the URLs), click the Enabled check box, and then click Save. Liferay will then redirect users to OpenSSO when they click the Sign In link.
Default User Associations
The Default User Associations tab has three fields allowing you to list (one per line) communities, roles, and user groups that you want new users to be members of by default. Liferay's default is to have new users be members of both the Users role and the Power Users role.
The Power Users role allows users to have their own set of pages where they can add their own portlets, such as blogs, mail, or calendar.
This is generally appropriate for an Intranet, but not an Internet, so you may want to change this for your own implementations. If you have defined other user groups, communities, or roles that you want newly created users to be members of by default, enter them here. For example, you may have defined page templates in certain user groups to pre-populate end users' private pages. If there is a particular configuration that you want everyone to have, you may want to enter those user groups here.
Reserved Screen Names
The next tab is Reserved Screen Names. You can enter screen names and email addresses here that you don't want others to use. Liferay will then prevent users from registering with these screen names and email addresses. You might use this feature to prevent users from creating IDs that look like administrative IDs or that have reserved words in their names.
Mail Host Names
The next tab is Mail Host Names. You can enter (one per line) other mail host names besides the one you configured on the General tab. Liferay will fail over to these host names in the event that the connection to the main one fails.
There are three tabs under the Email Notifications tab. The General tab allows you to set the portal administration name and email address. By default, this is Joe Bloggs and firstname.lastname@example.org. You can change it to anything you want. This name and address will appear in the From field in all email messages sent by the portal.
The other two tabs (Account Created Notification and Password Changed Notification) allow you to customize the email messages that are sent to users on those two events. A list of tokens for inserting certain values (such as the portal URL) is given if you wish to use those.
The Admin Portlet
The Admin portlet lets you perform various administrative tasks relating to server administration, as opposed to administering resources in the portal. Clicking the first tab (the Server tab) of the Admin portlet makes this abundantly clear: you're immediately presented with a graph showing the resources available in the JVM.
The first tab under the Server tab is called Resources. This tab contains the aforementioned graph plus several server wide actions that an administrator can execute. These are:
Garbage collection: You can send in a request to the JVM to begin the garbage collection task.
Clearing caches: You can send in a request to the JVM to clear a single VM cache, the cluster cache, or the database cache.
Reindex: You can send in a request to regenerate all search indexes. This will impact portal performance, so try not to do this except at non-peak times.
Generate Thread Dump: If you are performance testing, you can generate a thread dump which can be examined later to determine if there are any deadlocks and where they might be.
Here you can dynamically modify the log levels for any class hierarchy in the portal. If you have custom code that you have deployed which isn't in the list, you can use the Add Category tab to add it. If you change the log level near the top of the class hierarchy (such as at com.liferay), all the classes under that hierarchy will have their log levels changed. If you are testing something specific, it is much better to be as specific as you can when you change log levels, as by modifying them too high in the hierarchy you can generate a lot more log messages than you probably need.
This tab shows an exhaustive list of system properties for the JVM, as well as many Liferay system properties. This information can be used for debugging purposes or to check the configuration of the currently running portal.
This tab shows an exhaustive list of the portal properties. These properties can be customized as will be seen in the next chapter. If you need to check the current value of a particular property, it can be viewed from this screen without having to shut down the portal or open any properties files.
If you ever need to shut down your Liferay Portal server while users are logged in, you can use the Shutdown tab to inform your logged-in users of the impending shutdown. You can define the number of minutes until the shutdown and a custom message that will be displayed.
Users will see your message at the top of their portal pages for the duration of time you specified. When the time expires, all portal pages will display a message saying the portal has been shut down. At this point, the server will need to be restarted to restore access.
Liferay Portal contains a JSR-170 compliant document repository. This repository allows users to upload documents in many formats into a folder structure that they define.
OpenOffice.org is an open source office suite which is normally run in graphical mode to create documents, but it can be run in "server" mode. When run in server mode, OpenOffice.org can be used to convert documents to and from all of the file types it supports. Liferay's Document Library portlet can make use of this feature to automatically convert documents on the fly.
You would use this tab to tell Liferay how to connect to your running instance of OpenOffice.org. You can install OpenOffice.org on the same server upon which Liferay is running. Once you have it installed, you can start OpenOffice.org in server mode with the following command:
soffice -headless -accept="socket,host=127.0.0.1,port=8100;urp;" -nofirststartwizard
As you can see, the command above specifies that OpenOffice.org will run on port 8100, which is the default port in the Admin portlet. If you can use this port, all you need to do is check the Enabled box, and Liferay will be integrated with OpenOffice.org.
If you have something else running on this port, find a port that is open and specify it both in the command above and on the Admin portlet's OpenOffice.org configuration page. When you are finished, click Save.
Liferay Portal allows you to run more than one portal instance on a single server. Data for each portal instance are kept separate from every other portal instance. All portal data, however, is kept in the same database.
Each portal instance requires its own domain name. Liferay will direct users to the proper portal instance based on this domain name. So before you configure an instance, configure its domain name in your network first. When you're ready to add an instance, click the Add button on the Instances tab.
You'll be prompted for three fields:
Web ID: A general convention is to use the domain name for this. It's a user-generated ID for the instance.
Virtual Host: Put the domain name you configured in your network here. When users are directed to your Liferay server via this domain name, Liferay will then be able to send them to the proper portal instance.
Mail Domain: Enter the domain name for the mail host for this instance. Liferay will use this to send email notifications from the portal.
When you are finished filling out the form, click Save. Now navigate to the portal using your new domain name. You will see that you are brought to what looks like a clean install of Liferay. This is your new portal instance which can now be configured any way you like.
The Plugins tab shows all of the plugins that are currently installed. These are divided into tabs for portlets, themes, layout templates, and web applications. If you want to install a new plugin, click the Install More Portlets button. You will then be brought to the Plugin Installer, where you can browse Liferay's repository of portlets or install your own plugins. The Plugin Installer will be covered in the next chapter.