1. Liferay Help Center
  2. Biblioteca técnica
  3. How-to

Using Shibboleth 3 as IdP + SAML Integration

Avatar

Justin Choi

  • Actualización

Liferay Support does not recommend or endorse specific third-party products over others. Liferay is not responsible for any instructions herein or referenced regarding these products. Any implementation of these principles is the responsibility of the subscriber.

This article documents a proof of concept for setting up Shibboleth as an Identity Provider (IdP) and Liferay DXP 7.0 with SAML as a Service Provider (SP). This is a very common business implementation to use Shibboleth as a protocol in an IdP which is connected to a DXP or Portal instance that serve as the SP. That way, users can execute a Single Sign On (SSO) action from the SP and log into the instance.

This article serves as a general checklist with some steps listed for clarification. Administrators should always check review documentation pertaining to Shibboleth and LDAP before starting this process.

The following are required:

  • Shibboleth 3 installed on the local machine
  • One Liferay DXP 7.x instance configured as the SP
  • A database other than Hypersonic (HSQL)

Optional (but strongly suggested):

  • A second DXP instance
  • LDAP server

Important note: Shibboleth 3 comes with a native idp.war which must be deployed on an application server. To make things easier, we deployed this file into a DXP 7.0 instance. Normally, Liferay DXP 7.0 is not required to be on this app server; however, in this proof of concept, we can also use this instance to manage a LDAP server, especially if this LDAP server contains production data. 
Moreover, in a production environment, it is a best practice to use an LDAP server to manage all the users instead of relying solely on a database.

Resolution

Checklist

  1. Install Shibboleth 3
  2. Add the Required Java Server Tag Library Jar for Apache Tomcat
  3. Enable HTTPS
  4. Configure the idp-metadata.xml file
  5. Configure the IdP Instance
  6. Configure Liferay DXP as a Service Provider
  7. Add SP Metadata to Shibboleth
  8. Execute SP initiated SSO

Install Shibboleth 3

  1. Download and install the latest Shibboleth 3 IdP.
  2. During the installation process, specify the installation folder or use the default (for example, /opt/shibboleth-idp in *Nix environment). This will be referred to as idp.home as a short hand for future reference.
  3. When installing, use the following values:
    • hostname: localhost
    • SAML EntityID: https://localhost:8443/idp/shibboleth
    • Attribute Scope: localhost
    • Password: shibboleth-test

Add the Required Java Server Tag Library JAR for Apache Tomcat

If using Apache Tomcat 8.x, an additional Java Server Tag Library .jar is required to use the generated idp.war file. See the Additional Information section for more information about this JSTL.

  1. Download the jstl-1.2.jar.
  2. Open the generated idp.war using a zip file manager program like 7zip.
  3. Place the jar into the {idp.war}/../WEB-INF/lib/ folder.
  4. Save the updated idp.war.

Enable HTTPS

It is necessary to enable HTTPS in the application servers. Make sure that both application servers have SSL enabled and that a Java security certificate has been added to both application servers. If using Shibboleth in a production environment, ensure that the security certificate is appropriate to that level. Always consult the vendor's documentation first.

Configure the idp-metadata.xml file

Verify that the generated idp-metadata.xml has the correct port numbers in the element SingleSignOnService Binding. In particular, verify that the Location attribute includes the port number: 8443. 
<SingleSignOnService Binding="urn:mace:shibboleth:1.0:profiles:AuthnRequest" Location="https://localhost:8443/idp/profile/Shibboleth/SSO"/>
<SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://localhost:8443/idp/profile/SAML2/POST/SSO"/>
<SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST-SimpleSign" Location="https://localhost:8443/idp/profile/SAML2/POST-SimpleSign/SSO"/>
<SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://localhost:8443/idp/profile/SAML2/Redirect/SSO"/>

 

Configure IdP instance

As noted above, it is not necessary to have DXP 7.0 installed on the same application server where the Shibboleth 3 idp.war is deployed. However, it makes things easier to use this second DXP 7.x instance.

  1. Start the DXP 7.0 platform.
  2. Deploy the modified idp.war to this app server.
  3. Verify the war has been successfully deployed, navigate to https://localhost:8443/idp/status.

While this server is active, connect any LDAP server to this DXP instance. This entire stack serves as the IdP.

Once completed, shut down the application server. It is necessary for the application server to be shut down so that the SP's metadata be added to the Shibboleth configuration files.

Checkpoint:

  1. Shibboleth 3 has been installed on the local machine.
  2. If using Apache Tomcat, the additional JSTL .jar has been inserted inside the idp.war. Otherwise it is safe to skip this step.
  3. A Java security .jks file has been generated and HTTPS has been enabled in the IdP instance server.
  4. The idp-metadata.xml contains the correct ports.
  5. The idp.war has been deployed successfully.
  6. If using an LDAP, this server has been connected to DXP 7.0.

Configure Liferay DXP as a Service Provider

If there are two Liferay DXP instances running, it is necessary to modify the Service Provider instance to run on different ports so that they do not conflict. Different application servers have different ways to handle how ports are assigned and this guide is limited in scope. For demonstration purposes, the steps below are for Apache Tomcat. Administrators should consult the documentation first before making changes.

Suggested configuration:

  • LDAP Server as the IdP:
    • HTTP: 8080
    • HTTPS: 8443
  • DXP 7.0 as the SP:
    • HTTP: 8081
    • HTTPS: 8444

As noted above, it is essential that the Liferay DXP instance be connected to a production-level database and not a non-production database such as Hypersonic. See the Compatibility Matrix page to see which databases are supported. For demonstration purposes, we used MySQL 5.7.

Documentation already exists to guide administrators in configuring Liferay DXP as a SAML Service Provider. Obviously, remember to deploy the appropriate SAML Connector to the DXP instance first.

There are a few things to note when it comes with integrating Liferay DXP with Shibboleth:

  1. When generating the SAML SP Metadata, verify HTTPS is used (https://localhost:8444/c/portal/saml/metadata )
  2. Never check the Remember Me check box when signing in. This negates all SSO/SLO.
  3. The following settings have to be enabled on the General tab:
    • SAML Role: Service Provider
    • EntityID: https://localhost:8444
  4. The following settings have to be enabled on the Service Provider tab:
    • Assertion Signature Required
    • SSL Required
    • Enabled LDAP Import
    • Sign Metadata
  5. The following settings have to be enabled on the Identity Provider tab:
    • Name: Shibboleth
    • EntityID: https://localhost:8443/idp/shibboleth
    • Metadata URL: upload the idp-metadata.xml file.
    • Name Identifier Format: Unspecified*
    • Attribute Mapping: (blank)
  6. Click Save when finished.

In the SP instance, it is necessary to have users whose credentials match those in the IdP instance. For demonstration purposes, this DXP 7.0 SP instance manages its users using the database. Otherwise, SSO/SLO will fail. This is true regardless of whether this is a developer or a production environment. 

There is a simple way to test whether you have set up the instances correctly and that the IdP and the SP are communicating. In the SP instance's Control Panel, navigate to Users and Organizations. Create a DXP 7.0 user with administrator rights with the same credential that also exists in the LDAP directory. Use this newly created user (name: John Harrison / password: Khan) to try to authenticate against the LDAP from DXP 7.0. 

Lastly, generate the SP metadata file.

  1. Navigate to https://localhost:4444/c/portal/saml/metadata.
  2. Save the file as sp-metadata.xml

Checkpoint:

  1. The DXP 7.0 instance is running on a different port; 8444 in this example.
  2. DXP 7.0 has been enabled as a Service Provider.
  3. SAML SP metadata has been generated.
  4. Users have been created in DXP 7.0 SP that matches those in the LDAP.

Add SP Metadata to Shibboleth

Before we test the SSO/SLO in Liferay DXP 7.0, we have to connect the IdP instance and the SP instance by pointing each other's metadata towards each other. That means specifying the sp-metadata.xml in the Shibboleth IdP instance; conversely, the idp-metadata.xml was already specified in the SP instance when SAML was enabled. There are several files to be modified in the Shibboleth IdP instance.

First, the sp-metadata.xml must be specified in Shibboleth IdP to complete the configuration.

  1. Navigate to the {idp.home}/conf/ folder.
  2. Modify the file metadata-providers.xml with the following: 
    <MetadataProvider id="sp-metadata"
    xsi:type="FilesystemMetadataProvider"
    metadataFile="/{idp.home}/metadata/sp-metadata.xml"/>

    where metadataFile= contains the location of the sp-metadata.xml file (metadataFile="/opt/shibboleth-idp/metadata/sp-metadata.xml").

Next, enable SAML encryption. All the files are found in the {idp.home}/conf folders.

  1. Modify the file idp.properties with the following property:
    idp.encryption.optional = true

Lastly, add the following attribute policy liferaysp by modifying the attribute-filter.xml file:

<AttributeFilterPolicy id="liferaysp">
    <PolicyRequirementRule xsi:type="Requester"
        value="https://localhost:8444"/>
    <AttributeRule attributeID="uid">
        <PermitValueRule xsi:type="ANY"/>
    </AttributeRule>
    <AttributeRule attributeID="mail">
        <PermitValueRule xsi:type="ANY"/>
    </AttributeRule>
    <AttributeRule attributeID="firstName">
        <PermitValueRule xsi:type="ANY"/>
    </AttributeRule>
    <AttributeRule attributeID="lastName">
        <PermitValueRule xsi:type="ANY"/>
    </AttributeRule>
    <AttributeRule attributeID="screenName">
        <PermitValueRule xsi:type="ANY"/>
    </AttributeRule>
</AttributeFilterPolicy>

Checkpoint:

  1. The sp-metadata.xml has been added to the Shibboleth 3 IdP.
  2. Encryption has been enabled.
  3. The attribute-policy has been set.

At this point, start the IdP instance again. Verify that the server has started successfully without errors and that it is connected to the LDAP.

Execute SP-initiated SSO

  1. In a different browser window, navigate to https://locahost:8444. Also ensure there is no cached data.
  2. Click the Sign in link at the top right.
  3. Verify that the browser redirects to the Shibboleth page on https://localhost:8443.
  4. Enter the user name and password (John Harrison / Khan) created earlier which must correspond to the same user in LDAP.
  5. Verify that the user has been signed into DXP 7.0.

Additional Information

* An alternative to using Unspecified in the Name Identifier Format in the Service Provider is to use Email Address. Additional steps are required in the Shibboleth 3 IdP to connect the LDAP server to the IdP instance.

  1. In the DXP 7.0 Control Panel → Configuration → SAML Admin, enter the following in the Service Provider tab:
    • Name Identifier Format: Email Address
    • Attribute Mapping: 
      mail=emailAddress
screenName=screenName
firstName=firstName
lastName=lastName
uid=uuid
  2. Next, configure the NameIdPolicy because we are using Email Address.
    • Navigate to the {idp.home}/conf folder.
    • Open the saml-nameid.xml file.
    • Uncomment the entry: <bean parent="shibboleth.SAML2AttributeSourcedGenerator" ...>
    • Uncomment the entry: <bean parent="shibboleth.SAML1AttributeSourcedGenerator" ...>
  3. Lastly, update the attribute definitions in the attribute-resolver.xml file. This is because of the attribute mappings declared when enabling the Liferay SAML SP. These mappings have to match the five attributes specified above.

At this point, the IdP instance can communicate with the LDAP server to authenticate users. Depending on your attribute mapping, the five values are included in the request sent between Shibboleth and the SP.  

¿Fue útil este artículo?
Usuarios a los que les pareció útil: 0 de 0