Example: SAML With Microsoft Entra ID

Configure SSO SAML authentication using Microsoft Entra ID as the Identity Provider and integrating into PM Classic.

Overview

Configure ProcessMaker Platform and PM Classic to use SSO SAML authentication with the identity provider Microsoft Entra ID (Microsoft Azure Active Directory) as follows:

1. Create and configure an enterprise application in Microsoft Entra ID

2. Configure ProcessMaker using SAML with Microsoft Entra ID

3. Configuration for PM Classic (needed only for PM Classic users)

4. Configure the web browser

• It is recommended to create and configure an enterprise application in Microsoft Entra ID concurrently with configuring ProcessMaker Platform and PM Classic. This is because each configuration procedure requires values from the other.

• The web browser must support third-party cookies.

MS Azure Setup

Create and Configure an Enterprise Application in Microsoft Entra ID

Follow these steps to add an enterprise application in Microsoft Entra ID:

1. Log on to your Microsoft Azure account. The Welcome to Azure! window displays.

   
2. Click View in the Manage Microsoft Entra ID section. The Default Directory screen displays.

   
3. Click Enterprise Applications, then select the All Applications option. The Browse Microsoft Entra Gallery screen displays.

   
4. Click Create your own application. Create your own application screen displays on the right.

   
5. From the Create your own application screen:

   1. In the What's the name of your app?, enter the application name.

   2. Select Integrate any other application you don't find in the gallery (Non-gallery).

   3. Click Add.

6. On the sidebar, click Single sign-on. The Single sign-on screen displays.

   
7. Click the SAML option. The SAML-based Sign-on page displays.

   

   SAML-based Sign-on page
8. From the Basic SAML Configuration section, click the Edit link. The Basic SAML Configuration page displays.

   

   Basic SAML Configuration page
9. Pause this procedure, and then begin configuring the ProcessMaker Platform SAML authentication until the SSO - SAML settings display.

ProcessMaker Platform

Configure ProcessMaker Using SAML With Microsoft Entra ID

Required Permission

Permission Required

Furthermore, your user account or group membership must have the "Settings: Update Settings" permission to edit SSO SAML settings unless your user account has the Make this user a Super Admin setting selected.

See the Settings permissions or ask your Administrator for assistance.

Notice to Administrators

Enhance security for your ProcessMaker Platform instance by following these best practices. Among these best practices are to require all ProcessMaker users to log on to your ProcessMaker Platform instance via Single Sign-On (SSO), OAuth, OKTA and/or two-factor authentication.

Follow these steps to configure SAML SSO settings with Microsoft Entra ID as necessary:

1. ​View your SSO Settings. From the list of SSO identity providers, enable the SAML option. The SSO - SAML tab displays.

2. Click the SSO - SAML tab. The SSO - SAML settings display.

   
3. In Microsft Azure, go to the Basic SAML Configuration.

   
4. Copy the ProcessMaker Platform settings from the SSO - SAML settings in step two to Microsoft Azure settings in step three as follows:

   • Use the copy icon to copy the URL from the ACS Url setting, and then provide it to the Add reply URL setting.
   • Use the copy icon to copy the URL from the Entity ID (Metadata) setting, and then provide it to the Add identifier setting.
   • Use the copy icon to copy the URL from the Single Logout URL setting, and then provide it to the Logout Url (Optional) setting.
5. In Microsoft Azure, go to the Set up section and copy the following fields:

   • Login URL

   • Microsoft Entra Identifier

   • Logout URL

     
6. In ProcessMaker Platform, go to the following settings:

   

   Copy Microsoft Azure settings described in step five as follows:

   • Click the Edit iconfor the SSO Endpoint setting. Enter the identity provider URL from which ProcessMaker retrieves the authentication response and validates it when establishing the SSO session. Get this value from the Login URL value of Microsoft Azure settings described in step five.
   • Click the Edit iconfor the SSO Identifier setting. Enter the URL that references the SAML XML file for your identity provider (IdP). Get this value from the Microsoft Entra Identifier value of Microsoft Azure settings described in step five.
   • Click the Edit iconfor the SLO Endpoint setting. Enter the logout URL. Get this value from the Logout URL value from the Microsoft Entra Identifier value of Microsoft Azure settings described in step five.
7. In the Encryption Type setting, select the encryption type set in your Microsoft Azure environment. For this example, leave the default value as RSA_SHA1.

   
8. In Microsoft Azure, go to the SAML Certificates section and download the Certificate (Base 64) file. Open the file, copy all the content including BEGIN/END certificate lines.

   
9. In ProcessMaker Platform, click the Edit iconfor the Public Certificate setting. The Public Certificate screen displays.

   
10. If Microsoft Azure requires, enter the identity provider's certificate fingerprint. Get this value from the SAML Certificates setting in step eight.

11. Click the Edit iconfor the Variable Map and the User Matching setting. In this case, the Variable Map screen displays default values.

    

    Variable Map
12. Match the variables of the User Matching and Variables Map fields with one of the following Microsoft Azure data according to your needs and attributes available:

    • The attributes retrieved from the Federation Metadata XML file.

    • The data in the Attributes and Claims sections.

      

      
13. In Microsoft Azure, do the following:

    1. In the SAML Certificates section, download the Federation Metadata XML file.

       
    2. Open the file.

       
14. In ProcessPlatform, click the Copy icon for the Name ID Format setting to copy this value in the Required claim setting when configuring Microsoft Azure. Otherwise, leave with the default value.

    
15. Configure PM Classic.

PM Classic Config

Configuration for PM Classic

These settings are needed only if you are using PM Classic.

Follow the next steps to correctly run SAML integrated to PM Classic:

1. Access PM Classic as an Administrator.
2. From the left menu, click System Settings.

3. Install and enable the SAML Authentication Plugin.

4. Go to Admin > Users > SAML Auth. The SAML Configuration panel displays and the Service Provider tab displays by default. Click Service Provider to view this tab when it is not currently selected.

   
5. Copy the above values, and add them to new Microsoft Azure values in Basic SAML Configuration as follows:

   1. Entity ID to Identifier (Entity ID)

   2. Assertion Consumer Service to Reply URL (Assertion Consumer Service)

      
6. In PM Classic - SAML Configuration, click the Identity Provider tab. The interface to configure the identity provider displays.

   
7. From Microsoft Azure, in the Set up section, copy the following fields to the above Identity Provider section in PM Classic:

   • Login URL to Single Sign-On Service.

   • Microsoft Entra Identifier to Entity ID.

   • Logout URL to Single Logout Service.

     
8. In PM Classic - SAML Configuration, click the Configurations tab and go to the Field Matching section.

   
9. From Microsoft Azure, copy the Claim Name and then match it to the desired User Field in PM Classic Configurations section above. This should match the field that was configured in ProcessMaker Platform too.

10. In PM Classic - SAML Configuration in the Signature Algorithm dropdown, select the encryption type set in your Microsoft Azure environment that also matches with the one in ProcessMaker Platform. For this example, leave the default value as rsa-sha1.

11. In PM Classic - SAML Configuration, go to the Certificates section.

    
12. Click Upload New Certificate and upload the file in Certificate (Base 64) from the SAML Signing Certificate section in Microsoft Azure, which was downloaded when configuring ProcessMaker Platform.

13. Configure the Web Browser.

14. After configuring ProcessMaker Platform and PM Classic, do the following:

    1. Enable the SAML authentication in PM Classic by checking Enable SAML Authentication for this workspace?

       
    2. Click Update Configuration.

Web Browser Config

Configure the Web Browser

To run correctly this process, it is necessary to enable the Allow third-party cookies in Chrome/Firefox web browsers or any other browser that will be used for ProcessMaker platform.

For this purpose, follow the next steps:

1. In Chrome, go to the customize menu and open the settings and search for block. Otherwise, open this URL chrome://settings/cookies?search=block

   
2. Set the General settings to Allow all cookies as follows: