# MS Azure / Entra ID User Provisioning

This guide walks you through setting up **user provisioning** from Microsoft Entra ID (formerly Azure Active Directory) to Firstup using the **SCIM protocol**. It includes new customer setup, attribute mapping, and migration support.

## Prerequisites

* An active **Microsoft Entra ID** tenant.
* Admin privileges: *Application Administrator*, *Cloud Application Administrator*, or *Global Administrator*.
* Firstup **SCIM API token** (contact your Account Manager).


**Workflow Summary**

1. Create an Enterprise Application.
2. Attribute Mapping.
3. Create Custom Attributes in Entra.
4. Migrate Existing Customers.
5. User Deprovisioning.


## Create an Enterprise Application

**Step 1: Create Your Application**

1. Sign into the Microsoft Entra Admin Center .
2. Navigate to: `Identity > Applications > Enterprise applications > All applications`
3. Click **New application**.
4. Select **Create your own application**.
5. Name your app (e.g., `Firstup Provisioning`) and select **Integrate any other application you don't find in the gallery (Non-gallery application)**.
6. Click **Create**.


This creates an Enterprise Application in Entra ID, used for provisioning users for Cross-domain Identity Management (SCIM) protocol.

**Step 2: Configure Provisioning**

1. Open your created app and go to **Overview > Provision User Accounts**.
2. Click **Get Started**.
3. Then, in the provisioning page, click **Get Started** (again).
4. Under *Provisioning Mode*, select **Automatic**.
5. Enter the **Tenant URL**:
  * US1: `https://partner.socialchorus.com/ms-azure-ad/scim/v2/`
  * US2: `https://partner.us2.onfirstup.com/ms-azure-ad/scim/v2/`
  * EU: `https://partner.onfirstup.eu/ms-azure-ad/scim/v2/`
6. Paste the **SCIM Secret Token**.
7. Click **Test Connection**, then **Save**.


Microsoft Reference Documentation:  How Application Provisioning works in Azure Active Directory 

## Attribute Mapping

**Step 1: Remove Incompatible Defaults**

1. Select **Mappings**.
2. Select **Provision Azure Active Directory Users**
3. Remove: `Join(" ", [givenName], [surname])`
4. Remove: `country` (Entra uses free text; Firstup expects a 2-digit ISO).


**Step 2: Define Identifier Matching**

If users already exist in Firstup, you need to ensure the Entra ID’s Matching precedent matches the User File Sync Universal Identifier that maps to `userName` key in the SCIM Standard. This can be one of:

* `employeeId`
* `mail`
* Alternative attrbute.


1. Select **userPrincipleName**.
2. Dependng on the attribute used to map, update **Source attribute** to:


* **employeeId** or;
* **mail** or;
* an alternative attribute of your choice.


1. Select **Ok**.


Match this to `userName` in SCIM.

**Step 3: Required Field Mappings**

Update any of the required fields to map to the correct Entra ID field.

* `givenName` → First Name
* `surname` → Last Name
* `mail` → Email Address


Entra SCIM only updates fields that contain values. If a field in Entra is empty, it will not overwrite the corresponding value in Firstup. Likewise, removing a value in Entra will not automatically clear it in Firstup.

**Step 4 Optional: Custom Fields**

You have established the essential mapping needed to initiate the user provisioning process from Entra ID to the Firstup platform.

It's important to emphasize that you only need a matching field assigned to the Target attribute `userName`, complemented by `givenName`, `surname`, and `mail` to complete the minimal set of required fields for successful mapping.

## Create Custom Attributes in Entra ID

**Step 1: Get Field Name**

1. Get Field Name. Standard Firstup Custom SCIM Fields:


* `birthDate`
* `hireDate`
* `businessUnit`
* `gender`
* `managerName`
* `workLocation`


**Step 2: Get User ID**

1. If the field exists currently you will need to determine what the key is in the Firstup API.
2. Using the Token from `GET {baseUrl}ms-azure-ad/scim/v2/Users/{user_id}` where `{user_id}` equals a Firstup User ID that contains the required field.
3. Locate the key `urn:ietf:params:scim:schemas:extension:SocialChorus:2.0:User` in this object there is a `customAttributes` key. Each key inside this object represents the Custom Attributes associated to the user.


**Example Country**


```
{
    "urn:ietf:params:scim:schemas:extension:SocialChorus:2.0:User": {
        "customAttributes": {
            "country": "USA"
        },
        "birthDate": null,
        "hireDate": "2023-09-19T00:00:00.000Z",
        "businessUnit": null,
        "gender": null,
        "managerName": null,
        "workLocation": null,
        "_version": "5d578c34761e944ea1d67e4d1c4ae0f5"
    }
}
```

**Step 3: Add Custom Field in Entra**

1. In **Attribute Mapping**, select **Show advanced options**.
2. Select **Edit attribute list for customappsso**.
3. Scroll to the bottom and enter:


* Standard Firstup Attribute: `urn:ietf:params:scim:schemas:extension:SocialChorus:2.0:User:` and the field name from above.
* Custom Firstup User Attribute: `urn:ietf:params:scim:schemas:extension:SocialChorus:2.0:User:customAttribute`. and the field name from before.


1. Select **Save**.


**Examples**

* Standard example -  hire date: `urn:ietf:params:scim:schemas:extension:SocialChorus:2.0:User:hireDate`
* Custom example - country: `urn:ietf:params:scim:schemas:extension:SocialChorus:2.0:User:customAttribute.country`


**Step 4: Map the New Attributes**

1. Go to **Attribute Mapping > Add New Mapping**.
2. Set:
  * Mapping type: Direct
  * Source attribute: Entra Field
  * Default value if null (optional): Populate if required
  * Target attribute: Firstup Attribute that you added
  * Match objects using this attribute: No
*This setting is No because the matching logic is handled by the `userName` field already.*


For advanced attribute mapping, see Microsoft's official SCIM [documentation](https://learn.microsoft.com/en-us/azure/active-directory/app-provisioning/customize-application-attributes).

## Tips

* Use Entra's on-demand provisioning to trigger updates.
* Clean up default mappings before provisioning.
* Use accurate matching logic to prevent user duplication.


## User Deprovisioning

* When users are removed from Entra or unlinked from the Enterprise App, they are **automatically deprovisioned in Firstup**.
* Deprovisioning includes **GDPR-compliant data deletion**.
* This runs during Entra's regular sync cycle.


Need help? Contact your Firstup Technical Consultant or Account Manager for guidance.