Payroll provisioning using Microsoft SCIM

What is it for?

• Automates the creation, update, and deactivation of collaborators in Whalemate based on data that already exists in Microsoft Entra ID.

• Eliminates manual or file-based payroll uploads.

• Keeps Microsoft Entra ID groups synchronized with teams/groups in Whalemate.

• Centralizes the source of truth for collaborator data in Microsoft Entra ID, reducing inconsistencies.

How is it used or implemented?

Prerequisite: having Microsoft Entra ID P1 (included in Microsoft 365 E3 for enterprise customers, or in Microsoft 365 Business Premium for SMBs).

1. Create the application in Microsoft Azure

   1. Go to https://portal.azure.com/#home

   2. Go to Enterprise applications

   3. Click on Manage → All applications → + New application

   4. Click on Create your own application

   5. Fill in:

      • Application name: Whalemate SCIM Provisioning

      • Option: Integrate any other application you don't find in the gallery

   6. Press Create

   This creates the application in Microsoft Azure that will enable the integration of payroll with the Whalemate platform.

2. Configure provisioning

   1. Go to Manage → Provisioning → New configuration

   2. Fill in the fields:

      • Authentication method: Bearer authentication

      • Tenant URL: https://back.whalemate.com/scim/v2

      • Secret token

        • How to generate the Secret token:

          • Go to https://app.whalemate.com → Settings → Integrations → Azure AD | SCIM → Import → Generate Bearer Token

          The Bearer Token is shown only once. It is mandatory to copy it and save it in a secure location before closing the dialog, since it cannot be viewed again (the integration can only be managed from there onward).

          Validation: before creating the configuration, you must press Test connection. If the connection is successful, the Create button is enabled; if it fails, you must review the Tenant URL and the Secret token.

          Once created, the configuration Status appears as Disabled until provisioning is started (see step 5).

3. Assign attributes

   1. Go to Manage → Attribute Mapping (preview)

   a) Provision Microsoft Entra ID Users — map the attributes between SCIM and Microsoft Entra ID according to the following correspondence:

   SCIM Attribute (customappsso)

   Microsoft Entra ID Attribute

   Whalemate Collaborator Field

   userName

   userPrincipalName

   Email Address (*)

   emails[0].value

   mail

   Email Address

   name.givenName

   givenName

   First Name

   name.familyName

   surname

   Last Name

   addresses[0].country

   country

   Country

   preferredLanguage

   preferredLanguage

   Language

   title

   jobTitle

   Position

   department (enterprise extension)

   department

   Department

   externalId

   objectId

   —

   (*) If the mail field is empty, it is automatically filled with the User Principal Name (UPN).

   By default, the only field that must be manually modified is externalId, with the value employeeId.

   Matching precedence to establish:

   1. externalId ↔ objectId

   2. userName ↔ userPrincipalName

   3. emails[type eq "work"].value ↔ mail

   b) Provision Microsoft Entra ID Groups — map with the following precedence:

   1. externalId ↔ objectId

   2. displayName ↔ displayName

4. Assign users and groups

   1. Go to Manage → Users and groups → + Add user or group

   2. Click on None Selected, choose the Groups tab, and select the group(s) that will be automatically synchronized for provisioning

   3. Press Select and then Assign

      When assigning a group to the application, only users who are directly in that group will have access. The assignment does not cascade to nested groups.

5. Start provisioning

   1. Go to Manage → Provisioning

   2. Click on Start provisioning

   3. Return to Manage → Provisioning and confirm that the Provisioning Status shows as Enabled

❓ Frequently Asked Questions

• What happens if a collaborator does not have an email configured in Microsoft Entra ID?
  The system automatically fills the field with the user's User Principal Name (UPN).

• Can I view the Bearer Token again if I lose it?
  No. The token is shown only once when generated. If lost, you need to generate a new one from Settings → Integrations → Azure AD | SCIM.

• What version of Microsoft 365 do I need to use this feature?
  You need Microsoft Entra ID P1, included in Microsoft 365 E3 (enterprises) or Microsoft 365 Business Premium (SMBs).

• If I sync a group with nested subgroups, are the subgroups also synced?
  No. The assignment of a group does not cascade to nested groups; only users who belong directly to the selected group are synchronized.

• Is it mandatory to modify all mapped attributes?
  No. By default, the only field that requires manual modification is externalId, which must be configured with the value employeeId.

Do you have feedback or want to request improvements? Let us know at roadmap.whalemate.com/roadmap