Vanliga frågor och svar om API-driven inkommande etablering

  • Artikel

Den här artikeln besvarar vanliga frågor och svar om API-driven inkommande etablering.

Hur skiljer sig det nya API:et för inkommande etablering/bulkUpload från API:et för MS Graph-användare?

Det finns betydande skillnader mellan API:et provisioning/bulkUpload och MS Graph Users API-slutpunkten.

  • Nyttolastformat: MS Graph Users API-slutpunkten förväntar sig data i OData-format. Formatet för begärandenyttolast för den nya inkommande etableringen/bulkUpload-API:et använder SCIM-schemakonstruktioner. När du anropar det här API:et anger du rubriken "Innehållstyp" till application/scim+json.
  • Slutresultat för åtgärden:
    • När identitetsdata skickas till API-slutpunkten för MS Graph-användare bearbetas de omedelbart och en åtgärd för att skapa/uppdatera/ta bort sker i Microsoft Entra-användarprofilen.
    • Begär data som skickas till etablerings-/bulkUpload-API:et bearbetas asynkront av Microsoft Entra-etableringstjänsten. Etableringsjobbet tillämpar omfångsregler, attributmappning och transformering som konfigurerats av IT-administratören. Detta initierar en Create/Update/Delete åtgärd i Microsoft Entra-användarprofilen eller den lokala AD-användarprofilen.
  • IT-administratören behåller kontrollen: Med API-driven inkommande etablering har IT-administratören mer kontroll över hur inkommande identitetsdata bearbetas och mappas till Microsoft Entra-attribut. De kan definiera omfångsregler för att undanta vissa typer av identitetsdata (till exempel entreprenörsdata) och använda transformeringsfunktioner för att härleda nya värden innan de anger attributvärdena för användarprofilen.

Är api:et för inkommande etablering/bulkUpload en SCIM-standardslutpunkt?

MS Graph-API:et för inkommande etablering/bulkUpload använder SCIM-schema i begärandenyttolasten, men det är inte en standardiserad SCIM API-slutpunkt. Här är anledningen.

Normalt bearbetar en SCIM-tjänstslutpunkt HTTP-begäranden (POST, PUT, GET) med SCIM-nyttolasten och översätter dem till respektive åtgärder för (Skapa, Uppdatera, Leta upp) i identitetslagret. SCIM-tjänstslutpunkten placerar ansvaret för att ange åtgärdssemantiken, om du vill skapa/uppdatera/ta bort en identitet, på SCIM API-klienten. Den här mekanismen fungerar bra för scenarier där API-klienten är medveten om vilken åtgärd den vill utföra för användare i identitetsarkivet.

MS Graph-inkommande etablering /bulkUpload är utformad för att hantera ett annat scenario för integrering av företagsidentiteter som formats av tre unika krav:

  1. Möjlighet att asynkront bearbeta poster i bulk (till exempel bearbetning av 50K+ poster)
  2. Möjlighet att inkludera ett identitetsattribut i nyttolasten (till exempel costCenter, lönegrad, badgeId)
  3. Stöd för API-klienter som inte känner till åtgärdssemantik. Dessa klienter är icke-SCIM API-klienter som bara har åtkomst till rådata (till exempel poster i CSV-fil, SQL-tabell eller HR-poster). Dessa klienter har inte bearbetningsfunktionen för att läsa varje post och fastställa åtgärdens Create/Update/Delete semantik för i identitetsarkivet.

Det primära målet med MS Graph-inkommande etablering/bulkUpload-API är att göra det möjligt för kunder att skicka identitetsdata (till exempel costCenter, lönegrad, badgeId) från alla identitetsdatakällor (till exempel CSV/SQL/HR) för eventuell bearbetning av Microsoft Entra-etableringstjänsten. Microsoft Entra-etableringstjänsten använder massnyttolastdata som tas emot vid den här slutpunkten, tillämpar attributmappningsregler som konfigurerats av IT-administratören och avgör om datanyttolasten leder till (skapa, uppdatera, aktivera, inaktivera) i målidentitetslagret (Microsoft Entra-ID/lokal AD).

Stöder etablerings-/bulkUpload-API:et lokal Active Directory domäner som mål?

Ja, etablerings-API:et stöder lokala AD-domäner som mål.

Hur hämtar vi API-slutpunkten /bulkUpload för vår etableringsapp?

API:et /bulkUpload är endast tillgängligt för appar av typen: "API-driven inkommande etablering till Microsoft Entra-ID" och "API-driven inkommande etablering till lokal Active Directory". Du kan hämta den unika API-slutpunkten för varje etableringsapp från startsidan för etableringsbladet. I Statistik hittills>Visa teknisk information kopierar du URL:en för etablerings-API:ets slutpunkt.

Den har formatet:

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

Hur utför vi en fullständig synkronisering med hjälp av API:et provisioning/bulkUpload?

Om du vill utföra en fullständig synkronisering använder du API-klienten för att skicka data för alla användare från din betrodda källa till API-slutpunkten som massbegäran. När du har skickat alla data till API-slutpunkten bearbetar nästa synkroniseringscykel alla användarposter och gör att du kan spåra förloppet med hjälp av API-slutpunkten för etableringsloggar.

Hur utför vi deltasynkronisering med hjälp av API:et provisioning/bulkUpload?

Om du vill utföra en deltasynkronisering använder du API-klienten för att endast skicka information om användare vars data har ändrats i den betrodda källan. När du har skickat alla data till API-slutpunkten bearbetar nästa synkroniseringscykel alla användarposter och gör att du kan spåra förloppet med hjälp av API-slutpunkten för etableringsloggar.

Hur fungerar etablering av omstart?

Använd alternativet Starta om etablering endast om det behövs. Så här fungerar det:

Scenario 1: När du klickar på knappen Starta om etablering och jobbet körs fortsätter jobbet att bearbeta befintliga data som redan har mellanlagrats. EtableringsåtgärdenStarta om avbryter inte en befintlig cykel. I den efterföljande cykeln rensar etableringstjänsten alla depositionspunkter och väljer den nya massbegäran för bearbetning.

Scenario 2: När du klickar på knappen Starta om etablering och jobbet inte körs, rensar etableringsmotorn data som laddats upp före omstarten, rensar eventuella deposition och bearbetar endast nya inkommande data innan omstarten.

Hur skapar vi användare med api-slutpunkten etablering/bulkUpload?

Så här bearbetar etableringsjobbet som är associerat med api-slutpunkten /bulkUpload inkommande användarnyttolaster:

  1. Jobbet hämtar attributmappningen för etableringsjobbet och noterar det matchande attributparet (som standard externalId används API-attributet för att matcha med employeeId i Microsoft Entra-ID).
  2. Du kan ändra det här matchande standardattributparet.
  3. Jobbet extraherar varje åtgärd som finns i nyttolasten för massbegäran.
  4. Jobbet kontrollerar värdet som matchar identifieraren i begäran (som standard attributet externalId) och använder det för att kontrollera om det finns en användare i Microsoft Entra-ID med matchande employeeId värde.
  5. Om jobbet inte hittar någon matchande användare tillämpar jobbet synkroniseringsreglerna och skapar en ny användare i målkatalogen.

För att säkerställa att rätt användare skapas i Microsoft Entra-ID definierar du rätt matchande attributpar i din mappning som unikt identifierar användare i din källa och Microsoft Entra-ID.

Hur genererar vi unika värden för UPN?

Etableringstjänsten ger inte möjlighet att söka efter duplicerade userPrincipalName (UPN) och hantera konflikter. Om standardsynkroniseringsregeln för UPN-attributet genererar ett befintligt UPN-värde misslyckas åtgärden för att skapa användare.

Här följer några alternativ som du kan överväga för att generera unika UPN:er:

  1. Lägg till logiken för unik UPN-generering i API-klienten.
  2. Uppdatera synkroniseringsregeln för UPN-attributet så att funktionen RandomString används och ange parametern apply mapping till On object creation only. Exempel:

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

  1. Om du etablerar till lokal Active Directory kan du använda funktionen SelectUniqueValue och ange parametern apply mapping till On object creation only.

Hur skickar vi fler HR-attribut till api-slutpunkten för etablering/bulkUpload?

API-slutpunkten stöder som standard bearbetning av alla attribut som ingår i SCIM Core-användar- och företagsanvändarschemat. Om du vill skicka fler attribut kan du utöka schemat för etableringsappen, mappa de nya attributen till Microsoft Entra-attribut och uppdatera massbegäran för att skicka dessa attribut. Se självstudien Utöka API-driven etablering för att synkronisera anpassade attribut.

Hur undantar vi vissa användare från etableringsflödet?

Du kan ha ett scenario där du vill skicka alla användare till API-slutpunkten, men bara inkludera vissa användare i etableringsflödet och exkludera resten.

Du kan uppnå detta med hjälp av omfångsfiltret. I konfigurationen av etableringsappen kan du definiera ett källobjektomfång och undanta vissa användare från att bearbeta antingen med hjälp av en "inkluderingsregel" (till exempel endast bearbeta användare där avdelningen EQUALS Sales) eller en "exkluderingsregel" (till exempel exkludera användare som tillhör Försäljning, avdelning INTE LIKA med försäljning).

Se Omfångsanvändare eller grupper som ska etableras med omfångsfilter.

Hur uppdaterar vi användare med hjälp av api-slutpunkten provisioning/bulkUpload?

Så här bearbetar etableringsjobbet som är associerat med api-slutpunkten /bulkUpload inkommande användarnyttolaster:

  1. Etableringsjobbet hämtar attributmappningen för etableringsjobbet och noterar det matchande attributparet (som standard externalId används API-attributet för att matcha med employeeId i Microsoft Entra-ID). Du kan ändra det här matchande standardattributparet.
  2. Jobbet extraherar åtgärderna från nyttolasten för massbegäran.
  3. Jobbet kontrollerar värdet som matchar identifieraren i SCIM-begäran (som standard: API-attribut externalId) och använder det för att kontrollera om det finns en användare i Microsoft Entra-ID med matchande employeeId värde.
  4. Om jobbet hittar en matchande användare tillämpar det synkroniseringsreglerna och jämför käll- och målprofilerna.
  5. Om jobbet fastställer att vissa värden har ändrats uppdateras motsvarande användarpost i katalogen.

Se till att rätt användare uppdateras i Microsoft Entra-ID genom att definiera rätt matchande attributpar i din mappning som unikt identifierar användare i din källa och Microsoft Entra-ID.

Kan vi skapa fler än en app som stöder API-driven inkommande etablering?

Ja, det kan du. Här följer några scenarier som kan kräva mer än en etableringsapp:

Scenario 1: Anta att du har tre betrodda datakällor: en för anställda, en för leverantörer och en för leverantörer. Du kan skapa tre separata etableringsappar – en för varje identitetstyp med en egen distinkt attributmappning. Varje etableringsapp har en unik API-slutpunkt och du kan skicka respektive nyttolaster till varje slutpunkt.

Du kan hämta den unika API-slutpunkten för varje jobb från startsidan för etableringsbladet. Gå till Statistik hittills>Visa teknisk information och kopiera sedan URL:en för etablerings-API:ets slutpunkt.

Scenario 2: Anta att du har flera sanningskällor, var och en med en egen attributuppsättning. Hr tillhandahåller till exempel jobbinformationsattribut (till exempel jobTitle, employeeType) och Badging System tillhandahåller informationsattribut för märke (till exempel badgeId som representeras med hjälp av ett tilläggsattribut). I det här scenariot kan du konfigurera två etableringsappar:

  • Etableringsapp nr 1 som tar emot attribut från HR-källan och skapar användaren.

  • Etableringsapp nr 2 som tar emot attribut från Badging-systemet och endast uppdaterar användarattributen. Attributmappningen i den här appen är begränsad till attributen Badge Information och under Målobjektåtgärder är endast uppdateringen aktiverad.

  • Båda apparna använder samma matchande identifierarpar (externalId<->employeeId)

Hur bearbetar vi avslutningar med api-slutpunkten /bulkUpload?

Om du vill bearbeta avslutningar identifierar du ett attribut i källan som ska användas för att ange accountEnabled flaggan i Microsoft Entra-ID. Om du etablerar till lokal Active Directory mappar du källattributet till attributetaccountDisabled.

Som standard avgör värdet som är associerat med scim core-användarschemat active statusen för användarens konto i målkatalogen.

Om attributet är inställt på true aktiverar standardmappningsregeln kontot. Om attributet är inställt på false inaktiverar standardmappningsregeln kontot.

Hur kan vi förhindra oavsiktlig inaktivering/borttagning av användare?

För att förhindra och återställa från oavsiktliga borttagningar rekommenderar vi att du konfigurerar tröskelvärdet för oavsiktlig borttagning i etableringsappen och aktiverar lokal Active Directory papperskorgen. I bladet Attributmappning i etableringsappen inaktiverar du åtgärden Ta bort under Målobjektåtgärder.

Återställa borttagna konton

  • Om målkatalogen för åtgärden är Microsoft Entra-ID tas den matchade användaren bort mjukt. Användaren kan visas på sidan Borttagna användare i administrationscentret för Microsoft Entra under de kommande 30 dagarna och kan återställas under den tiden.
  • Om målkatalogen för åtgärden är lokal Active Directory tas den matchade användaren bort hårt. Om Papperskorgen för Active Directory är aktiverad kan du återställa det borttagna lokala AD-användarobjektet.

Behöver vi skicka alla användare från HR-systemet i varje begäran?

Nej, du behöver inte skicka alla användare från HR-systemet/"sanningskällan" i varje begäran. Skicka bara de användare som du vill skapa eller uppdatera.

Stöder API:et alla HTTP-åtgärder (GET/POST/PUT/PATCH)?

Nej, api-slutpunkten /bulkUpload-etablering stöder endast POST HTTP-åtgärden.

Behöver jag skicka en PUT/PATCH-begäran om jag vill uppdatera en användare?

Nej, API-slutpunkten stöder inte PUT/PATCH-begäran. Om du vill uppdatera en användare skickar du de data som är associerade med användaren i nyttolasten för POST-massbegäran.

Etableringsjobbet som bearbetar data som tas emot av API-slutpunkten identifierar automatiskt om användaren som tas emot i POST-begärandenyttolasten måste skapas/uppdateras/aktivera/inaktiveras baserat på de konfigurerade synkroniseringsreglerna. Som API-klient behöver du inte vidta några fler åtgärder om du vill att en användarprofil ska uppdateras.

Hur stöds tillbakaskrivning?

Det aktuella API:et stöder endast inkommande data. Här är några alternativ att överväga för att implementera tillbakaskrivning av attribut som e-post/användarnamn/telefon som genereras av Microsoft Entra-ID, som du kan skicka tillbaka till HR-systemet:

  • Alternativ 1 – SCIM-anslutning till HR-slutpunkt/proxytjänst som i sin tur uppdaterar HR-källan

    • Om postsystemet tillhandahåller en SCIM-slutpunkt för användaruppdateringar kan du skapa ett anpassat SCIM-program i företagsappgalleriet och konfigurera etablering som dokumenterat.
    • Om postsystemet inte tillhandahåller en SCIM-slutpunkt utforskar du möjligheten att konfigurera en PROXY SCIM-tjänst, som tar emot uppdateringen och sprider ändringen till HR-systemet.

  • Alternativ 2 – Använd Microsoft Entra ECMA-anslutningsappen för tillbakaskrivningsscenariot

    • Beroende på kundens krav kan du utforska om någon av ECMA-anslutningsapparna kan användas (PowerShell/SQL/Web Services).

  • Alternativ 3 – Använda anpassad tilläggsuppgift för livscykelarbetsflöden i ett joiner-arbetsflöde

Nästa steg