Configuring PayAnalytics SSO/SAML against Google (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 Google Workspace as an Identity Provider, "IdP".

Roles & Responsibilities

• IT specialist: A person within the customer 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 to set up a “Web and mobile app” on Google Workspace Admin.

Procedure

1. IT specialist: Log into the Google Admin panel (admin.google.com) and click “Apps” > “Web and mobile apps”

2. IT specialist: In the Google Admin panel, click “Add app” and then “Add custom SAML app” (see Figure 4.1)

Figure 4.1: Entering the “New App” flow

3. IT specialist: In the Google Admin panel, Step 1 (“App details”), fill in the App name and Description fields as needed. A logo is available here (see Figure 4.2)

Figure 4.2: App details screen

4. IT specialist: In the Google Admin panel, on step 2 (“Google Identity Provider details”), observe the values provided in the page (see Figure 4.3). You will use them in later steps.

Figure 4.3: Google IdP configuration values to be copied to PayAnalytics interface

5. PayAnalytics system owner: Open a new browser tab where you 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.

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

7. IT specialist / PayAnalytics system owner: In PayAnalytics , fill in fields from Google IdP metadata (Figure 4.3) as follows (Caution: The urls look very similar and the ordering of the url fields is reversed between the systems):

   • SSO URL (Google side) -> Identity provider Single Sign-On URL (PayAnalytics side)

   • Entity ID (Google side) -> Identity provider issuer ID (PayAnalytics side)

   • Leave “Identity provider Single logout URL” on the PayAnalytics side empty.

   • Certificate (Google side) -> Identity provider X.509 certificate (PayAnalytics side)

   • See example of filled-out fields in Figure 4.5.

   • Click “Save”.

Figure 4.5: Example of a filled-in screen for PayAnalytics

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

Figure 4.6: Values to be copied from PayAnalytics into Google SSO configuration.

9. IT specialist / PayAnalytics system owner: In the Google Admin panel, click “Continue” to proceed to step 3. Copy the following values from PayAnalytics:

   • PayAnalytics landing URL from identity provider (PayAnalytics side) -> ACS URL (Google side)

   • Service Provider (SP) audience restriction (SP Entity ID) (PayAnalytics side) -> Entity ID (Google side)

   • Optionally provide the URL to your PayAnalytics instance as the “Start URL”

10. IT specialist: In the Google Admin panel, step 3 (“Service provider details”), select the desired “Name ID format”. PayAnalytics supports any choice, select “UNSPECIFIED” if unsure.

11. IT specialist: Click Continue. An example of a filled-in form is provided in Figure 4.7.

Figure 4.7: A filled in “Service provider details” form.

12. IT specialist: In the Google Admin panel, step 4 (“Attribute mapping”), set up the following mappings:

    • First name -> FirstName

    • Last name -> LastName

    • Primary email -> Email

    • A filled out form is demonstrated in Figure 4.8

Figure 4.8: Attribute mapping

13. IT specialist: (Optional) You can automatically assign roles in PayAnalytics based on group membership in the Google environment. Before carrying out this step, roles need to be created in PayAnalytics.

    • This is an optional step. If it is not configured, a superuser needs to manually assign roles to users after they have logged in for the first time. This can also be configured at a later time.

    • For automatic role mapping you use the “Role” attribute. Note that the Google group name needs to match the PayAnalytics role exactly (case sensitive). See Figure 4.9.

Figure 4.9: Role mapping

14. IT specialist: In the Google Admin panel, step 4 (“Attribute mapping”), click “Finish”.

15. IT specialist: In the Google Admin panel, from the overview screen for the PayAnalytics app, click the “User access” box (click anywhere except on the links, see Figure 4.10).

Figure 4.10: User access configuration

16. IT specialist: Configure your organization access to the PayAnalytics application according to preference.

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