1. Liferay Help Center
  2. 知识库
  3. How-to

Deploying and Managing SAML on Liferay DXP

Avatar

Liferay Support

  • 更新

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. The Liferay Connector to SAML 2.0 plugin should be deployed onto Liferay DXP 7.0 through Liferay DXP 7.2 using the appropriate version. Liferay DXP 7.3 and future releases of the product contain the Connector plugin as part of their core release. Updates to the plugin for DXP 7.3+ will be included in fixpacks. Please see the release notes or the change log to see more details about changes made to the Liferay Connector to SAML 2.0 plugin.

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).
    Certificate_and_Private_Key.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

The following use case demonstrates how to configure two Liferay DXP bundles for SAML authentication with one functioning as the Service Provider (SP) and the second as the Identity Provider (IdP). 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.

Existing documentation for Setting up Liferay as a SAML Identity Provider can be found on learn.liferay.com via the embedded links.

Due to changes implemented in Liferay DXP if the Identity Provider for the following steps is on the same machine as the Service Provider, the Identity Provider needs to be accessible via a distinct domain name in order for SLO to work as expected. As this is a Proof of Concept the following steps incorporate this distinct domain name for the Identity Provider. 

 

Configuring a Liferay DXP bundle as the SP:

  1. Sign in as the Administrator
  2. Navigate to the Open Menu icon -> Control Panel > Security > SAML Admin.
  3. On the General tab:
    • Select - SAML Role: Service Provider
    • Enter - Entity Id: samlsp
  4. Click On Save
  5. Under Certificate and Private Key, click on Create Certificate
    • Common Name: Joe Bloggs
    • Organization: Liferay
    • Organization Unit: Liferay Inc
    • Locality: Diamond Bar
    • State: CA
    • Country: USA
    • Validity (days): 356
    • Key Algorithm: RSA
    • Key Length (Bits): 2048
    • Key Password: liferaysp
  6. Check the box next to Enabled and click on Save

Configuring a Liferay DPX bundle as the IdP:

  1. Sign in as the Administrator
  2. Configure the bundle to use a virtual host of liferaytest.com, configure the local environment’s hosts file to make this domain viable.
  3. Navigate to the Open Menu icon -> Control Panel > Security > SAML Admin.
  4. On the General tab:
    • Select - SAML Role: Identity Provider
    • Enter - Entity Id: samlidp
  5. Click On Save
  6. Under Certificate and Private Key, click on Create Certificate
    • Common Name: Joe Bloggs
    • Organization: Liferay
    • Organization Unit: Liferay Inc
    • Locality: Diamond Bar
    • State: CA
    • Country: USA
    • Validity (days): 356
    • Key Algorithm: RSA
    • Key Length (Bits): 2048
    • Key Password: liferayidp
  7. On the General tab click the box next to Enabled and then click on Save
  8. Select the Service Provider Connections tab then Add Service Provider
    • Name: samlsp
    • Entity Id: samlsp
    • Enabled: Checked
    • Metadata URL: http://localhost:8080/c/portal/saml/metadata
    • Name Identifier Format: Email Address
    • Name Identifier Attribute Name: emailAddress
  9. Click on Save, you should return to the Service Provider Connections tab if the configurations are saved successfully. 

Return to the Service Provider Liferay DXP bundle:

  1. Sign in as the Administrator if the account was signed out
  2. Return to the SAML Admin menu
  3. Select the Identity Provider Connections then click on Add Identity Provider
    • Name: samlidp
    • Entity ID: samlidp
    • Enabled: Checked
    • Metadata URL: http://liferaytest.com:9080/c/portal/saml/metadata
    • Name Identifier Format: Email Address
  4. Click on Save

Testing the SAML authentication:

  1. For testing purposes only, do not perform this in production, add the Sign In portlet to the landing page of the Service Provider. In case the SAML configurations are incorrect this will allow for a direct login to the Service Provider bypassing the SAML authentication entirely.
  2. Sign out of the SP bundle or use a different browser
  3. Access the SP bundle
  4. Click on the Sign In button in the top right corner
  5. The user should be redirected to the IdP, in this case: http://liferaytest.com:9080/web/guest/home?...
  6. Sign in using the provided portlet
  7. The user should be redirected to the SP and logged in there

Use Case #3: User Attributes Other Than Email Address

The Configuring Service Provider and Identity Provider Connections documentation discusses Attribute Mapping and how the mapping needs to be configured to work as expected. The following information goes into specific use cases seen for some Identity Providers.

  • 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 Liferay Connector to SAML 2.0 plugin 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. 

Documentation regarding SAML Connector specific plugins can be found on the Configuring Service Provider and Identity Provider Connections page. The following are proof of concept steps for both configuring HTTPS within a Liferay DXP bundle and the configurations needed within the SAML Admin page.

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.
    Identify_Provider_-_SSL_Required.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.
    Service_Provider_-_SSL_Required.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.
    Service_Provider_-_disable.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: Bypassing SAML by adjusting the URL
In this scenario, assume that DXP 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.
Service_Provider_-_login_portlet.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: enabled=B"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 Save.
    SAML_-_KeystoreManager.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.
    SAML_-_KeyStorePath.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.

这篇文章有帮助吗？
1 人中有 1 人觉得有帮助