Skip to main content

Provision users and groups using Microsoft Entra (SCIM)

System for Cross-Domain Identity Management (SCIM) is an open standard protocol for automated user provisioning. In Harness, automated provisioning involves creating users and user groups, assigning users to groups, and managing some user attributes (such as names and email addresses). In addition to creating users and groups, automated provisioning also edits and removes users and user groups as and when required.

If Microsoft Entra ID is your identity provider, you can efficiently provision and manage users in your Harness account. Using Microsoft Entra ID's SCIM integration with Harness enables Microsoft Entra ID to serve as a single identity manager, to add and remove users, and to provision user groups. This is especially efficient for managing users at scale.

This topic describes how to use an Microsoft Entra ID SCIM integration for automated provisioning in Harness. To configure this integration, you must take steps in both Microsoft Entra ID and Harness.

Requirements

You need an understanding of:

You must be an Administrator in your Microsoft Entra ID account, and you must be an Account Admin in Harness.

You need a Harness API key and unexpired token that has all Users and User Groups permissions. API keys inherit permissions from the user they are associated with. If you use an API key for a service account, make sure the service account has all Users and User Groups permissions.

Add Harness in Microsoft Entra ID

In Microsoft Entra ID, add Harness to your list of managed SaaS applications from the Microsoft Entra ID Application Gallery.

  1. In your Azure portal, under Azure services, select Microsoft Entra ID (formerly Active Directory).
  2. Select Enterprise applications, and then select All applications.
  3. Select New application.
  4. Search for Harness, select Harness in the results list, and then select Add to add the application to your list of managed SaaS apps in Microsoft Entra ID.

Enable Microsoft Entra ID provisioning for Harness

  1. In your Azure portal, under Azure services, select Microsoft Entra ID (formerly Active Directory).

  2. Select Enterprise Applications, and then select All applications.

  3. Select the Harness app.

  4. Select Provisioning.

  5. For Provisioning Mode, select Automatic.

  6. Configure the Admin Credentials as follows:

    1. For Tenant URL, enter https://app.harness.io/gateway/ng/api/scim/account/ACCOUNT_ID. Replace ACCOUNT_ID with your Harness account ID. You can get your account ID from any Harness URL or by navigating to Account Settings and Overview in Harness.
    2. For Secret Token, enter your Harness Harness API key's token as the SCIM Authentication Token value.
    3. Select Test Connection to ensure that Microsoft Entra ID can connect to Harness. If the connection fails, make sure your API key has admin permissions, and then try again.

  7. Under Settings, in Notification Email, enter the email address for the person or group that should receive provisioning error notification emails.

  8. Select Save.

  9. Under Mappings:

    1. Enable Provision Microsoft Entra ID (formerly Active Directory) Groups and Provision Microsoft Entra ID (formerly Active Directory) Users.

    2. Select Provision Microsoft Entra ID (formerly Active Directory) Users and review the user Attribute Mappings. These user attributes are synchronized from Microsoft Entra ID to Harness. Attributes marked as Matching are used to match Harness user accounts with Microsoft Entra ID user accounts when user attributes need to be updated. Make any changes as necessary.

    3. Select Edit Attribute and make sure Apply this mapping is set to Always if you want to sync create/update changes for the attribute. If you only want to capture this attribute when it's created, select Only during object creation.

    4. Exit the user attribute mappings, and select Provision Microsoft Entra ID (formerly Active Directory) Groups.

    5. Review the group Attribute Mappings. These group attributes are synchronized from Microsoft Entra ID to Harness. Attributes marked as Matching are used to match Harness user groups with Microsoft Entra ID user groups when group attributes need to be updated. Make any changes as necessary.

  10. Under Settings, switch Provisioning Status to On to enable the Microsoft Entra ID provisioning service for Harness.

  11. Under Settings, for Scope, select how you want to sync users and groups to Harness.

Scoping filters

If you want to configure scoping filters for your attribute mappings, go to the Microsoft documentation on Scoping users or groups to be provisioned with scoping filters.

  1. Select Save.

Saving the configuration in Microsoft Entra ID triggers an initial provisioning sync. The initial sync takes longer to run than subsequent syncs. Syncs occur approximately every 40 minutes if the Microsoft Entra ID provisioning service is running. To monitor sync progress, go to Synchronization Details in Microsoft Entra ID. From there you can also find links to provisioning activity reports, which describe all actions performed by the Microsoft Entra ID provisioning service in Harness. For more information about how to read the Microsoft Entra ID provisioning logs, go to the Microsoft documentation on Reporting on automatic user account provisioning.

After enabling Microsoft Entra ID provisioning for Harness, you must assign permissions to user groups in Harness.

Harness user management with Microsoft Entra ID SCIM

Using the Microsoft Entra ID SCIM integration requires you to manage users, user groups, and user/group attributes in Microsoft Entra ID, rather than in Harness. Changes are synced from Microsoft Entra ID to Harness approximately every 40 minutes. Data you must manage in Microsoft Entra ID includes:

  • Adding, removing, and editing group members. Group membership must be managed in Microsoft Entra ID.
  • Renaming user groups. Groups can only be renamed in Microsoft Entra ID.
  • Deleting user groups. Groups can only be deleted in Microsoft Entra ID.
  • Editing user email addresses, full names, and group assignments.
    • You can't edit these user details in Harness if the user was provisioned as part of an Microsoft Entra ID-provisioned user group.
    • If you need to change a user's group (for example, to change their permissions), you must change the user's group membership in Microsoft Entra ID.
    • You must use Microsoft Entra ID to delete Microsoft Entra ID-provisioned users from Harness.

Role and resource group assignments are not controlled in Microsoft Entra ID. You must assign permissions to user groups in Harness.

Group names

When provisioning user groups through SCIM, Harness creates IDs for user groups based on the group name in Microsoft Entra ID. If the name contains periods, dashes, or spaces, those characters are replaced by underscores in the Harness user group ID. For example, if a group's name is example-group in Microsoft Entra ID, the group's Harness ID is example_group.

If an Microsoft Entra ID-provisioned user group has the same name as an existing user group in Harness, Harness retains both groups. To prevent confusion, you can rename the existing Harness group.

After enabling Microsoft Entra ID provisioning for Harness, you can use Microsoft Entra ID to provision individual users or groups containing sets of users. If you use Microsoft Entra ID to provision individual users directly to Harness, these users initially have no user group assignment in Harness. You must assign them to a group, either in Microsoft Entra ID or in Harness. Directly provisioning individual users is the only way that you can change an Microsoft Entra ID user's group membership in Harness. When provisioned as part of an Microsoft Entra ID group, the user's group membership must always be managed through Microsoft Entra ID.

Provisioning errors

If an error prevents adding, updating, or deleting a user in Harness, Azure retries the operation in the next sync cycle. If it fails again, and admin must check the provisioning logs in Microsoft Entra ID to determine the root cause of the failure and take corrective action. For more information, go to the Microsoft documentation on Errors and retries in Microsoft Entra ID app provisioning.

Assign permissions

After user groups are provisioned through SCIM, you can manage permissions granted to the users in those groups by assigning roles and resource groups to user groups in Harness.

Harness roles and resource groups aren't managed in the Microsoft Entra admin center.

If you need to change a user's group (for example, to change their permissions), you must change the user's group membership in Microsoft Entra ID.

I already have a Harness FirstGen Microsoft Entra ID integration

If you currently have a Harness FirstGen App Integration in your IdP, and you want to create one for Harness NextGen, make sure the user information is included in the FirstGen App Integration before attempting to log into Harness NextGen through SSO.

Harness authenticates users using either the FirstGen App Integration or the NextGen App Integration. If you have set up both, Harness continues to use your existing App Integration in FirstGen to authenticate users that attempt to log in using SSO.

For example:

  1. An App Integration is already set up for FirstGen with two users as members: user1@example.com and user2@example.com.

  2. You create the App Integration for Harness NextGen, and you add user1@example.com and user_2@example.com as members.

  3. You provision these users to Harness NextGen through SCIM.

  4. user1@example.com and user_2@example.com try to log in to Harness NextGen through SSO.

  5. The FirstGen App Integration is used for user authentication through SSO.

    • user1@example.com is a member of the FirstGen App Integration. They are successfully authenticated and logged in to Harness NextGen.
    • user_2@example.com is not a member of the FirstGen App Integration. Authentication fails and the user can't log in to Harness NextGen.