Delen via

Veelgestelde vragen over api-gestuurde binnenkomende inrichting

  • Artikel

In dit artikel vindt u antwoorden op veelgestelde vragen over api-gestuurde binnenkomende inrichting.

Hoe verschilt de nieuwe inkomende inrichting /bulkUpload-API van MS Graph Users API?

Er zijn aanzienlijke verschillen tussen de inrichtings-/bulkUpload-API en het MS Graph Users API-eindpunt.

  • Payload-indeling: het MS Graph Users API-eindpunt verwacht gegevens in OData-indeling. De payload-indeling van de aanvraag voor de nieuwe inkomende inrichting /bulkUpload-API maakt gebruik van SCIM-schemaconstructies. Wanneer u deze API aanroept, stelt u de header 'Content-Type' in op application/scim+json.
  • Eindresultaat van bewerking:
    • Wanneer identiteitsgegevens worden verzonden naar het EINDPUNT van de MS Graph Users-API, worden deze onmiddellijk verwerkt en vindt er een bewerking maken/bijwerken/verwijderen plaats in het Microsoft Entra-gebruikersprofiel.
    • Aanvraaggegevens die naar de inrichtings-/bulkUpload-API worden verzonden, worden asynchroon verwerkt door de Microsoft Entra-inrichtingsservice. De inrichtingstaak past bereikregels, kenmerktoewijzing en transformatie toe die zijn geconfigureerd door de IT-beheerder. Hiermee wordt een Create/Update/Delete bewerking gestart in het Microsoft Entra-gebruikersprofiel of het on-premises AD-gebruikersprofiel.
  • IT-beheerder behoudt de controle: met API-gestuurde binnenkomende inrichting heeft de IT-beheerder meer controle over hoe de binnenkomende identiteitsgegevens worden verwerkt en toegewezen aan Microsoft Entra-kenmerken. Ze kunnen bereikregels definiëren om bepaalde typen identiteitsgegevens (bijvoorbeeld aannemergegevens) uit te sluiten en transformatiefuncties te gebruiken om nieuwe waarden af te leiden voordat de kenmerkwaarden voor het gebruikersprofiel worden ingesteld.

Is de inkomende inrichting /bulkUpload-API een standaard SCIM-eindpunt?

De MS Graph inkomende inrichting /bulkUpload-API maakt gebruik van het SCIM-schema in de nettolading van de aanvraag, maar is geen gestandaardiseerd SCIM API-eindpunt. Dat zit zo.

Normaal gesproken verwerkt een SCIM-service-eindpunt HTTP-aanvragen (POST, PUT, GET) met SCIM-nettolading en vertaalt deze naar respectieve bewerkingen van (Maken, Bijwerken, Opzoeken) in het identiteitsarchief. Het EINDPUNT van de SCIM-service plaatst de onus van het opgeven van de semantiek van de bewerking, of u een identiteit wilt maken/bijwerken/verwijderen, op de SCIM API-client. Dit mechanisme werkt goed voor scenario's waarin de API-client weet welke bewerking het voor gebruikers in het identiteitsarchief zou willen uitvoeren.

Het binnenkomende inrichten /bulkUpload van MS Graph is ontworpen voor het afhandelen van een ander enterprise identity integration-scenario dat wordt gevormd door drie unieke vereisten:

  1. Mogelijkheid om records bulksgewijs te verwerken (bijvoorbeeld 50.000 records verwerken)
  2. Mogelijkheid om een identiteitskenmerk op te nemen in de nettolading (bijvoorbeeld costCenter, pay grade, badgeId)
  3. Ondersteuning voor API-clients die zich niet bewust zijn van de semantiek van de bewerking. Deze clients zijn niet-SCIM API-clients die alleen toegang hebben tot onbewerkte brongegevens (bijvoorbeeld records in CSV-bestand, SQL-tabel of HR-records). Deze clients hebben niet de verwerkingsmogelijkheid om elke record te lezen en de semantiek van de bewerking in Create/Update/Delete het identiteitsarchief te bepalen.

Het primaire doel van ms Graph inkomende inrichting /bulkUpload-API is om klanten in staat te stellen identiteitsgegevens (bijvoorbeeld costCenter, pay grade, badgeId) te verzenden vanuit elke identiteitsgegevensbron (bijvoorbeeld CSV/SQL/HR) voor uiteindelijke verwerking door Microsoft Entra-inrichtingsservice. De Microsoft Entra-inrichtingsservice verbruikt de bulksgewijze nettoladinggegevens die zijn ontvangen op dit eindpunt, past regels voor kenmerktoewijzing toe die zijn geconfigureerd door de IT-beheerder en bepaalt of de nettolading van de gegevens leidt tot de bewerking (Maken, Bijwerken, Inschakelen, Uitschakelen) in het doelidentiteitsarchief (Microsoft Entra ID/on-premises AD).

Biedt de inrichtings-/bulkUpload-API ondersteuning voor on-premises Active Directory-domeinen als doel?

Ja, de inrichtings-API ondersteunt on-premises AD-domeinen als doel.

Hoe krijgen we het API-eindpunt /bulkUpload voor onze inrichtings-app?

De /bulkUpload-API is alleen beschikbaar voor apps van het type: 'API-driven inbound provisioning to Microsoft Entra ID' en 'API-driven inbound provisioning to on-premises Active Directory'. U kunt het unieke API-eindpunt voor elke inrichtings-app ophalen op de startpagina van de inrichtingsblade. In Statistieken tot heden>technische informatie weergeven kopieert u de URL van het inrichtings-API-eindpunt.

De indeling heeft de volgende indeling:

https://graph.microsoft.com/beta/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/bulkUpload

Hoe voeren we een volledige synchronisatie uit met behulp van de inrichtings-/bulkUpload-API?

Als u een volledige synchronisatie wilt uitvoeren, gebruikt u uw API-client om de gegevens van alle gebruikers van uw vertrouwde bron als bulkaanvraag naar het API-eindpunt te verzenden. Zodra u alle gegevens naar het API-eindpunt hebt verzonden, verwerkt de volgende synchronisatiecyclus alle gebruikersrecords en kunt u de voortgang bijhouden met behulp van het API-eindpunt van de inrichtingslogboeken.

Hoe voeren we deltasynchronisatie uit met behulp van de inrichtings-/bulkUpload-API?

Als u een deltasynchronisatie wilt uitvoeren, gebruikt u uw API-client om alleen informatie te verzenden over gebruikers van wie de gegevens zijn gewijzigd in de vertrouwde bron. Zodra u alle gegevens naar het API-eindpunt hebt verzonden, verwerkt de volgende synchronisatiecyclus alle gebruikersrecords en kunt u de voortgang bijhouden met behulp van het API-eindpunt van de inrichtingslogboeken.

Hoe werkt het inrichten van opnieuw opstarten?

Gebruik de optie Opnieuw opstarten alleen als dat nodig is. Dit werkt als volgt:

Scenario 1: Wanneer u op de knop Inrichten opnieuw opstarten klikt en de taak momenteel wordt uitgevoerd, blijft de taak de bestaande gegevens verwerken die al zijn gefaseerd. Deinrichtingsbewerking Opnieuw opstarten onderbreekt geen bestaande cyclus. In de volgende cyclus wist de inrichtingsservice alle borgen en kiest de nieuwe bulkaanvraag voor verwerking.

Scenario 2: Wanneer u op de knop Inrichting opnieuw opstarten klikt en de taak niet wordt uitgevoerd, verwijdert de inrichtingsengine de gegevens die zijn geüpload vóór het opnieuw opstarten, wist de eventuele borgs en verwerkt alleen nieuwe binnenkomende gegevens.

Hoe maken we gebruikers met behulp van het inrichtings-/bulkUpload-API-eindpunt?

Hier ziet u hoe de inrichtingstaak die is gekoppeld aan het /bulkUpload-API-eindpunt, binnenkomende nettoladingen van gebruikers verwerkt:

  1. De taak haalt de kenmerktoewijzing voor de inrichtingstaak op en noteert het overeenkomende kenmerkpaar (standaard externalId wordt api-kenmerk gebruikt om overeen te komen met employeeId in Microsoft Entra-id).
  2. U kunt dit standaardkenmerkkoppelingspaar wijzigen.
  3. De taak extraheert elke bewerking die aanwezig is in de nettolading van de bulkaanvraag.
  4. De taak controleert de overeenkomende waarde in de aanvraag (standaard het kenmerk externalId) en gebruikt deze om te controleren of er een gebruiker in Microsoft Entra-id is met overeenkomende employeeId waarde.
  5. Als de taak geen overeenkomende gebruiker vindt, past de taak de synchronisatieregels toe en maakt een nieuwe gebruiker in de doelmap.

Om ervoor te zorgen dat de juiste gebruikers worden gemaakt in Microsoft Entra ID, definieert u het juiste overeenkomende kenmerkpaar in uw toewijzing waarmee gebruikers in uw bron en Microsoft Entra-id uniek worden geïdentificeerd.

Hoe genereren we unieke waarden voor UPN?

De inrichtingsservice biedt niet de mogelijkheid om te controleren op dubbele userPrincipalName (UPN) en conflicten af te handelen. Als de standaardsynchronisatieregel voor het UPN-kenmerk een bestaande UPN-waarde genereert, mislukt de bewerking voor het maken van de gebruiker.

Hier volgen enkele opties die u kunt overwegen voor het genereren van unieke UPN's:

  1. Voeg de logica toe voor unieke UPN-generatie in uw API-client.
  2. Werk de synchronisatieregel voor het UPN-kenmerk bij om de functie RandomString te gebruiken en stel de toewijzingsparameter toepassen in op On object creation only. Voorbeeld:

Join("", Replace([userName], , "(?<Suffix>@(.)*)", "Suffix", "", , ), RandomString(3, 3, 0, 0, 0, ), "@", DefaultDomain())

  1. Als u inricht voor on-premises Active Directory, kunt u de functie SelectUniqueValue gebruiken en de toewijzingsparameter On object creation onlytoepassen op .

Hoe verzenden we meer HR-kenmerken naar het inrichtings-/bulkUpload-API-eindpunt?

Standaard biedt het API-eindpunt ondersteuning voor het verwerken van elk kenmerk dat deel uitmaakt van het SCIM Core User- en Enterprise User-schema. Als u meer kenmerken wilt verzenden, kunt u het schema van de inrichtings-app uitbreiden, de nieuwe kenmerken toewijzen aan Microsoft Entra-kenmerken en de bulkaanvraag bijwerken om deze kenmerken te verzenden. Raadpleeg de zelfstudie Api-gestuurde inrichting uitbreiden om aangepaste kenmerken te synchroniseren.

Hoe sluiten we bepaalde gebruikers uit van de inrichtingsstroom?

Mogelijk hebt u een scenario waarin u alle gebruikers naar het API-eindpunt wilt verzenden, maar alleen bepaalde gebruikers in de inrichtingsstroom wilt opnemen en de rest wilt uitsluiten.

U kunt dit bereiken met behulp van het bereikfilter. In de configuratie van de inrichtings-app kunt u een bronobjectbereik definiëren en bepaalde gebruikers uitsluiten van verwerking met behulp van een 'insluitingsregel' (bijvoorbeeld alleen gebruikers verwerken waarbij afdeling EQUALS Sales is toegewezen) of een uitsluitingsregel (bijvoorbeeld gebruikers uitsluiten die behoren tot Verkoop, afdeling NOT EQUALS Sales).

Zie Bereikgebruikers of groepen die moeten worden ingericht met bereikfilters.

Hoe werken we gebruikers bij met behulp van het inrichtings-/bulkUpload-API-eindpunt?

Hier ziet u hoe de inrichtingstaak die is gekoppeld aan het /bulkUpload-API-eindpunt, binnenkomende nettoladingen van gebruikers verwerkt:

  1. De inrichtingstaak haalt de kenmerktoewijzing voor de inrichtingstaak op en noteert het overeenkomende kenmerkpaar (standaard externalId api-kenmerk wordt gebruikt om overeen te komen met employeeId in Microsoft Entra-id). U kunt dit standaardkenmerkkoppelingspaar wijzigen.
  2. De taak extraheert de bewerkingen uit de nettolading van de bulkaanvraag.
  3. De taak controleert de waarde die overeenkomt met de id in de SCIM-aanvraag (standaard: API-kenmerk externalId) en gebruikt deze om te controleren of er een gebruiker in Microsoft Entra-id is met overeenkomende employeeId waarde.
  4. Als de taak een overeenkomende gebruiker vindt, worden de synchronisatieregels toegepast en worden de bron- en doelprofielen vergeleken.
  5. Als de taak bepaalt dat sommige waarden zijn gewijzigd, wordt de bijbehorende gebruikersrecord in de map bijgewerkt.

Om ervoor te zorgen dat de juiste gebruikers worden bijgewerkt in Microsoft Entra ID, moet u ervoor zorgen dat u het juiste overeenkomende kenmerkpaar definieert in uw toewijzing die gebruikers uniek identificeert in uw bron en Microsoft Entra-id.

Kunnen we meer dan één app maken die ondersteuning biedt voor api-gestuurde binnenkomende inrichting?

Ja, dat kan. Hier volgen enkele scenario's waarvoor mogelijk meer dan één inrichtings-app is vereist:

Scenario 1: Stel dat u drie vertrouwde gegevensbronnen hebt: één voor werknemers, één voor aannemers en één voor leveranciers. U kunt drie afzonderlijke inrichtings-apps maken: één voor elk identiteitstype met een eigen afzonderlijke kenmerktoewijzing. Elke inrichtings-app heeft een uniek API-eindpunt en u kunt de respectieve nettoladingen naar elk eindpunt verzenden.

U kunt het unieke API-eindpunt voor elke taak ophalen op de startpagina van de inrichtingsblade. Navigeer naar Statistieken tot heden>Technische informatie weergeven en kopieer vervolgens de URL van het inrichtings-API-eindpunt.

Scenario 2: Stel dat u meerdere waarheidsbronnen hebt, elk met een eigen kenmerkenet. Hr biedt bijvoorbeeld kenmerken voor functiegegevens (bijvoorbeeld jobTitle, employeeType) en Badging System biedt badgeinformatiekenmerken (bijvoorbeeld badgeId die worden weergegeven met een extensiekenmerk). In dit scenario kunt u twee inrichtings-apps configureren:

  • Inrichtings-app #1 die kenmerken van uw HR-bron ontvangt en de gebruiker maakt.

  • Inrichtings-app 2 die kenmerken van het Badging-systeem ontvangt en alleen de gebruikerskenmerken bijwerkt. De kenmerktoewijzing in deze app is beperkt tot de kenmerken Badgeinformatie en onder Alleen doelobjectacties is ingeschakeld.

  • Beide apps gebruiken hetzelfde overeenkomende id-paar (externalId<->employeeId)

Hoe verwerken we beëindigingen met behulp van het API-eindpunt /bulkUpload?

Als u beëindigingen wilt verwerken, identificeert u een kenmerk in uw bron dat wordt gebruikt om de accountEnabled vlag in te stellen in Microsoft Entra-id. Als u inricht in on-premises Active Directory, wijst u dat bronkenmerk toe aan het accountDisabled kenmerk.

Standaard bepaalt de waarde die is gekoppeld aan het schemakenmerk active SCIM Core-gebruiker de status van het account van de gebruiker in de doelmap.

Als het kenmerk is ingesteld op true, wordt met de standaardtoewijzingsregel het account ingeschakeld. Als het kenmerk is ingesteld op false, wordt het account door de standaardtoewijzingsregel uitgeschakeld.

Hoe kunnen we voorkomen dat gebruikers per ongeluk worden uitgeschakeld/verwijderd?

Als u onbedoelde verwijderingen wilt voorkomen en herstellen, raden we u aan om de drempelwaarde voor onbedoeld verwijderen in de inrichtings-app te configureren en de on-premises Prullenbak van Active Directory in te schakelen. Schakel in de blade Kenmerktoewijzing van de inrichtings-app onder Doelobjectacties de bewerking Verwijderen uit.

Verwijderde accounts herstellen

  • Als de doelmap voor de bewerking Microsoft Entra-id is, wordt de overeenkomende gebruiker voorlopig verwijderd. De gebruiker kan de komende 30 dagen worden weergegeven op de pagina Verwijderde gebruikers van het Microsoft Entra-beheercentrum en kan gedurende die tijd worden hersteld.
  • Als de doelmap voor de bewerking on-premises Active Directory is, wordt de overeenkomende gebruiker hard verwijderd. Als de Prullenbak van Active Directory is ingeschakeld, kunt u het verwijderde on-premises AD-gebruikersobject herstellen.

Moeten alle gebruikers vanuit het HR-systeem in elke aanvraag worden verzonden?

Nee, u hoeft niet alle gebruikers te verzenden vanuit het HR-systeem/'bron van waarheid' in elke aanvraag. Stuur de gebruikers die u wilt maken of bijwerken.

Ondersteunt de API alle HTTP-acties (GET/POST/PUT/PATCH)?

Nee, het /bulkUpload-inrichtings-API-eindpunt ondersteunt alleen de POST HTTP-actie.

Als ik een gebruiker wil bijwerken, moet ik een PUT/PATCH-aanvraag verzenden?

Nee, het API-eindpunt biedt geen ondersteuning voor PUT-/PATCH-aanvragen. Als u een gebruiker wilt bijwerken, verzendt u de gegevens die zijn gekoppeld aan de gebruiker in de nettolading van de POST-bulkaanvraag.

De inrichtingstaak die gegevens verwerkt die door het API-eindpunt worden ontvangen, detecteert automatisch of de gebruiker die in de nettolading van de POST-aanvraag is ontvangen, moet worden gemaakt/bijgewerkt/uitgeschakeld op basis van de geconfigureerde synchronisatieregels. Als API-client hoeft u geen stappen meer uit te voeren als u wilt dat een gebruikersprofiel wordt bijgewerkt.

Hoe wordt write-back ondersteund?

De huidige API ondersteunt alleen binnenkomende gegevens. Hier volgen enkele opties die u kunt overwegen voor het implementeren van write-back van kenmerken, zoals e-mail/gebruikersnaam/telefoon die door Microsoft Entra-id wordt gegenereerd, die u kunt terugstromen naar het HR-systeem:

  • Optie 1: SCIM-connectiviteit met HR-eindpunt/proxyservice die de HR-bron op zijn beurt bijwerkt

    • Als het recordsysteem een SCIM-eindpunt biedt voor gebruikersupdates, kunt u een aangepaste SCIM-toepassing maken in de galerie met bedrijfsapps en inrichting configureren zoals gedocumenteerd.
    • Als het recordsysteem geen SCIM-eindpunt biedt, verkent u de mogelijkheid om een proxy-SCIM-service in te stellen, die de update ontvangt en de wijziging doorgeeft aan het HR-systeem.

  • Optie 2: Microsoft Entra ECMA-connector gebruiken voor het write-backscenario

    • Afhankelijk van de behoeften van de klant kunt u verkennen of een van de ECMA-connectors kan worden gebruikt (PowerShell/SQL/Web Services).

  • Optie 3: aangepaste extensietaak voor levenscycluswerkstromen gebruiken in een Joiner-werkstroom

    • Definieer in Levenscycluswerkstromen een joiner-werkstroom en definieer een aangepaste extensietaak die een Logic Apps-proces aanroept, waarmee het HR-systeem wordt bijgewerkt of een CSV-bestand wordt gegenereerd dat door het HR-systeem wordt gebruikt.

Volgende stappen