Setup SAML on Liferay DXP

Description

This article serves as a guide is for deploying SAML on Liferay DXP both as an Identity provider and Service provider

Table of Contents

1. Introduction
2. Setting Up Liferay SAML as an IdP
3. Setting Up Liferay SAML as an SP
4. Use Case #1: Salesforce Integration
5. Use Case #2 Liferay as Both IdP and SP
   • Add a Service Provider
   • IdP-initiated SSO
   • SP-initiated SSO
6. Use Case #3: User Attributes Other Than Email Address
7. Use Case #4: Connecting Through a Secure Proxy Connection
8. Troubleshooting

Introduction
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. SAML is a form of Single Sign On / Single LogOut (SSO / SLO) authentication. It was developed by OASIS in 2001 (SAML 1.0) with the latest update to the standard coming in 2005 (SAML 2.0). 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 is built on OpenSAML, is platform neutral, and is supported by many Saas applications. For credentials, a java keystore is used.
Liferay SAML offers two different configurations: as an Identity Provider (abbrev. as IdP) and as a Service Provider (abbrev. as SP). Developers can also 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.0 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.0.
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

Liferay SAML as IdP
The following steps describe how to setup SAML as an IdP.

1. Start Liferay DXP on default port 8080.
2. Sign in and do not flag "Remember Me". (Otherwise this will invalidate SAML.)
3. Deploy the latest SAML plugin available on Liferay Marketplace.
4. Once the plugin has been successfully deployed, navigate to the Control Panel > Configuration> SAML Admin
   
5. On the General tab, enter the following:
   1. SAML Role: Identity Provider
   2. Entity ID: samlidp
6. Click the Save button.
7. Users now have to generate the certificate. In the past, this was done all in a command line. The latest SAML versions beginning with 6.1 EE GA3 allows developers to generate the certificate in the Control Panel.
   1. Common Name: liferayidp
   2. Organization: liferay
   3. Country: USA
   4. Validity: 356
   5. Key Algorithm: RSA (leave the default value)
   6. Key Length: 2048 (leave the default value)
   7. Key Password: liferayidp
8. Click the Save button.
9. Check the Enabled check box.
   The completed configuration should look like this:
   
10. Click the Identity Provider tab.
11. Click the Sign Metadata.
12. Check the Authn Request Signature Required check box.
13. Click Save.

At this point, the basic IdP configuration is complete. To add a Service Provider, the Service Provider must already be active because the IdP authenticates the SP's metadata URL. To add a Service Provider, go to the Service Provider Connections tab and click "Add Service Provider". At this point, anything can serve as the Service Provider, especially other third party technologies. Follow the configuations required to connect with Liferay; Salesforce (see below) is one good example.

---

Liferay SAML as SP
The following steps are on how to set up SAML as an SP. For demonstration purposes and to differentiate between the IdP and SP, the SP will be using a virtual host called www.alpha.com with Apache Tomcat port number 9080. If users wish to connect two Liferay bundles, go through this pre-start checklist:

• The SP instance runs on a different database.
• The SP instance uses a different port number or a different virtual host name.
• The IdP and SP uses the same method for authentication. By default it is the user's email address but it could also be the screen name or another method such as a role.
• The same users are on both databases.
• The SP runs on a different OSGi console port number. This can be set in the portal-ext.properties:
  module.framework.properties.osgi.console=localhost:11312

Once the pre-start checklist is completed, start Liferay DXP and follow the steps below to configure Liferay SAML as a Service Provider (SP).

1. Start Liferay DXP using the virtual host www.alpha.com on default port 9080 (http://www.alpha.com:9080).
2. Sign in and do not flag "Remember Me". (Otherwise this will invalidate SAML.)
3. Deploy the latest SAML plugin available on Liferay Marketplace.
4. Once the plugin has been successfully deployed, navigate to the Control Panel > Configuration> SAML Admin
   
5. On the General tab, enter the following:
   1. SAML Role: Service Provider
   2. Entity ID: samlidp
6. Click the Save button.
7. Users now have to generate the certificate. In the past, this was done all in a command line. The latest SAML versions beginning with 6.1 EE GA3 allows developers to generate the certificate in the Control Panel.
   1. Common Name: liferaysp
   2. Organization: liferay
   3. Country: USA
   4. Validity: 356
   5. Key Algorithm: RSA (leave the default value)
   6. Key Length: 2048 (leave the default value)
   7. Key Password: liferaysp
8. Click the Save button.
   The initial configuration should look something like this:
   
9. Do not flag the Enabled check box yet. The SP requires an active IdP. Users can set another Liferay instance as the SP; this is not portal version specific. Or users can set other non-Liferay technology as the IdP. The following configuration uses another Liferay instance as the IdP.
10. Click the Identity Provider Connection tab.
11. Enter the following:
    1. Name: samlidp
    2. Entity ID: samlidp
    3. Metadata URL: http://localhost:8080/c/portal/saml/metadata
    4. Name Identifier Format: Email Address
       
12. Click the Save button.
13. Once the configurations have been saved, click the General tab.
14. Check the Enabled check box.
15. Click the Save button.
16. At this point, the SP has been enabled. To verify, administrators can view the metadata by appending /c/portal/saml/metadata to the end of the host URL (e.g. http://localhost:8080/c/portal/saml/metadata).

---

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 the section on 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).
   
   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"
   
   
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.

---

Liferay as both IdP and as 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
   
   
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 Liferay Digital Enterprise 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 Liferay Digital Enterprise 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 Liferay Digital Enterprise 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 Liferay Digital Enterprise 7.0 is configured as a SAML IdP server, then check the SSL Required check box in the Identity Provider tab.
   
3. The same is true for Liferay Digital Enterprise 7.0 instances configured as a SAML SP server. Check the SSL Required check box in the Service Provider tab.
   
4. Click Save.

---

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.