Quick Start Guide to SAML on Liferay Portal 6.1 EE GA3

This article is a legacy article. It applies to previous versions of the Liferay product. While the article is no longer maintained, the information may still be applicable. 

If you are working with a Liferay Portal version prior to 6.1 GA3, you can read the article here.

SAML (Security Assertion Markup Language) is an XML-based open standard data format for exchanging authentication and authorization data between identity providers and service providers. 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.

One major advantage of the SAML portlet in 6.1 EE GA3 is that configuring the portlet can be done in the portal's Control Panel GUI. The GUI will change slightly depending on whether the Liferay instance is designated as the Identity Provider or the Service Provider.

The following abbreviations will be used: Identity Provider is often written as IdP and Service Provider as SP.

As of March, 2015, there has been a major release of the SAML App (2.1.0 for Liferay Portal 6.2 and beyond and 1.0.3 for Liferay Portal 6.1GA2). For a list of the new features that were added, please see the following link.

Table of Contents


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

This first section sets up a Liferay bundle as an IdP.

  1. Start Liferay Portal.
  2. When signing in, do not flag the Remember Me check box. Doing so will invalidate the entire test.
  3. Navigate to the Control Panel
  4. Click SAML Admin
  5. Enter the following:
    • SAML Role: Identity Provider
    • Entity ID (Required): samlidp
  6. Click Save
  7. In the CertificateandPrivateKey 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): samlidp
  8. Click Save
  9. Check the Enabled check box.
  10. Click the Download Certificate
  11. Save the saml.pem file.
  12. Click Users and Organizations
  13. Click Add > User
  14. Enter the following:
    • Screen Name: test1
    • Email Address: {valid email address}
    • First Name: Liferay
    • Last Name: Support
  15. Click Save
  16. Click Password
  17. Enter the following:
    • New Password: test
    • Enter Again: test
  18. Click Roles
  19. Set user test1 as Administrator

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

  1. Navigate to http://developer.force.com
  2. Create an account using the same valid email address in step 14. This will also serve as the user account.
  3. Once signed in, click Setup.
  4. Click Security Controls > Single Sign-on Settings
  5. Click the Edit button.
  6. Click the Save button.
  7. Click the New button.
  8. Enter the following:
    • Name: samlsp
    • Issuer: samlidp
    • Entity ID: https://saml.salesforce.com
    • Identity Provider Certificate: Upload the saml.pem
    • Identity Provider Login URL: http://localhost:8080/c/portal/saml/sso
    • Identity Provider Logout URL: http://localhost:8080/c/portal/logout
    • SAML User ID Type: Assertion contains User's salesforce.com username
    • SAML User ID Location: User ID is in the NameIdentifier element of the Subject statement
  9. Click the Save button
  10. Click the Download Metadata button and save the XML file.
  11. Rename the XML file as salesforce-metadata.xml.
  12. Log out of Salesforce.

The next few steps finishes the setup.

  1. In Liferay Portal, continuing on the Control Panel> SAML Admin, click Service Provider Connections.
  2. Click the Add Service Provider button.
  3. Enter the following:
    • Name: salesforce
    • Entity ID: https://saml.salesforce.com
    • Enabled: checked
    • Assertion Lifetime: 1800
  4. Click Upload Metadata XML
  5. Upload the salesforce-metadata.xml
  6. Select Unspecified from the Name Identifier Format drop-down menu.
  7. Enter static:${email address used to sign up for Salesforce} in the Name Identifier Attribute Name field
  8. Check the Attributes Enabled check box.
  9. Click the Save button.

Execute SSO/SLO.

  1. In Liferay Portal, click Sites.
  2. Click Liferay > Site Pages.
  3. Click Add Page.
  4. Enter the following:
    • Name: Salesforce
    • Type: URL
  5. Click Add
  6. Click the Salesforce Page.
  7. Enter in the URL field: http://localhost:8080/c/portal/saml/sso?entityId=https://saml.salesforce.com
  8. Click Go to > Liferay
  9. Click on the Salesforce page. It should redirect to a Sign in Portlet.
  10. Sign in with the email address used above. It should redirect to the Salesforce page.

Use Case #2: Liferay as both IdP and SP

Configuring Liferay as both IdP and SP, 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 set up the IdP, users can follow the first 19 steps in the first section above.

To set up the second Liferay instance as the SP, this requires going back and forth between the IdP and the SP. Users should remember which IP address corresponds the correct instance.

  1. Start Liferay Portal.
  2. When signing in, do not flag the Remember Me check box. 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 CertificateandPrivateKey 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
  9. Click the Identity Provider Connection tab.
  10. Enter the following:
    • Name: samlidp
    • Entity ID: samlidp
    • Metadata URL: http://{IdP IP Address}:8080/c/portal/saml/metadata
    • Name Identifier Format: Email Address
  11. Click the Save button.
  12. Click the General tab.
  13. Check the Enabled check box.
  14. In Liferay Portal configured as the Identity Provider, continue at the Control Panel> SAML Admin, click Service Provider Connections.
  15. Click the Add Service Provider button.
  16. Enter the following:
    • Name: samlsp
    • Entity ID: samlsp
    • Enabled: checked
    • Assertion Lifetime: 1800
    • Metadata URL: http://{SP IP Address}:8080/c/portal/saml/metadata
    • Name Identifier Format: Email Address (This is for users who are using email addresses to authenticate. Select the appropriate one.)
    • Name Identifier Attribute Name: emailAddress
  17. Click the Save button.

The following steps demonstrate Single Sign On (SS0) and Single Log Out (SLO). Both the IdP and the SP can initiate SSO and SLO.
The next section deal 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 IP Address}:8080/c/portal/saml/sso?entityId=samlsp&RelayState=http://{SP IP Address}:8080
  3. Watch the site redirect from the IdP to the SP.
  4. Open a new browser window.
  5. Navigate to the first instance at http://{IP Address}:8080
  6. Click Sign Out. This will trigger the process.
  7. Navigate to the SP's browser window. 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 SPinitiatedSSOandSLO.

  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 window, navigate to the IdP. It should be signed in already. 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.

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 name or last name can be used. Shibboleth can use screen names to authenticate. In the SP, change the Name Identifier Format from Email Address to Unspecified.

Frequently Asked Questions (FAQs):

  1. 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.

  2. 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.

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

    See the resolution here.

  4. 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 values exist in the Default Logout Page field.

  5. 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.

  6. 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'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.

0 人中有 0 人觉得有帮助