This guide explains how to install and configure the Freshservice SCIM provisioning app with Microsoft Entra ID.

SCIM automates user provisioning from Microsoft Entra ID to Freshservice. It creates users, updates existing users, and deactivates users when required. SCIM does not delete users from Freshservice.

Before You Start

Before configuring SCIM, make sure you have the following:

  • Freshservice admin access: Install the app using an Account Admin or a user with the required admin privileges. Do not use an Occasional Agent, as their day pass expires after 24 hours and the connection will stop working when it expires.

  • Attribute mapping plan: Decide which Microsoft Entra ID attributes should map to which Freshservice user fields, such as name, job title, and department.

  • Existing field values: Ensure that any required departments, locations, and dropdown values already exist in Freshservice.

Step 1: Install the SCIM App in Freshservice

  1. Log in to Freshservice using an Account Admin account or a user with admin privileges.

  2. Go to Admin > Apps.

  3. Search for Azure Active Directory provisioning (SCIM).

  4. Click Install and authorize the app.

  5. After installation, note the following details:

    • SCIM endpoint URL

    • OAuth token

Keep both values secure. You will need them to configure provisioning in Microsoft Entra ID.

Important: The OAuth token is valid for 365 days. To generate a new token, you must uninstall and reinstall the app. Never share the token in support tickets or emails.

Step 2: Add the App in Microsoft Entra ID

  1. Sign in to the Microsoft Entra admin centre.

  2. Go to Enterprise applications > New application.

  3. Search for Freshservice Provisioning in the application gallery.

  4. Select the app and click Create.

Important: Make sure you select Freshservice Provisioning. Do not use the Freshservice single sign-on app or the SAML Toolkit for SCIM provisioning.

If you see the message "out of the box provisioning is not supported", you have likely selected the wrong application. Add Freshservice Provisioning instead.

Step 3: Configure the Connection

  1. Open the newly created enterprise application.

  2. Go to Provisioning.

  3. Under Admin Credentials, enter the following details:

    • Tenant URL: Enter the SCIM endpoint URL copied from Freshservice.

    • Secret Token: Enter the OAuth token generated by the Freshservice app.

  4. Click Test Connection.

  5. If the test succeeds, click Save.

If the connection test fails with a "not authorized" error, refer to OAuth Token Expired or Not Authorized Error: How to Fix.

Step 4: Review and Configure Attribute Mappings

Attribute mappings determine how user information is transferred from Microsoft Entra ID to Freshservice.

Review the default mappings

  1. Go to Provisioning > Mappings.

  2. Click Provision Microsoft Entra ID Users.

  3. Review the existing attribute mappings and verify the following:

    • userPrincipalName is mapped to userName.

    • The externalId mapping is retained. Do not remove this mapping, as it is required for provisioning to work correctly.

    • Optional attributes, such as department, jobTitle, and physicalDeliveryOfficeName, are mapped according to your requirements.

Add a custom attribute

To map an Entra ID attribute to a custom Freshservice user field:

  1. On the mapping screen, scroll down and click Show advanced options > Edit attribute list for Freshservice.

  2. Add a new attribute using the following naming format:

    urn:ietf:params:scim:schemas:extension:freshservice:2.0:User:<field_key>

    Replace <field_key> with the appropriate Freshservice field key. The corresponding field must already exist in Freshservice.

  3. Select a data type that matches the Freshservice field and click Save.

  4. Return to the attribute mapping screen.

  5. Click Add New Mapping.

  6. Select the Microsoft Entra ID source attribute and map it to the newly added Freshservice target attribute.

  7. Save your changes.

Note: Microsoft Entra ID sends employee_id as a string. Therefore, the corresponding Freshservice field must be a text field.

Step 5: Assign Users or Groups

You must assign users or groups to the enterprise application before provisioning can be tested or started.

  1. Open the Users and groups tab.

  2. Click Add user/group.

  3. Select the users or groups you want to provision.

  4. Click Assign.

Only assigned users and groups are included in provisioning, subject to your provisioning scope and configuration.

Step 6: Test Provisioning and Start the Sync

Before enabling automatic provisioning, test the configuration with a single user.

Test one user

  1. Go to the Provisioning tab.

  2. Select Provision on demand.

  3. Choose a user who already exists in Freshservice.

  4. Run the provisioning operation.

  5. Verify that the existing Freshservice user is updated correctly and that no duplicate user is created.

For detailed instructions, refer to How to Test One User with Provision on Demand.

Start automatic provisioning

Once the test succeeds:

  1. Return to the Provisioning tab.

  2. Click Start provisioning.

  3. Monitor the provisioning status and logs to confirm that synchronization is working as expected.

Microsoft Entra ID typically runs automatic provisioning approximately every 40 minutes.

Best Practices

Follow these recommendations to maintain a reliable SCIM connection:

  • Do not manually change userName in Freshservice after SCIM provisioning is enabled. Changes may be overwritten during subsequent syncs.

  • Test before enabling automatic provisioning. Use Provision on demand to validate the configuration with an existing user.

  • Create dropdown values in advance. Values for fields such as company or region must already exist in Freshservice; otherwise, provisioning may fail.

  • Verify departments and locations. Ensure the required departments and locations exist in Freshservice before starting synchronization.

  • Retain the externalId mapping. Removing it can affect provisioning behavior.

  • Renew the OAuth token before it expires. Uninstall and reinstall the app to generate a new token, then update the Secret Token in Microsoft Entra ID.

  • Monitor provisioning logs. Review errors regularly and correct mapping or configuration issues as needed.

Troubleshooting

If provisioning does not work as expected, refer to the following knowledge base articles:

Need Help?

If you encounter complex provisioning issues or need assistance interpreting provisioning logs, contact our support team at support@effy.co.in.