Example: SAML With Microsoft Entra ID

Configure SSO SAML authentication using Microsoft Entra ID as the Identity Provider.

Overview

Security Assertion Markup Language (SAML) is an XML-oriented open-standard used to exchange identity information between an identity provider (IdP) and ProcessMaker Platform. Configure ProcessMaker Platform to use SSO SAML authentication with the identity provider Microsoft Entra ID (Microsoft Azure Active Directory).

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

Create and Configure an Enterprise Application in Microsoft Entra ID

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

1. Add ​a Microsoft Entra ID enterprise application. The Overview enterprise application page displays.

   

   Enterprise application window
2. Click the Set up single sign on option. The Single sign-on page displays.

   

   Single Sign-On page
3. Click the SAML option. The SAML-based Sign-on page displays.

   

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

   

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

6. From the Identifier (Entity ID) setting, click the Add identifier link to add the ProcessMaker Platform SAML identifier. Get this value from the Entity ID (Metadata) setting when configuring the ProcessMaker Platform SAML authentication (step 4 of that procedure).

7. From the Reply URL (Assertion Consumer Service URL) setting, click the Add reply URL link to add the ProcessMaker Platform SAML reply URL. Get this value from the ACS Url setting, when configuring the ProcessMaker Platform SAML authentication (step 3 of that procedure).

8. In the Logout Url (Optional) setting, enter the ProcessMaker Platform SAML logout URL. Get this value from the Single Logout URL setting, when configuring the ProcessMaker Platform SAML authentication (step 5 of that procedure).

9. On the top left of the screen, click the Save icon to save the basic SAML configuration. The SAML-based Sign-on page returns.

   

   SAML-based Sign-on page displays again
10. From the Attributes & Claims section, click the Edit link. The Attributes & Claims page displays.

    

    Attributes & Claims page
11. From the Required claim section, click the Unique User Identifier (Name ID) row to match the claim name with the ProcessMaker Platform format. The Manage claim page displays.

    

    Manage claim page

    Do the following:

    1. Clear values in the Namespace setting.

    2. In the Name setting, copy the value from the Name ID Format setting when configuring the ProcessMaker Platform SAML authentication (step 16 of that procedure).

    3. On the top left, click the Save button. The Attributes & Claims page returns.

12. In the Additional claims section, match SAML attributes from the Variable Map setting when configuring the ProcessMaker Platform SAML authentication (step 14 of that procedure).

13. In the breadcrumbs, return to the SAML-based Sign-on settings.

    

    SAML-based Sign-on page
14. From the SAML Certificates section, locate the Certificate (Base64) setting, and then click its Download link. Copy the content of the downloaded certificate file to the Public Certificate setting when configuring the ProcessMaker Platform SAML authentication.

15. From the Set up section, copy the Login URL value to the SSO Endpoint setting when configuring the ProcessMaker Platform SAML authentication (step 6 in that procedure).

16. From the Set up section, copy the Azure AD Identifier value to the SSO Identifier setting when configuring the ProcessMaker Platform SAML authentication (step 8 of that procedure).

17. From the Set up section, copy the Logout URL value to the SLO Endpoint setting when configuring the ProcessMaker Platform SAML authentication (step 10 of that procedure).

18. Now your Microsoft Entra admin center has configured the ProcessMaker Platform SAML application. You need to finish configuring the ProcessMaker Platform SAML authentication to start authenticating ProcessMaker Platform through SAML with Microsoft Entra ID.

Configure ProcessMaker Using SAML With Microsoft Entra ID

Package Required

The Auth package must be installed.

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, select the SAML option. The SSO - SAML tab displays.

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

3. Use the copy icon to copy the URL from the ACS Url setting, and then provide it to the Add reply URL setting when configuring the Microsoft Entra ID provider (step 7 of that procedure).
4. Use the copy icon to copy the URL from the Entity ID (Metadata) setting, and then provide it to the Add identifier setting when configuring the Microsoft Entra ID provider (step 6 of that procedure).
5. Use the copy icon to copy the URL from the Single Logout URL setting, and then provide it to the Logout Url (Optional) setting when configuring the Microsoft Entra ID provider (step 8 of that procedure).
6. Click the Edit iconfor the SSO Endpoint setting. The SSO Endpoint screen displays.
7. 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 when configuring the Microsoft Entra ID provider (step 15 of that procedure).

8. Click the Edit iconfor the SSO Identifier setting. The SSO Identifier screen displays.
9. Enter the URL that references the SAML XML file for your identity provider (IdP). Get this value from the Azure AD Identifier value when configuring the Microsoft Entra ID provider (step 16 of that procedure).

10. Click the Edit iconfor the SLO Endpoint setting. The SLO Endpoint screen displays.
11. Enter the logout URL. Get this value from the Logout URL value when configuring the Microsoft Entra ID provider (step 17 of that procedure).

12. Click the Edit iconfor the Public Certificate setting. The Public Certificate screen displays.
13. Enter the identity provider's certificate fingerprint by pasting it into this setting. Ensure to include the -----BEGIN CERTIFICATE----- header. Get this value from the SAML Certificates setting when configuring the Microsoft Entra ID provider (step 14 of that procedure).

14. Click the Edit iconfor the Variable Map setting. The Variable Map screen displays default values.

    

    Variable Map
15. Copy each SAML Attribute value to match with the Additional claims settings when configuring the Microsoft Entra ID provider (step 12 of that procedure).

16. Click the Copy icon for the Name ID Format setting to copy this value in the Required claim setting when configuring the Microsoft Entra ID provider (step 11 of that procedure).

17. Leave other settings as they are.