SCIM User Provisioning

If your organization manages people in Microsoft Entra ID (Azure AD), you can provision them into Ditio automatically instead of maintaining users in two places. Ditio supports the SCIM 2.0 protocol: when someone joins, changes role, or leaves in your directory, the change flows into Ditio on the next provisioning cycle.

What SCIM provisioning does

• Creates new Ditio accounts when people join your team or organization
• Assigns the correct base role to users in Ditio
• Updates user profiles when changes are made in Entra ID
• Deactivates Ditio accounts when people leave the team or organization

Note

Data flows one way: Entra ID → Ditio. Changes made in Ditio are not synced back — your directory is treated as the master source.

Limitations

• Group provisioning is not supported
• Write-back from Ditio to Entra ID is not supported

Prerequisites

1. An Entra ID (Azure AD) tenant with an active subscription
2. A Ditio company already registered
3. Provide your Azure Tenant ID to Ditio — we need it to generate a JWT security token for the SCIM application

SCIM endpoint and token

Ditio operates a dedicated SCIM endpoint per environment (production and test). When you send your Azure Tenant ID to support@ditio.no, Ditio replies with:

• the SCIM endpoint URL (the “Tenant URL” in Azure’s provisioning setup)
• a secret token used to fetch the JWT bearer token for the integration

The secret is sent separately for security.

Test environment

There is a separate SCIM endpoint for the Ditio test environment — useful for verifying attribute mappings against test data before provisioning into production.

Setup in Azure

1. Sign in to the Azure Portal
2. Go to Enterprise Applications → select your Ditio application
3. Go to the Provisioning configuration page
4. Set Provisioning Mode to Automatic
5. Enter the SCIM endpoint URL and the JWT token provided by Ditio

For detailed instructions, see Microsoft’s guide: SCIM provisioning with Entra ID.

Attribute mapping

Ensure the following attributes are mapped correctly in Entra ID.

Required attributes

Entra ID attribute	SCIM attribute	Description
userPrincipalName	userName	Email address
Switch([IsSoftDeleted]…)	active	Enable / disable user
displayName	displayName	Full name
telephoneNumber	phoneNumbers[type eq "work"].value	Work phone (either work or mobile is required)
mobile	phoneNumbers[type eq "mobile"].value	Mobile phone (either work or mobile is required)
employeeId	urn:...:enterprise:2.0:User:employeeNumber	Employee number (must be unique within the company)
Extension attribute	urn:...:ditio:1.0:User:birthDate	Date of birth
Extension attribute	urn:...:ditio:1.0:User:employmentStartDate	Employment start date

Optional attributes

Entra ID attribute	SCIM attribute	Description
givenName	name.givenName	First name
surname	name.familyName	Last name
jobTitle	title	Work title
department	urn:...:enterprise:2.0:User:department	Department on the employment
Extension attribute	urn:...:enterprise:2.0:User:costCenter	Sets “Main project number” on the employment
Extension attribute	urn:...:ditio:1.0:User:employmentEndDate	Employment end date (terminates the employment)
Extension attribute	urn:...:ditio:1.0:User:builderCard	Builder card ID
Extension attribute	urn:...:ditio:1.0:User:builderCardExpirationDate	Builder card expiration date
Extension attribute	urn:...:ditio:1.0:User:payrollConnected	true = hourly paid, false = fixed salary
Extension attribute	urn:...:ditio:1.0:User:workTimeArrangement	Work time arrangement table
Extension attribute	urn:...:enterprise:2.0:User:organization	Organization number (which Ditio company to create the user in)
Extension attribute	urn:...:ditio:1.0:User:tags	Key-value pairs, e.g. "tag1:false,tag2:true"
manager	urn:...:enterprise:2.0:User:manager.value	Sets the user’s nearest manager. The value must be the Entra Object ID of an existing Ditio user; the resolved user becomes the primary immediate supervisor. Existing non-primary supervisors are preserved. Removing the attribute does not clear an existing supervisor.

Supported date formats

• dd.MM.yyyy (e.g. 15.01.2026)
• ddMMyyyy (e.g. 15012026)
• yyyy-MM-dd (e.g. 2026-01-15)

Note

If some attributes don’t appear in the mapping UI, tick “Show advanced options” and edit the attribute list.

Adding extension attributes in Entra ID

Extension attributes (for fields like birthDate and employmentStartDate) can be added in two ways.

Option 1: use existing extension attributes

Set-ADUser -Identity "anyUser" -Add @{extensionAttribute4="myString"}

Option 2: create custom extension attributes

See Microsoft’s guides:

• Syncing extension attributes for provisioning
• Add custom attributes flow

Setting extension values:

Set-AzureADUserExtension `
  -ObjectId {objectId} `
  -ExtensionName extension_{your_extension_id}_BuilderCardId `
  -ExtensionValue "Builder Card Value"

Reading all user properties including extensions:

(Get-AzureADUser -ObjectId {objectId}).ToJson()

Testing

Test with individual users before running a full provisioning cycle:

1. Go to Enterprise Applications → your Ditio app → Users and Groups
2. Add a few test users
3. Use Azure’s on-demand provisioning to provision them manually
4. Verify the users appear correctly in Ditio
5. Once confirmed, enable automatic provisioning for all users

⚠️ Production environment

A misconfigured active mapping can deactivate real accounts. Always verify the mapping with on-demand provisioning of a handful of users before enabling the full cycle against production.

Common issues

Issue	Cause	Fix
User skipped during provisioning	Missing required attribute (phone, employee number, birth date, employment start date)	Check the provisioning log in Azure; fill the attribute in Entra ID
Duplicate employee number	employeeId already in use in the Ditio company	Employee numbers must be unique within a company — correct the conflicting value
User lands in the wrong company	organization attribute doesn’t match a Ditio company organization number	Verify the organization number mapping with Ditio support
Nothing happens after setup	Provisioning cycle hasn’t run yet	Azure runs cycles roughly every 40 minutes; use on-demand provisioning to test immediately

Alternatives

• If your HR system (not Entra ID) is the master, use the Employees API v5 instead
• For sign-in (not provisioning) with Microsoft accounts, see Azure AD SSO

Related

• Azure AD SSO — single sign-on setup
• Employees API v5 — API-based employee management
• Users API (v4) — legacy user endpoints
• SCIM specification