API-driven inbound provisioning: HR koppelen aan Entra ID zonder handmatig accounts aanmaken

Voordat je begint, is het goed om te weten welke licenties en technische grenzen voor jouw organisatie gelden.

API-driven provisioning zit in Entra ID P1, P2 en Entra ID Governance, met een licentie voor elke identiteit die je via de API binnenhaalt. De licentie bepaalt ook hoeveel je per dag mag versturen:

• Maximaal 50 operaties per aanroep. Elke operatie is één medewerker.
• Maximaal 40 aanroepen binnen vijf seconden. Daarboven krijg je HTTP 429 (Too Many Requests). Bouw een pauze tussen je verzoeken.
• Overschrijd je het dagquotum, dan krijg je ook 429. Stop dus niet tien records per aanroep in als het er vijftig kunnen zijn.

De inrichting doe je grotendeels één keer. Daarna draait het proces op de achtergrond, mits de aanlevering uit HR goed geregeld is.

1. 1Ga in het Entra-beheercentrum naar Entra ID, Enterprise apps, New application, zoek op "API-driven" en kies de app voor Entra ID of voor AD. Geef hem een naam die zegt welke bron het is, bijvoorbeeld Provision-Medewerkers-HR-naar-AD.
2. 2Open Provisioning, kies Get started en zet de modus op Automatic. Sla op.
3. 3Voor AD: download via de melding de Microsoft Entra provisioning agent, installeer hem op een Windows-server in je domein, kies daarna je domein en de OU waar nieuwe accounts komen, en test de verbinding.
4. 4Vul onder Settings een notificatieadres in. Dat is verplicht: zonder adres gaat de koppeling bij het starten direct in quarantaine.
5. 5Zet onder Settings ook Prevent accidental deletions aan, met een drempel die past bij je organisatie.
6. 6Controleer de attribuutmappings. Standaard herkent de app een bestaande gebruiker door externalId uit je verzoek te vergelijken met employeeId in de directory. Pas dat aan als je personeelsnummer ergens anders staat.
7. 7Kies Start provisioning. De job staat dan te luisteren. Kopieer onder Statistics to date, View technical information de Provisioning API Endpoint.
8. 8Geef je API-client (een app-registratie of managed identity) de applicatiepermissie SynchronizationData-User.Upload en ProvisioningLog.Read.All, met toestemming van een beheerder.

Onder de motorkap verwacht Microsoft een vast formaat. Hieronder zie je hoe zo’n bericht is opgebouwd.

Het endpoint accepteert alleen POST, met Content-Type: application/scim+json. Ontbreekt die header, dan krijg je 400 Bad Request; dat is de meest voorkomende fout. De body is een SCIM BulkRequest met per medewerker een operatie. De velden komen uit het SCIM Core User-schema en de Enterprise User-extensie. Voor eigen velden, zoals een kostenplaats of functiecode, breid je het schema van de app uit.

POST https://graph.microsoft.com/v1.0/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/bulkUpload
Authorization: Bearer {token}
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
  "Operations": [
    {
      "method": "POST",
      "bulkId": "100482",
      "path": "/Users",
      "data": {
        "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
                    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
        "externalId": "100482",
        "userName": "jan.jansen@bedrijf.nl",
        "name": { "givenName": "Jan", "familyName": "Jansen" },
        "displayName": "Jan Jansen",
        "title": "Medewerker crediteuren",
        "active": true,
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
          "employeeNumber": "100482",
          "department": "Financiële administratie",
          "manager": { "value": "100017" }
        }
      }
    },
    {
      "method": "POST",
      "bulkId": "100233",
      "path": "/Users",
      "data": {
        "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
                    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
        "externalId": "100233",
        "active": true,
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
          "department": "Inkoop"
        }
      }
    }
  ],
  "failOnErrors": null
}

• `manager.value` is het externalId van de leidinggevende, niet zijn e-mailadres. De provisioning service zoekt hem zelf op.
• `active: false` schakelt het account uit. Zo verwerk je een vertrek.
• Stuur het volledige record, ook bij een kleine wijziging. Zet je "clear attribute values" (preview) aan, dan kan een weggelaten veld een bestaande waarde leegmaken. Het tweede record hierboven is alleen veilig zolang die instelling uit staat.
• Het antwoord is 202 Accepted, met een Location-header die naar de provisioninglogs van deze job wijst. 202 betekent dat het verzoek is ontvangen, niet dat de accounts er al zijn.

Connect-MgGraph -ClientId $appId -TenantId $tenantId -CertificateThumbprint $thumbprint

$uri  = "https://graph.microsoft.com/v1.0/servicePrincipals/$spId/synchronization/jobs/$jobId/bulkUpload"
$body = Get-Content .\bulkrequest.json -Raw

Invoke-MgGraphRequest -Method POST -Uri $uri -Body $body -ContentType "application/scim+json"

# Even later: wat is er met elk record gebeurd?
Get-MgAuditLogProvisioning -Filter "jobid eq '$jobId'" -Top 50 |
  Select-Object ActivityDateTime, ProvisioningAction,
    @{ n = "Status"; e = { $_.ProvisioningStatusInfo.Status } },
    @{ n = "Fout";   e = { $_.ProvisioningStatusInfo.ErrorInformation.Reason } }

Microsoft kan accounts verwerken, maar haalt niet automatisch gegevens uit ieder HR-pakket. Juist dat deel bepaalt hoeveel beheerwerk je overhoudt.

Microsoft levert het endpoint en de verwerking. Alles daarvoor is aan jou. Wie deze route kiest, bouwt en onderhoudt een eigen koppeling:

• Het ophalen uit HR: een export, een API of een database, met de authenticatie en de wijzigingen van de leverancier.
• Het omzetten naar SCIM: welke HR-velden naar welke SCIM-attributen gaan, datums in het juiste formaat, landcodes, lege velden, de manager als externalId.
• Het plannen: wanneer de koppeling draait, in porties van 50, met pauzes voor de limiet, en wat er gebeurt als een run halverwege stopt.
• Foutafhandeling: de provisioninglogs uitlezen, records die mislukten opnieuw aanbieden, en iemand waarschuwen als het blijft mislukken.
• Een controle vooraf: de drempel van Microsoft telt uitschakelingen en verwijderingen per cyclus. Een export die ineens honderden nieuwe accounts zou aanmaken, of een veld verkeerd vult, vang je zelf af voordat je verstuurt.
• Het verwijderen: het endpoint verwijdert niets. Wil je accounts na een bewaartermijn opruimen, dan regel je dat apart, bijvoorbeeld met de taak Delete user in Lifecycle Workflows.
• De terugweg: e-mailadres of gebruikersnaam terugschrijven naar HR kan deze API niet. Dat is een aparte koppeling.

Voor één bron en een stabiele export is dat te doen, en Microsoft heeft voorbeelden met PowerShell en Logic Apps. Het onderhoud blijft: elke wijziging in het HR-pakket, elk nieuw veld en elke nieuwe werkmaatschappij komt bij je script terecht.