Självstudie: Utveckla och planera etablering för en SCIM-slutpunkt i Microsoft Entra-ID

Artikel
11/23/2024

Som programutvecklare kan du använda ANVÄNDARHANTERINGS-API:et System for Cross-Domain Identity Management (SCIM) för att aktivera automatisk etablering av användare och grupper mellan ditt program och Microsoft Entra-ID. Den här artikeln beskriver hur du skapar en SCIM-slutpunkt och integrerar med Microsoft Entra-etableringstjänsten. SCIM-specifikationen innehåller ett vanligt användarschema för etablering. När det används med federationsstandarder som SAML eller OpenID Connect ger SCIM administratörer en standardbaserad lösning från slutpunkt till slutpunkt för åtkomsthantering.

Etablering från Microsoft Entra-ID till en app med SCIM

SCIM 2.0 är en standardiserad definition av två slutpunkter: en /Users slutpunkt och en /Groups slutpunkt. Den använder vanliga REST API-slutpunkter för att skapa, uppdatera och ta bort objekt. SCIM består av ett fördefinierat schema för vanliga attribut som gruppnamn, användarnamn, förnamn, efternamn och e-post.

Appar som erbjuder ett SCIM 2.0 REST API kan minska eller eliminera smärtan av att arbeta med ett patentskyddad användarhanterings-API. Till exempel vet alla kompatibla SCIM-klienter hur man skapar en HTTP POST för ett JSON-objekt till /Users slutpunkten för att skapa en ny användarpost. I stället för att behöva ett något annorlunda API för samma grundläggande åtgärder kan appar som följer SCIM-standarden omedelbart dra nytta av befintliga klienter, verktyg och kod.

Med standardschemat för användarobjekt och rest-API:er för hantering som definieras i SCIM 2.0 (RFC 7642, 7643, 7644) kan identitetsprovidrar och appar lättare integreras med varandra. Programutvecklare som skapar en SCIM-slutpunkt kan integreras med alla SCIM-kompatibla klienter utan att behöva utföra anpassat arbete.

För att automatisera etableringen till ett program krävs det att du skapar och integrerar en SCIM-slutpunkt som har åtkomst till Microsoft Entra-etableringstjänsten. Använd följande steg för att börja etablera användare och grupper i ditt program.

Utforma ditt användar- och gruppschema – Identifiera programmets objekt och attribut för att avgöra hur de mappar till det användar- och gruppschema som stöds av Microsoft Entra SCIM-implementeringen.
Förstå Microsoft Entra SCIM-implementeringen – Förstå hur Microsoft Entra-etableringstjänsten implementeras för att modellera hantering och svar för SCIM-protokollbegäranden.
Skapa en SCIM-slutpunkt – En slutpunkt måste vara SCIM 2.0-kompatibel för att kunna integreras med Microsoft Entra-etableringstjänsten. Som ett alternativ använder du CLI-bibliotek (Microsoft Common Language Infrastructure) och kodexempel för att skapa slutpunkten. Dessa exempel är endast till för referens och testning. vi rekommenderar att du inte använder dem som beroenden i din produktionsapp.
Integrera DIN SCIM-slutpunkt med Microsoft Entra-etableringstjänsten. Microsoft Entra ID stöder flera program från tredje part som implementerar SCIM 2.0. Om du använder någon av dessa appar kan du snabbt automatisera både etablering och avetablering av användare och grupper.
[Valfritt] Publicera ditt program till Microsoft Entra-programgalleriet – Gör det enkelt för kunderna att identifiera ditt program och enkelt konfigurera etablering.

Diagram som visar de steg som krävs för att integrera en SCIM-slutpunkt med Microsoft Entra-ID.

Utforma ditt användar- och gruppschema

Varje program kräver olika attribut för att skapa en användare eller grupp. Starta integreringen genom att identifiera de objekt (användare, grupper) och attribut (namn, chef, jobbtitel och så vidare) som programmet behöver.

SCIM-standarden definierar ett schema för hantering av användare och grupper.

Kärnanvändarschemat kräver bara tre attribut (alla andra attribut är valfria):

id, definierad identifierare för tjänstleverantör
userName, en unik identifierare för användaren (vanligtvis mappas till användarens huvudnamn för Microsoft Entra)
meta, skrivskyddade metadata som underhålls av tjänstleverantören

Utöver det grundläggande användarschemat definierar SCIM-standarden ett företagsanvändartillägg med en modell för att utöka användarschemat så att det uppfyller programmets behov.

Om ditt program till exempel kräver både en användares e-post och användarens chef använder du kärnschemat för att samla in användarens e-post och enterprise-användarschemat för att samla in användarens chef.

Följ dessa steg för att utforma schemat:

Lista de attribut som programmet kräver och kategorisera sedan som attribut som behövs för autentisering (till exempel loginName och e-post). Attribut krävs för att hantera användarlivscykeln (till exempel status/aktiv) och alla andra attribut som krävs för att programmet ska fungera (till exempel chef, tagg).
Kontrollera om attributen redan har definierats i huvudanvändarschemat eller företagsanvändarschemat . Annars måste du definiera ett tillägg till användarschemat som täcker de attribut som saknas. Se exempel för ett tillägg till användaren för att tillåta etablering av en användare tag.
Mappa SCIM-attribut till användarattributen i Microsoft Entra ID. Om ett av de attribut som du har definierat i SCIM-slutpunkten inte har en tydlig motsvarighet i Microsoft Entra-användarschemat kan du vägleda klientadministratören att utöka sitt schema eller använda ett tilläggsattribut som visas i exemplet för tags egenskapen.

I följande tabell visas ett exempel på obligatoriska attribut:

Obligatoriskt appattribut/exempel	Mappat SCIM-attribut	Mappat Microsoft Entra-attribut
loginName	userName	userPrincipalName
firstName	name.givenName	givenName
lastName	name.familyName	efternamn
workMail	emails[type eq "work"].value	Postadress
föreståndare	föreståndare	föreståndare
tagg	`urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User:tag`	extensionAttribute1
status	aktiv	isSoftDeleted (beräknat värde som inte lagras på användaren)

Följande JSON-nyttolast visar ett exempel på ETT SCIM-schema:

{
     "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
      "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
      "urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User"],
     "userName":"bjensen@testuser.com",
     "id": "48af03ac28ad4fb88478",
     "externalId":"bjensen",
     "name":{
       "familyName":"Jensen",
       "givenName":"Barbara"
     },
     "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
     "manager": "123456"
   },
     "urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User": {
     "tag": "701984",
   },
   "meta": {
     "resourceType": "User",
     "created": "2010-01-23T04:56:22Z",
     "lastModified": "2011-05-13T04:42:34Z",
     "version": "W\/\"3694e05e9dff591\"",
     "location":
 "https://example.com/v2/Users/00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
   }
}

Kommentar

Förutom de attribut som krävs för programmet innehåller JSON-representationen även de obligatoriska idattributen , externalIdoch meta .

Det hjälper till att kategorisera mellan /User och /Group mappa alla standardanvändarattribut i Microsoft Entra-ID till SCIM RFC, se hur anpassa attribut mappas mellan Microsoft Entra-ID och DIN SCIM-slutpunkt.

I följande tabell visas ett exempel på användarattribut:

Microsoft Entra-användare	`urn:ietf:params:scim:schemas:extension:enterprise:2.0:User`
IsSoftDeleted	aktiv
Avdelning	`urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department`
displayName	displayName
employeeId	`urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber`
Facsimile-TelephoneNumber	phoneNumbers[type eq "fax"].value
givenName	name.givenName
jobTitle	rubrik
e-post	emails[type eq "work"].value
mailNickname	externalId
föreståndare	`urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager`
mobil	phoneNumbers[type eq "mobile"].value
postalCode	addresses[type eq "work"].postalCode
proxyadresser	email[type eq "other"]. Värde
physical-Delivery-OfficeName	addresses[type eq "other"]. Formaterad
streetAddress	addresses[type eq "work"].streetAddress
surname	name.familyName
telefonnummer	phoneNumbers[type eq "work"].value
user-PrincipalName	userName

I följande tabell visas ett exempel på gruppattribut:

Microsoft Entra-grupp	`urn:ietf:params:scim:schemas:core:2.0:Group`
displayName	displayName
medlemmar	medlemmar
objectId	externalId

Kommentar

Du behöver inte ha stöd för både användare och grupper, eller alla attribut som visas här, det är bara en referens till hur attribut i Microsoft Entra-ID ofta mappas till egenskaper i SCIM-protokollet.

Det finns flera slutpunkter som definierats i SCIM RFC. Du kan börja med /User slutpunkten och sedan expandera därifrån. I följande tabell visas några av SCIM-slutpunkterna:

Slutpunkt	beskrivning
/användare	Utför CRUD-åtgärder på ett användarobjekt.
/Grupp	Utför CRUD-åtgärder på ett gruppobjekt.
/Scheman	Den uppsättning attribut som stöds av varje klient och tjänstleverantör kan variera. En tjänstleverantör kan inkludera `name`, `title`och `emails`, medan en annan tjänstleverantör använder `name`, `title`och `phoneNumbers`. Schemaslutpunkten tillåter identifiering av de attribut som stöds.
/Omfång	Med massåtgärder kan du utföra åtgärder på en stor samling resursobjekt i en enda åtgärd (till exempel uppdatera medlemskap för en stor grupp).
/ServiceProviderConfig	Innehåller information om funktionerna i SCIM-standarden som stöds, till exempel de resurser som stöds och autentiseringsmetoden.
/ResourceTypes	Anger metadata om varje resurs.

Kommentar

/Schemas Använd slutpunkten för att stödja anpassade attribut eller om schemat ändras ofta eftersom det gör att en klient kan hämta det senaste schemat automatiskt. /Bulk Använd slutpunkten för att stödja grupper.

Förstå Microsoft Entra SCIM-implementeringen

Microsoft Entra-etableringstjänsten är utformad för att stödja ett SCIM 2.0-användarhanterings-API.

Viktigt!

Beteendet för Microsoft Entra SCIM-implementeringen uppdaterades senast den 18 december 2018. Information om vad som har ändrats finns i SCIM 2.0-protokollefterlevnad för Microsoft Entra-användaretableringstjänsten.

I SCIM 2.0-protokollspecifikationen måste ditt program ha stöd för följande krav:

Krav	Referensanteckningar (SCIM-protokoll)
Skapa användare och eventuellt även grupper	Avsnitt 3.3
Ändra användare eller grupper med PATCH-begäranden	Avsnitt 3.5.2. Stöd säkerställer att grupper och användare etableras på ett högpresterande sätt.
Hämta en känd resurs för en användare eller grupp som skapades tidigare	Avsnitt 3.4.1
Fråga användare eller grupper	Avsnitt 3.4.2. Som standard hämtas användarna med sina `id` och efterfrågas med sina `username` och `externalId`, och grupper efterfrågas med `displayName`.
Filtret excludedAttributes=members när du frågar efter gruppresursen	Avsnitt 3.4.2.2
Stöd för att lista användare och sidnumrering	Avsnitt 3.4.2.4.
Mjuk borttagning av en användare `active=false` och återställning av användaren `active=true`	Användarobjektet ska returneras i en begäran om användaren är aktiv eller inte. Den enda gången användaren inte ska returneras är när den tas bort hårt från programmet.
Stöd för /Schemas-slutpunkten	Avsnitt 7 Slutpunkten för schemaidentifiering används för att identifiera fler attribut.
Acceptera en enda ägartoken för autentisering och auktorisering av Microsoft Entra-ID till ditt program.

Använd de allmänna riktlinjerna när du implementerar en SCIM-slutpunkt för att säkerställa kompatibilitet med Microsoft Entra-ID:

Allmänt:

id är en obligatorisk egenskap för alla resurser. Varje svar som returnerar en resurs bör se till att varje resurs har den här egenskapen, förutom ListResponse med noll element.
Värden som skickas ska lagras i samma format som de skickades. Ogiltiga värden ska avvisas med ett beskrivande, åtgärdsbart felmeddelande. Omvandlingar av data bör inte ske mellan data från Microsoft Entra-ID och data som lagras i SCIM-programmet. (till exempel. Ett telefonnummer som skickas som 55555555555 ska inte sparas/returneras som +5 (555) 555-5555)
Det är inte nödvändigt att ta med hela resursen i PATCH-svaret .
Kräv inte skiftlägeskänslig matchning på strukturella element i SCIM, särskilt PATCH-åtgärdsvärdenop, enligt definitionen i avsnitt 3.5.2. Microsoft Entra-ID genererar värdena för som Lägg till, Ersätt och Ta bort.op
Microsoft Entra-ID gör begäranden om att hämta en slumpmässig användare och grupp för att säkerställa att slutpunkten och autentiseringsuppgifterna är giltiga. Det görs också som en del av testanslutningsflödet.
Stöd för HTTPS på SCIM-slutpunkten.
Anpassade komplexa och flervärdesattribut stöds, men Microsoft Entra ID har inte många komplexa datastrukturer att hämta data från i dessa fall. Namn-/värdeattribut kan enkelt mappas till, men att flöda data till komplexa attribut med tre eller flera underattribut stöds inte.
Underattributvärdena "typ" för komplexa attribut med flera värden måste vara unika. Det kan till exempel inte finnas två olika e-postadresser med undertypen "arbete".
Rubriken för alla svar ska vara av innehållstyp: application/scim+json

Hämtar resurser:

Svar på en fråga/filterbegäran bör alltid vara en ListResponse.
Microsoft Entra använder endast följande operatorer: eq, and
Attributet som resurserna kan frågas om ska anges som ett matchande attribut i programmet. Mer information finns i Anpassa mappningar för användaretableringsattribut.

/Användare:

Attributet berättiganden stöds inte.
Alla attribut som anses vara unika för användaren måste kunna användas som en del av en filtrerad fråga. (om användarens unika egenskaper utvärderas för både userName och email[type eq "work"], måste en GET to /Users med ett filter tillåta både userName eq "user@contoso.com" och email[type eq "work"].value eq "user@contoso.com" frågor.

/Grupper:

Grupper är valfria, men stöds bara om SCIM-implementeringen stöder PATCH-begäranden .
Grupper måste ha unika värden för "displayName" för att matcha med Microsoft Entra-ID och SCIM-programmet. Det unika är inte ett krav för SCIM-protokollet, men är ett krav för att integrera en SCIM-slutpunkt med Microsoft Entra-ID.

/Scheman (schemaidentifiering):

Exempel på begäran/svar
Schemaidentifiering används i vissa galleriprogram. Schemaidentifiering är den enda metoden för att lägga till fler attribut i schemat för ett befintligt SCIM-galleriprogram. Schemaidentifiering stöds för närvarande inte i ett anpassat SCIM-program som inte är ett galleriprogram.
Om ett värde inte finns skickar du inte null-värden.
Egenskapsvärden ska vara kamelhölje (till exempel readWrite).
Måste returnera ett listsvar.
Microsoft Entra-etableringstjänsten gör /schemas-begäran när du sparar etableringskonfigurationen. Begäran görs också när du öppnar sidan för redigeringsetablering. Andra attribut som identifieras visas för kunder i attributmappningarna under listan över målattribut. Schemaidentifiering leder bara till att fler målattribut läggs till. Attribut tas inte bort.

Användaretablering och avetablering

Följande diagram visar de meddelanden som Microsoft Entra-ID skickar till en SCIM-slutpunkt för att hantera livscykeln för en användare i programmets identitetsarkiv.

Gruppetablering och avetablering

Gruppetablering och avetablering är valfria. När det implementeras och aktiveras visar följande bild de meddelanden som Microsoft Entra-ID skickar till en SCIM-slutpunkt för att hantera livscykeln för en grupp i programmets identitetsarkiv. Dessa meddelanden skiljer sig från meddelandena om användare på två sätt:

Begäranden om att hämta grupper anger att medlemsattributet ska undantas från alla resurser som tillhandahålls som svar på begäran.
Begäranden om att avgöra om ett referensattribut har ett visst värde är begäranden om medlemsattributet.

Följande diagram visar sekvensen för gruppborttagning:

SCIM-protokollbegäranden och svar

Den här artikeln innehåller exempel på SCIM-begäranden som genereras av Microsoft Entra-etableringstjänsten och exempel på förväntade svar. För bästa resultat bör du koda din app för att hantera dessa begäranden i det här formatet och generera förväntade svar.

Viktigt!

Information om hur och när Microsoft Entra-tjänsten för användaretablering genererar de åtgärder som beskrivs i exemplet finns i avsnittet Etableringscykler: Initial och inkrementell i Hur etablering fungerar.

Användaråtgärder

Skapa användare (begärandesvar / )
Hämta användare (begärandesvar / )
Hämta användare efter fråga (begärandesvar / )
Hämta användare efter fråga – Noll resultat (begärandesvar / )
Uppdatera användare [Egenskaper för flera värden] (begärandesvar / )
Uppdatera användare [Egenskaper med en enda värde] (begärandesvar / )
Inaktivera användare (begärandesvar / )
Ta bort användare (begärandesvar / )

Gruppåtgärder

Skapa grupp (begärandesvar / )
Hämta grupp (begärandesvar / )
Hämta grupp efter displayName (begärandesvar / )
Uppdatera grupp [icke-medlemsattribut] (begärandesvar / )
Uppdatera grupp [Lägg till medlemmar] (begärandesvar / )
Uppdatera grupp [Ta bort medlemmar] (begärandesvar / )
Ta bort grupp (begärandesvar / )

Schemaidentifiering

Identifiera schema (begärandesvar / )

Användaråtgärder

Använd userName eller emails[type eq "work"] attribut för att fråga användare.

Skapa användare

Förfrågan

POST /Användare

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
    "externalId": "0a21f0f2-8d2a-4f8e-bf98-7363c4aed4ef",
    "userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "active": true,
    "emails": [{
        "primary": true,
        "type": "work",
        "value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com"
    }],
    "meta": {
        "resourceType": "User"
    },
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName"
    },
    "roles": []
}

Response

HTTP/1.1 201 Skapad

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "48af03ac28ad4fb88478",
    "externalId": "0a21f0f2-8d2a-4f8e-bf98-7363c4aed4ef",
    "meta": {
        "resourceType": "User",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
    },
    "userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName",
    },
    "active": true,
    "emails": [{
        "value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com",
        "type": "work",
        "primary": true
    }]
}

Hämta användare

Förfrågan

GET /Users/5d48a0a8e9f04aa38008

Svar (användaren hittade)

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "5d48a0a8e9f04aa38008",
    "externalId": "58342554-38d6-4ec8-948c-50044d0a33fd",
    "meta": {
        "resourceType": "User",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
    },
    "userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName",
    },
    "active": true,
    "emails": [{
        "value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com",
        "type": "work",
        "primary": true
    }]
}

Förfrågan

GET /Users/5171a35d82074e068ce2

Svar (användaren hittades inte. Informationen krävs inte, endast status.)

HTTP/1.1 404 hittades inte

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:Error"
    ],
    "status": "404",
    "detail": "Resource 23B51B0E5D7AE9110A49411D@7cca31655d49f3640a494224 not found"
}

Hämta användare efter fråga

Förfrågan

GET /Users?filter=userName eq "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee"

Response

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "totalResults": 1,
    "Resources": [{
        "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
        "id": "2441309d85324e7793ae",
        "externalId": "7fce0092-d52e-4f76-b727-3955bd72c939",
        "meta": {
            "resourceType": "User",
            "created": "2018-03-27T19:59:26.000Z",
            "lastModified": "2018-03-27T19:59:26.000Z"
            
        },
        "userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "name": {
            "familyName": "familyName",
            "givenName": "givenName"
        },
        "active": true,
        "emails": [{
            "value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com",
            "type": "work",
            "primary": true
        }]
    }],
    "startIndex": 1,
    "itemsPerPage": 20
}

Hämta användare efter fråga – Noll resultat

Förfrågan

GET /Users?filter=userName eq "non-existent user"

Response

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "totalResults": 0,
    "Resources": [],
    "startIndex": 1,
    "itemsPerPage": 20
}

Uppdatera användare [Egenskaper för flera värden]

Förfrågan

PATCH /Users/6764549bef60420686bc HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
            {
            "op": "Replace",
            "path": "emails[type eq \"work\"].value",
            "value": "updatedEmail@microsoft.com"
            },
            {
            "op": "Replace",
            "path": "name.familyName",
            "value": "updatedFamilyName"
            }
    ]
}

Response

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "6764549bef60420686bc",
    "externalId": "6c75de36-30fa-4d2d-a196-6bdcdb6b6539",
    "meta": {
        "resourceType": "User",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
    },
    "userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "name": {
        "formatted": "givenName updatedFamilyName",
        "familyName": "updatedFamilyName",
        "givenName": "givenName"
    },
    "active": true,
    "emails": [{
        "value": "updatedEmail@microsoft.com",
        "type": "work",
        "primary": true
    }]
}

Uppdatera användare [Egenskaper med en enda värde]

Förfrågan

PATCH /Users/5171a35d82074e068ce2 HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "Replace",
        "path": "userName",
        "value": "5b50642d-79fc-4410-9e90-4c077cdd1a59@testuser.com"
    }]
}

Response

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "5171a35d82074e068ce2",
    "externalId": "aa1eca08-7179-4eeb-a0be-a519f7e5cd1a",
    "meta": {
        "resourceType": "User",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
        
    },
    "userName": "5b50642d-79fc-4410-9e90-4c077cdd1a59@testuser.com",
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName",
    },
    "active": true,
    "emails": [{
        "value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com",
        "type": "work",
        "primary": true
    }]
}

Inaktivera användare

Förfrågan

PATCH /Users/5171a35d82074e068ce2 HTTP/1.1

{
    "Operations": [
        {
            "op": "Replace",
            "path": "active",
            "value": false
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ]
}

Response

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "id": "CEC50F275D83C4530A495FCF@834d0e1e5d8235f90a495fda",
    "userName": "deanruiz@testuser.com",
    "name": {
        "familyName": "Harris",
        "givenName": "Larry"
    },
    "active": false,
    "emails": [
        {
            "value": "gloversuzanne@testuser.com",
            "type": "work",
            "primary": true
        }
    ],
    "addresses": [
        {
            "country": "ML",
            "type": "work",
            "primary": true
        }
    ],
    "meta": {
        "resourceType": "Users",
        "location": "/scim/5171a35d82074e068ce2/Users/CEC50F265D83B4530B495FCF@5171a35d82074e068ce2"
    }
}

Ta bort användare

Förfrågan

DELETE /Users/5171a35d82074e068ce2 HTTP/1.1

Response

HTTP/1.1 204 Inget innehåll

Gruppåtgärder

Grupper skapas med en tom medlemslista.
Använd attributet displayName för att fråga efter grupper.
Uppdatera till gruppen PATCH-begäran ska ge http 204 inget innehåll i svaret. Det är inte lämpligt att returnera en brödtext med en lista över alla medlemmar.
Det är inte nödvändigt att stödja att alla medlemmar i gruppen returneras.

Skapa grupp

Förfrågan

POST /Groups HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group", "http://schemas.microsoft.com/2006/11/ResourceManagement/ADSCIM/2.0/Group"],
    "externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159",
    "displayName": "displayName",
    "meta": {
        "resourceType": "Group"
    }
}

Response

HTTP/1.1 201 Skapad

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "id": "927fa2c08dcb4a7fae9e",
    "externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159",
    "meta": {
        "resourceType": "Group",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
        
    },
    "displayName": "displayName",
    "members": []
}

Hämta grupp

Förfrågan

GET /Groups/40734ae655284ad3abcc?excludedAttributes=members HTTP/1.1

Response

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "id": "40734ae655284ad3abcc",
    "externalId": "60f1bb27-2e1e-402d-bcc4-ec999564a194",
    "meta": {
        "resourceType": "Group",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
    },
    "displayName": "displayName",
}

Hämta grupp efter displayName

Förfrågan

GET /Groups?excludedAttributes=members&filter=displayName eq "displayName" HTTP/1.1

Response

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "totalResults": 1,
    "Resources": [{
        "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
        "id": "8c601452cc934a9ebef9",
        "externalId": "0db508eb-91e2-46e4-809c-30dcbda0c685",
        "meta": {
            "resourceType": "Group",
            "created": "2018-03-27T22:02:32.000Z",
            "lastModified": "2018-03-27T22:02:32.000Z",
            
        },
        "displayName": "displayName",
    }],
    "startIndex": 1,
    "itemsPerPage": 20
}

Uppdatera grupp [icke-medlemsattribut]

Förfrågan

PATCH /Groups/fa2ce26709934589afc5 HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "Replace",
        "path": "displayName",
        "value": "1879db59-3bdf-4490-ad68-ab880a269474updatedDisplayName"
    }]
}

Response

HTTP/1.1 204 Inget innehåll

Uppdatera grupp [Lägg till medlemmar]

Förfrågan

PATCH /Groups/a99962b9f99d4c4fac67 HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "Add",
        "path": "members",
        "value": [{
            "$ref": null,
            "value": "f648f8d5ea4e4cd38e9c"
        }]
    }]
}

Response

HTTP/1.1 204 Inget innehåll

Uppdatera grupp [Ta bort medlemmar]

Förfrågan

PATCH /Groups/a99962b9f99d4c4fac67 HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "Remove",
        "path": "members",
        "value": [{
            "$ref": null,
            "value": "f648f8d5ea4e4cd38e9c"
        }]
    }]
}

Response

HTTP/1.1 204 Inget innehåll

Ta bort grupp

Förfrågan

DELETE /Groups/cdb1ce18f65944079d37 HTTP/1.1

Response

HTTP/1.1 204 Inget innehåll

Schemaidentifiering

Identifiera schema

Förfrågan

GET /Schemas

Response

HTTP/1.1 200 OK

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "itemsPerPage": 50,
    "startIndex": 1,
    "totalResults": 3,
    "Resources": [
  {
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
    "id" : "urn:ietf:params:scim:schemas:core:2.0:User",
    "name" : "User",
    "description" : "User Account",
    "attributes" : [
      {
        "name" : "userName",
        "type" : "string",
        "multiValued" : false,
        "description" : "Unique identifier for the User, typically
used by the user to directly authenticate to the service provider.
Each User MUST include a non-empty userName value.  This identifier
MUST be unique across the service provider's entire set of Users.
REQUIRED.",
        "required" : true,
        "caseExact" : false,
        "mutability" : "readWrite",
        "returned" : "default",
        "uniqueness" : "server"
      },                
    ],
    "meta" : {
      "resourceType" : "Schema",
      "location" :
        "/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:User"
    }
  },
  {
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
    "id" : "urn:ietf:params:scim:schemas:core:2.0:Group",
    "name" : "Group",
    "description" : "Group",
    "attributes" : [
      {
        "name" : "displayName",
        "type" : "string",
        "multiValued" : false,
        "description" : "A human-readable name for the Group.
REQUIRED.",
        "required" : false,
        "caseExact" : false,
        "mutability" : "readWrite",
        "returned" : "default",
        "uniqueness" : "none"
      },
    ],
    "meta" : {
      "resourceType" : "Schema",
      "location" :
        "/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:Group"
    }
  },
  {
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
    "id" : "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
    "name" : "EnterpriseUser",
    "description" : "Enterprise User",
    "attributes" : [
      {
        "name" : "employeeNumber",
        "type" : "string",
        "multiValued" : false,
        "description" : "Numeric or alphanumeric identifier assigned
to a person, typically based on order of hire or association with an
organization.",
        "required" : false,
        "caseExact" : false,
        "mutability" : "readWrite",
        "returned" : "default",
        "uniqueness" : "none"
      },
    ],
    "meta" : {
      "resourceType" : "Schema",
      "location" :
"/v2/Schemas/urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    }
  }
]
}

Säkerhetskrav

TLS-protokollversioner

Den enda godtagbara protokollversionen är TLS 1.2. Ingen annan SSL/TLS-version är tillåten.

RSA-nycklar måste vara minst 2 048 bitar.
ECC-nycklar måste vara minst 256 bitar, genereras med hjälp av en godkänd elliptisk kurva

Nyckellängder

Alla tjänster måste använda X.509-certifikat som genererats med kryptografiska nycklar med tillräcklig längd, vilket innebär:

Chiffersviter

Alla tjänster måste konfigureras för att använda följande chiffersviter i den exakta ordning som anges i exemplet. Om du bara har ett RSA-certifikat har installerade ECDSA-chiffersviterna ingen effekt.

TLS 1.2 Chiffersviter minsta stapel:

TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384

IP-intervall

Microsoft Entra-etableringstjänsten fungerar för närvarande under IP-intervallen för Microsoft Entra-ID enligt listan här. Du kan lägga till DE IP-intervall som anges under taggen AzureActiveDirectory för att tillåta trafik från Microsoft Entra-etableringstjänsten till ditt program. Du måste granska LISTAN över IP-intervall noggrant för beräknade adresser. En adress som "40.126.25.32" kan representeras i LISTAN över IP-intervall som "40.126.0.0/18". Du kan också programmatiskt hämta LISTAN över IP-intervall med hjälp av följande API.

Microsoft Entra-ID stöder också en agentbaserad lösning för att tillhandahålla anslutning till program i privata nätverk (lokalt, värdhanterad i Azure, värdhanterad i AWS och så vidare). Kunder kan distribuera en enkel agent som tillhandahåller anslutning till Microsoft Entra-ID utan att öppna några inkommande portar på en server i deras privata nätverk. Läs mer här.

Skapa en SCIM-slutpunkt

Nu när du har utformat ditt schema och förstått Microsoft Entra SCIM-implementeringen kan du komma igång med att utveckla DIN SCIM-slutpunkt. I stället för att börja från grunden och skapa implementeringen helt på egen hand kan du förlita dig på många öppen källkod SCIM-bibliotek som publicerats av SCIM-communityn.

Vägledning om hur du skapar en SCIM-slutpunkt, inklusive exempel, finns i Utveckla en SCIM-exempelslutpunkt.

Referenskodexemplet öppen källkod .NET Core som publicerats av Microsoft Entra-etableringsteamet är en sådan resurs som kan få igång din utveckling. Skapa en SCIM-slutpunkt och testa den sedan genom att köra igenom de exempelbegäranden/svar som tillhandahålls.

Kommentar

Referenskoden är avsedd att hjälpa dig att komma igång med att skapa DIN SCIM-slutpunkt och tillhandahålls "AS IS". Bidrag från communityn är välkomna för att hjälpa till att skapa och underhålla koden.

Lösningen består av två projekt, Microsoft.SCIM och Microsoft.SCIM.WebHostSample.

Microsoft.SCIM-projektet är det bibliotek som definierar komponenterna i webbtjänsten som överensstämmer med SCIM-specifikationen. Den deklarerar gränssnittet Microsoft.SCIM.IProvider, begäranden översätts till anrop till leverantörens metoder, som skulle programmeras att fungera i ett identitetslager.

Uppdelning: En begäran översätts till anrop till leverantörens metoder

Projektet Microsoft.SCIM.WebHostSample är ett ASP.NET Core-webbprogram baserat på mallen Tom. Det gör att exempelkoden kan distribueras som fristående, värdhanterad i containrar eller i Internet Information Services. Det implementerar också microsoft.SCIM.IProvider-gränssnittet som håller klasser i minnet som ett exempel på identitetsarkiv.

public class Startup
{
    ...
    public IMonitor MonitoringBehavior { get; set; }
    public IProvider ProviderBehavior { get; set; }

    public Startup(IWebHostEnvironment env, IConfiguration configuration)
    {
        ...
        this.MonitoringBehavior = new ConsoleMonitor();
        this.ProviderBehavior = new InMemoryProvider();
    }
    ...

Skapa en anpassad SCIM-slutpunkt

SCIM-slutpunkten måste ha en HTTP-adress och ett certifikat för serverautentisering som rotcertifikatutfärdare är ett av följande namn:

CNNIC
Comodo
CyberTrust
DigiCert
GeoTrust
GlobalSign
Gå pappa
VeriSign
WoSign
DST Root CA X3

.NET Core SDK innehåller ett HTTPS-utvecklingscertifikat som används under utvecklingen. Certifikatet installeras som en del av den första körningen. Beroende på hur du kör ASP.NET Core-webbprogrammet lyssnar det på en annan port:

Microsoft.SCIM.WebHostSample: https://localhost:5001
IIS Express: https://localhost:44359

Mer information om HTTPS i ASP.NET Core finns på följande länk: Framtvinga HTTPS i ASP.NET Core

Hantera slutpunktsautentisering

Begäranden från Microsoft Entra-etableringstjänsten innehåller en OAuth 2.0-ägartoken. En auktoriseringsserver utfärdar ägartoken. Microsoft Entra ID är ett exempel på en betrodd auktoriseringsserver. Konfigurera Microsoft Entra-etableringstjänsten så att den använder någon av följande token:

En långlivad ägartoken. Om SCIM-slutpunkten kräver en OAuth-ägartoken från en annan utfärdare än Microsoft Entra-ID kopierar du den nödvändiga OAuth-ägartoken till det valfria fältet Hemlig token . I en utvecklingsmiljö kan du använda testtoken från /scim/token slutpunkten. Testtoken ska inte användas i produktionsmiljöer.
Microsoft Entra-ägartoken. Om fältet Hemlig token lämnas tomt innehåller Microsoft Entra-ID en OAuth-ägartoken som utfärdats från Microsoft Entra-ID med varje begäran. Appar som använder Microsoft Entra-ID som identitetsprovider kan verifiera denna Microsoft Entra ID-utfärdade token.
- Programmet som tar emot begäranden bör verifiera token utfärdaren som Microsoft Entra-ID för en förväntad Microsoft Entra-klientorganisation.
- Ett iss anspråk identifierar utfärdaren av token. Exempel: "iss":"https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/" I det här exemplet identifierar basadressen för anspråksvärdet https://sts.windows.net Microsoft Entra-ID som utfärdare, medan det relativa adresssegmentet, aaaabbbb-0000-cccc-1111-dddd222eeee, är en unik identifierare för Microsoft Entra-klientorganisationen som token utfärdades för.
- Målgruppen för en token är program-ID för programmet i galleriet. Program som är registrerade i en enda klientorganisation får samma iss anspråk med SCIM-begäranden. Program-ID:t för alla anpassade appar är 8adf8e6e-67b2-4cf2-a259-e3dc5476c621. Den token som genereras av Microsoft Entra-ID:t ska endast användas för testning. Den bör inte användas i produktionsmiljöer.

I exempelkoden autentiseras begäranden med hjälp av paketet Microsoft.AspNetCore.Authentication.JwtBearer. Följande kod framtvingar att begäranden till någon av tjänstens slutpunkter autentiseras med hjälp av ägartoken som utfärdats av Microsoft Entra-ID för en angiven klientorganisation:

public void ConfigureServices(IServiceCollection services)
{
    if (_env.IsDevelopment())
    {
        ...
    }
    else
    {
        services.AddAuthentication(options =>
        {
            options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
            options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
        })
            .AddJwtBearer(options =>
            {
                options.Authority = " https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/";
                options.Audience = "8adf8e6e-67b2-4cf2-a259-e3dc5476c621";
                ...
            });
    }
    ...
}

public void Configure(IApplicationBuilder app)
{
    ...
    app.UseAuthentication();
    app.UseAuthorization();
    ...
}

Exempelkoden använder ASP.NET Core-miljöer för att ändra autentiseringsalternativen under utvecklingsfasen och aktivera användningen av en självsignerad token.

Mer information om flera miljöer i ASP.NET Core finns i Använda flera miljöer i ASP.NET Core.

Följande kod framtvingar att begäranden till någon av tjänstens slutpunkter autentiseras med en ägartoken signerad med en anpassad nyckel:

public void ConfigureServices(IServiceCollection services)
{
    if (_env.IsDevelopment())
    {
        services.AddAuthentication(options =>
        {
            options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
            options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
        })
        .AddJwtBearer(options =>
        {
            options.TokenValidationParameters =
                new TokenValidationParameters
                {
                    ValidateIssuer = false,
                    ValidateAudience = false,
                    ValidateLifetime = false,
                    ValidateIssuerSigningKey = false,
                    ValidIssuer = "Microsoft.Security.Bearer",
                    ValidAudience = "Microsoft.Security.Bearer",
                    IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("A1B2C3D4E5F6A1B2C3D4E5F6"))
                };
        });
    }
...

Skicka en GET-begäran till tokenkontrollanten för att hämta en giltig ägartoken. Metoden GenerateJSONWebToken ansvarar för att skapa en token som matchar de parametrar som konfigurerats för utveckling:

private string GenerateJSONWebToken()
{
    // Create token key
    SymmetricSecurityKey securityKey =
        new SymmetricSecurityKey(Encoding.UTF8.GetBytes("A1B2C3D4E5F6A1B2C3D4E5F6"));
    SigningCredentials credentials =
        new SigningCredentials(securityKey, SecurityAlgorithms.HmacSha256);

    // Set token expiration
    DateTime startTime = DateTime.UtcNow;
    DateTime expiryTime = startTime.AddMinutes(120);

    // Generate the token
    JwtSecurityToken token =
        new JwtSecurityToken(
            "Microsoft.Security.Bearer",
            "Microsoft.Security.Bearer",
            null,
            notBefore: startTime,
            expires: expiryTime,
            signingCredentials: credentials);

    string result = new JwtSecurityTokenHandler().WriteToken(token);
    return result;
}

Hantera etablering och avetablering av användare

Exempel 1. Fråga efter en matchande användare i tjänsten

Microsoft Entra ID frågar tjänsten efter en användare med ett externalId attributvärde som matchar attributet mailNickname för en användare i Microsoft Entra-ID. Frågan uttrycks som en HTTP-begäran (Hypertext Transfer Protocol), till exempel det här exemplet, där jyoung är ett exempel på ett mailNickname för en användare i Microsoft Entra-ID.

Kommentar

Det här är bara ett exempel. Alla användare har inte ett mailNickname-attribut och värdet som en användare har kanske inte är unikt i katalogen. Dessutom kan attributet som används för matchning (vilket i det här fallet är externalId) konfigureras i Microsoft Entra-attributmappningarna.

GET https://.../scim/Users?filter=externalId eq jyoung HTTP/1.1
 Authorization: Bearer ...

I exempelkoden översätts begäran till ett anrop till QueryAsync-metoden för tjänstens provider. Här är signaturen för den metoden:

// System.Threading.Tasks.Tasks is defined in mscorlib.dll.  
// Microsoft.SCIM.IRequest is defined in 
// Microsoft.SCIM.Service.  
// Microsoft.SCIM.Resource is defined in 
// Microsoft.SCIM.Schemas.  
// Microsoft.SCIM.IQueryParameters is defined in 
// Microsoft.SCIM.Protocol.  

Task<Resource[]> QueryAsync(IRequest<IQueryParameters> request);

För en användare med ett angivet värde för attributet i exempelfrågan är värdena för externalId argumenten som skickas till QueryAsync-metoden:

Parametrar. AlternateFilters.Count: 1
Parametrar. AlternateFilters.ElementAt(0). AttributePath: "externalId"
Parametrar. AlternateFilters.ElementAt(0). ComparisonOperator: ComparisonOperator.Equals
Parametrar. AlternateFilter.ElementAt(0). ComparisonValue: "jyoung"

Exempel 2. Etablera en användare

Om svaret på en fråga till SCIM-slutpunkten för en användare med ett externalId attributvärde som matchar attributet mailNickname för en användare inte returnerar några användare, begär Microsoft Entra ID att tjänsten etablerar en användare som motsvarar den i Microsoft Entra-ID. Här är ett exempel på en sådan begäran:

POST https://.../scim/Users HTTP/1.1
Authorization: Bearer ...
Content-type: application/scim+json
{
   "schemas":
   [
     "urn:ietf:params:scim:schemas:core:2.0:User",
     "urn:ietf:params:scim:schemas:extension:enterprise:2.0User"],
   "externalId":"jyoung",
   "userName":"jyoung@testuser.com",
   "active":true,
   "addresses":null,
   "displayName":"Joy Young",
   "emails": [
     {
       "type":"work",
       "value":"jyoung@Contoso.com",
       "primary":true}],
   "meta": {
     "resourceType":"User"},
    "name":{
     "familyName":"Young",
     "givenName":"Joy"},
   "phoneNumbers":null,
   "preferredLanguage":null,
   "title":null,
   "department":null,
   "manager":null}

I exempelkoden översätts begäran till ett anrop till metoden CreateAsync för tjänstens provider. Här är signaturen för den metoden:

// System.Threading.Tasks.Tasks is defined in mscorlib.dll.  
// Microsoft.SCIM.IRequest is defined in 
// Microsoft.SCIM.Service.  
// Microsoft.SCIM.Resource is defined in 
// Microsoft.SCIM.Schemas.  

Task<Resource> CreateAsync(IRequest<Resource> request);

I en begäran om användaretablering är värdet för resursargumentet en instans av Microsoft.SCIM.Core2EnterpriseUser klassen. Den här klassen definieras i Microsoft.SCIM.Schemas biblioteket. Om begäran om att etablera användaren lyckas förväntas implementeringen av metoden returnera en instans av Microsoft.SCIM.Core2EnterpriseUser klassen. Värdet för Identifier egenskapen är inställt på den nya etablerade användarens unika identifierare.

Exempel 3. Fråga efter aktuellt tillstånd för en användare

Microsoft Entra-ID begär aktuellt tillstånd för den angivna användaren från tjänsten med en begäran som:

GET ~/scim/Users/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 HTTP/1.1
Authorization: Bearer ...

I exempelkoden översätts begäran till ett anrop till metoden RetrieveAsync för tjänstens provider. Här är signaturen för den metoden:

// System.Threading.Tasks.Tasks is defined in mscorlib.dll.  
// Microsoft.SCIM.IRequest is defined in 
// Microsoft.SCIM.Service.  
// Microsoft.SCIM.Resource and 
// Microsoft.SCIM.IResourceRetrievalParameters 
// are defined in Microsoft.SCIM.Schemas 

Task<Resource> RetrieveAsync(IRequest<IResourceRetrievalParameters> request);

I exemplet med en begäran, för att hämta användarens aktuella tillstånd, är värdena för egenskaperna för objektet som anges som värdet för parameterargumentet följande:

Identifierare: "a0a0a0a0-bbbb-cccc-ddddd-e1e1e1e1e1e1"
SchemaIdentifier: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Exempel 4. Fråga efter värdet för ett referensattribut som ska uppdateras

Microsoft Entra-ID kontrollerar det aktuella attributvärdet i identitetsarkivet innan det uppdateras. Det är dock bara chefsattributet som kontrolleras först för användare. Här är ett exempel på en begäran om att avgöra om chefsattributet för ett användarobjekt för närvarande har ett visst värde: I exempelkoden översätts begäran till ett anrop till QueryAsync-metoden för tjänstens provider. Värdet för egenskaperna för objektet som anges som värdet för parameterargumentet är följande:

Parametrar. AlternateFilters.Count: 2
Parametrar. AlternateFilters.ElementAt(x). AttributePath: "ID"
Parametrar. AlternateFilters.ElementAt(x). ComparisonOperator: ComparisonOperator.Equals
Parametrar. AlternateFilter.ElementAt(x). ComparisonValue: "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"
Parametrar. AlternateFilters.ElementAt(y). AttributePath: "manager"
Parametrar. AlternateFilters.ElementAt(y). ComparisonOperator: ComparisonOperator.Equals
Parametrar. AlternateFilter.ElementAt(y). ComparisonValue: "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
Parametrar. RequestedAttributePaths.ElementAt(0): "ID"
Parametrar. SchemaIdentifier: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Värdet för index x kan vara 0 och värdet för indexet y kan vara 1. Eller värdet för x kan vara 1 och värdet för y kan vara 0. Det beror på ordningen på uttrycken för filterfrågeparametern.

Exempel 5. Begära från Microsoft Entra-ID till en SCIM-slutpunkt för att uppdatera en användare

Här är ett exempel på en begäran från Microsoft Entra-ID till en SCIM-slutpunkt för att uppdatera en användare:

PATCH ~/scim/Users/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 HTTP/1.1
Authorization: Bearer ...
Content-type: application/scim+json
{
    "schemas": 
    [
      "urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations":
    [
      {
        "op":"Add",
        "path":"manager",
        "value":
          [
            {
              "$ref":"http://.../scim/Users/00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
              "value":"00aa00aa-bb11-cc22-dd33-44ee44ee44ee"}]}]}

I exempelkoden översätts begäran till ett anrop till metoden UpdateAsync för tjänstens provider. Här är signaturen för den metoden:

// System.Threading.Tasks.Tasks and 
// System.Collections.Generic.IReadOnlyCollection<T>  // are defined in mscorlib.dll.  
// Microsoft.SCIM.IRequest is defined in
// Microsoft.SCIM.Service.
// Microsoft.SCIM.IPatch, 
// is defined in Microsoft.SCIM.Protocol. 

Task UpdateAsync(IRequest<IPatch> request);

I exemplet med en begäran om att uppdatera en användare har objektet som anges som värdet för patchargumentet följande egenskapsvärden:

Argument	Värde
`ResourceIdentifier.Identifier`	"a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"
`ResourceIdentifier.SchemaIdentifier`	`urn:ietf:params:scim:schemas:extension:enterprise:2.0:User`
`(PatchRequest as PatchRequest2).Operations.Count`	1
`(PatchRequest as PatchRequest2).Operations.ElementAt(0).OperationName`	`OperationName.Add`
`(PatchRequest as PatchRequest2).Operations.ElementAt(0).Path.AttributePath`	Ansvarig
`(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.Count`	1
`(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.ElementAt(0).Reference`	`http://.../scim/Users/00aa00aa-bb11-cc22-dd33-44ee44ee44ee`
`(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.ElementAt(0).Value`	00aa00aa-bb11-cc22-dd33-44ee44ee44ee

Exempel 6. Avetablera en användare

Om du vill avetablera en användare från ett identitetslager som frontas av en SCIM-slutpunkt skickar Microsoft Entra-ID en begäran som:

DELETE ~/scim/Users/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 HTTP/1.1
Authorization: Bearer ...

I exempelkoden översätts begäran till ett anrop till metoden DeleteAsync för tjänstens provider. Här är signaturen för den metoden:

// System.Threading.Tasks.Tasks is defined in mscorlib.dll.  
// Microsoft.SCIM.IRequest is defined in 
// Microsoft.SCIM.Service.  
// Microsoft.SCIM.IResourceIdentifier, 
// is defined in Microsoft.SCIM.Protocol. 

Task DeleteAsync(IRequest<IResourceIdentifier> request);

Objektet som anges som värdet för argumentet resourceIdentifier har dessa egenskapsvärden i exemplet med en begäran om att avetablera en användare:

ResourceIdentifier.Identifier: "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1e1"
ResourceIdentifier.SchemaIdentifier: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Integrera DIN SCIM-slutpunkt med Microsoft Entra-etableringstjänsten

Microsoft Entra-ID kan konfigureras för att automatiskt etablera tilldelade användare och grupper till program som implementerar en specifik profil för SCIM 2.0-protokollet. Profilens detaljer dokumenteras i Förstå Microsoft Entra SCIM-implementeringen.

Kontakta programleverantören eller programleverantörens dokumentation för att få instruktioner om kompatibilitet med dessa krav.

Viktigt!

Microsoft Entra SCIM-implementeringen bygger på Microsoft Entra-användaretableringstjänsten, som är utformad för att ständigt hålla användarna synkroniserade mellan Microsoft Entra-ID och målprogrammet, och implementerar en mycket specifik uppsättning standardåtgärder. Det är viktigt att förstå dessa beteenden för att förstå beteendet för Microsoft Entra-etableringstjänsten. Mer information finns i avsnittet Etableringscykler: Inledande och inkrementell i Så här fungerar etableringen.

Komma igång

Dricks

Stegen i den här artikeln kan variera något beroende på vilken portal du börjar från.

Program som stöder SCIM-profilen som beskrivs i den här artikeln kan anslutas till Microsoft Entra-ID med hjälp av funktionen "icke-galleriprogram" i Microsoft Entra-programgalleriet. När microsoft Entra-ID har anslutits körs en synkroniseringsprocess. Processen körs var 40:e minut. Processen frågar programmets SCIM-slutpunkt efter tilldelade användare och grupper och skapar eller ändrar dem enligt tilldelningsinformationen.

Så här ansluter du ett program som stöder SCIM:

Logga in på administrationscentret för Microsoft Entra som minst programadministratör.
Bläddra till Identity>Applications Enterprise-program.>
En lista över alla konfigurerade appar visas, inklusive appar som har lagts till från galleriet.
Välj + Nytt program>+ Skapa ett eget program.
Ange ett namn för ditt program, välj alternativet "integrera andra program som du inte hittar i galleriet" och välj Lägg till för att skapa ett appobjekt. Den nya appen läggs till i listan över företagsprogram och öppnas på skärmen för apphantering.

Följande skärmbild visar Microsoft Entra-programgalleriet:
På skärmen apphantering väljer du Etablering i den vänstra panelen.
På menyn Etableringsläge väljer du Automatisk.

Följande skärmbild visar konfigurationen av etableringsinställningar i administrationscentret för Microsoft Entra:
I fältet Klient-URL anger du URL:en för programmets SCIM-slutpunkt. Exempel: https://api.contoso.com/scim/
Om SCIM-slutpunkten kräver en OAuth-ägartoken från en annan utfärdare än Microsoft Entra-ID kopierar du den nödvändiga OAuth-ägartoken till det valfria fältet Hemlig token . Om det här fältet lämnas tomt innehåller Microsoft Entra-ID en OAuth-ägartoken som utfärdats från Microsoft Entra-ID med varje begäran. Appar som använder Microsoft Entra-ID som identitetsprovider kan verifiera denna Microsoft Entra ID-utfärdade token.

Kommentar

Vi rekommenderar inte att du lämnar fältet tomt och förlitar dig på en token som genereras av Microsoft Entra-ID. Det här alternativet är främst tillgängligt för testning.
Välj Testa anslutning om du vill att Microsoft Entra-ID ska försöka ansluta till SCIM-slutpunkten. Om försöket misslyckas visas felinformation.

Kommentar

Testa anslutning frågar SCIM-slutpunkten efter en användare som inte finns, med hjälp av ett slumpmässigt GUID som matchande egenskap som valts i Microsoft Entra-konfigurationen. Det förväntade korrekta svaret är HTTP 200 OK med ett tomt SCIM ListResponse-meddelande.
Om försöken att ansluta till programmet lyckas väljer du Spara för att spara administratörsautentiseringsuppgifterna.
I avsnittet Mappningar finns det två valbara uppsättningar med attributmappningar: en för användarobjekt och en för gruppobjekt. Välj var och en för att granska attributen som synkroniseras från Microsoft Entra-ID till din app. De attribut som valts som Matchande egenskaper används för att matcha användare och grupper i din app för uppdateringsåtgärder. Välj Spara för att checka in eventuella ändringar.

Kommentar

Du kan också inaktivera synkronisering av gruppobjekt genom att inaktivera mappningen "grupper".
Under Inställningar definierar fältet Omfång vilka användare och grupper som synkroniseras. Välj Synkronisera endast tilldelade användare och grupper (rekommenderas) för att endast synkronisera användare och grupper som tilldelats på fliken Användare och grupper .
När konfigurationen är klar anger du Etableringsstatus till På.
Välj Spara för att starta Microsoft Entra-etableringstjänsten.
Om du bara synkroniserar tilldelade användare och grupper (rekommenderas) väljer du fliken Användare och grupper . Tilldela sedan de användare eller grupper som du vill synkronisera.

När den inledande cykeln har startat kan du välja Etableringsloggar i den vänstra panelen för att övervaka förloppet, vilket visar alla åtgärder som utförs av etableringstjänsten i din app. Mer information om hur du läser Microsoft Entra-etableringsloggarna finns i Rapportering om automatisk etablering av användarkonton.

Kommentar

Den inledande cykeln tar längre tid att utföra än senare synkroniseringar, vilket sker ungefär var 40:e minut så länge tjänsten körs.

Publicera ditt program till Microsoft Entra-programgalleriet

Om du skapar ett program som används av mer än en klientorganisation gör du det tillgängligt i Microsoft Entra-programgalleriet. Det är enkelt för organisationer att identifiera programmet och konfigurera etablering. Det är enkelt att publicera din app i Microsoft Entra-galleriet och göra etableringen tillgänglig för andra. Kolla in stegen här. Microsoft samarbetar med dig för att integrera ditt program i galleriet, testa din slutpunkt och släppa registreringsdokumentation för kunder.

Checklista för galleri onboarding

Använd checklistan för att snabbt publicera ditt program och kunderna har en smidig distributionsupplevelse. Informationen samlas in från dig när du registrerar dig i galleriet.

Stöd för en SCIM 2.0-användar - och gruppslutpunkt (endast en krävs men båda rekommenderas)
Stöd för minst 25 begäranden per sekund per klientorganisation för att säkerställa att användare och grupper etableras och avetableras utan fördröjning (krävs)
Upprätta tekniska kontakter och supportkontakter för att vägleda kunder efter galleri onboarding (obligatoriskt)
3 Testautentiseringsuppgifter som inte upphör att gälla för ditt program (krävs)
Stöd för beviljande av OAuth-auktoriseringskod eller en långlivad token enligt beskrivningen i exemplet (krävs)
OIDC-appar måste ha minst en roll (anpassad eller standard) definierad
Upprätta en teknisk och supportkontakt för att stödja kunder efter galleri onboarding (krävs)
Identifiering av stödschema (krävs)
Stöd för uppdatering av flera gruppmedlemskap med en enda PATCH
Dokumentera SCIM-slutpunkten offentligt

Auktorisering för etablering av anslutningsappar i programgalleriet

SCIM-specifikationen definierar inte ett SCIM-specifikt schema för autentisering och auktorisering och förlitar sig på användningen av befintliga branschstandarder.

Auktoriseringsmetod	Fördelar	Nackdelar	Support
Användarnamn och lösenord (rekommenderas inte eller stöds inte av Microsoft Entra-ID)	Lätt att implementera	Osäker – Din Pa$$word spelar ingen roll	Stöds inte för nya galleri- eller icke-galleriappar.
Långlivad ägartoken	Långlivade token kräver inte att en användare finns. De är enkla för administratörer att använda när de konfigurerar etablering.	Långlivade token kan vara svåra att dela med en administratör utan att använda osäkra metoder som e-post.	Stöds för galleri- och icke-galleriappar.
Beviljande av OAuth-auktoriseringskod	Åtkomsttoken har en kortare livslängd än lösenord och har en automatiserad uppdateringsmekanism som långlivade ägartoken inte har. En verklig användare måste vara närvarande under den första auktoriseringen och lägga till en ansvarsnivå.	Kräver att en användare finns. Om användaren lämnar organisationen är token ogiltig och auktoriseringen måste slutföras igen.	Stöds för galleriappar, men inte för andra appar än galleriappar. Du kan dock ange en åtkomsttoken i användargränssnittet som hemlig token för kortsiktiga testningsändamål. Stöd för OAuth-kodbeviljande på icke-galleri finns i vår kvarvarande information, förutom stöd för konfigurerbara autentiserings-/token-URL:er i galleriappen.
Bevilja OAuth-klientautentiseringsuppgifter	Åtkomsttoken har en kortare livslängd än lösenord och har en automatiserad uppdateringsmekanism som långlivade ägartoken inte har. Både beviljandet av auktoriseringskoden och de klientautentiseringsuppgifter som beviljas skapar samma typ av åtkomsttoken, så att flytta mellan dessa metoder är transparent för API:et. Etableringen kan automatiseras och nya token kan begäras tyst utan användarinteraktion.		Stöds för galleriappar, men inte för andra appar än galleriappar. Du kan dock ange en åtkomsttoken i användargränssnittet som hemlig token för kortsiktiga testningsändamål. Stöd för OAuth-klientautentiseringsuppgifter som beviljas för icke-galleri finns i vår kvarvarande information.

Kommentar

Vi rekommenderar inte att du lämnar tokenfältet tomt i användargränssnittet för microsoft Entra-etableringskonfigurationsanpassad app. Den token som genereras är främst tillgänglig i testsyfte.

Beviljandeflöde för OAuth-kod

Etableringstjänsten stöder beviljandet av auktoriseringskoden och när du har skickat din begäran om att publicera din app i galleriet arbetar vårt team med dig för att samla in följande information:

Auktoriserings-URL, en URL från klienten för att få auktorisering från resursägaren via omdirigering av användaragenten. Användaren omdirigeras till den här URL:en för att auktorisera åtkomst.
URL för tokenutbyte, en URL från klienten för att byta ut ett auktoriseringsbidrag för en åtkomsttoken, vanligtvis med klientautentisering.
Klient-ID, auktoriseringsservern utfärdar den registrerade klienten en klientidentifierare, vilket är en unik sträng som representerar registreringsinformationen som tillhandahålls av klienten. Klientidentifieraren är ingen hemlighet. den exponeras för resursägaren och får inte användas ensam för klientautentisering.
Klienthemlighet, en hemlighet som genereras av auktoriseringsservern och som ska vara ett unikt värde som endast är känt för auktoriseringsservern.

Kommentar

Auktoriserings-URL :en och tokenutbytes-URL:en kan för närvarande inte konfigureras per klientorganisation.

Kommentar

OAuth v1 stöds inte på grund av exponering av klienthemligheten. OAuth v2 stöds.

När du använder OAuth Code Grant-flödet måste du ha stöd för en modell där varje kund skickar sitt eget klient-ID och sin klienthemlighet när de konfigurerar en etableringsinstans. Ett enda appomfattande klient-ID/klienthemlighetspar stöds inte.

Så här konfigurerar du OAuth-kod bevilja flöde

Logga in på administrationscentret för Microsoft Entra som minst programadministratör.
Bläddra till Identity>Applications Enterprise-program>>Programetablering> och välj Auktorisera.
Logga in på administrationscentret för Microsoft Entra som minst programadministratör.
Bläddra till Identity>Applications Enterprise-program.>
Välj ditt program och gå till Etablering.
Välj Auktorisera.
1. Användarna omdirigeras till auktoriserings-URL:en (inloggningssidan för appen från tredje part).
2. Administratören tillhandahåller autentiseringsuppgifter till programmet från tredje part.
3. Appen från tredje part omdirigerar användaren tillbaka och tillhandahåller beviljandekoden
4. Etableringstjänsten anropar token-URL:en och tillhandahåller beviljandekoden. Programmet från tredje part svarar med åtkomsttoken, uppdateringstoken och förfallodatumet
När etableringscykeln börjar kontrollerar tjänsten om den aktuella åtkomsttoken är giltig och byter ut den mot en ny token om det behövs. Åtkomsttoken tillhandahålls i varje begäran som görs till appen och giltigheten för begäran kontrolleras före varje begäran.

Kommentar

Det går inte att konfigurera OAuth för program som inte är galleriprogram, men du kan manuellt generera en åtkomsttoken från auktoriseringsservern och ange den som hemlig token i ett program som inte är ett galleriprogram. På så sätt kan du kontrollera kompatibiliteten för SCIM-servern med Microsoft Entra-etableringstjänsten innan du registrerar dig för appgalleriet, vilket stöder OAuth-kodbeviljandet.

Långlivade OAuth-ägartoken: Om ditt program inte stöder OAuth-auktoriseringskodens beviljandeflöde genererar du i stället en långlivad OAuth-ägartoken som en administratör kan använda för att konfigurera etableringsintegreringen. Token ska vara evig, annars sätts etableringsjobbet i karantän när token upphör att gälla.

Mer autentiserings- och auktoriseringsmetoder finns i UserVoice.

Bocklista för gallerilansering

För att öka medvetenheten och efterfrågan på vår gemensamma integrering rekommenderar vi att du uppdaterar din befintliga dokumentation och förstärker integreringen i dina marknadsföringskanaler. Vi rekommenderar att du slutför följande checklista för att stödja lanseringen:

Se till att dina sälj- och kundsupportteam är medvetna, redo och kan prata med integreringsfunktionerna. Informera dina team, ge dem vanliga frågor och svar och inkludera integreringen i ditt säljmaterial.
Skapa ett blogginlägg eller pressmeddelande som beskriver den gemensamma integrationen, fördelarna och hur du kommer igång. Exempel: Imprivata och Microsoft Entra Press Release
Använd dina sociala medier som X, Facebook eller LinkedIn för att främja integreringen till dina kunder. Se till att inkludera @Microsoft Entra-ID så att vi kan retweeta ditt inlägg. Exempel: Imprivata X Post
Skapa eller uppdatera dina marknadsföringssidor/din webbplats (till exempel integrationssida, partnersida, prissida och så vidare) för att inkludera tillgängligheten för den gemensamma integreringen. Exempel: Pingboard-integreringssida, Smartsheet-integreringssida, Monday.com prissida
Skapa en hjälpcenterartikel eller teknisk dokumentation om hur kunder kan komma igång. Exempel: Envoy + Microsoft Entra-integrering.
Varna kunder om den nya integreringen via din kundkommunikation (månatliga nyhetsbrev, e-postkampanjer, produktpubliceringsanteckningar).

Nästa steg

Utveckla en SCIM-exempelslutpunkt Automatisera användaretablering och avetablering till SaaS-appar Anpassa attributmappningar för användaretablering Skriva uttryck för attributmappningar Omfångsfilter för användaretablering Kontoetableringsaviseringar Lista över självstudier om hur du integrerar SaaS-appar

Dela via

Självstudie: Utveckla och planera etablering för en SCIM-slutpunkt i Microsoft Entra-ID

Utforma ditt användar- och gruppschema

Förstå Microsoft Entra SCIM-implementeringen

Allmänt:

Hämtar resurser:

/Användare:

/Grupper:

/Scheman (schemaidentifiering):

Användaretablering och avetablering

Gruppetablering och avetablering

SCIM-protokollbegäranden och svar

Användaråtgärder

Skapa användare

Förfrågan

Response

Hämta användare

Förfrågan

Svar (användaren hittade)

Förfrågan

Svar (användaren hittades inte. Informationen krävs inte, endast status.)

Hämta användare efter fråga

Förfrågan

Response

Hämta användare efter fråga – Noll resultat

Förfrågan

Response

Uppdatera användare [Egenskaper för flera värden]

Förfrågan

Response

Uppdatera användare [Egenskaper med en enda värde]

Förfrågan

Response

Inaktivera användare

Förfrågan

Response

Ta bort användare

Förfrågan

Response

Gruppåtgärder

Skapa grupp

Förfrågan

Response

Hämta grupp

Förfrågan

Response

Hämta grupp efter displayName

Förfrågan

Response

Uppdatera grupp [icke-medlemsattribut]

Förfrågan

Response

Uppdatera grupp [Lägg till medlemmar]

Förfrågan

Response

Uppdatera grupp [Ta bort medlemmar]

Förfrågan

Response

Ta bort grupp

Förfrågan

Response

Schemaidentifiering

Identifiera schema

Förfrågan

Response

Säkerhetskrav

IP-intervall

Skapa en SCIM-slutpunkt

Skapa en anpassad SCIM-slutpunkt

Hantera slutpunktsautentisering

Hantera etablering och avetablering av användare

Integrera DIN SCIM-slutpunkt med Microsoft Entra-etableringstjänsten

Komma igång

Publicera ditt program till Microsoft Entra-programgalleriet

Checklista för galleri onboarding

Auktorisering för etablering av anslutningsappar i programgalleriet

Beviljandeflöde för OAuth-kod

Så här konfigurerar du OAuth-kod bevilja flöde

Bocklista för gallerilansering

Nästa steg