UserProvisioningConfig Metadata Type in SFDX

Architectural Overview#

The UserProvisioningConfig metadata type manages automated user lifecycle synchronization between Salesforce and external cloud platforms. When Salesforce operates as an enterprise Identity Provider (IdP) or central authentication hub, administrators require automated workflows to provision, update attributes for, and deprovision downstream accounts when employees change roles or depart the organization.

UserProvisioningConfig bridges Connected Apps with execution engines such as Salesforce Flows or Apex plugins implementing the UserProvisioningPlugin interface. It defines error handling, batch reconciliation schedules, and attribute mapping logic. Managing this configuration as version-controlled metadata ensures that identity governance policies remain consistent across enterprise sandbox environments and production releases.

Directory and File Conventions#

In Salesforce DX projects, UserProvisioningConfig files are located within the userProvisioningConfigs/ folder.

Key Metadata Fields#

The XML schema for UserProvisioningConfig encompasses the following parameters:

Declarative XML and Package Manifest Examples#

The following declarative XML sample defines an automated provisioning configuration for ServiceNow accounts:

<?xml version="1.0" encoding="UTF-8"?>
<UserProvisioningConfig xmlns="http://soap.sforce.com/2006/04/metadata">
    <apexClass>ServiceNowProvisioningHandler</apexClass>
    <connectedApp>ServiceNow_Integration_App</connectedApp>
    <developerName>ServiceNow_User_Sync</developerName>
    <isActive>true</isActive>
    <masterLabel>ServiceNow User Sync</masterLabel>
</UserProvisioningConfig>

Manifest Definition (package.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>ServiceNow_User_Sync</members>
        <name>UserProvisioningConfig</name>
    </types>
    <version>68.0</version>
</Package>

CLI Retrieval and Deployment Commands#

Manage UserProvisioningConfig records using the Salesforce CLI:

# Retrieve all user provisioning configurations
sf project retrieve start --metadata UserProvisioningConfig

# Retrieve a specific provisioning config
sf project retrieve start --metadata UserProvisioningConfig:ServiceNow_User_Sync

# Deploy configuration to an identity staging org
sf project deploy start --metadata UserProvisioningConfig:ServiceNow_User_Sync --target-org idp-sandbox

Architect Best Practices and Gotchas#

• Dependency Sequencing: Ensure that the referenced ConnectedApp and ApexClass or Flow are deployed before or alongside UserProvisioningConfig to avoid broken metadata references.
• Deprovisioning Safeguards: Implement reconciliation audits to guarantee that deactivating a Salesforce user immediately triggers deactivation in target SaaS systems, preventing orphaned active accounts.
• Rate Limiting and Retries: When configuring high-volume provisioning flows, account for downstream API rate limits by queuing requests asynchronously using batch apex or platform events.

Frequently asked questions

What is the primary role of UserProvisioningConfig in Salesforce identity?

It links a Connected App with an Apex or Flow provisioning process to automatically create, update, or deactivate user accounts in third-party SaaS systems.

How do you retrieve UserProvisioningConfig metadata using Salesforce CLI?

Run sf project retrieve start with the metadata flag set to UserProvisioningConfig to download the provisioning configuration files.

Which downstream systems commonly integrate via UserProvisioningConfig?

Common targets include Google Workspace, ServiceNow, Box, Slack, and Workday, synchronizing user accounts whenever a Salesforce user is modified.

Can custom Apex classes handle the provisioning payload transformation?

Yes, UserProvisioningConfig can reference a custom Apex class implementing the UserProvisioningPlugin interface to handle custom API formats.