Skip to main content

On-prem Active Directory: Setup for user provisioning

R
Written by Riya Sebastian
Updated over 3 weeks ago

User provisioning is essential to keep access and identity in sync during onboarding, offboarding, and role changes. With Atomicwork, you can automate user provisioning to on-premise Active Directory (AD) using Microsoft Entra’s API-driven provisioning framework, eliminating manual effort and reducing security risks.

Based on updates to any system of record, such as your HR or payroll platforms, you can trigger workflows in Atomicwork that provision users in on-prem AD, sync them to Azure AD via AD Connect, and kick off any follow-up actions such as notifications or access assignments. This ensures:

  • Consistency: User data is reliably synced across systems.

  • Efficiency: Workflows replace manual steps and reduce provisioning time.

  • Security: Accounts are automatically deactivated or updated when needed.

  • Scalability: Handles large number of provisioning tasks without extra overhead.

How it works

The integration leverages Microsoft’s secure, SCIM-based provisioning API and Atomicwork's webhook actions in workflows to automate user provisioning. Here’s how it works:

  1. Your system of record (e.g., an HRIS) registers an event like a new hire or role change.

  2. This is captured in Atomicwork via a service catalog item to create a new request.

  3. The request triggers the user provisioning workflow in Atomicwork which:

    • Authenticates using a registered service principal to fetch an OAuth token

    • Sends a SCIM API request with user details to the Azure provisioning app endpoint for on-prem AD. The API payload will include a unique identifier such called externalId to ensure identity consistency across systems and avoid duplicate provisioning

  4. The Microsoft Entra Provisioning Agent—installed on your on-prem server—processes the request and creates or updates the user in AD.

  5. Azure AD Connect then syncs the user to Azure AD

  6. Atomicwork proceeds with any additional actions like user creation within Atomicwork or sending alerts to relevant teams

What is the externalId and why does it matter?

The externalId is a core concept in SCIM-based (System for Cross-domain Identity Management) identity provisioning. It serves as a client-side identifier to uniquely match a user across different systems.

While on-prem AD does not include an externalId attribute by default, it can be mapped to fields like employeeID or any custom extension attributes.

This mapping is crucial to:

  • Avoid duplicate user creation when retries happen

  • Enable idempotent provisioning behavior

  • Support reliable matching across sync cycles

Azure AD Connect Cloud Provisioning, for instance, typically maps externalId to the employeeID field in AD.

Setup for onboarding user provisioning

Step 1: Create an enterprise application for provisioning in Microsoft Entra

  • Go to the Microsoft Entra admin portal and navigate to Enterprise Applications > New application

  • Search for and select API-driven provisioning to on-premises Active Directory

  • Provide a name for your application and create the app

  • Grant the required permissions to enable provisioning and logging for the API endpoint.

    The following are mandatory permissions:

    • SynchronizationData-User.Upload – Allows Atomicwork to send user data into Microsoft Entra for provisioning

    • AuditLog.Read.All – Enables tracking of provisioning events and troubleshooting via Entra audit logs

  • Open the newly created app and select the Provisioning tab

  • Configure attribute mappings to align the SCIM user schema with your on-prem AD attributes

  • Click Start provisioning to activate the service

  • Copy the Provisioning API Endpoint to your clipboard

For additional details or FAQs regarding the app configuration, refer to Microsoft's article on creating the API-driven inbound provisioning app.

Step 2: Install the Microsoft Entra provisioning agent

Step 3: Configure a service principal to call the provisioning app

To access the provisioning app securely, you need to configure a service principal in Azure AD. Refer to Microsoft's article on granting access to the inbound provisioning API for further details.

  • Copy the client ID, tenant ID and the created client secret.

Step 4: Setup a webhook-based workflow in Atomicwork

  • Go to your Atomicwork tenant (eg. https://yourcompany.atomicwork.com) and navigate to Settings > Your Workspace name > Workflows

  • Create a new workflow for on-prem AD user provisioning

  • Set up the trigger based on how your system-of-record data enters Atomicwork—for example, through a service catalog request

  • Use the Azure action - Generate unique email from name to create the user email ID from the given name information

  • Configure a Create a webhook action to generate a token to access the provisioning app:

    • Choose the POST method and paste https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token as the API URL, updating the tenant ID as copied.

    • Include the client ID and client secret from the service principal under Body

      {    "client_id": "{client_id} ",    "client_secret": "{client_secret} ",    "scope": "https://graph.microsoft.com/.default",    "grant_type": "client_credentials"	}

    • Test the connection and click Done

  • Configure another webhook action to create/update the user in on-prem AD:

    • Choose the POST method and paste the Provisioning API Endpoint from your app

    • Add the following key-value pairs under Headers:

    • Add the SCIM payload with the required placeholders under Body. Ensure that the externalId is mapped to correct attribute from your input data (eg. employeeId)

      {  "schemas": [    "urn:ietf:params:scim:api:messages:2.0:BulkRequest"  ],  "Operations": [    {      "method": "POST",      "bulkId": "bulk-user-create",      "path": "/Users",      "data": {        "schemas": [          "urn:ietf:params:scim:schemas:core:2.0:User",          "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"        ],        "externalId": "######{{request.service_item.employee_id}}",        "userName": "######{{action.response.body.email}}",        "name": {          "formatted": "######{{request.service_item.employee_name}} ######{{request.service_item.last_name}}",          "familyName": "######{{request.service_item.last_name}}",          "givenName": "######{{request.service_item.employee_name}}"        },        "firstName": "######{{request.service_item.employee_name}}",        "lastName": "######{{request.service_item.last_name}}",        "displayName": "######{{request.service_item.employee_name}} ######{{request.service_item.last_name}}",        "nickName": "######{{action.fetch_email.response.body.email?split('@')[0]}}",        "emails": [          {            "value": "######{{action.response.body.email}}",            "type": "work",            "primary": true          }        ],        "title": "######{{request.service_item.position_title}}",        "active": true,        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {          "department": "######{{request.service_item.users_department}}",          "manager": {            "value": "######{{action.fetch_manager.response.body.employeeId}}",            "displayName": "######{{action.fetch_manager.response.body.givenName}} ######{{action.fetch_manager.response.body.surname}}"          }        }      }    }  ],  "failOnErrors": null}

    • Test the connection and click Done

  • Add a Wait action of upto 60 minutes to allow Azure AD Connect to sync the user details from on-prem AD

  • Use the Azure action - Reset a user's password to either auto-generate a password or force the user to reset the password on the next login

  • Retrieve the user's email address using the Azure action - Get user details from email

  • Notify the user of the update by using the Send an email action with the required information

  • Add additional actions to the workflow to suit your onboarding/offboarding flow

  • Click on Publish to activate the workflow

Setup for offboarding user provisioning

To manage user provisioning during offboarding:

  • Follow steps 1 to 3 as above.

  • In step 4, when adding the SCIM payload, the "active" property needs to be set to false.

By combining Azure Entra's provisioning framework with Atomicwork's workflow engine, organizations can fully automate the user onboarding process into on-premises AD and Azure AD. This ensures consistency, reduces operational overhead, and enhances employee onboarding experiences.

Did this answer your question?