Deploying and Managing SAML on Liferay DXP

This troubleshooting guide is meant to supplement the existing SAML documentation. The information in this guide explains in more detail to demonstrate the most common use cases.

 

Table of Contents

  1. Introduction
  2. Use Case #1: Salesforce Integration
  3. Use Case #2: Liferay as Both IdP and SP
  4. Use Case #3: User Attributes Other Than Email Address
  5. Use Case #4: Connecting Through a Secure Proxy Connection
  6. Use Case #5: SAML in a Clustered Environment
  7. Disabling SAML
  8. Troubleshooting

Introduction
To reiterate, Liferay SAML offers two different configurations: as an Identity Provider (abbrev. as IdP) and as a Service Provider (abbrev. as SP). Administrators often connect Liferay SAML in either configuration to third party technologies such as an ADFS, another SSO/SLO protocol like Shibboleth, or to Salesforce. Liferay SAML plugin version 3.x is specific to Liferay DXP. Please see the release notes or the change log to see more details about the changes in the latest SAML plugin version 3.x.

Important note 1: Using SAML requires two different IP addresses, or two different virtual hosts, or two different ports. In the Windows environment, admins can go to the etc/hosts file and create several virtual hosts. The examples below will use a combination of different settings as illustrations.

Resolution

Use case #1: Salesforce Integration: Salesforce as a SP.
Administrators can execute a SSO request to Salesforce. To do so, Liferay DXP must be configured as an IdP (see configuring Liferay DXP with SAML as an IdP).

  1. Start up Liferay DXP with the SAML app deployed.
  2. Navigate to Control Panel > Configuration > SAML Admin
  3. Verify that the IdP enabled check box is flagged.
  4. Click Download Certificate (Certificate and Private Key section).
    06_-_samldxpidp.PNG
    Save the .pem file. This file is needed on Salesforce to generate the Salesforce metadata.xml.
  5. Navigate to the Control Panel > Users.
  6. Create a new user with the same email address as the one used to sign into Salesforce. Do not use the default test@liferay.com.
    1. First Name: Salesforce
    2. Last Name: Admin
    3. Password: samlidp1
  7. Grant full Administrator roles to this new user.

The next series of steps is to generate the metadata file from Salesforce.

  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 the password for the Salesforce account.
  3. After signing in, go to salesforce.com, log in and then click Setup
  4. Click Security Controls > Single Sign on Settings
  5. Click Edit and check the SAML Enabled checkbox.
  6. Click Save
  7. Click New
  8. 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: http://localhost:8080/c/portal/logout
    • SAML Identity Type: "Assertion contains User's salesforce.com username"
    • SAML Identity Location: "Identity is in the NameIdentifier element of the Subject statement"
    07_-_samldxpsalesforce__1_.png
  9. Click the Save button.
  10. Download the metadata xml file and rename it salesforce-metadata.xml.

The next steps complete the set up:

  1. In Liferay DXP, navigate to the Control Panel > Configuration >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-metadata.xml
    • Select Unspecified from the Name Identifier Format drop down
    • Enter static: {email address used to sign up for Salesforce without the braces of course} in the Name Identifier Attribute Name field
    • Check the Attributes Enabled box
  5. Click the Save button

Execute SSO to Salesforce

  1. In Liferay DXP, Click Menu > Liferay DXP site
  2. Make sure that the user are signed in as the user created above (e.g Salesforce Admin). If not, sign out and sign in again with the correct credentials.
  3. Click Navigation
  4. Click the three dot icon next to Public Pages > Add Public Page
  5. Enter Salesforce in the Name field.
  6. Select Link to URL from the Type dropdown.
  7. Enter in the URL field: http://localhost:8080/c/portal/saml/sso?entityId=https://saml.salesforce.com
  8. Click the Add Page button
  9. The system will redirect back to the main page. Click on the Salesforce page. It should redirect to the salesforce.com site without having to reauthenticate.

Use case #2: Liferay as Both IdP and SP

Add a SP to the IdP instance.

In this use case, Liferay is able to serve as both an IdP and a SP. Furthermore, users can have multiple SPs. Every SP must be added individually to the IdP. Follow the steps below to add a SP to the IdP.

  1. Ensure that every SP instance has been started. This is important because there will be an error message that the endpoint is invalid.
  2. Ensure that the user is sign in without "Remember Me" checked.
  3. Navigate to the Control Panel > Configuration > SAML Admin.
  4. Click the Service Provider Connections tab.
  5. Click Add Service Provider.
  6. Enter the following:
    • Name: samlsp
    • Entity ID: samlsp
    • Enabled: checked
    • Metadata URL: http://www.alpha.com:9080/c/portal/saml/metadata
    • Name Identifier Format: Email Address
    • Name Identifier Attribute Name: emailAddress
    08_-_samldxpsp__1_.png
  7. Click the Save button.
  8. Repeat these for every unique SP to be added.

Once all the SPs have been added, Liferay SAML offers two different ways to execute SSO/SLO.

IdP-initiated SSO/SLO

  1. Follow the steps to configure the first Liferay DXP bundle as an IdP. The example SP's virtual host name is www.alpha.com:9080
  2. Ensure that the user is sign in without "Remember Me" checked.
  3. In the IdP browser URL, enter the following:
    http://localhost:8080/c/portal/saml/sso?entityId=samlsp&RelayState=http://www.alpha.com:9080
  4. Watch the IdP redirecting to the SP. If the same users with the same email address are present on both instances, it will authenticate and show the SP. If users are found in only one instance whether it is an ADFS or a Liferay instance but not the other, authentication will fail. SAML can authenticate across major portal versions, that is, the IdP can be Portal 6.1 EE GA3 or Liferay Portal 6.2 EE and the SP can be Portal 6.2. EE GA1 or Liferay DXP. For testing purposes, it is obvious if the authentication succeeds or fails if the IdP and SP are different portal versions.
  5. On the SP, there is no need to sign in a separate time.
  6. Open a new browser window showing the IdP. Click Sign Out.
  7. There is a javascript that runs to execute SLO on all instances. Once the IdP has been logged out, go to the SP instance. Refresh the browser window on the SP instance.
  8. The SP will have signed out as well.

SP-initiated SSO/SLO

  1. In the SP browser window on www.able.com:9080, click the Sign In link at the top right. Do not use the Sign In portlet.
  2. The browser will redirect to the IdP instance's Sign In portlet.
  3. Sign In. Do not check "Remember Me".
  4. The system will redirect back to the SP.
  5. Open a new browser window to the IdP. In this case: localhost:8080.
  6. The IdP will already have been signed in.
  7. Go to the SP instance.
  8. Click Sign Out.
  9. Go to the IdP instance. Refresh the browser window. The IdP will be signed out.

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.


Use Case #4: Connecting through a Secure Proxy Connection

Often, in a typical DXP 7.0 environment, there are more than just the two IdP and SP servers communicating with each other. The environment might also have a load balancer server (this is very strongly suggested if not actually required) in a clustered environment and a web server to handle web requests. For additional security, administrators will use the https protocol instead of the default http. The SAML plugin deployed on DXP 7.0 will still be able to execute both an IdP initiated SSO and a SP initiated SSO as long as the Assertion process has been configured to redirect from HTTP to HTTPS.

While each application server is different in how it enables and configures redirecting to secure ports 443, there is only one change required in DXP 7.0's portal-ext.properties:

portal.instance.protocol=https
web.server.protocol=https


Once these properties have been added to the portal-ext.properties file, the portal now recognizes the HTTPS message being sent and then sends it successfully through the SAML Assertion process.

Lastly, administrators must ensure that SSL Required is activated in the SAML Admin Control Panel. To do so:

  1. Navigate to the Control Panel > Configuration > SAML Admin
  2. If this instance of DXP 7.0 is configured as a SAML IdP server, then check the SSL Required check box in the Identity Provider tab.
    09_-_samldxpidp.PNG
  3. The same is true for DXP 7.0 instances configured as a SAML SP server. Check the SSL Required check box in the Service Provider tab.
    10_-_samldxpsp__1_.png
  4. Click Save.

Use Case #5: SAML in a Clustered Environment

Refer to the "Setting Up SAML in a Clustered Environment" section of this Official Documentation.

Disabling SAML

There are several ways to disable SAML. Each way is slightly different and reflective of different situations.

Use case 1: Through the UI
Assume that DXP 7.0 has been configured as the IdP. The easiest way is through the Control Panel UI and will disable the SSO/SLO functionality for this instance. It will be necessary to disable the other instances running with SAML enabled.

  1. Sign in as the system administrator.
  2. Navigate to the Control Panel → Configuration → SAML Admin.
  3. Uncheck the Enabled checkbox on the General tab.
    11_-_samldxpdisable__1_.png
  4. Click Save.

At this point, the Liferay SAML app is still deployed on the platform but users will now sign in without SSO.

Use case 2: Adjusting the URL
In this scenario, assume that DXP 7.0 has been configured as the SP. As the Service Provider, the platform is connected to another instance configured as the IdP or an active directory like ADFS. Because the default guest site does not have a Sign In application, users are forced to sign in using SAML. To access the platform by bypassing SSO, it is possible to do so by modifying the URL.

Append the following: ?p_p_id=com_liferay_login_web_portlet_LoginPortlet&p_p_lifecycle=0&p_p_state=maximized&p_p_mode=view&saveLastPath=false&_com_liferay_login_web_portlet_LoginPortlet_mvcRenderCommandName=%2Flogin%2Flogin to the end of the URL.

Example: http://www.able.com:8080?p_p_id=com_liferay_login_web_portlet_LoginPortlet&p_p_lifecycle=0&p_p_state=maximized&p_p_mode=view&saveLastPath=false&_com_liferay_login_web_portlet_LoginPortlet_mvcRenderCommandName=%2Flogin%2Flogin

Once signed in, system administrators can deactivate the Liferay SAML Provider the same way as the first use case. As noted above, the Sign In application bypasses the SAML authentication functionality and was invoked using that extended URL. If the landing page is not on /web/guest/home, then add the Sign In application to the page.

12_-samldxpdisable__1_.png

The picture demonstrates the addition of the Sign In app to the mock-up page which bypasses SAML.

Use case 3: Using an OSGi config File
This use case disables SAML from the back end. Because of the implementation of OSGi in DXP 7.0, there is less risk and fewer runtime penalties. This use case requires two parts: 1) finding the value in the configuration_ table in the database and 2) creating a config file.

  1. In whatever database, look up the configuration_ table (e.g. in MySQL 5.7 Command Line Client, select * from configuration_ \G;. Note: the \G is optional; it makes the values easier to read).
  2. Look for com.liferay.saml.runtime.configuration.SamlProviderConfiguration.xxxxxxx.xxxx.xxxx.x (the numbered part here will look different in each case).
  3. In the /osgi/configs folder, create a file named code>com.liferay.saml.runtime.configuration.SamlProviderConfiguration-xxxxxxx.xxxx.xxxx.xxxx.config.
    • Important note 1: It must contain the ID string.
    • Important note 2: It must use a hyphen to separate the hash value from ...SAMLProvider Configuration... (e.g. com.liferay.saml.runtime.configuration.SamlProviderConfiguration-bda43632-74fc-458a-9bb7-5f4c4e81fb96).
  4. Inside that file, enter the following: saml.enabled=false.

Once the steps are completed, the Liferay SAML Provider has been disabled and will not be enabled again should the instance have to be restarted. To re-enable SAML, delete this file or change the values back to saml.enabled=true



Troubleshooting

SAML issues are often configuration issues. Users might have skipped a step or entered a value incorrectly. Nevertheless, some of the more commonly found questions are adressed here.

1. I cannot execute SLO on either instance!
Usually, this is caused by one or more of the following scenarios:

  1. Users cannot flag "Remember Me in the Sign In portlet.
  2. SAML timeout must be shorter than Liferay timeout. In this second scenario, if the SAML timeout is longer than the Liferay timeout, the system will act as if "Remember Me" has been checked. The solution is to set the SAML timeout to 180 seconds.
  3. Users defined something other than slo_redirect in their portal settings. Navigate to the Control Panel > Portal Settings and change the settings to c/portal/saml/slo_redirect.

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

Answer: 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.

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

4. Can I upload my own custom keystore?

The latest version of the Liferay SAML 2.0 Provider allows administrators to add keystore (.jks) file instead of using the default version. Download the Liferay SAML 2.0 Provider version 3.1.0 from Liferay Marketplace. This version requires DXP 7.0 Fix Pack DE-32 or higher. Note that the older Liferay SAML 2.0 Provider version 3.0.0 does not have this feature.

Once the app has been deployed, configure the platform using the following steps:

  1. Navigate to the Control Panel → Configuration → System Settings.
  2. Click on the Foundation tab.
  3. Search for SAML KeyStoreManager Implementation Configuration.
  4. Select Filesystem Keystore Manager from the dropdown and click Update.
    13_-_samldxpjks__1_.png
  5. If the previous search results are still showing, click SAML Configuration. Otherwise, search for it.
  6. In the SAML Configuration page, enter the path to the new keystore. By default, the keystore is stored in ${liferay.home}/data/keystore.jks.
    14_-_samldxpjks.png
  7. Click Save.
  8. At this point, the platform will recognize the new keystore file.

5. Where are the Liferay SAML configurations stored in the database?

Liferay SAML configurations are stored in the database table called configuration_ on DXP 7.0 (and 7.1 as well) as of the 3.1.0 version of the app (see further information here). If you want to inspect any database table, consult your database's manual on how to retrieve data stored in the respective tables. For example, in a MySQL command console, enter select * from configuration_ \G; (where \G displays the results vertically and easier to read).

It will look something like this:

configurationId: com.liferay.portal.security.auth.verifier.internal.basic.auth.header.module.configuration.BasicAuthHeaderAuthVerifierConfiguration.f0d64ebc-896b-4606-b907-2edba57850ce
     dictionary: enabled="true"
felix.fileinstall.filename="com.liferay.portal.security.auth.verifier.internal.basic.auth.header.module.configuration.BasicAuthHeaderAuthVerifierConfiguration-default.cfg"
service.factoryPid="com.liferay.portal.security.auth.verifier.internal.basic.auth.header.module.configuration.BasicAuthHeaderAuthVerifierConfiguration"
service.pid="com.liferay.portal.security.auth.verifier.internal.basic.auth.header.module.configuration.BasicAuthHeaderAuthVerifierConfiguration.f0d64ebc-896b-4606-b907-2edba57850ce"
urlsExcludes="/api/liferay*"
urlsIncludes="/api/*,/xmlrpc*"

Keep scrolling down until you see the actual configuration values stored. In this example, this Liferay DXP instance has been configured as an IdP; its entityId is samlidp, the keystore password is password, and SSL is not required:

configurationId: com.liferay.saml.runtime.configuration.SamlProviderConfiguration.338a3905-8765-4701-872b-7352cf975341
     dictionary: companyId=L"20115"
saml.enabled="true"
saml.entity.id="samlidp"
saml.idp.authn.request.signature.required="true"
saml.idp.session.maximum.age="0"
saml.idp.session.timeout="0"
saml.keystore.credential.password="password"
saml.role="idp"
saml.sign.metadata="true"
saml.ssl.required="false"
service.bundleLocation="?"
service.factoryPid="com.liferay.saml.runtime.configuration.SamlProviderConfiguration"
service.pid="com.liferay.saml.runtime.configuration.SamlProviderConfiguration.338a3905-8765-4701-872b-7352cf975341"

The following configurationIds are connected to the SAML app:

com.liferay.saml.opensaml.integration.internal.transport.configuration.HttpClientFactoryConfiguration
com.liferay.saml.runtime.configuration.SamlProviderConfiguration
com.liferay.saml.runtime.configuration.SamlConfiguration

Important Note: Customers who have deployed SAML on legacy Liferay Portal 6.2 must pay attention to this change. In the past, this was stored in the table called PortalPreferences.

Additional Information

To refer to previous versions, please see SAML Comprehensive Quick Start Guide for Liferay Portal.

Este artigo foi útil?
Utilizadores que acharam útil: 0 de 0