1. Liferay Help Center
  2. Knowledge Base
  3. How-to

SAML Comprehensive Quick Start Guide for Liferay Portal

Avatar

Justin Choi

  • Updated

This is a comprehensive article that documents the steps for how to set up SAML on Liferay Portal 6.2 EE. In addition, this article covers the different ways that SAML can be implemented and utilized.

SAML (Security Assertion Markup Language) is an XML-based open standard data format for exchanging authentication and authorization data between identity providers (IdP) and service providers (SP). It was developed by OASIS in 2001 (SAML 1.0) with the latest update to the standard released in 2005 (SAML 2.0). It is used for single sign on and single log out. One prime example is Google and Youtube; users with Google and Youtube accounts do not have to sign on a second time.

From a Liferay perspective, SAML 2.0 is available as an EE plugin. The plugin supports two operation modes: identity provider and service provider. The plugin, built on OpenSAML, is platform neutral and is supported by many SaaS applications. For credentials, a Java keystore is used.

Using SAML requires two different IP addresses, or two different virtual hosts, or two different ports. Be careful and please note: If you use localhost for testing purposes, setting different port numbers is allowed as the instances run on separate machines. If the instances are on the same JVM, create different virtual host names in the /etc/hosts file. The examples below will use a combination of different settings as illustrations.

As of March 2015, there has been a major release of the SAML App (2.1.0 for Liferay Portal 6.2).  For a list of the new features that were added, please see the link for LPS-50220.

For Liferay Portal 6.2 EE, navigate the table below to access specific information and steps to implement the different uses of SAML.

Table of Contents

Use Case 1: Integrating Salesforce as SP
Use Case 2: Liferay as both ldP and SP
Use Case 3: User Attributes other than Email Address
Frequently Asked Questions (FAQs)

Resolution

Use Case #1: Liferay as IdP with Salesforce as SP

Using the SAML 2.0 Provider app, Liferay Portal 6.2 is able to execute a Single Sign On (SSO) on to Salesforce. This use case requires the following: Liferay Portal 6.2 EE configured as an Identity Provider (IdP), a separate user other than the admin user, and Salesforce credentials.

Part 1: Configuring Liferay Portal as the IdP

*Complete fields should match image below.
01.png

  1. Start Liferay Portal 6.2 and deploy the latest SAML 2.0 Provider EE plugin.
  2. When signing in, DO NOT flag the Remember Me checkbox. Doing so will invalidate the entire test.
  3. Navigate to the Admin → Control Panel.
  4. Click SAML Admin.
  5. Enter the following:
    • SAML Role (Required): Identity Provider.
    • Entity ID (Required): samlidp
  6. Click Save.
  7. In the Certificate and Private Key section, enter the following:
    • Common Name (Required): Liferay Support
    • Organization (Required): Liferay
    • Organization Unit: (leave blank)
    • Locality: (leave blank)
    • State: (leave blank)
    • Country: USA
    • Validity (days) (Required): 356
    • Key Algorithm: RSA
    • Key Length (Bits): 2048
    • Key Password (Required): samlidp
  8. Click Save
  9. Check the Enabled check box and click Save.
  10. Click Download Certificate.
  11. Save the samlidp.pem file.

Next, create a user that has the same credentials to validate against Salesforce.

*Note: This format is needed because Salesforce requires a password to have at least 8 characters with a number.

  1. Click Users at the top navigation bar.
  2. Click Add → User
  3. Enter the following:
    • Screen Name: test1
    • Email Address: (a valid email address)
    • First Name: Liferay
    • Last Name: Support
  4. Click Save.
  5. Click Password in the right pane.
  6. Enter the following:
    • New Password: samlidp1
    • Enter Again: samlidp1

Next, grant administrator roles to this user.

  1. Click Roles in the right pane.
  2. Click the Select button.
  3. Click Choose next to Administrator.
  4. Remove the Power User role.
  5. Click Save.

The downloaded sampl.pem is necessary to provide the correct metadata information to the Salesforce SP. The next steps are on how to configure Salesforce as the SP.

  1. Navigate to http://developer.force.com
  2. Create an account using the same valid email address. This will also serve as the user account. Use samlidp1 as your password for your Salesforce account.
  3. Click Setup
  4. Click Security Controls → Single Sign on Settings .
  5. Enter the following:
    • Name: samlsp
    • Issuer: samlidp
    • Entity ID: https://saml.salesforce.com
    • Identity Provider Certificate: Upload the samlidp.pem file.
    • Identity Provider Login URL: http://localhost:8080/c/portal/saml/sso
    • Identity Provider Logout URL: https:http://localhost:8080/c/portal/logout
    • SAML Identity Type: Click the Assertion contains User’s salesforce.com username radio button.
    • SAML Identity Location: Click the Identity is in the NameIdentifier element of the Subject statement radio button.

    *Completed fields should match the image below:
    02.png

  6. Click Save.
  7. Click Download Metadata and save the XML file.
  8. Rename the XML file as salesforce-metadata.xml.
  9. Log out of Salesforce.

The next steps complete the setup in Liferay Portal 6.2.

  1. In Liferay Portal, navigate to Control Panel → SAML Admin.
  2. Click the Service Provider Connections tab.
  3. Click the Add Service Provider button.
  4. Enter the following:
    • Name: salesforce
    • Entity ID:https://saml.salesforce.com
    • Check the Enabled checkbox.
    • Click Upload Metadata XML.
    • Upload the salesforce-meta.xml file.
    • Select Unspecified from the Name Identifier Format drop down.
    • Enter static: {email address used to sign up for Salesforce} in the Name Identifier Attribute Name (e.g. static:static:jane.smith@liferay.com)
    • Check the Attributes Enabled box
    • Click Save.
  5. Verify that the new Salesforce SP has been created.
  6. Click Sign out.
  7. Sign in again as the user created for Salesforce. Do not flag remember me when signing in.

Execute the SSO/SLO

To test the SSO with Salesforce, it is best if you create a special site page using the Link to URL type. You can use the default Liferay home site.

  1. Navigate to the home site.
  2. Click Add → Page .
  3. Give the page a name: Salesforce
  4. Click the Link to URL radio button to change the page type. Note that this page cannot be the first page.
  5. In the URL field, enter: http://localhost:8080/c/portal/saml/sso?entityId=https://saml.salesforce.com
    where localhost:8080 stands in for the local web address.
  6. Click the Add Page button.
  7. Verify that a new page has been created.
  8. Click on the Salesforce page. It should take you directly to the salesforce.com site without having to reauthenticate.

Use Case #2: Liferay as both IdP and SP

Liferay Portal 6.2 can be configure as both an IdP and a SP; this requires two separate instances (i.e. two bundles) running concurrently. Users can change either the IP address that two bundles are using or the port numbers, depending on how their servers are set up. For illustration purposes in this section, the presumption is that the two instances are running on separate physical machines.

To configure the IdP, use the same steps listed in Use Case 1. After finishing the initial configuration, there are several additional steps.

  1. In the Control Panel → SAML Admin, click the Identity Provider tab.
  2. Check the Sign Metadata and Authn Request Signature Required checkboxes.
  3. Click Save.

At this point, the IdP instance is ready to go. Set up the second portal instance using the steps below. (Users should remember which IP address corresponds the correct instance. Many of the steps are similar except for the SAML Role and Entity ID.)

  1. Start the second portal instance.
  2. Remember when signing in, do NOT flag the Remember Me checkbox. Doing so will invalidate the entire test.
  3. Navigate to the Control Panel.
  4. Click SAML Admin.
  5. Enter the following:
    • SAML Role: Service Provider
    • Entity ID (Required): samlsp
  6. Click Save.
  7. In the Certificate and Private Key section, enter the following:
    • Common Name: Liferay Support
    • Organization: Liferay
    • Organization Unit: {leave blank}
    • Locality: {leave blank}
    • State: {leave blank}
    • Country: USA
    • Validity (days)(Required): 356
    • Key Algorithm: RSA
    • Key Length (Bits): 2048
    • Key Password (Required): samlsp
  8. Click Save.

At this point, the SP instance needs to be connected to the IdP. To do, the SP must recognize the IdP's metadata.

  1. Click the Identity Provider Connection tab.
  2. Enter the following:
    • Name (Required): samlidp
    • Entity ID: samlidp
    • Metadata URL: http://{IdP's IP Address or virtual host name}:{port number}/c/portal/saml/metadata
      (e.g. http://localhost:8080/c/portal/saml/metadata)

    It is important to emphasize that the IdP and the SP should be on separate IP Addresses (or virtual hosts specified in the etc/hosts file).

  3. Select Email Address from the Name Identifier Format drop down menu.
  4. Click Save.
  5. Now enable the SP instance. Click the General tab.
  6. Check the Enabled checkbox.
  7. Click the Save button.

Return to the portal instance configured as the IdP.

  1. Navigate to the Control Panel → SAML Admin
  2. Click the Service Provider Connections
  3. Click the Add Service Provider button.
  4. Enter the following:
    • Name: samlsp
    • Entity ID: samlsp
    • Check the Enabled checkbox.
    • Assertion Lifetime: 1800
    • Metadata URL:http://{SP's host name}:{port number}/c/portal/saml/metadata
      (e.g. http://localhost:9080/c/portal/saml/metadata)
    • Name Identifier Format: Email Address (This is for users who are using email addresses to authenticate.)
    • Name Identifier Attribute Name: emailAddress (one word)
  5. Click Save.

Testing SSO and SLO

The following steps demonstrate Single Sign On (SSO) and Single Log Out (SLO). Both the IdP and the SP can initiate SSO and SLO.

The next section deals with IdP initiated SSO and SLO.

  1. Go to the Liferay Portal Instance that has been configured as the IdP.
  2. In the browser URL, enter the following: http://{IdP virtual host name}:{port number}/c/portal/saml/sso?entityId=samlsp&RelayState=http://{SP host name}:{port number}

    *Remember to put the correct IP or Port Number in the respective IdP and SP instances.

    **An IP address, a virtual host name, or a URL are valid as a host name; for example: http://192.168.234.119:8080 or see the Salesforce example.

    http://samlidp:8080/c/portal/saml/sso?entityId=samlsp&RelayState=http://samlsp:9080

  3. Watch the site redirect from the IdP to the SP. The SP site will be signed in without having to log in a second time. The authentication works as long as the same user with the same credentials exist in both instances.

To test IdP initiated SLO:

  1. Open a new browser tab with the IdP (https://localhost:8080).
  2. Verify that the user is already signed in.
  3. Click Sign Out in the IdP to trigger the SLO.
  4. Navigate to the SP's browser window.
  5. Refresh the page. The second instance will have been signed out as well. This works as long as Remember Me has not been checked.

The following steps demonstrate SP initiated SSO and SLO.

  1. Navigate to the SP instance.
  2. Click the Sign In link at the top right. Do NOT use the Sign In portlet.
  3. In the browser URL, it will redirect to the IdP.
  4. Enter the credentials.
  5. After signing in, it will stay on the SP's page.
  6. In a new browser tab, navigate to the IdP. It should be already signed in. If not, refresh the page.
  7. In the SP instance, click Sign Out.
  8. In the IdP instance, refresh the page again. It should be signed out as well.

A variant of this use case is to have multiple Service Providers. In the latest Liferay Portal versions, simply repeat the steps on configuring a Service Provider for every additional instance. Currently, Liferay supports only one Identity Provider to multiple Service Providers. Future versions will support multiple Identity Providers to multiple Service Providers.

Use Case #3: User Attributes Other Than Email Address

Users can use other attributes beside email addresses to authenticate. For example, the use case involving Salesforce integration requires users to change the Name Identifier to Unspecified and enter other values (e.g. static:${salesforce-user-name} or static:${user-email-address}.

Another example where other attributes is integrating with Shibboleth. There are use cases where the IdP is ADFS or Shibboleth and the SP is Liferay. Depending on how the ADFS is configured, other attributes such as first or last name can be used. Shibboleth can use screen names to authenticate. In the Liferay Portal instance configured as the SP, change the Name Identifier Format from Email Address to Unspecified.

Frequently Asked Questions (FAQs)

What if an IdP does not support metadata downloading? Does Liferay SP support installing a certificate (similar to Salesforce)?

SAML Metadata XML must be provided. It can be provided either through url or file. If the IdP does not support SAML metadata, then the XML file must be manually created.

When using Liferay as an IdP, can I add a Liferay expando attribute value as a customized SAML assertion attribute value? Is it possible to add a SAML assertion attribute "Customer Type" and when this subscriber is provisioned to SP, an expando value to the "Customer Type" attribute can be assigned?

Yes. This method is viable.

There is a NullPointerException in the logs and an error on the page when trying to access metadata.

See the resolution, SAML Plugin Throws NPE When Trying to Access Metadata.

Users are redirected to the wrong logout page.

It is possible that the "Default Log Out Page" has already been set in the Portal Settings. Go to the Control Panel → Portal Settings and verify that no value exists in the Default Logout Page field.

03.png

What are session timeout and assertion lifetime? How are they different?

Session timeout refers to how long the SAML IdP will remain connected to the SP. In the context of Liferay Portal, ensure that the SAML session timeout is shorter than the portal's or else SLO will not work. If the session ends due to user inactivity, users will have to re-authenticate.

Assertion lifetime refers to how long the assertion between IdP and SP is valid. Assertions can expire or otherwise not recognized if the server times are out of sync. Usually, this is measured in seconds. To fix this, adjust the clock skew feature accordingly.

What is the logic of using SAML metadata file or SAML metadata URL?

The SAML 2.0 Provider EE plugin supports using either a URL to a SAML IdP metadata file or an actual (uploaded) SAML metadata XML file. The value entered in the Metadata URL field will only be persisted to the database when there is one entered metadata URL and there is no specified metadata XML file. Otherwise, the portal keeps the original metadata URL in the database. This behavior ensures that once a metadata URL has been specified, there will always be a metadata URL saved in the database. This way, if a portal administrator forgets the previously entered metadata URL or its format, he or she can simply look at the displayed metadata URL and either choose to modify the displayed metadata URL or to overwrite the previously saved metadata URL by specifying a metadata XML file.

Currently, the SAML 2.0 Provider EE plugin does not provide a way to "clear" the SAML IdP metadata URL or metadata XML file fields using the Control Panel UI. If you really need to clear these fields, it's possible (but not recommended) to delete the contents of the SAML IdP metadata URL and metadata XML file columns of the SamlSpIdpConnection table of Liferay portal's database. (A way to "clear" the SAML IdP metadata URL or metadata XML file fields using the Control Panel UI has been requested as a feature. You can track the issue progress here: LPS-59199.

What changes do I need in order to automatically provision users, when I SSO to Salesforce? I have already configured Salesforce from the following link: https://login.salesforce.com/help/doc/en/sso_saml.htm

At this moment, we do not have any reference configurations available. Testing for automatic provisioning has only occurred via Liferay SAML SP.

To provision with Liferay SAML SP, please add the following lines:

	saml.idp.metadata.attributes.enabled[liferaysamlspdemo]=true
	saml.idp.metadata.attribute.names[liferaysamlspdemo]=screenName,firstName,lastName,emailAddress,uuid

The liferaysamlspdemo is the entity ID of the SP.

Additional Information

Was this article helpful?
3 out of 3 found this helpful