Submit Feedback

SAML Admin

The SAML Admin panel is the best place to configure your SAML instance. Use it instead of Instance Settings to streamline your SAML administration experience.

Note

Starting from Liferay 7.4, SAML is available out-of-the-box. Installing SAML Connector 2.0 is not required.

You can configure an Identity Provider (IdP), a Service Provider (SP), and connections to each with SAML Admin. To access it, open the Global Menu () → Control Panel → SAML Admin.

There are three tabs:

General: Enables or disables the SAML SP or IdP and manages the required keystore.

Service/Identity Provider: Manages basic and advanced configurations for the SP or IdP based on the selected SAML role.

Identity/Service Provider Connection: Manages connections to the SP (if SAML role is Identity Provider) or IdP (if SAML role is Service Provider). There can be multiple SP/IdP connections.

General Tab

The General tab shows options that apply to SAML regardless of its role:

Enabled: Check this box to enable SAML authentication once you have everything configured.

SAML Role: Choose the SAML role, either Identity Provider or Service Provider.

Entity ID: The unique identifier for this SAML entity (IdP or SP). It can be up to 1024 characters long.

The Certificate and Private Key section appears after the first save and displays the key generated when you set up your key store in system settings. Here, you can replace the certificate by generating a new certificate or importing one you created elsewhere, and you can also download the certificate to import elsewhere.

If you must replace the auto-generated certificate, you can:

Click Replace Certificate.
The Create Certificate tab is activated by default. Fill out the necessary fields for your key.
When finished, click Save.

Your new key’s details are now displayed.

If you’ve already generated a key, that key must be stored in a PKCS #12 archive to be imported into Liferay DXP:

Click Replace Certificate.
Click the Import Certificate tab.
Type your key store’s password and either drop the PKCS #12 key file into the upload area or use the file selector to choose it.

Your key is now imported.

Service Provider

Choose the Service Provider role from the SAML Role field.
The Certificate and Private Key section is for creating a keystore for SAML. Click Create Certificate and enter the following information:
- Your common name (your first and last name)
- The name of your organization
- The name of your organizational unit
- The name of your city or locality
- The name of your state or province
- The name of your country
- The length in days that your keystore remains valid (how long before it expires)
- The key algorithm (RSA is the default)
- The key length in bits (2048 is the default)
- The key password
Remember that the keystore has two storage options: file system storage (the default) and Documents and Media storage. By default, the certificate uses the SHA256 algorithm for encryption and is fingerprinted and self-signed via MD5 and SHA256. When you enter all the required information, click Save.
After you clicked Save, check that you can view information about your certificate or download your certificate. If you can, you successfully created a keystore.
You can also generate an encryption certificate. This is a separate key for encrypting assertions. If you want assertions encrypted, you must generate a key for this. The procedure is exactly the same as generating your certificate in step 2 above.
Next, you must configure an Identity Provider connection. Click on the Identity Provider Connections tab and click Add Identity Provider.
Enter a name for the Identity Provider, enter its entity ID, and enter its metadata URL. If you have already configured a separate Liferay DXP installation as an Identity Provider, you’d enter this information:
- Name: Liferay IdP
- Entity ID: [ID of IdP]
- Clock Skew: Set the tolerance in milliseconds between SP and IdP.
- Force Authn: Whether the IdP should force re*authentication regardless of context.
- Metadata URL: http://localhost:8080/c/portal/saml/metadata (test this URL first)
- Name Identifier Format: See settings.
- Attribute Mapping: See settings.
- Keep Alive URL: See settings.
Important

The Liferay Connector to SAML 2.0 app 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 is persisted to the database only when there is a metadata URL and there is no specified metadata XML file. Otherwise, Liferay DXP keeps the original metadata URL in its database. This behavior ensures that once a metadata URL has been specified, there is always a metadata URL saved in the database. This way, if you forget the previously entered metadata URL or its format, you can look at the displayed metadata URL and choose to modify the displayed metadata URL or overwrite the previously saved metadata URL by specifying a metadata XML file.
Finally, after you save your certificate and private key information and configure an Identity Provider connection, check the Enabled box at the top of the General tab and click Save. Liferay is now a SAML Service Provider!

Note that the SAML Service Provider session is tied to the normal session on the application server. Session expiration on the application server terminates the session on the Service Provider but does not initiate single logout.

Configuring the Service Provider

Require Assertion Signature: Check this box to require SAML assertions to be individually signed by the IdP in addition to the entire SAML message.

Clock Skew: See settings.

LDAP Import Enabled: Check this box to import user attributes from the LDAP servers declared in this SP’s instance settings.

Sign Authn Requests?: If configured as an SP, digitally sign Authn requests.

Sign Metadata?: Sign the metadata sent to peer SAML entities.

SSL Required: Check this box to require SSL for the transfer of all SAML messages. All URLs in metadata sent to peers become prefixed with the https protocol.

Allow showing the login portlet: Allow the login portlet to appear when no SAML IdP is matched to the login request. Users in this scenario log in locally to Liferay DXP.

Important

Individual assertions need not be signed as long as the SAML response itself is signed. The SP and IdP should always communicate over https to have encryption at the transport level.

Liferay DXP requires signed SAML responses. If you believe man-in-the-middle attacks are possible and the information in the assertions is sensitive, you can both sign and encrypt them.

You can add multiple IdP connections. To add another Identity Provider, click Add Identity Provider again and enter the details for the other provider. When users log in, they are asked to choose an identity provider, so be sure to name the providers so users can recognize them.

Setting Up Liferay DXP as a SAML Service Provider in a Clustered Environment

You can use the Liferay Connector to SAML 2.0 app as an SSO solution for a clustered environment. If your multi-node cluster is behind a load balancer, you must enable all the nodes as SPs, and they must share the same keystore manager.

If using the Filesystem Keystore Manager (the default):

Configure each node of your Liferay cluster as a SAML service provider as above.
Copy the keystore file ([Liferay Home]/data/keystore.jks, by default) from the first node to the remaining nodes. This file is the Java keystore that’s created by the SAML Provider app. The keystore contains the valid or self-signed certificate managed by the SAML connector app.
Verify that the service provider metadata has been generated to be used either as a URL or an XML file. The metadata is the same for all nodes because of the same database backend. The IdP’s request goes through the load balancer.
At this point, all nodes have the same SAML SP configuration and each of them can respond to web requests and handle the SAML protocol. To test your SSO solution, sign into Liferay via your load balancer, navigate to a few pages of a few different sites, and then log out.

If using the Document Library Keystore Manager, skip step 2 because the keystore file is stored in the database shared by all the nodes.

Now you know how to configure Liferay DXP either as a SAML service provider. You also know how to configure SAML in a clustered environment.

Note

Starting from Liferay 7.4, SAML is available out-of-the-box. Installing SAML Connector 2.0 is not required.

Identity Provider

Choose the Identity Provider role from the SAML Role field.
The Certificate and Private Key section is for creating a keystore for SAML. Click Create Certificate and enter the following information:
- Your common name (your first and last name)
- The name of your organization
- The name of your organizational unit
- The name of your city or locality
- The name of your state or province
- The name of your country
- The length in days that your keystore remains valid (how long before it expires)
- The key algorithm (RSA is the default)
- The key length in bits (2048 is the default)
- The key password
Remember that the keystore has two storage options: file system storage (the default) and Documents and Media storage. By default, the certificate uses the SHA256 algorithm for encryption and is fingerprinted and self-signed via MD5 and SHA256. When you enter all the required information, click Save.
After you clicked Save, check that you can view information about your certificate or download your certificate. If you can, you successfully created a keystore.
You can also generate an encryption certificate. This is a separate key for encrypting assertions. If you want assertions encrypted, you must generate a key for this. The procedure is exactly the same as generating your certificate in step 2 above.
Next, you must configure a service provider connection. Go to Service Provider Connections tab and click Add Service Provider.
Enter a name for the service provider, enter its entity ID, and metadata URL. If you have already configured a separate Liferay DXP installation as an service provider, you’d enter this information:
- Name: Liferay SP
- Entity ID: ID of the service provider
- Enabled: Check this box to activate the Service Provider connection.
- Force Encryption: See settings.
- Metadata URL: http://localhost:8080/c/portal/saml/metadata (test this URL first)
- Name Identifier Format: See settings.
- Attribute Mapping: See settings.
- Keep Alive URL: See settings.
Finally, after you save your certificate and private key information and configure the service provider connection, check the Enabled box at the top of the General tab and click Save. Liferay is now a SAML identity provider.

Configuring the Identity Provider

Sign Metadata?: Sign the metadata sent to peer SAML entities.

SSL Required: Check this box to require SSL for the transfer of all SAML messages. All URLs in metadata sent to peers become prefixed with the https protocol.

Require Authn Request Signature: Check this box to require each Authn request to be signed by the sending Service Provider. In most cases, this should be enabled.

Session Maximum Age: The amount of time in seconds the SSO session, managed by the IdP, lasts.

Session Idle Timeout: The amount of time in seconds an idle session lasts before it expires.

SAML Settings

Many of the same fields appear in both the Service Provider and the Identity Provider configurations. Here’s a reference.

Name: Name the SP or IdP. This is only a descriptive name; it’s not used in the configuration.

Entity ID: The official name of this SP or IdP. When configuring connections, they must match this name.

Enabled: Check this box to enable this SAML provider.

Clock Skew: Set the tolerance for the time difference between the SP and the IdP in milliseconds.

Force Encryption: If the SP does not provide a public key for encrypting the assertions, abort the single sign-on.

Force Authn: Check this box to have the Service Provider ask the Identity Provider to re-authenticate the user before verifying the user.

Unknown Users are Strangers: Stranger behavior is defined in Control Panel → Instance Settings → Platform → User Authentication → General.

Metadata: Provide a URL to the Service Provider metadata XML file or manually upload the Service Provider metadata XML file. If you provide a URL, the XML file is retrieved and periodically polled for updates. The update interval can be configured in System Settings with the Runtime Metadata Refresh Interval property which specifies the number of seconds. If fetching the metadata XML file by URL fails, you can’t enable the Service Provider connection. If the Identity Provider server cannot access the metadata via URL, you can upload the XML file manually. In this case, the metadata XML file is not updated automatically.

Name Identifier: Choose a Name Identifier Format from the available options in section 8.3 of the SAML specification. Set this according to what the Service Provider expects to receive. For Liferay Service Providers, any selection other than email address indicates that the Name Identifier refers to screen name. The formats don’t have any special meaning to Liferay Identity Providers. The NameID value is defined by the Name Identifier attribute.

User Resolution: Choose from No Matching, Match a User Field Chosen Dynamically Based on Name ID Format, or Match Using a Specific SAML Attribute Mapping. This algorithm determines how users are found or provisioned. For example, if you choose based on Name ID Format and the Name ID Format is email address, the algorithm matches by email address.

Attribute Mapping: Choose a field from Liferay to match to a SAML attribute. You can choose several fields from Liferay’s User object or custom fields you have created for the User object. These attributes are updated from the SAML assertion when a user logs into the system. By default the NameID and Service Provider are bound to a user after the emailAddress is matched at least once. Bindings are preferred and checked before user matching is conducted, so users whose email addresses have changed don’t lose their ability to log in, and email addresses can be corrected through SAML attribute mappings. Liferay attributes available for mapping are emailAddress, screenName, firstName, lastName, modifiedDate, and uuid.

Keep Alive: If users are logged into several Liferay SP instances via a Liferay IdP, their sessions can be kept alive as long as they keep a browser window open to one of them. Configure this only if the SP is Liferay DXP. The URL is https://[SP host name]/c/portal/saml/keep_alive.

OSGi Configuration Properties

You can configure SAML outside the UI through OSGi configuration files and by uploading metadata XML to configure how connections are negotiated.

As noted previously, anything related to configuring SP connections must be done through the SAML Admin UI where configurations are saved to Liferay’s database.

Note

Don’t use OSGi .config files or Liferay DXP’s System Settings Control Panel application to configure SAML providers (IdP or SP). The System Settings UI is auto-generated, and is for advanced administrators. It does not perform the enhanced validation on the fields that the SAML Admin UI performs, so administrators could create invalid configurations.

This is a portal instance-scoped configuration which can be managed via OSGi Configuration Admin. The affected properties are those in the SAMLProviderConfiguration metatype:

keyStoreCredentialPassword()
keyStoreEncryptionCredentialPassword()
assertionSignatureRequired()
authnRequestSignatureRequired()
clockSkew()
defaultAssertionLifetime()
entityId()
enabled()
ldapImportEnabled
role()
sessionMaximumAge
sessionTimeout()
signAuthnRequest()
signMetadata()
sslRequired()
allowShowingTheLoginPortlet()

The SAML Admin UI remains the place for creating the portal instance scoped configuration instances.

Note that there is also a system wide configuration, represented by the SamlConfiguration metatype.

If you used Liferay 6.2, please note that the following system-wide properties were removed:

saml.metadata.paths (served no purpose after removal of SP connection defaults)
saml.runtime.metadata.max.refresh.delay
saml.runtime.metadata.min.refresh.delay

The latter two properties were replaced with the single property com.liferay.saml.runtime.configuration.SamlConfiguration.getMetadataRefreshInterval().

Note also the introduction of the SAML KeyStoreManager Implementation Configuration in Control Panel → System Settings → Security → SSO. The options for this configuration are explained above in Configuring SAML at the System Level.

In recent versions, SHA256 is the default encryption algorithm used in the configuration and to generate keys. The default configuration tries SHA256, then SHA384, then SHA512 before falling back to SHA1. Because SHA1 is potentially vulnerable, you can blacklist it using this property:

blacklisted.algorithms=["blacklisted_algorithm_url", "another_blacklisted_algorithm_url"]

To blacklist SHA1, therefore, you’d have this configuration:

blacklisted.algorithms=["http://www.w3.org/2000/09/xmldsig#sha1"]

Place these in a config file with this name:

com.liferay.saml.opensaml.integration.internal.bootstrap.SecurityConfigurationBootstrap.config

There’s a lot more granularity in how connections are negotiated if you configure the metadata XML.

Configuring Negotiation Via metadata.xml

If the default negotiation configuration doesn’t work for you, you can craft your own configuration and upload it. Before doing this, visit your host’s metadata URL and save a copy of the configuration in case you need it later:

http://[hostname]/c/portal/saml/metadata

For example, if you’re stuck connecting to a legacy IdP that only supports SHA1, you can upload a configuration that disables the other algorithms:

<?xml version="1.0" encoding="UTF-8"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="samlidp">
  <md:IDPSSODescriptor WantAuthnRequestsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:Extensions>
      <alg:SigningMethod xmlns:alg="urn:oasis:names:tc:SAML:metadata:algsupport" Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
    </md:Extensions>
    <md:KeyDescriptor use="signing">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>... omitted ...</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="http://localhost:8080/c/portal/saml/slo"/>
    <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="http://localhost:8080/c/portal/saml/slo"/>
    <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="http://localhost:8080/c/portal/saml/sso"/>
    <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="http://localhost:8080/c/portal/saml/sso"/>
  </md:IDPSSODescriptor>
</md:EntityDescriptor>

Notice that in the configuration above, the <md:Extensions> block has only one signing algorithm: SHA1.

Note

Since the default configuration falls back to SHA1, you shouldn’t need to do this unless your legacy system can’t negotiate via the fallback mechanism. Also note that if you blacklisted SHA1, this won’t work. Due to vulnerabilities in SHA1, it’s best to avoid using it altogether if possible.

If you’ve changed your metadata configuration, you can go back to the default configuration if you saved it before making the change. If you didn’t, you can provide a URL instead of an uploaded XML file to one of your peers’ metadata configurations.

Capability:

Platform

Resource Type:

Official Documentation

Feature:

DXP Configuration

Identity Management and Authentication

Deployment Approach:

Liferay PaaS

Liferay SaaS

Liferay Self-Hosted