Setting up User Provisioning is a six-piece configuration: enable the Connected App, pick the protocol (SCIM or custom Apex), configure OAuth credentials for the target system, build the user attribute mapping, choose the event triggers, and verify with a small pilot group. Each piece is independent of the others, but they have to be wired up in the right order or the first provisioning attempt fails silently. The pilot group is the most important step: never roll out User Provisioning to all users in one shot.
- Configure the Connected App and OAuth for the target system
Open Setup, App Manager, and find or create the Connected App that represents the target system. In the Connected App configuration, enable OAuth Settings, choose the right OAuth scopes (api, refresh_token, openid usually), and generate the Consumer Key and Consumer Secret. Configure the OAuth callback URL with the target system administrator. On the target side, register Salesforce as an OAuth client with the Consumer Key and Secret. Authorize the Connected App once as an admin user with the right target-system permissions, since the resulting refresh token is what User Provisioning uses for all subsequent calls.
- Pick the provisioning protocol and configure the connector
In the Connected App User Provisioning section, click Configure User Provisioning. The wizard asks whether the target system supports SCIM. If yes, enter the SCIM endpoint URL and select the connector. If no, click Create Custom Connector and supply the Apex class that implements the UserProvisioning.Plugin interface. The Apex class has to be written by a developer and deployed to the org separately; the wizard only references it. Configure the protocol-specific options (SCIM version, custom Apex parameter values) and save before moving to attribute mapping.
- Build the user attribute mapping
The attribute mapping wizard shows the target system user schema (loaded automatically over SCIM, or manually defined for custom Apex). Map each required target field to a Salesforce User attribute or a Salesforce expression. Common mappings: target Username from Salesforce Username; target FirstName from Salesforce FirstName; target Email from Salesforce Email; target Department from Salesforce Department; target Role from Salesforce Permission Set Group. Mark each mapping as required or optional based on the target system rules. Test the mapping by selecting a test user and clicking Preview, which shows the actual SCIM payload Salesforce will send.
- Enable triggers, pilot, and roll out
In the wizard final step, choose which events trigger provisioning (Create User, Update User, Deactivate User, Reactivate User). Most orgs enable all four. Save the configuration. Run a pilot by assigning a small group of test users to the Connected App profile or permission set and confirming the target system receives the provisioning calls. Watch the User Provisioning Log for the pilot group for 48 hours, then expand to the full population once you are confident. Never enable for all users on day one; bad mappings discovered mid-rollout are expensive to clean up.
- OAuth refresh tokens expire if not used for the configured token lifetime. When they expire, every provisioning call fails until an admin re-authorizes the Connected App. Monitor token age on a quarterly cadence.
- Attribute mapping is one-way (Salesforce to target). Changes on the target side do not flow back. If users edit profile fields on the target system, they get overwritten on the next Salesforce update.
- User Provisioning is asynchronous. A user activated in Salesforce may not appear in the target system for several minutes. Set expectations with the help desk so they do not file false bugs about missing accounts.
- Permission Set Group changes do not always fire the User Update event automatically. Confirm in sandbox that role changes propagate the way you expect before relying on them for downstream access management.
- Bad mappings can lock real users out of real systems. Always pilot with a small group before rolling out, and always test the deactivation path in sandbox before enabling in production.