Handleiding: Ontwikkelen en plannen van de inrichting voor een SCIM-eindpunt in Microsoft Entra ID

Als toepassingsontwikkelaar kunt u de USER Management-API (System for Cross-Domain Identity Management) gebruiken om automatische inrichting van gebruikers en groepen tussen uw toepassing en Microsoft Entra ID mogelijk te maken. In dit artikel wordt beschreven hoe u een SCIM-eindpunt bouwt en integreert met de Microsoft Entra inrichtingsservice. De SCIM-specificatie biedt een gemeenschappelijk gebruikersschema voor provisioning. Wanneer SCIM wordt gebruikt met federatiestandaarden zoals SAML of OpenID Connect, biedt SCIM beheerders een end-to-end oplossing op basis van standaarden voor toegangsbeheer.

SCIM 2.0 is een gestandaardiseerd protocol dat kernresource-eindpunten definieert, waaronder een /Users eindpunt en een /Groups eindpunt. Er worden algemene REST API-eindpunten gebruikt om objecten te maken, bij te werken en te verwijderen. De SCIM bestaat uit een vooraf gedefinieerd schema voor algemene kenmerken, zoals groepsnaam, gebruikersnaam, voornaam, achternaam en e-mail.

Apps die een SCIM 2.0 REST API bieden, kunnen de last van werken met een propriëtair gebruikersbeheer-API verminderen of elimineren. Elke compatibele SCIM-client weet bijvoorbeeld hoe een HTTP POST van een JSON-object naar het /Users eindpunt moet worden gemaakt om een nieuwe gebruikersvermelding te maken. In plaats van een iets andere API voor dezelfde basisacties nodig te hebben, kunnen apps die voldoen aan de SCIM-standaard direct profiteren van bestaande clients, hulpprogramma's en code.

Met het standaardobjectschema en rest-API's voor beheer die zijn gedefinieerd in SCIM 2.0 (RFC 7642, 7643, 7644) kunnen id-providers en apps eenvoudiger met elkaar worden geïntegreerd. Toepassingsontwikkelaars die een SCIM-eindpunt bouwen, kunnen worden geïntegreerd met elke SCIM-compatibele client zonder dat ze aangepast werk hoeven te doen.

Als u het inrichten voor een toepassing wilt automatiseren, moet er een SCIM-eindpunt worden gebouwd en geïntegreerd dat toegankelijk is voor de Microsoft Entra inrichtingsservice. Gebruik de volgende stappen om gebruikers en groepen in te richten in uw toepassing.

1. Ontwerp uw gebruikers- en groepsschema - Identificeer de objecten en kenmerken van de toepassing om te bepalen hoe deze worden toegewezen aan het gebruikers- en groepsschema dat wordt ondersteund door de Microsoft Entra SCIM-implementatie.

2. Begrijp de Microsoft Entra SCIM-implementatie - Begrijp hoe de Microsoft Entra inrichtingsservice is geïmplementeerd om de manier waarop uw SCIM-protocolaanvragen worden verwerkt en beantwoord te modelleren.

3. Build a SCIM endpoint - Om te integreren met de Microsoft Entra voorzieningsservice, moet een eindpunt SCIM 2.0-compatibel zijn. Gebruik als optie Microsoft CLI-bibliotheken (Common Language Infrastructure) en codevoorbeelden om uw eindpunt te bouwen. Deze voorbeelden zijn alleen bedoeld voor referentie en testen; we raden u af deze als afhankelijkheden in uw productieapplicatie te gebruiken.

4. Integreer uw SCIM-eindpunt met de Microsoft Entra-provisioningservice. Microsoft Entra ID ondersteunt verschillende toepassingen van derden die SCIM 2.0 implementeren. Als u een van deze apps gebruikt, kunt u snel de toewijzing en intrekking van gebruikers en groepen automatiseren.

5. [Optioneel] Publiceer uw toepassing in de Microsoft Entra toepassingsgalerie : maak het eenvoudig voor klanten om uw toepassing te detecteren en eenvoudig inrichting te configureren.

Uw gebruikers- en groepsschema ontwerpen

Voor elke toepassing zijn verschillende kenmerken vereist om een gebruiker of groep te maken. Start uw integratie door de vereiste objecten (gebruikers, groepen) en kenmerken (naam, manager, functie, enzovoort) te identificeren die uw toepassing nodig heeft.

De SCIM-standaard definieert een schema voor het beheren van gebruikers en groepen.

Het basisgebruikersschema vereist slechts drie kenmerken (alle andere kenmerken zijn optioneel):

• id, door serviceprovider gedefinieerde id
• userName, een unieke identificator voor de gebruiker (komt over het algemeen overeen met de Microsoft Entra gebruikers-principalnaam)
• meta, alleen lezen metagegevens onderhouden door de dienstverlener

Naast het basisgebruikersschema definieert de SCIM-standaard een enterprise-gebruikersextensie met een model voor het uitbreiden van het gebruikersschema om te voldoen aan de behoeften van uw toepassing.

Als uw toepassing bijvoorbeeld zowel het e-mailadres van een gebruiker als de manager van een gebruiker vereist, gebruikt u het kernschema om het e-mailadres van de gebruiker en het schema van de ondernemingsgebruiker te verzamelen om de manager van de gebruiker te verzamelen.

Voer de volgende stappen uit om uw schema te ontwerpen:

1. Vermeld de kenmerken die uw toepassing nodig heeft en categoriseer vervolgens als kenmerken die nodig zijn voor verificatie (bijvoorbeeld loginName en e-mail). Kenmerken zijn nodig om de levenscyclus van de gebruiker te beheren (bijvoorbeeld status/actief) en alle andere kenmerken die nodig zijn om de toepassing te laten werken (bijvoorbeeld manager, tag).

2. Controleer of de kenmerken al zijn gedefinieerd in het basisschema van de gebruiker of het enterprise-gebruikersschema . Zo niet, dan moet u een extensie definiëren voor het gebruikersschema dat betrekking heeft op de ontbrekende kenmerken. Zie een voorbeeld voor een extensie voor de gebruiker om het inrichten van een gebruiker tagtoe te staan.

3. Wijs SCIM-kenmerken toe aan de gebruikerskenmerken in Microsoft Entra ID. Als een van de kenmerken die u hebt gedefinieerd in uw SCIM-eindpunt geen duidelijke tegenhanger heeft in het Microsoft Entra gebruikersschema, begeleidt u de tenantbeheerder om het schema uit te breiden of gebruikt u een extensiekenmerk, zoals wordt weergegeven in het voorbeeld voor de eigenschap tags.

De volgende tabel bevat een voorbeeld van vereiste kenmerken:

De volgende JSON-nettolading toont een voorbeeld van een 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"
   }
}   

Het helpt bij het categoriseren tussen /User en /Group om standaardgebruikerskenmerken in Microsoft Entra ID toe te wijzen aan scim RFC. Zie hoe u kenmerken aanpast tussen Microsoft Entra ID en uw SCIM-eindpunt.

De volgende tabel bevat een voorbeeld van gebruikerskenmerken:

De volgende tabel bevat een voorbeeld van groepskenmerken:

Er zijn verschillende eindpunten gedefinieerd in de SCIM RFC. U kunt beginnen met het /User eindpunt en vervolgens uitbreiden. De volgende tabel bevat een aantal SCIM-eindpunten:

Inzicht in de Microsoft Entra SCIM-implementatie

De Microsoft Entra inrichtingsservice is ontworpen ter ondersteuning van een SCIM 2.0-API voor gebruikersbeheer.

Binnen de specificatie van het SCIM 2.0-protocol moet uw toepassing ondersteuning bieden voor deze vereisten:

Gebruik de algemene richtlijnen bij het implementeren van een SCIM-eindpunt om compatibiliteit met Microsoft Entra ID te garanderen:

Algemeen:

• id is een vereiste eigenschap voor alle resources. Elk antwoord dat een resource retourneert, moet ervoor zorgen dat elke resource deze eigenschap heeft, met uitzondering van gevallen met ListResponse nul elementen.
• Waarden die worden verzonden, moeten worden opgeslagen in dezelfde indeling als ze zijn verzonden. Ongeldige waarden moeten worden geweigerd met een beschrijvend, uitvoerbaar foutbericht. Transformaties van gegevens mogen niet plaatsvinden tussen gegevens uit Microsoft Entra ID en gegevens die zijn opgeslagen in de SCIM-toepassing. (bijvoorbeeld). Een telefoonnummer dat is verzonden als 55555555555 mag niet worden opgeslagen/geretourneerd als +5 (555) 555-5555)
• Het is niet nodig om de hele resource op te nemen in het PATCH-antwoord .
• Er is geen hoofdlettergevoelige overeenkomst vereist voor structurele elementen in SCIM, met name PATCH-bewerkingswaardenop, zoals gedefinieerd in sectie 3.5.2. Microsoft Entra ID verzendt de waarden van op als Add, Replace en Remove.
• Microsoft Entra ID aanvragen doet om een willekeurige gebruiker en groep op te halen om ervoor te zorgen dat het eindpunt en de referenties geldig zijn. Dit wordt ook gedaan als onderdeel van het proces Verbinding testen.
• Ondersteuning voor HTTPS op uw SCIM-eindpunt.
• Aangepaste complexe en multivalued kenmerken worden ondersteund, maar Microsoft Entra ID heeft niet veel complexe gegevensstructuren om gegevens uit te halen in deze gevallen. Naam-/waardekenmerken kunnen eenvoudig worden toegewezen, maar het doorsluizen van data naar complexe kenmerken met drie of meer subattributen wordt niet ondersteund.
• De "type" subattribuutwaarden van complexe attributen met meerdere waarden moeten uniek zijn. Er kunnen bijvoorbeeld geen twee verschillende e-mailadressen zijn met het subtype 'werk'.
• De header voor alle antwoorden moet van het inhoudstype zijn: application/scim+json

Resources ophalen

• Antwoord op een queryverzoek of filterverzoek moet altijd een ListResponse zijn.
• Microsoft Entra maakt alleen gebruik van de volgende operators: eq, and
• Het kenmerk waarop de resources kunnen worden opgevraagd, moet worden ingesteld als een overeenkomend kenmerk in de toepassing. Zie Toewijzingen van gebruikersinrichtingskenmerken aanpassen.

/Gebruikers:

• Het kenmerk Rechten wordt niet ondersteund.
• Kenmerken die in aanmerking komen voor de uniekheid van de gebruiker, moeten kunnen worden gebruikt als onderdeel van een gefilterde query. (Als de uniekheid van de gebruiker bijvoorbeeld wordt geëvalueerd voor zowel userName als e-mails[type eq "work"], moet een GET to /Users met een filter zowel userName eq "user@contoso.com" als emails[type eq "work"].value eq "user@contoso.com" query's toestaan.

/Groepen:

• Groepen zijn optioneel, maar worden alleen ondersteund als de SCIM-implementatie PATCH-aanvragen ondersteunt.
• Groepen moeten een unieke 'displayName'-waarde hebben om te voldoen aan Microsoft Entra ID en de SCIM-toepassing. De uniekheid is geen vereiste van het SCIM-protocol, maar is een vereiste voor het integreren van een SCIM-eindpunt met Microsoft Entra ID.

/Schema's (schemadetectie):

• Voorbeeld van aanvraag/antwoord
• Schemadetectie wordt gebruikt voor bepaalde galerietoepassingen. Schemadetectie is de enige methode om meer kenmerken toe te voegen aan het schema van een bestaande SCIM-toepassing in de galerie. Schemadetectie wordt momenteel niet ondersteund voor aangepaste en niet-galerij SCIM-toepassingen.
• Als een waarde niet aanwezig is, verzendt u geen null-waarden.
• Eigenschapswaarden moeten in camelcase zijn (bijvoorbeeld readWrite).
• Er moet een lijst met antwoorden worden gegeven.
• De Microsoft Entra inrichtingsservice verstuurt de aanvraag /schemas wanneer u de inrichtingsconfiguratie opslaat. De aanvraag wordt ook ingediend wanneer u de pagina voor het bewerken van de inrichting opent. Andere gedetecteerde kenmerken worden aan klanten weergegeven in de kenmerktoewijzingen onder de lijst met doelkenmerken. Schemadetectie leidt alleen tot meer doelkenmerken die worden toegevoegd. Kenmerken worden niet verwijderd.

Toelichting en intrekking van gebruikersaccounts

In het volgende diagram ziet u de berichten die Microsoft Entra ID verzendt naar een SCIM-eindpunt om de levenscyclus van een gebruiker in het identiteitsarchief van uw toepassing te beheren.

Voorziening en devoorziening van groepen

Groepsvoorziening en intrekking zijn optioneel. Wanneer deze is geïmplementeerd en ingeschakeld, ziet u in de volgende afbeelding de berichten die Microsoft Entra ID verzendt naar een SCIM-eindpunt om de levenscyclus van een groep in het identiteitsarchief van uw toepassing te beheren. Deze berichten verschillen op twee manieren van de berichten over gebruikers:

• Aanvragen voor het ophalen van groepen geven aan dat het ledenkenmerk moet worden uitgesloten van elke resource die wordt geleverd als reactie op de aanvraag.
• Aanvragen om te bepalen of een verwijzingskenmerk een bepaalde waarde heeft, hebben betrekking op het ledenkenmerk.

In het volgende diagram ziet u de volgorde van de deprovisioning van groepen:

SCIM-protocolaanvragen en -antwoorden

Dit artikel bevat voorbeelden van SCIM-aanvragen die worden verzonden door de Microsoft Entra inrichtingsservice en voorbeeld van verwachte antwoorden. Voor de beste resultaten moet u uw app codeeren om deze aanvragen in deze indeling te verwerken en de verwachte antwoorden te verzenden.

Gebruikershandelingen

• Gebruiker maken (antwoord aanvragen / )
• Gebruiker ophalen (Aanvraag / Antwoord)
• Gebruiker opvragen met query (Verzoek / Antwoord)
• Gebruiker ophalen via query - Nul resultaten (Aanvraag / Antwoord)
• Gebruiker bijwerken [Eigenschappen met meerdere waarden] (Antwoord op aanvraag / )
• Gebruiker bijwerken [Eigenschappen met één waarde] (Antwoord op aanvraag / )
• Gebruiker uitschakelen (antwoord aanvragen / )
• Gebruiker verwijderen (antwoord aanvragen / )

Groepsbewerkingen

• Groep maken (antwoord op aanvraag / )
• Groep ophalen (Request / Response)
• Haal de groep op via displayName (Aanvraag / Antwoord)
• Groep bijwerken [niet-lidkenmerken] (Antwoord aanvragen / )
• Groep bijwerken [Leden toevoegen] (antwoord aanvragen / )
• Groep bijwerken [Leden verwijderen] (antwoord aanvragen / )
• Groep verwijderen (antwoord op aanvraag / )

Schemadetectie

• Schema detecteren (antwoord op aanvraag / )

Gebruikersbewerkingen

• Gebruik userName of emails[type eq "work"] kenmerken om query's uit te voeren op gebruikers.

Gebruiker maken

Aanvraag

POST /Gebruikers

{
    "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": []
}

Reactie

HTTP/1.1 201 gemaakt

{
    "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
    }]
}

Validaties uitgevoerd door SCIM Validator

Nieuwe gebruiker maken

• POST /Users: hiermee maakt u een nieuwe gebruiker met een volledige JSON-nettolading.
  • Eindpunt retourneert HTTP 201
  • POST-antwoord bevat gemaakte gebruikers-id
• GET /Users?filter={joiningProperty} eq "value" – Controleert het maken door te filteren op de eigenschap voor samenvoegen.
  • GET retourneert gecreëerde gebruiker
  • Geretourneerde waarden van GET komen overeen met de doorgegeven waarden uit de POST-aanvraag (varieert op basis van eindpunt)
• DELETE /Users : testgebruiker opschonen. -Alleen aangeroepen als harde verwijdering wordt ondersteund

Dubbele gebruiker maken

• POST /Users - probeert een gebruiker te maken met behulp van een identieke payload (met hetzelfde unieke of samenvoegende kenmerk) van een bestaande gebruiker.
  • HTTP 201 retourneren bij de eerste aanvraag voor aanmaken
  • HTTP 409 retourneren bij tweede verzoek tot aanmaken

Gebruiker ophalen

Aanvraag

GET /users/5d48a0a8e9f04aa38008

Antwoord (gebruiker gevonden)

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
    }]
}

Aanvraag

GET /Users/5171a35d82074e068ce2

Antwoord (gebruiker is niet gevonden. De details zijn niet vereist, alleen de status.)

HTTP/1.1 404 niet gevonden

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

Gebruiker opzoeken met query

Aanvraag

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

Reactie

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
}

Gebruiker opvragen op basis van een query - Nul resultaten

Aanvraag

GET /Users?filter=userName eq "niet-bestaande gebruiker"

Reactie

HTTP/1.1 200 OK

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

Gebruiker bijwerken [Eigenschappen met meerdere waarden]

Aanvraag

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"
            }
    ]
}

Reactie

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
    }]
}

Gebruiker bijwerken [Eigenschappen met één waarde]

Aanvraag

PATCH /Gebruikers/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"
    }]
}

Reactie

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
    }]
}

Validaties uitgevoerd door SCIM Validator

Kenmerken toevoegen

• POST /Users - Maakt de gebruikersresource
  • HTTP 2xx geslaagd
• PATCH /Users/{id}: maakt gebruik van een JSON Patch-document (met de bewerking toevoegen) om extra niet-vereiste kenmerken in te voegen.
• GET /Users?filter={joiningProperty} eq "value": haalt de gebruiker op om de toegevoegde kenmerken te verifiëren.
  • Gebruiker wordt geretourneerd
  • Ingevoegde kenmerken zijn nu aanwezig op de gebruiker

Gebruikerskenmerken vervangen

• POST /Users - Maakt de gebruikersresource
  • HTTP 2xx geslaagd
• PATCH /Users/{id}: verzendt een JSON Patch-document (met behulp van de vervangingsbewerking) om een of meer kenmerken bij te werken.
• GET /Users?filter={joiningProperty} eq "value" – Controleert of de bijgewerkte kenmerken correct zijn toegepast.
  • Gebruiker wordt geretourneerd
  • Bijgewerkte kenmerken zijn aanwezig voor de gebruiker

Koppelingskenmerk bijwerken

• POST /Users - Maakt de gebruikersresource
  • HTTP 2xx geslaagd
• PATCH /Users/{id}: werkt de eigenschap voor deelname (bijvoorbeeld userName) bij via een JSON Patch-document.
• GET /Users?filter={joiningProperty} eq "newValue": bevestigt dat het koppelingsattribuut is bijgewerkt.
  • De eigenschap wordt bijgewerkt op de gebruiker

Gebruiker uitschakelen

Aanvraag

PATCH /Gebruikers/5171a35d82074e068ce2 HTTP/1.1

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

Reactie

{
    "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"
    }
}

Validaties uitgevoerd door SCIM Validator

Actief kenmerk bijwerken naar onwaar

• POST /Users/ - Maakt een resource op basis van het schema
  • HTTP 2xx geslaagd
  • Uitgeschakelde gebruiker moet worden geretourneerd bij GET-aanvraag
• PATCH /Users/{id}: geeft een JSON Patch-document uit waarmee het kenmerk Actief wordt ingesteld op False.
  • HTTP 2xx geslaagd
• GET /Users?filter={joiningProperty} eq "value": haalt de gebruiker op om te bevestigen dat het actieve kenmerk nu onwaar is.
  • Geretourneerde gebruikersrecord moet ACTIVE=FALSE hebben"

Gebruiker verwijderen

Aanvraag

DELETE /Gebruikers/5171a35d82074e068ce2 HTTP/1.1

Reactie

HTTP/1.1 204 Geen inhoud

Groepsbewerkingen

• Groepen worden gemaakt met een lege ledenlijst.
• Gebruik het displayName kenmerk om query's uit te voeren op groepen.
• Bijwerken van het PATCH-verzoek van de groep moet een HTTP 204 Geen inhoud in het antwoord opleveren. Het is niet raadzaam om een lichaam met een lijst met alle leden te retourneren.
• Het is niet nodig om het ondersteunen van de terugkeer van alle leden van de groep.

Groep maken

Aanvraag

POST /Groepen 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"
    }
}

Reactie

HTTP/1.1 201 gemaakt

{
    "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": []
}

Validaties uitgevoerd door SCIM Validator

Nieuwe groep maken

• POST /Groups: hiermee maakt u een nieuwe groep met een volledige JSON-nettolading.
  • Eindpunt retourneert HTTP 201
  • POST-antwoord bevat gemaakte groeps-id
• GET /Group?filter={joiningProperty} eq "value" – Controleert het maken door te filteren op de eigenschap voor samenvoegen.
  • GET retourneert een gemaakte groep
  • Geretourneerde waarden van GET komen overeen met de doorgegeven waarden uit de POST-aanvraag (varieert op basis van eindpunt)
• DELETE /Groups : testgebruiker opschonen.
  • Alleen aangeroepen als hard verwijderen wordt ondersteund

Dubbele groep maken

• POST /Groepen: probeert een groep te maken met behulp van een identieke payload (met hetzelfde unieke/samenvoegkenmerk) aan een bestaande groep.
  • HTTP 201 retourneren bij de eerste aanvraag voor aanmaken
  • HTTP 409 retourneren bij tweede verzoek tot aanmaken

Groep opvragen

Aanvraag

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

Reactie

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",
}

Verkrijg groep op displayName

Aanvraag

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

Reactie

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
}

Groep bijwerken [niet-lidkenmerken]

Aanvraag

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"
    }]
}

Reactie

HTTP/1.1 204 Geen inhoud

Validaties uitgevoerd door SCIM Validator

Groepskenmerken bijwerken

• POST/Groepen - Hiermee maakt u een nieuwe groepsresource voor het bijwerken van kenmerken op
  • POST retourneert HTTP 2xx
• PATCH /Groups/{id}: verzendt een JSON Patch-document met behulp van de vervangingsbewerking om een of meer kenmerken van een bestaande groep bij te werken (met uitzondering van leden).
  • PATCH retourneert succes (HTTP 2xx)
• GET /Groups?filter={joiningProperty} eq "value": bevestigt dat de kenmerken van de groep correct zijn bijgewerkt.
  • GET retourneert een gepatchte groep
  • Kenmerken van geretourneerde groepsattributen komen overeen met de gewijzigde kenmerken in de PATCH-aanvraag.

Groep bijwerken [Leden toevoegen]

Aanvraag

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"
        }]
    }]
}

Reactie

HTTP/1.1 204 Geen inhoud

Validaties uitgevoerd door SCIM Validator

Een nieuwe groepsresource maken

• POST /Groups - Hiermee maakt u een nieuwe groepsresource om lid toe te voegen aan
  • POST retourneert HTTP 2xx
• POST /Users: hiermee maakt u een nieuwe gebruikersresource die moet worden gebruikt als groepslid.
  • POST retourneert HTTP 2xx
• PATCH /Groups/{id}: voegt de id van de zojuist gemaakte gebruiker toe aan de groep met behulp van een JSON Patch-document.
  • PATCH retourneert succes

Groep bijwerken [Leden verwijderen]

Aanvraag

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"
        }]
    }]
}

Reactie

HTTP/1.1 204 Geen inhoud

Groep verwijderen

Aanvraag

VERWIJDEREN /groups/cdb1ce18f65944079d37 HTTP/1.1

Reactie

HTTP/1.1 204 Geen inhoud

Schema-ontdekking

Schema ontdekken

Aanvraag

GET /Schemas

Reactie

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"
    }
  }
]
}

Beveiligingsvereisten

TLS-protocolversies

De enige acceptabele protocolversie is TLS 1.2. Er is geen andere SSL/TLS-versie toegestaan.

• RSA-sleutels moeten ten minste 2048 bits zijn.
• ECC-sleutels moeten ten minste 256 bits zijn, gegenereerd met behulp van een goedgekeurde elliptische curve

Sleutellengten

Alle services moeten X.509-certificaten gebruiken die zijn gegenereerd met behulp van cryptografische sleutels van voldoende lengte, wat betekent:

Versleutelingssuites

Alle services moeten worden geconfigureerd voor gebruik van de volgende coderingssuites, in de exacte volgorde die in het voorbeeld is opgegeven. Als u alleen een RSA-certificaat hebt, hebben de ECDSA-cijfersuites geen effect.

Minimumniveau TLS 1.2 Coderingssuites:

• 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-bereiken

De Microsoft Entra inrichtingsservice werkt momenteel met de IP-bereiken voor Microsoft Entra ID zoals vermeld hier. U kunt de IP-bereiken die worden vermeld onder de tag AzureActiveDirectory toevoegen om verkeer van de Microsoft Entra inrichtingsservice naar uw toepassing toe te staan. U moet de lijst met IP-bereiken zorgvuldig bekijken voor berekende adressen. Een adres zoals '40.126.25.32' kan worden weergegeven in de lijst met IP-bereiken als '40.126.0.0/18'. U kunt de lijst met IP-bereiken ook programmatisch ophalen met behulp van de volgende API.

Microsoft Entra ID ondersteunt ook een oplossing op basis van een agent om connectiviteit te bieden met toepassingen in privénetwerken (on-premises, gehost in Azure, gehost in AWS, enzovoort). Klanten kunnen een lichtgewicht agent implementeren, die connectiviteit biedt met Microsoft Entra ID zonder binnenkomende poorten te openen, op een server in hun privénetwerk. Meer informatie hier.

Een SCIM-eindpunt bouwen

Nu u uw schema hebt ontworpen en de Microsoft Entra SCIM-implementatie begrijpt, kunt u aan de slag met het ontwikkelen van uw SCIM-eindpunt. In plaats van helemaal zelf te beginnen en de implementatie volledig zelf te bouwen, kunt u vertrouwen op veel open source SCIM-bibliotheken die zijn gepubliceerd door de SCIM-community.

Zie Een SCIM-voorbeeldeindpunt ontwikkelen voor hulp bij het bouwen van een SCIM-eindpunt, inclusief voorbeelden.

Het open source .NET Core referentiecodevoorbeeld gepubliceerd door het Microsoft Entra-inrichtingsteam is een dergelijke resource die uw ontwikkeling kan versnellen. Bouw een SCIM-eindpunt en test het vervolgens door de verstrekte voorbeeldaanvragen /antwoorden uit te voeren.

De oplossing bestaat uit twee projecten, Microsoft. SCIM en Microsoft. SCIM. WebHostSample.

De Microsoft. SCIM project is de bibliotheek die de onderdelen van de webservice definieert die voldoet aan de SCIM-specificatie. Het verklaart de interface Microsoft.SCIM.IProvider. Aanvragen worden vertaald naar oproepen van de methoden van de provider, die zo geprogrammeerd zouden zijn om op een identiteitsarchief te werken.

De Microsoft. SCIM. WebHostSample project is een ASP.NET Core-webtoepassing op basis van de sjabloon Empty. Hiermee kan de voorbeeldcode worden geïmplementeerd als zelfstandige toepassing, gehost worden in containers of via Internet Information Services. Het implementeert ook de Microsoft. SCIM. IProvider interface die klassen in het geheugen bewaart als voorbeeldidentiteitsarchief.

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();
    }
    ...

Een aangepast SCIM-eindpunt bouwen

Het SCIM-eindpunt moet een HTTP-adres en serververificatiecertificaat hebben waarvan de basiscertificeringsinstantie een van de volgende namen heeft:

• CNNIC
• Comodo
• Cybervertrouwen
• DigiCert
• GeoTrust
• GlobalSign
• Go Daddy
• VeriSign
• WoSign
• DST Root CA X3

De .NET Core SDK bevat een HTTPS-ontwikkelingscertificaat dat tijdens de ontwikkeling wordt gebruikt. Het certificaat wordt geïnstalleerd als onderdeel van de first-run-ervaring. Afhankelijk van hoe u de ASP.NET Core-webtoepassing uitvoert, luistert deze naar een andere poort:

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

Gebruik de volgende koppeling voor meer informatie over HTTPS in ASP.NET Core: Enforce HTTPS in ASP.NET Core

Omgaan met eindpuntverificatie

Aanvragen van de Microsoft Entra voorzieningsservice bevatten een OAuth 2.0 bearer-token. Een autorisatieserver geeft het bearer-token uit. Microsoft Entra ID is een voorbeeld van een vertrouwde autorisatieserver. Configureer de Microsoft Entra provisioneringsservice om een van de volgende tokens te gebruiken.

• Een bearer-token met een lange levensduur. Als voor het SCIM-eindpunt een OAuth Bearer-token van een andere verlener dan Microsoft Entra ID is vereist, kopieert u het vereiste OAuth Bearer-token naar het optionele Secret-token veld. In een ontwikkelomgeving kunt u het testtoken van het /scim/token eindpunt gebruiken. Testtokens mogen niet worden gebruikt in productieomgevingen.

• Microsoft Entra bearertoken. Als Secret-token leeg blijft, bevat Microsoft Entra ID een OAuth Bearer-token dat is uitgegeven vanuit Microsoft Entra ID bij elke aanvraag. Apps die Microsoft Entra ID als id-provider gebruiken, kunnen dit Microsoft Entra ID uitgegeven token valideren.

  • De toepassing die aanvragen ontvangt, moet de tokenverlener valideren als Microsoft Entra ID voor een verwachte Microsoft Entra tenant.
  • Een iss claim identificeert de uitgever van het token. Bijvoorbeeld: "iss":"https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/". In dit voorbeeld: het basisadres van de claimwaarde, https://sts.windows.net identificeert Microsoft Entra ID als de verlener, terwijl het relatieve adressegment, aabbbb-0000-cccc-1111-ddd22222eeeee, een unieke id is van de Microsoft Entra-tenant waarvoor het token is uitgegeven.
  • De doelgroep voor een token is de toepassings-id voor de toepassing in de galerie. Toepassingen die zijn geregistreerd in één tenant, ontvangen dezelfde iss claim met SCIM-aanvragen. De toepassings-id voor alle aangepaste apps is 8adf8e6e-67b2-4cf2-a259-e3dc5476c621. Het token dat door de Microsoft Entra ID wordt gegenereerd, mag alleen worden gebruikt voor het testen. Deze mag niet worden gebruikt in productieomgevingen.

In de voorbeeldcode worden aanvragen geverifieerd met behulp van de Microsoft. AspNetCore.Authentication.JwtBearer-pakket. Met de volgende code wordt afgedwongen dat aanvragen voor een van de eindpunten van de service worden geverifieerd met behulp van het Bearer-token dat is uitgegeven door Microsoft Entra ID voor een opgegeven tenant:

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();
    ...
}

De voorbeeldcode maakt gebruik van ASP.NET Core omgevingen om de verificatieopties tijdens de ontwikkelingsfase te wijzigen en het gebruik van een zelfondertekend token in te schakelen.

Zie Gebruik meerdere omgevingen in ASP.NET Core voor meer informatie over meerdere omgevingen in ASP.NET Core.

Met de volgende code wordt afgedwongen dat aanvragen voor een van de eindpunten van de service worden geverifieerd met behulp van een Bearer-token dat is ondertekend met een aangepaste sleutel:

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"))
                };
        });
    }
...

Verzend een GET-aanvraag naar de tokencontroller om een geldig bearer-token op te halen. De methode GenerateJSONWebToken is verantwoordelijk voor het maken van een token dat overeenkomt met de parameters die zijn geconfigureerd voor ontwikkeling:

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;
}

Beheer van provisioning en deprovisioning van gebruikers

Voorbeeld 1. Een query uitvoeren op de service voor een overeenkomende gebruiker

Microsoft Entra ID voert een query uit op de service voor een gebruiker met een externalId kenmerkwaarde die overeenkomt met de mailNickname-kenmerkwaarde van een gebruiker in Microsoft Entra ID. De query wordt uitgedrukt als een HTTP-aanvraag (Hypertext Transfer Protocol), zoals in dit voorbeeld, waarbij jyoung een voorbeeld is van een mailNickname van een gebruiker in Microsoft Entra ID.

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

In de voorbeeldcode wordt de aanvraag omgezet in een aanroep naar de QueryAsync-methode van de provider van de service. Dit is de handtekening van die methode:

// 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);

In de voorbeeldquery zijn voor een gebruiker met een bepaalde waarde voor het externalId kenmerk de waarden van de argumenten die zijn doorgegeven aan de methode QueryAsync:

• parameters. AlternateFilters.Count: 1
• Parameters. AlternateFilters.ElementAt(0). AttribuutPad: "externalId"
• Parameters. AlternateFilters.ElementAt(0). VergelijkingOperator: VergelijkingOperator.Is gelijk aan
• Parameters. AlternateFilter.ElementAt(0). ComparisonValue: "jyoung"

Voorbeeld 2. Een gebruiker inrichten

Als het antwoord op een query naar het SCIM-eindpunt voor een gebruiker met een externalId kenmerkwaarde die overeenkomt met de mailNickname-kenmerkwaarde van een gebruiker geen gebruikers retourneert, Microsoft Entra ID vraagt de service een gebruiker in te richten die overeenkomt met de waarde in Microsoft Entra ID. Hier volgt een voorbeeld van een dergelijke aanvraag:

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}

In de voorbeeldcode wordt de aanvraag omgezet in een aanroep naar de Methode CreateAsync van de provider van de service. Dit is de handtekening van die methode:

// 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);

In een aanvraag voor het inrichten van gebruikers is de waarde van het resourceargument een exemplaar van de klasse Microsoft.SCIM.Core2EnterpriseUser. Deze klasse wordt gedefinieerd in de bibliotheek Microsoft.SCIM.Schemas. Als de aanvraag voor het inrichten van de gebruiker slaagt, wordt verwacht dat de implementatie van de methode een exemplaar van de klasse Microsoft.SCIM.Core2EnterpriseUser retourneert. De waarde van de Identifier eigenschap wordt ingesteld op de unieke id van de zojuist ingerichte gebruiker.

Voorbeeld 3. De huidige status van een gebruiker opvragen

Microsoft Entra ID vraagt de huidige status van de opgegeven gebruiker van de service aan met een aanvraag zoals:

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

In de voorbeeldcode wordt de aanvraag omgezet in een aanroep naar de methode RetrieveAsync van de provider van de service. Dit is de handtekening van die methode:

// 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);

In het voorbeeld van een aanvraag, om de huidige status van een gebruiker op te halen, zijn de waarden van de eigenschappen van het object dat is opgegeven als de waarde van het parameterargument als volgt:

• Identificatiecode: "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1e1"
• SchemaIdentificator: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Voorbeeld 4. Voer een query uit op de waarde van een verwijzingskenmerk dat moet worden bijgewerkt

Microsoft Entra ID controleert de huidige kenmerkwaarde in het identiteitsarchief voordat u deze bijwerkt. Alleen het kenmerk Manager is echter de eerste controle voor gebruikers. Hier volgt een voorbeeld van een aanvraag om te bepalen of het managerkenmerk van een gebruikersobject momenteel een bepaalde waarde heeft: In de voorbeeldcode wordt de aanvraag omgezet in een aanroep van de QueryAsync-methode van de provider van de service. De waarde van de eigenschappen van het object dat is opgegeven als de waarde van het parameterargument, zijn als volgt:

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

De waarde van de index x kan zijn 0 en de waarde van de index y kan zijn 1. Of de waarde van x kan zijn 1 en de waarde van y kan zijn 0. Dit is afhankelijk van de volgorde van de expressies van de filterqueryparameter.

Example 5. Aanvraag van Microsoft Entra ID naar een SCIM-eindpunt om een gebruiker bij te werken

Hier volgt een voorbeeld van een aanvraag van Microsoft Entra ID naar een SCIM-eindpunt om een gebruiker bij te werken:

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"}]}]}

In de voorbeeldcode wordt de aanvraag omgezet in een aanroep naar de UpdateAsync-methode van de serviceprovider. Dit is de handtekening van die methode:

// 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);

In het voorbeeld van een aanvraag heeft het object dat is opgegeven als de waarde van het patchargument de volgende eigenschapswaarden om een gebruiker bij te werken:

Voorbeeld 6. Een gebruiker deprovisioneren

Als u een gebruiker wilt deprovisioneren vanuit een identiteitsarchief gefaciliteerd door een SCIM-eindpunt, verzendt Microsoft Entra ID een aanvraag zoals:

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

In de voorbeeldcode wordt de aanvraag omgezet in een aanroep naar de DeleteAsync-methode van de provider van de service. Dit is de handtekening van die methode:

// 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);

Het object dat is opgegeven als de waarde van het argument resourceIdentifier heeft deze eigenschapswaarden in het voorbeeld van een aanvraag voor het deprovisioneren van een gebruiker.

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

Uw SCIM-eindpunt integreren met de Microsoft Entra-inrichtingsservice

Microsoft Entra ID kunnen worden geconfigureerd om automatisch toegewezen gebruikers en groepen in te richten voor toepassingen die een specifiek profiel van het protocol SCIM 2.0 implementeren. De details van het profiel worden beschreven in Onderstand de Microsoft Entra SCIM-implementatie.

Neem contact op met uw toepassingsprovider of de documentatie van uw toepassingsprovider voor instructies over compatibiliteit met deze vereisten.

Aan de slag

Toepassingen die ondersteuning bieden voor het SCIM-profiel dat in dit artikel wordt beschreven, kunnen worden verbonden met Microsoft Entra ID met behulp van de functie 'niet-galerietoepassing' in de Microsoft Entra toepassingsgalerie. Zodra verbinding is gemaakt, voert Microsoft Entra ID een synchronisatieproces uit. Het proces wordt elke 40 minuten uitgevoerd. Het proces voert een query uit op het SCIM-eindpunt van de toepassing voor toegewezen gebruikers en groepen en maakt of wijzigt deze op basis van de toewijzingsgegevens.

Een toepassing verbinden die SCIM ondersteunt:

1. Meld u aan bij de Microsoft Entra-beheercentrum als minimaal een Applicatiebeheerder.

2. Blader naar Entra ID>Enterprise apps.

3. Er wordt een lijst weergegeven met alle geconfigureerde apps, inclusief apps die zijn toegevoegd vanuit de galerie.

4. Selecteer + Nieuwe toepassing>+ Uw eigen toepassing maken.

5. Voer een naam in voor uw toepassing, kies de optie 'Een andere toepassing integreren die u niet in de galerie vindt' en selecteer Toevoegen om een app-object te maken. De nieuwe app wordt toegevoegd aan de lijst met bedrijfstoepassingen en wordt geopend op het scherm voor app-beheer.

   In de volgende schermopname ziet u de Microsoft Entra toepassingsgalerie:

   

6. Selecteer Inrichten in het linkerdeelvenster in het scherm App-beheer.

7. Selecteer + Nieuwe configuratie.

8. Voer in het veld Tenant-URL de URL in van het SCIM-eindpunt van de toepassing. Voorbeeld: https://api.contoso.com/scim/

9. Als voor het SCIM-eindpunt een OAuth Bearer-token van een andere verlener dan Microsoft Entra ID is vereist, kopieert u het vereiste OAuth Bearer-token naar het optionele Secret-token veld. Als dit veld leeg blijft, bevat Microsoft Entra ID bij elke aanvraag een OAuth bearer-token dat is uitgegeven vanuit Microsoft Entra ID. Apps die Microsoft Entra ID als id-provider gebruiken, kunnen dit Microsoft Entra ID uitgegeven token valideren.

   Opmerking

   Het wordt not aanbevolen om dit veld leeg te laten en te vertrouwen op een token dat is gegenereerd door Microsoft Entra ID. Deze optie is voornamelijk beschikbaar voor testdoeleinden.

10. Selecteer Test Connection om Microsoft Entra ID verbinding te laten maken met het SCIM-eindpunt. Als de poging mislukt, wordt er informatie over de fout weergegeven.

    Opmerking

    Test Connection voert een query uit op het SCIM-eindpunt voor een gebruiker die niet bestaat, waarbij een willekeurige GUID wordt gebruikt als de overeenkomende eigenschap die is geselecteerd in de Microsoft Entra-configuratie. Het verwachte juiste antwoord is HTTP 200 OK met een leeg SCIM ListResponse-bericht.

11. Als de poging om verbinding te maken met de toepassing slaagt, selecteer dan Maken om de provisioningtaak te maken.

12. Als alleen toegewezen gebruikers en groepen worden gesynchroniseerd (aanbevolen), selecteert u het tabblad Gebruikers en groepen . Wijs vervolgens de gebruikers of groepen toe die u wilt synchroniseren. Deze stap is vereist om het inrichten te laten werken wanneer het bereik zodanig is ingesteld dat alleen toegewezen gebruikers en groepen worden gesynchroniseerd. Als er geen gebruikers of groepen zijn toegewezen, hoeft u niets in te richten. Zie Gebruikers en groepen toewijzen aan een toepassing voor gedetailleerde instructies voor het toewijzen van gebruikers en groepen.

    Belangrijk

    De provisioningservice van Microsoft Entra voorziet alleen gebruikers en groepen die zijn toegewezen aan de toepassing (wanneer het bereik is ingesteld op Sync alleen toegewezen gebruikers en groepen). Als je geen gebruikers of groepen toewijst, vindt er geen voorziening plaats. Zorg ervoor dat u deze stap voltooit voordat u begint met inrichten.

13. Selecteer Kenmerktoewijzing in de linker zijbalk. Er zijn twee selecteerbare sets van kenmerktoewijzingen: één voor gebruikersobjecten en één voor groepsobjecten. Selecteer elk kenmerk om de kenmerken te controleren die vanuit Microsoft Entra ID met uw app worden gesynchroniseerd. De kenmerken die als overeenkomende eigenschappen zijn geselecteerd, worden gebruikt om de gebruikers en groepen in uw app te vinden voor updatebewerkingen. Selecteer Opslaan om wijzigingen door te voeren.

    U kunt het synchroniseren van groepsobjecten desgewenst uitschakelen door de koppeling 'groepen' uit te schakelen.

14. Selecteer Inrichten op aanvraag in het linkerdeelvenster. Zoek naar een gebruiker die binnen het bereik valt voor provisioning en voorzie hen op aanvraag. Herhaal dit met andere gebruikers waarmee u de inrichting wilt testen.

15. Zodra uw configuratie is voltooid, selecteert u Overzicht in het linkerdeelvenster.

16. Selecteer Eigenschappen.

17. Selecteer het potlood om de eigenschappen te bewerken. Schakel e-mailberichten voor meldingen in en geef een e-mailbericht op om quarantaine-e-mailberichten te ontvangen. Preventie van onbedoelde verwijderingen inschakelen. Klik op Toepassen om de wijzigingen op te slaan.

18. Selecteer Start inrichten om de Microsoft Entra inrichtingsservice te starten.

Zodra de eerste cyclus is gestart, kunt u inrichtingslogboeken in het linkerdeelvenster selecteren om de voortgang te controleren, waarin alle acties worden weergegeven die door de inrichtingsservice in uw app worden uitgevoerd. Zie Rapporten over automatische inrichting van gebruikersaccounts voor meer informatie over het lezen van de Microsoft Entra inrichtingslogboeken.

Uw toepassing publiceren naar de Microsoft Entra toepassingsgalerie

Als u een toepassing bouwt die door meer dan één tenant wordt gebruikt, maakt u deze beschikbaar in de Microsoft Entra toepassingsgalerie. Het is eenvoudig voor organisaties om de toepassing te detecteren en inrichting te configureren. Het publiceren van uw app in de Microsoft Entra galerij en het beschikbaar maken van voorziening voor anderen is eenvoudig. Bekijk de stappen hier. Microsoft werkt samen met u om uw toepassing in de Galerij te integreren, uw eindpunt te testen en onboarding-documentatie uit te brengen voor klanten.

Controlelijst voor onboarding van galerijen

Gebruik de controlelijst om uw toepassing snel te onboarden en klanten hebben een soepele implementatie-ervaring. De informatie wordt van u verzameld bij het onboarden naar de galerie.

Autorisatie voor het voorzien van connectors in de applicatiegalerie

De SCIM-specificatie definieert geen SCIM-specifiek schema voor verificatie en autorisatie en is afhankelijk van het gebruik van bestaande industriestandaarden.

Voor meer verificatie- en autorisatiemethoden laat het ons weten op UserVoice.

OAuth 2.0-clientreferenties toekenningsproces

De inrichtingsservice ondersteunt de toekenning van OAuth 2.0-clientreferenties. Na het indienen van uw aanvraag voor het publiceren van uw app in de galerie, werkt ons team samen met u om de volgende informatie te verzamelen:

• Tenant-URL: Dit is de URL van het SCIM API-eindpunt die wordt geleverd door uw serviceprovider. Het kan bijvoorbeeld iets zijn als https://example.test/scim.
• Tokeneindpunt: Dit is de OAuth2-token-URL. Het is het eindpunt dat de voorzieningsservice gebruikt voor het uitwisselen van clientgegevens voor een toegangstoken. Het kan bijvoorbeeld iets zijn als https://example.test/oauth2/token.
• Client-id: Dit is een unieke id die is toegewezen aan uw toepassing door de serviceprovider.
• Clientgeheim: Dit is een token met een lange levensduur met de benodigde machtigingen voor de API. Deze wordt gebruikt om uw toepassing te verifiëren bij het aanvragen van een toegangstoken.

Wanneer u het OAuth 2.0-proces voor clientreferenties-verlening gebruikt, moet u een model ondersteunen waarin elke klant bij het instellen van een provisioning-instantie zijn eigen client-id en clientgeheim verzendt. Eén client-id/clientgeheimpaar voor de hele app wordt niet ondersteund.

Client-inloggegevens instellen

1. Meld u aan bij de Microsoft Entra-beheercentrum als minimaal een Applicatiebeheerder.
2. Blader naar Entra ID>Enterprise apps.
3. Selecteer uw toepassing en ga naar Inrichten.
4. Selecteer > voor verificatiemethode voor beheerreferenties.
5. Voer uw gegevens in voor de resterende velden:
   • Tenant-URL
   • Tokeneindpunt
   • Client-id
   • Clientgeheim
6. Klik op Verbinding testen.

Voor meer verificatie- en autorisatiemethoden laat het ons weten op UserVoice.

Galerie go-to- checklist voor marktintroductie

Om het bewustzijn en de vraag van onze gezamenlijke integratie te vergroten, raden we u aan uw bestaande documentatie bij te werken en de integratie in uw marketingkanalen te versterken. U wordt aangeraden de volgende controlelijst te voltooien ter ondersteuning van de lancering:

Volgende stappen