Integrate Azure AD with Liferay DXP Using SAML

Integrating Liferay DXP with other Identity Providers (IdPs) is a recommended security best practice. By leveraging external authentication mechanisms, you can strengthen your system's security and simplify user management processes.

This how to guides you through the basic steps needed to integrate Azure AD, your Identity Provider (IdP), with your Liferay environment using Security Assertion Markup Language (SAML).

Prerequisites

• Liferay DXP environment

• A user with administrative access to SAML Admin in Liferay's Control Panel

• A Microsoft Azure account with permissions to administer Azure AD

• At least one user created in your Azure AD account

Steps

1. From the Azure portal, go to Enterprise Applications.
   

2. Click New application to create a new application.

3. Click Create your own application.

4. Name your application as desired and select Integrate any other application you don't find in the gallery (Non-gallery).
   

5. Once your application is created, go to Users and groups on the left sidebar menu and assign your users to the application.

6. Go to Single sign-on on the left sidebar menu and select SAML.
   This redirects you to the SAML SSO configuration page.
   

7. Under Basic SAML Configuration, click Edit, enter these values, and click Save:

   Field	Value
   Identifier (Entity ID)	https://[your_web_server]/saml
   Reply URL	https://[your_web_server]/c/portal/saml/acs

8. Edit the Attributes & Claims section and ensure that user.mail is set as the Unique User Identifier (Name ID).

9. Under Additional claims, ensure it has suitable values for the user's given name (first name), surname (last name), and email address.

   Note: You can add, update, or delete any of the Additional Claims. However, Liferay requires specific values (first name, last name, and email address) to successfully add a user to the instance.

   

10. Back in the SSO setup page, edit the SAML Certificates section and ensure the Signing Option is set to Sign SAML response and assertion.
    This is necessary for Liferay DXP to trust Azure as its Identity Provider.
    

11. Copy the App Federation Metadata Url and download the Federation Metadata XML.
    You'll use these in a later step to configure Liferay.
    

12. On your Liferay DXP instance, open the Global Menu and go to Control Panel → Security → SAML Admin.

13. Under the General tab, set these values and click Save:

    Field	Value
    SAML Role	Service Provider
    Entity ID	https://[your_web_server]/saml

     
    Warning: Do not enable SAML until you have finished configuring all settings.

14. Create a Certificate and Private Key. An Encryption Certificate is not needed.
    

15. Go to the Service Provider tab, ensure these settings are checked, and click Save:

    • Require Assertion Signature?

    • Sign Authn Requests?

    • Sign Authn Requests?

    • Sign Authn Requests?

    • Sign Authn Requests?

16. Go to the Identity Provider Connections tab.

17. Click Add Identity Provider and configure these settings:

    Field	Value
    Name	Azure AD
    Entity ID	Enter the entityID found in the Federation Metadata XML file you downloaded from Azure
    Enabled	Checked
    Upload Metadata XML	Checked
    Metadata XML	Upload the Federation Metadata XML file
    Name Identifier Format	Email Address

18. Under Attribute Mapping, add these Basic User Fields:

    User Field Expression	SAML Attribute
    emailAddress	mail
    firstName	givenname
    lastName	surname

    
    

19. Click Save.

20. Go back to the General tab, check Enabled, and click Save.

    You can now use Azure with SAML to authenticate in your Liferay instance.

21. Log out of your current user.

22. Click Sign In.

    This redirects you to Microsoft's login page.
    

23. Enter the email address and password for your user.

    Once you've successfully logged in, your Azure user should be registered in Liferay.
    

24. Sign back in as your Liferay admin user.

25. Open the Global Menu and go to Control Panel → Users and Organizations. Verify that your Azure user displays on the list.
    

Conclusion

Congratulations! Users may now authenticate to your Liferay environment by using Azure AD via SAML.

Tips

• Identifier Not Found In The Directory: Ensure the configuration in Azure AD and Liferay DXP matches, particularly the Entity IDs and reply URLs.
• Unable To Process SAML Request: If you see an error message indicating that Liferay DXP was unable to parse the SAML request, ensure the SAML Certificates in Azure AD are set to sign the SAML response and assertion.