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

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 Anslut ger SCIM administratörer en standardbaserad lösning från slutpunkt till slutpunkt för åtkomsthantering.

Provisioning from Microsoft Entra ID to an app with 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.

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. [Valfritt] Publicera ditt program till Microsoft Entra-programgalleriet – Gör det enkelt för kunderna att identifiera ditt program och enkelt konfigurera etablering.

Diagram that shows the required steps for integrating a SCIM endpoint with 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 osv.) 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:

  1. 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).

  2. 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.

  3. 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
Manager Manager Manager
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/2819c223-7f76-453a-919d-413861904646"
   }
}   

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
Manager 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, titleoch emails, medan en annan tjänstleverantör använder name, titleoch phoneNumbers. Schemaslutpunkten tillåter identifiering av de attribut som stöds.
/Bulk 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 testflödet Anslut ion.
  • 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.

Diagram that shows the user deprovisioning sequence.

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:

Diagram that shows the group deprovisioning sequence.

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

Gruppåtgärder

Schemaidentifiering

Användaråtgärder

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

Skapa användare

Begär

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_ab6490ee-1e48-479e-a20b-2d77186b5dd1",
    "active": true,
    "emails": [{
        "primary": true,
        "type": "work",
        "value": "Test_User_fd0ea19b-0777-472c-9f96-4f70d2226f2e@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_ab6490ee-1e48-479e-a20b-2d77186b5dd1",
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName",
    },
    "active": true,
    "emails": [{
        "value": "Test_User_fd0ea19b-0777-472c-9f96-4f70d2226f2e@testuser.com",
        "type": "work",
        "primary": true
    }]
}

Hämta användare

Begär

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_feed3ace-693c-4e5a-82e2-694be1b39934",
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName",
    },
    "active": true,
    "emails": [{
        "value": "Test_User_22370c1a-9012-42b2-bf64-86099c2a1c22@testuser.com",
        "type": "work",
        "primary": true
    }]
}
Begär

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

Begär

GET /Users?filter=userName eq "Test_User_dfeef4c5-5681-4387-b016-bdf221e82081"

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_dfeef4c5-5681-4387-b016-bdf221e82081",
        "name": {
            "familyName": "familyName",
            "givenName": "givenName"
        },
        "active": true,
        "emails": [{
            "value": "Test_User_91b67701-697b-46de-b864-bd0bbe4f99c1@testuser.com",
            "type": "work",
            "primary": true
        }]
    }],
    "startIndex": 1,
    "itemsPerPage": 20
}

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

Begär

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]

Begär

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_fbb9dda4-fcde-4f98-a68b-6c5599e17c27",
    "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]

Begär

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_49dc1090-aada-4657-8434-4995c25a00f7@testuser.com",
        "type": "work",
        "primary": true
    }]
}

Inaktivera användare

Begär

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

Begär

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

Begär

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

Begär

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

Begär

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]

Begär

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]

Begär

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]

Begär

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

Begär

DELETE /Groups/cdb1ce18f65944079d37 HTTP/1.1

Response

HTTP/1.1 204 Inget innehåll

Schemaidentifiering

Identifiera schema

Begär

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 Microsoft Entra-ID-taggen 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, i Azure, i AWS osv.). 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. Använd samlingen med Postman-tester som tillhandahålls som en del av referenskoden eller kör 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.

Breakdown: A request translated into calls to the provider's methods

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/12345678-0000-0000-0000-000000000000/" 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 12345678-0000-0000-0000-0000000000000000 ä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/12345678-0000-0000-0000-000000000000/";
                options.Audience = "8adf8e6e-67b2-4cf2-a259-e3dc5476c621";
                ...
            });
    }
    ...
}

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

En ägartoken krävs också för att använda de angivna Postman-testerna och utföra lokal felsökning med localhost. 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/54D382A4-2050-4C03-94D1-E769F1D15682 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: "54D382A4-2050-4C03-94D1-E769F1D15682"
  • 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: "54D382A4-2050-4C03-94D1-E769F1D15682"
  • Parametrar. AlternateFilters.ElementAt(y). AttributePath: "manager"
  • Parametrar. AlternateFilters.ElementAt(y). ComparisonOperator: ComparisonOperator.Equals
  • Parametrar. AlternateFilter.ElementAt(y). ComparisonValue: "2819c223-7f76-453a-919d-413861904646"
  • 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/54D382A4-2050-4C03-94D1-E769F1D15682 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/2819c223-7f76-453a-919d-413861904646",
              "value":"2819c223-7f76-453a-919d-413861904646"}]}]}

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 "54D382A4-2050-4C03-94D1-E769F1D15682"
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/2819c223-7f76-453a-919d-413861904646
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.ElementAt(0).Value 2819c223-7f76-453a-919d-413861904646

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/54D382A4-2050-4C03-94D1-E769F1D15682 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: "54D382A4-2050-4C03-94D1-E769F1D15682"
  • 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:

  1. Logga in på administrationscentret för Microsoft Entra som minst programadministratör.

  2. Bläddra till Identity>Applications Enterprise-program.>

  3. En lista över alla konfigurerade appar visas, inklusive appar som har lagts till från galleriet.

  4. Välj + Nytt program>+ Skapa ett eget program.

  5. 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:

    Screenshot shows the Microsoft Entra application gallery.

  6. På skärmen apphantering väljer du Etablering i den vänstra panelen.

  7. På menyn Etableringsläge väljer du Automatisk.

    Följande skärmbild visar konfigurationen av etableringsinställningar i administrationscentret för Microsoft Entra:

    Screenshot of app provisioning page in the Microsoft Entra admin center.

  8. I fältet Klient-URL anger du URL:en för programmets SCIM-slutpunkt. Exempel: https://api.contoso.com/scim/

  9. 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.

  10. Välj Testa Anslut ion om du vill att Microsoft Entra-ID ska försöka ansluta till SCIM-slutpunkten. Om försöket misslyckas visas felinformation.

    Kommentar

    Testa Anslut ion frågar SCIM-slutpunkten för 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.

  11. Om försöken att ansluta till programmet lyckas väljer du Spara för att spara administratörsautentiseringsuppgifterna.

  12. 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".

  13. 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 .

  14. När konfigurationen är klar anger du Etableringsstatus till .

  15. Välj Spara för att starta Microsoft Entra-etableringstjänsten.

  16. 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.

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.

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

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.

Vi rekommenderar, men inte krävs, att du stöder flera hemligheter för enkel förnyelse utan stilleståndstid.

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

  1. Logga in på administrationscentret för Microsoft Entra som minst programadministratör.

  2. Bläddra till Identity>Applications Enterprise-program>>Programetablering> och välj Auktorisera.

  3. Logga in på administrationscentret för Microsoft Entra som minst programadministratör.

  4. Bläddra till Identity>Applications Enterprise-program.>

  5. Välj ditt program och gå till Etablering.

  6. 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

  7. 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.

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 Twitter, 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 Twitter-inlägg
  • Skapa eller uppdatera dina marknadsföringssidor/din webbplats (t.ex. integrationssida, partnersida, prissida osv.) 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