Configuring PayAnalytics SSO/SAML against Azure AD/Microsoft Entra ID (IdP)

Purpose

This document describes the steps a technical contact for a PayAnalytics customer is required to carry out in order to configure SSO/SAML authentication for the PayAnalytics online solution (the Service Provider, "SP") using Microsoft Entra ID as an Identity Provider, "IdP".

Azure AD was renamed to Microsoft Entra ID in July 2023.

Roles & Responsibilities

• IT specialist: A person within the customer organization that has access to the Microsoft Entra ID configuration for the organization.

• PayAnalytics system owner: A person within the customer organization that has Superuser access (permissions to create and modify users) to PayAnalytics

Prerequisites

• A dedicated PayAnalytics instance with SSO support enabled has been created for the customer.

• PayAnalytics system owner: Has a user account (using username/password) with Superuser privileges on the PayAnalytics customer instance.

• IT specialist: Has the appropriate privileges on Azure, for example, is assigned to one of the following roles:

  • Global administrator

  • Cloud application administrator

  • Application administrator

Procedure

1. IT specialist: Log into the Azure portal, and under "Azure services" click "Microsoft Entra ID".

2. IT specialist: Click “Enterprise applications”.

3. IT specialist: Create a new Enterprise application by clicking “+ New application” (see Figure 4.1).

Figure 4.1: Microsoft Entra ID menu.

4. IT specialist: In the Microsoft Entra ID Gallery page, select "+ Create your own application". A form displayed in Figure 4.2 will appear.

Figure 4.2: Microsoft Entra ID "Create your own application" form.

5. IT specialist: Set the name of the application (e.g. “PayAnalytics”) and select the "Integrate any other application you don’t find in the gallery (Non-gallery)" option. Click "create".

6. IT specialist: In the newly created application, in the left menu under "Manage" select “Single sign-on”. When asked to "Select a single sign-on method" click SAML (see Figure 4.3).

Figure 4.3: Microsoft Entra ID SSO method selection.

7. PayAnalytics system owner: Log into your PayAnalytics instance as administrator (see Figure 4.4). If you're logging in for the first time you will need to retrieve your password with the "Forgot Password" feature.

Figure 4.4: Administrator login on PayAnalytics SSO login screen.

8. PayAnalytics system owner: In PayAnalytics , open settings (by clicking ) and from the settings page click "SSO (SAML) Configuration".

9. PayAnalytics system owner: Take note of the values in the gray-background boxes (see Figure 4.5)

Figure 4.5: Values to be copied from PayAnalytics into Microsoft Entra ID SAML configuration.

10. IT specialist: Under Microsoft Entra ID configuration section 1 (Basic SAML Configuration), click "Edit". Fill in the values as follows (also, see Figure 4.6):

    • Identifier (Entity ID): Click "Add identifier" and copy/paste the "Service Provider (SP) Audience Restriction (SP Entity ID)" value from PayAnalytics.

    • Reply URL (Assertion Consumer Service URL): Click "Add reply URL" and copy/paste the "PayAnalytics landing URL from Identity Provider." value from PayAnalytics

    • Sign on URL (Optional): Insert the url for your PayAnalytics instance.

Figure 4.6: Microsoft Entra ID Basic SAML Configuration filled in example.

11. IT specialist: Under Microsoft Entra ID configuration section 2 (Attributes & Claims), click "Edit" and make the following modifications:

    • Delete the "user.userprincipalname" entity.

    • Modify the "user.mail" entity: Set Name to "Email" and clear the Namespace field (see Figure 4.7).

    • Modify the "user.givenname" entity: Set Name to "FirstName" and clear the Namespace field.

    • Modify the "user.surname" entity: Set Name to "LastName" and clear the Namespace field.

Figure 4.7: The email claim configuration section in Microsoft Entra ID.

Figure 4.8: Attributes & Claims section. Note that the "Claim name" set be set to a different attribute (e.g. a username). It is required to be a value that is unique per user. It is possible to add an additional claim for “Role” (if set, it will assign or clear the User Role of the user). Be advised however that Microsoft Entra ID does not include empty attributes in the SAML message.

12. IT specialist: Under Microsoft Entra ID configuration section 3 (SAML Signing Certificate), download the Base64 version of the certificate (See Figure 4.9). Open the downloaded file in a text editor, copy the contents and paste into the "Identity Provider X.509 certificate" field in PayAnalytics.

Figure 4.9: Microsoft Entra ID certificate download section.

13. IT specialist: Under Microsoft Entra ID configuration section 4 (Set up ...), identify and copy the following items to PayAnalytics (note that the ordering of the items is reversed between the two systems). An example configuration from PayAnalytics is provided in Figure 4.10.

    • Copy Microsoft Entra ID Identifier from Microsoft Entra ID and paste into "Identity Provider Issuer ID" in PayAnalytics.

    • Copy Login URL from Microsoft Entra ID and paste into "Identity Provider Single Sign-On URL" in PayAnalytics

Figure 4.10: Example of a configured PayAnalytics SSO instance.

14. PayAnalytics system owner: In the PayAnalytics SSO config page, click "Save" (a message will appear confirming that the configuration was saved).

15. IT specialist: In Microsoft Entra ID, click "Users and groups" and add users as needed.

Your SSO/SAML authentication should now be correctly configured and your users can initiate the authentication flow into PayAnalytics by clicking the "Click here to authenticate" button.

Other information

The SP metadata is available on the following url: https://my-company.payanalytics.com/api/v1/sso/metadata