Oktatóanyag: SCIM-végpont kiépítése és tervezése a Microsoft Entra ID-ban

Alkalmazásfejlesztőként a System for Cross-Domain Identity Management (SCIM) felhasználókezelési API-val engedélyezheti a felhasználók és csoportok automatikus kiépítését az alkalmazás és a Microsoft Entra-azonosító között. Ez a cikk bemutatja, hogyan hozhat létre SCIM-végpontokat, és hogyan integrálható a Microsoft Entra kiépítési szolgáltatással. Az SCIM-specifikáció egy gyakori felhasználói sémát biztosít a kiépítéshez. Ha olyan összevonási szabványokat használ, mint az SAML vagy az OpenID Csatlakozás, az SCIM a rendszergazdák számára egy végpontok közötti, szabványokon alapuló megoldást biztosít a hozzáférés-kezeléshez.

Az SCIM 2.0 két végpont szabványosított definíciója: egy /Users végpont és egy /Groups végpont. Általános REST API-végpontokat használ objektumok létrehozásához, frissítéséhez és törléséhez. Az SCIM egy előre definiált sémából áll olyan általános attribútumokhoz, mint a csoportnév, a felhasználónév, az utónév, a vezetéknév és az e-mail.

Az SCIM 2.0 REST API-t kínáló alkalmazások csökkenthetik vagy kiküszöbölhetik a védett felhasználói felügyeleti API-k használatának fájdalmát. A megfelelő SCIM-ügyfél például tudja, hogyan hozhat létre egy JSON-objektum HTTP POST-bejegyzését a /Users végponton új felhasználói bejegyzés létrehozásához. Ahelyett, hogy egy kissé eltérő API-ra van szüksége ugyanazon alapvető műveletekhez, az SCIM szabványnak megfelelő alkalmazások azonnal kihasználhatják a már meglévő ügyfelek, eszközök és kódok előnyeit.

Az SCIM 2.0-ban (RFC 7642, 7643, 7644) definiált felügyeleti standard felhasználói objektumséma és rest API-k lehetővé teszik, hogy az identitásszolgáltatók és az alkalmazások könnyebben integrálhatók legyenek egymással. Az SCIM-végpontot készítő alkalmazásfejlesztők bármilyen SCIM-kompatibilis ügyféllel integrálhatók egyéni munka nélkül.

Az alkalmazások üzembe helyezésének automatizálásához létre kell hoznia és integrálnia kell egy SCIM-végpontot, amelyet a Microsoft Entra kiépítési szolgáltatása ér el. Az alábbi lépésekkel megkezdheti a felhasználók és csoportok üzembe helyezését az alkalmazásba.

1. A felhasználó- és csoportséma megtervezése – Azonosítsa az alkalmazás objektumait és attribútumait annak meghatározásához, hogyan vannak megfeleltetve a Microsoft Entra SCIM implementáció által támogatott felhasználói és csoportsémának.

2. Ismerje meg a Microsoft Entra SCIM implementációját – Ismerje meg, hogyan valósítja meg a Microsoft Entra kiépítési szolgáltatást az SCIM protokoll kéréskezelésének és válaszainak modellezéséhez.

3. SCIM-végpont létrehozása – A végpontnak SCIM 2.0-kompatibilisnek kell lennie a Microsoft Entra kiépítési szolgáltatással való integrációhoz. Lehetőségként használja a Microsoft Common Language Infrastructure (CLI) kódtárait és kódmintáit a végpont létrehozásához. Ezek a minták csak referenciaként és tesztelésre szolgálnak; azt javasoljuk, hogy ne használja őket függőségként az éles alkalmazásban.

4. Az SCIM-végpont integrálása a Microsoft Entra kiépítési szolgáltatással. A Microsoft Entra ID számos külső alkalmazást támogat, amelyek az SCIM 2.0-t implementálják. Ha ezen alkalmazások egyikét használja, akkor gyorsan automatizálhatja a felhasználók és csoportok kiépítését és megszüntetését is.

5. [Nem kötelező] Az alkalmazás közzététele a Microsoft Entra alkalmazáskatalógusában – Megkönnyítheti az ügyfelek számára az alkalmazás felderítését és a kiépítés egyszerű konfigurálását.

A felhasználói és csoportséma megtervezése

Minden alkalmazáshoz különböző attribútumok szükségesek egy felhasználó vagy csoport létrehozásához. Indítsa el az integrációt az alkalmazás által igényelt szükséges objektumok (felhasználók, csoportok) és attribútumok (név, vezető, beosztás stb.) azonosításával.

Az SCIM szabvány egy sémát határoz meg a felhasználók és csoportok kezeléséhez.

Az alapvető felhasználói séma csak három attribútumot igényel (az összes többi attribútum nem kötelező):

• id, szolgáltató által definiált azonosító
• userName, a felhasználó egyedi azonosítója (általában a Microsoft Entra felhasználónévre van leképezve)
• meta, a szolgáltató által fenntartott írásvédett metaadatok

Az alapvető felhasználói séma mellett az SCIM szabvány egy vállalati felhasználói bővítményt is meghatároz, amely modellel bővíti a felhasználói sémát az alkalmazás igényeinek megfelelően.

Ha például az alkalmazáshoz a felhasználó e-mail-címe és a felhasználó kezelője is szükséges, az alapvető sémával gyűjtse össze a felhasználó e-mail-címét és a vállalati felhasználói sémát a felhasználó kezelőjének gyűjtéséhez.

A séma megtervezéséhez kövesse az alábbi lépéseket:

1. Sorolja fel az alkalmazás által igényelt attribútumokat, majd kategorizálja a hitelesítéshez szükséges attribútumokat (például loginName és e-mail). Attribútumokra van szükség a felhasználói életciklus kezeléséhez (például állapot/aktív), valamint az alkalmazás működéséhez szükséges összes egyéb attribútumra (például kezelő, címke).

2. Ellenőrizze, hogy az attribútumok már definiálva vannak-e az alapvető felhasználói sémában vagy a vállalati felhasználói sémában. Ha nem, meg kell határoznia a hiányzó attribútumokat lefedő felhasználói séma bővítményét. A felhasználó kiépítésének engedélyezéséhez tekintse meg a felhasználó tagbővítményét.

3. SCIM-attribútumok leképezése a Microsoft Entra ID felhasználói attribútumaihoz. Ha az SCIM-végpontban definiált attribútumok egyike nem rendelkezik egyértelmű megfelelővel a Microsoft Entra felhasználói sémáján, a bérlői rendszergazda útmutatást nyújt a séma kiterjesztéséhez, vagy használjon egy bővítményattribútumot a tags tulajdonság példájában látható módon.

Az alábbi táblázat felsorol egy példát a szükséges attribútumokra:

Kötelező alkalmazásattribútum/példa	Megfeleltetett SCIM attribútum	Megfeleltetett Microsoft Entra attribútum
loginName	Felhasználónév	userPrincipalName
firstName	name.givenName	givenName
lastName	name.familyName	Vezetéknév
workMail	emails[type eq "work"].value	Mail
manager	manager	manager
címke	urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User:tag	extensionAttribute1
status	active	isSoftDeleted (a felhasználó által nem tárolt számított érték)

Az alábbi JSON hasznos adatok egy SCIM-sémát mutatnak be:

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

Segít kategorizálni /User a /Group Microsoft Entra ID-ban lévő alapértelmezett felhasználói attribútumokat az SCIM RFC-re, és leképezni az attribútumokat a Microsoft Entra ID és az SCIM-végpont között.

Az alábbi táblázat a felhasználói attribútumok példáját sorolja fel:

Microsoft Entra-felhasználó	urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
IsSoftDeleted	active
department	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	Cím
levélküldés	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
irányítószám	addresses[type eq "work"].postalCode
proxycímek	email[type eq "other"]. Érték
physical-Delivery-OfficeName	addresses[type eq "other"]. Formázott
streetAddress	addresses[type eq "work"].streetAddress
surname	name.familyName
telefonszám	phoneNumbers[type eq "work"].value
user-PrincipalName	Felhasználónév

Az alábbi táblázat a csoportattribútumok példáját sorolja fel:

Microsoft Entra-csoport	urn:ietf:params:scim:schemas:core:2.0:Group
displayName	displayName
tagok	tagok
objectId	externalId

Az SCIM RFC-ben több végpont is definiálva van. Kezdje a /User végponttal, majd onnan bontsa ki a elemet. Az alábbi táblázat felsorol néhány SCIM-végpontot:

Végpont	Leírás
/felhasználó	CRUD-műveleteket hajthat végre egy felhasználói objektumon.
/Csoport	CRUD-műveleteket hajthat végre egy csoportobjektumon.
/Sémák	Az egyes ügyfelek és szolgáltatók által támogatott attribútumok halmaza eltérő lehet. Az egyik szolgáltató tartalmazhat name, titleés emails, míg egy másik szolgáltató használja name, titleés phoneNumbers. A sémavégpont lehetővé teszi a támogatott attribútumok felderítését.
/Tömeges	A tömeges műveletek lehetővé teszik, hogy műveleteket hajthasson végre egy nagy erőforrás-objektumgyűjteményen egyetlen műveletben (például egy nagy csoport tagságainak frissítése).
/ServiceProviderConfig	Részletesen ismerteti az SCIM szabvány által támogatott funkciókat, például a támogatott erőforrásokat és a hitelesítési módszert.
/ResourceTypes	Az egyes erőforrások metaadatait adja meg.

A Microsoft Entra SCIM implementációjának ismertetése

A Microsoft Entra kiépítési szolgáltatás célja egy SCIM 2.0 felhasználói felügyeleti API támogatása.

Az SCIM 2.0 protokollspecifikáción belül az alkalmazásnak támogatnia kell az alábbi követelményeket:

Követelmény	Referenciajegyzetek (SCIM protokoll)
Felhasználók és opcionálisan csoportok létrehozása	3.3. szakasz
Felhasználók vagy csoportok módosítása PATCH-kérésekkel	3.5.2. A támogatás biztosítja, hogy a csoportok és a felhasználók teljesíthető módon legyenek kiépítve.
Egy korábban létrehozott felhasználó vagy csoport ismert erőforrásának lekérése	3.4.1. szakasz
Felhasználók vagy csoportok lekérdezése	3.4.2. Alapértelmezés szerint a rendszer lekéri a felhasználókat a saját idusernameexternalIdés a , és a csoportok lekérdezésével.displayName
A szűrő kizártAttributes=tagok a csoporterőforrás lekérdezésekor	3.4.2.2. szakasz
Felhasználók listázásának és lapszámozásának támogatása	3.4.2.4.
Felhasználó helyreállítható active=false törlése és visszaállítása active=true	A felhasználói objektumot egy kérésben kell visszaadni, függetlenül attól, hogy a felhasználó aktív-e. A felhasználó csak akkor adható vissza, ha az alkalmazásból keményen törölve van.
A /Schemas végpont támogatása	7 . szakasz A sémafelderítési végpont további attribútumok felderítésére szolgál.
Fogadjon el egyetlen tulajdonosi jogkivonatot a Microsoft Entra-azonosító hitelesítéséhez és az alkalmazáshoz való engedélyezéséhez.

Az SCIM-végpontok implementálásakor használja az általános irányelveket a Microsoft Entra-azonosítóval való kompatibilitás biztosításához:

Általános:

• id az összes erőforrás kötelező tulajdonsága. Minden erőforrást visszaadó válasznak biztosítania kell, hogy minden erőforrás rendelkezik ezzel a tulajdonsággal, kivéve ListResponse a nulla elemekkel.
• Az elküldött értékeket az elküldött formátumban kell tárolni. Az érvénytelen értékeket leíró, végrehajtható hibaüzenettel kell elutasítani. Az adatok átalakítása nem történhet a Microsoft Entra-azonosítóból származó adatok és az SCIM-alkalmazásban tárolt adatok között. (például. A 55555555555 ként küldött telefonszámot nem szabad +5 (555) 555-5555)-ként menteni/visszaadni)
• Nem szükséges a teljes erőforrást belefoglalni a PATCH-válaszba .
• Ne igényeljön kis- és nagybetűkre érzékeny egyezést az SCIM szerkezeti elemein, különösen a PATCHop műveleti értékein , a 3.5.2. A Microsoft Entra ID a Hozzáadás, Csere és Eltávolítás értékeket opbocsátja ki.
• A Microsoft Entra ID kéréseket küld egy véletlenszerű felhasználó és csoport lekérésére annak biztosítása érdekében, hogy a végpont és a hitelesítő adatok érvényesek legyenek. A tesztelési Csatlakozás ion folyamat részeként is elvégezhető.
• A HTTPS támogatása az SCIM-végponton.
• Az egyéni összetett és többértékű attribútumok támogatottak, de a Microsoft Entra ID nem rendelkezik sok összetett adatstruktúrával az adatok lekéréséhez ezekben az esetekben. A név- és értékattribútumok egyszerűen leképezhetők, de az adatok három vagy több résztulajdonságú összetett attribútumba való áramlása nem támogatott.
• A többértékű összetett attribútumok "type" felosztott értékeinek egyedinek kell lenniük. Nem lehet például két különböző e-mail-cím a "work" altípussal.
• Az összes válasz fejlécének tartalomtípusúnak kell lennie: application/scim+json

Erőforrások lekérése:

• A lekérdezési/szűrőkérésre adott válasznak mindig egynek ListResponsekell lennie.
• A Microsoft Entra csak a következő operátorokat használja: eq, and
• Az erőforrások lekérdezhető attribútumát egyező attribútumként kell beállítani az alkalmazáson, lásd : A felhasználókiépítési attribútumleképezések testreszabása.

/Felhasználók:

• A jogosultságok attribútum nem támogatott.
• A felhasználói egyediség szempontjából figyelembe vett attribútumoknak használhatónak kell lenniük egy szűrt lekérdezés részeként. (ha például a felhasználó egyediségét a userName és az e-mailek[type eq "work"], akkor a get to /Users with a filter egyaránt engedélyezi a userName eq "user@contoso.com" és az e-mailek[type eq "work"].value eq "user@contoso.com" lekérdezéseket.

/Csoportok:

• A csoportok nem kötelezőek, de csak akkor támogatottak, ha az SCIM-implementáció támogatja a PATCH-kéréseket .
• A csoportoknak egyedinek kell lenniük a "displayName" értéken, hogy megfeleljenek a Microsoft Entra-azonosítónak és az SCIM-alkalmazásnak. Az egyediség nem az SCIM protokoll követelménye, hanem egy SCIM-végpont Microsoft Entra-azonosítóval való integrálásának követelménye.

/Sémák (sémafelderítés):

• Mintakérés/válasz
• A sémafelderítést bizonyos katalógusalkalmazásokon használják. A sémafelderítés az egyetlen módszer, amely további attribútumokat ad hozzá egy meglévő katalógus SCIM-alkalmazás sémáihoz. A sémafelderítés jelenleg nem támogatott az egyéni, nem katalógusalapú SCIM-alkalmazásokban.
• Ha egy érték nincs jelen, ne küldjön null értékeket.
• A tulajdonságértékeket kisbetűsre kell tenni (például readWrite).
• Listaválaszt kell visszaadnia.
• A Microsoft Entra kiépítési szolgáltatás a /schemas kérést küldi a kiépítési konfiguráció mentésekor. A kérés a szerkesztési kiépítési oldal megnyitásakor is megnyílik. A felderített egyéb attribútumok a célattribútumlista attribútumleképezéseiben jelennek meg az ügyfelek számára. A sémafelderítés csak további célattribútumok hozzáadásához vezet. Az attribútumok nem törlődnek.

Felhasználó kiépítése és megszüntetése

Az alábbi ábra azokat az üzeneteket mutatja be, amelyeket a Microsoft Entra ID küld egy SCIM-végpontnak egy felhasználó életciklusának kezeléséhez az alkalmazás identitástárolójában.

Csoportkiépítés és -megszüntetés

A csoportkiépítés és a deprovisionálás nem kötelező. A implementálás és engedélyezés esetén az alábbi ábra azokat az üzeneteket mutatja be, amelyeket a Microsoft Entra ID küld egy SCIM-végpontnak egy csoport életciklusának kezeléséhez az alkalmazás identitástárolójában. Ezek az üzenetek kétféleképpen különböznek a felhasználókról szóló üzenetektől:

• A csoportok lekérésére irányuló kérések azt határozzák meg, hogy a tagok attribútumát ki kell zárni a kérésre adott válaszként megadott erőforrásokból.
• A referenciaattribútum bizonyos értékének meghatározására irányuló kérések a tagok attribútumával kapcsolatos kérések.

Az alábbi ábra a csoportbontási sorozatot mutatja be:

SCIM protokollkérelmek és válaszok

Ez a cikk a Microsoft Entra kiépítési szolgáltatás által kibocsátott SCIM-kérelmeket és a várt válaszokat tartalmazza. A legjobb eredmény érdekében kódolhatja az alkalmazást, hogy ilyen formátumban kezelje ezeket a kéréseket, és adja ki a várt válaszokat.

Felhasználói műveletek

• Felhasználó létrehozása (válaszkérés / )
• Felhasználó lekérése (Válasz kérése / )
• Felhasználó lekérése lekérdezés alapján (Válasz kérése / )
• Felhasználó lekérése lekérdezés alapján – Nulla eredmény (Kérelemre / adott válasz)
• Felhasználó frissítése [Többértékű tulajdonságok] (Kérelem / válasza)
• Felhasználó frissítése [Egyértékű tulajdonságok] (Kérelem / válasza)
• Felhasználó letiltása (válaszkérés / )
• Felhasználó törlése (Válasz kérése / )

Csoportműveletek

• Csoport létrehozása (kérelemre / adott válasz)
• Csoport lekérése (Válasz kérése / )
• Csoport lekérése displayName (Kérés / válasza) alapján
• Csoport frissítése [Nem tag attribútumok] (Kérelem / válasza)
• Csoport frissítése [Tagok hozzáadása] (Válasz kérése / )
• Csoport frissítése [Tagok eltávolítása] (Válasz kérése / )
• Csoport törlése (Válasz kérése / )

Sémafelderítés

• Séma felderítése (Kérelem / válasza)

Felhasználói műveletek

• Felhasználók lekérdezéséhez használjon userName vagy emails[type eq "work"] attribútumokat.

Felhasználó létrehozása

Kérelem

POST /Felhasználók

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

Válasz

HTTP/1.1 201 Létrehozva

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

Felhasználó beolvasása

Kérelem

GET /Users/5d48a0a8e9f04aa38008

Válasz (a felhasználó megtalálta)

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

Kérelem

GET /Users/5171a35d82074e068ce2

Válasz (a felhasználó nem található. A részletek nem kötelezőek, csak állapot.)

HTTP/1.1 404 nem található

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

Felhasználó lekérése lekérdezés alapján

Kérelem

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

Válasz

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
}

Felhasználó lekérése lekérdezés alapján – Nulla eredmény

Kérelem

GET /Users?filter=userName eq "nem létező felhasználó"

Válasz

HTTP/1.1 200 OK

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

Felhasználó frissítése [Többértékű tulajdonságok]

Kérelem

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

Válasz

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

Felhasználó frissítése [Egyértékű tulajdonságok]

Kérelem

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

Válasz

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

Felhasználó letiltása

Kérelem

PATCH /Users/5171a35d82074e068ce2 HTTP/1.1

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

Válasz

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

Felhasználó törlése

Kérelem

DELETE /Users/5171a35d82074e068ce2 HTTP/1.1

Válasz

HTTP/1.1 204 Nincs tartalom

Csoportműveletek

• A csoportok egy üres taglistával jönnek létre.
• Használja az displayName attribútumot csoportok lekérdezéséhez.
• A csoport PATCH-kérésének frissítése HTTP 204-et eredményez , amely nem tartalmaz tartalmat a válaszban. Nem ajánlott visszaadni egy olyan törzset, amely tartalmazza az összes tag listáját.
• Nem szükséges támogatni a csoport összes tagjának visszatérését.

Csoport létrehozása

Kérelem

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

Válasz

HTTP/1.1 201 Létrehozva

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

Csoport lekérése

Kérelem

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

Válasz

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

Csoport lekérése displayName szerint

Kérelem

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

Válasz

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
}

Csoport frissítése [Nem tag attribútumok]

Kérelem

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

Válasz

HTTP/1.1 204 Nincs tartalom

Csoport frissítése [Tagok hozzáadása]

Kérelem

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

Válasz

HTTP/1.1 204 Nincs tartalom

Csoport frissítése [Tagok eltávolítása]

Kérelem

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

Válasz

HTTP/1.1 204 Nincs tartalom

Csoport törlése

Kérelem

DELETE /Groups/cdb1ce18f65944079d37 HTTP/1.1

Válasz

HTTP/1.1 204 Nincs tartalom

Sémafelderítés

Séma felderítése

Kérelem

GET /Schemas

Válasz

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

Biztonsági követelmények

TLS-protokollverziók

Az egyetlen elfogadható protokollverzió a TLS 1.2. Más SSL/TLS-verzió nem engedélyezett.

• Az RSA-kulcsoknak legalább 2048 bitnek kell lenniük.
• Az ECC-kulcsoknak legalább 256 bitesnek kell lenniük, és jóváhagyott háromliptikus görbe használatával kell generálni

Kulcshosszok

Minden szolgáltatásnak megfelelő hosszúságú titkosítási kulcsokkal létrehozott X.509-tanúsítványokat kell használnia, azaz:

Titkosítási csomagok

Minden szolgáltatást úgy kell konfigurálni, hogy az alábbi titkosítási csomagokat használja a példában megadott pontos sorrendben. Ha csak RSA-tanúsítvánnyal rendelkezik, az ECDSA-titkosítási csomagok nincsenek hatással.

TLS 1.2 Titkosítási csomagok minimális sávja:

• 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-tartományok

A Microsoft Entra kiépítési szolgáltatás jelenleg a Microsoft Entra ID IP-tartományai alatt működik az itt felsoroltak szerint. A Microsoft Entra ID címke alatt felsorolt IP-tartományokat hozzáadhatja, hogy engedélyezze a Microsoft Entra kiépítési szolgáltatásból érkező forgalmat az alkalmazásba. Alaposan át kell tekintenie az IP-címtartományok listáját a számított címek esetében. Egy olyan cím, mint a "40.126.25.32", a "40.126.0.0/18" cím jelenhet meg az IP-címtartományok listájában. Az IP-tartománylistát programozott módon is lekérheti az alábbi API-val.

A Microsoft Entra ID emellett egy ügynökalapú megoldást is támogat, amely privát hálózatokban (helyszíni, Azure-ban üzemeltetett, AWS-ben üzemeltetett stb.) alkalmazásokhoz biztosít kapcsolatot. Az ügyfelek üzembe helyezhetnek egy egyszerűsített ügynököt, amely a Microsoft Entra-azonosítóhoz való kapcsolódást biztosítja anélkül, hogy bármilyen bejövő portot megnyithatnának a magánhálózatuk kiszolgálóin. További tájékoztatást itt olvashat.

SCIM-végpont létrehozása

Most, hogy megtervezte a sémát, és megismerte a Microsoft Entra SCIM implementációját, megkezdheti az SCIM-végpont fejlesztését. Ahelyett, hogy teljesen önállóan építené fel az implementációt, az SCIM-közösség által közzétett számos nyílt forráskód SCIM-kódtárra támaszkodhat.

Az SCIM-végpontok létrehozására vonatkozó, példákat is tartalmazó útmutatásért tekintse meg a minta SCIM-végpont fejlesztése című témakört.

A Microsoft Entra kiépítési csapata által közzétett nyílt forráskód .NET Core-referenciakód-példa egy olyan erőforrás, amely elindíthatja a fejlesztést. Hozzon létre egy SCIM-végpontot, majd tesztelje. Használja a referenciakód részeként megadott Postman-tesztek gyűjteményét, vagy futtassa a megadott mintakéréseket/ válaszokat.

A megoldás két projektből áll, a Microsoft.SCIM-ből és a Microsoft.SCIM.WebHostSample-ből.

A Microsoft.SCIM-projekt az a kódtár, amely meghatározza a webszolgáltatás azon összetevőit, amelyek megfelelnek az SCIM specifikációjának. Deklarálja a Microsoft.SCIM.IProvider felületet, a kéréseket a szolgáltató metódusaihoz intézett hívásokká fordítja le, amelyek egy identitástárolón való működésre lennének programozva.

A Microsoft.SCIM.WebHostSample projekt egy ASP.NET Core webalkalmazás, amely az Üres sablonon alapul. Lehetővé teszi a mintakód önálló, tárolókban vagy az Internet Information Servicesben történő üzembe helyezését. Emellett implementálja a Microsoft.SCIM.IProvider felületet is, amely a memóriában tárolja az osztályokat minta identitástárként.

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

Egyéni SCIM-végpont létrehozása

Az SCIM-végpontnak rendelkeznie kell egy HTTP-címmel és kiszolgálóhitelesítési tanúsítvánnyal, amelynek legfelső szintű hitelesítésszolgáltatója az alábbi nevek egyike:

• CNNIC
• Comodo
• CyberTrust
• DigiCert
• GeoTrust
• Globalsign
• Go Daddy
• Verisign
• WoSign
• DST Root CA X3

A .NET Core SDK tartalmaz egy HTTPS fejlesztési tanúsítványt, amelyet a fejlesztés során használnak. A tanúsítvány az első futtatás során települ. A ASP.NET Core-webalkalmazás futtatásától függően egy másik portot figyel:

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

A HTTPS-ről a ASP.NET Core-ban a következő hivatkozáson tájékozódhat: HTTPS kényszerítése ASP.NET Core-ban

Végponthitelesítés kezelése

A Microsoft Entra kiépítési szolgáltatás kérései között szerepel egy OAuth 2.0 tulajdonosi jogkivonat. Egy engedélyezési kiszolgáló kiadja a tulajdonosi jogkivonatot. A Microsoft Entra ID egy megbízható engedélyezési kiszolgáló példája. Konfigurálja a Microsoft Entra kiépítési szolgáltatást az alábbi jogkivonatok egyikének használatára:

• Egy hosszú élettartamú tulajdonosi jogkivonat. Ha az SCIM-végponthoz a Microsoft Entra-azonosítótól eltérő kiállítótól származó OAuth-tulajdonosi jogkivonat szükséges, másolja a szükséges OAuth-tulajdonosi jogkivonatot az opcionális Titkos jogkivonat mezőbe. Fejlesztői környezetben használhatja a végpont tesztelési jogkivonatát /scim/token . A tesztelési jogkivonatokat nem szabad éles környezetben használni.

• Microsoft Entra tulajdonosi jogkivonat. Ha a Titkos jogkivonat mező üres, a Microsoft Entra ID minden kéréshez tartalmaz egy OAuth-tulajdonosi jogkivonatot, amelyet a Microsoft Entra ID-tól adnak ki. A Microsoft Entra-azonosítót identitásszolgáltatóként használó alkalmazások érvényesíthetik ezt a Microsoft Entra-azonosítóval kiállított jogkivonatot.

  • A kéréseket fogadó alkalmazásnak microsoft Entra-azonosítóként kell érvényesítenie a jogkivonat-kiállítót egy várt Microsoft Entra-bérlőhöz.
  • A iss jogcím azonosítja a jogkivonat kiállítóját. Például: "iss":"https://sts.windows.net/12345678-0000-0000-0000-000000000000/". Ebben a példában a jogcímérték https://sts.windows.net alapcíme a Microsoft Entra-azonosítót azonosítja kiállítóként, míg az 12345678-0000-0000-0000-000000000 relatív címszegmens annak a Microsoft Entra-bérlőnek az egyedi azonosítója, amelyhez a jogkivonatot kiadták.
  • A jogkivonat célközönsége a katalógusban található alkalmazás alkalmazásazonosítója . Az egyetlen bérlőben regisztrált alkalmazások ugyanazt iss a jogcímet kapják SCIM-kérésekkel. Az összes egyéni alkalmazás alkalmazásazonosítója 8adf8e6e-67b2-4cf2-a259-e3dc5476c621. A Microsoft Entra ID által létrehozott jogkivonatot csak teszteléshez szabad használni. Éles környezetben nem használható.

A mintakódban a kérelmek hitelesítése a Microsoft.AspNetCore.Authentication.JwtBearer csomag használatával történik. A következő kód kikényszeríti, hogy a szolgáltatás bármely végpontjára irányuló kérések hitelesítése a Microsoft Entra ID által adott bérlőhöz kiadott tulajdonosi jogkivonat használatával történik:

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

Egy tulajdonosi jogkivonatra is szükség van a megadott Postman-tesztek használatához és a helyi hibakereséshez a localhost használatával. A mintakód ASP.NET Core-környezetekkel módosítja a hitelesítési beállításokat a fejlesztési szakaszban, és engedélyezi az önaláírt jogkivonat használatát.

A ASP.NET Core több környezetéről további információt a ASP.NET Core több környezetének használata című témakörben talál.

A következő kód kikényszeríti, hogy a szolgáltatás bármely végpontjára irányuló kérések hitelesítése egy egyéni kulccsal aláírt tulajdonosi jogkivonattal történik:

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

Get kérés küldése a jogkivonat-vezérlőnek érvényes tulajdonosi jogkivonat lekéréséhez. A GenerateJSONWebToken metódus feladata létrehozni egy, a fejlesztéshez konfigurált paramétereknek megfelelő jogkivonatot:

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

Felhasználók kiépítésének és megszüntetésének kezelése

1. példa. Egyező felhasználó szolgáltatásának lekérdezése

A Microsoft Entra ID lekérdezi egy felhasználó szolgáltatását egy externalId felhasználó mailNickname attribútumértékével egyező attribútumértékkel a Microsoft Entra ID-ban. A lekérdezés hypertext transfer protocol (HTTP) kérésként van kifejezve, például ebben a példában a jyoung egy Microsoft Entra ID-felhasználó mailNickname-jének mintája.

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

A mintakódban a kérés a szolgáltatás szolgáltatójának QueryAsync metódusára irányuló hívássá lesz lefordítva. Ennek a módszernek az aláírása a következő:

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

A minta lekérdezésben az attribútum egy adott értékével externalId rendelkező felhasználó esetében a QueryAsync metódusnak átadott argumentumok értékei a következők:

• Paraméterek. AlternateFilters.Count: 1
• Paraméterek. AlternateFilters.ElementAt(0). AttributePath: "externalId"
• Paraméterek. AlternateFilters.ElementAt(0). ComparisonOperator: ComparisonOperator.Equals
• Paraméterek. AlternateFilter.ElementAt(0). ComparisonValue: "jyoung"

2. példa. Felhasználó kiépítése

Ha a felhasználó mailNickname attribútumértékének megfelelő attribútumértékkel rendelkező externalId felhasználó SCIM-végpontjára irányuló lekérdezésre adott válasz nem ad vissza felhasználókat, akkor a Microsoft Entra ID azt kéri, hogy a szolgáltatás a Microsoft Entra-azonosítóban szereplő felhasználónak megfelelő felhasználót építsen ki. Íme egy példa egy ilyen kérésre:

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}

A mintakódban a kérés a szolgáltatás szolgáltatójának CreateAsync metódusára irányuló hívássá lesz lefordítva. Ennek a módszernek az aláírása a következő:

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

A felhasználói kiépítési kérelemben az erőforrás-argumentum értéke az Microsoft.SCIM.Core2EnterpriseUser osztály egy példánya. Ez az osztály a Microsoft.SCIM.Schemas tárban van definiálva. Ha a felhasználó kiépítésére irányuló kérés sikeres, akkor a metódus implementálása várhatóan az osztály egy példányát Microsoft.SCIM.Core2EnterpriseUser adja vissza. A tulajdonság értéke az Identifier újonnan kiépített felhasználó egyedi azonosítójára van állítva.

3. példa. Felhasználó aktuális állapotának lekérdezése

A Microsoft Entra ID a megadott felhasználó aktuális állapotát kéri le a szolgáltatásból egy kéréssel, például:

GET ~/scim/Users/54D382A4-2050-4C03-94D1-E769F1D15682 HTTP/1.1
Authorization: Bearer ...

A mintakódban a rendszer a kérést a szolgáltatás szolgáltatójának RetrieveAsync metódusának hívására fordítja le. Ennek a módszernek az aláírása a következő:

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

Egy kérés példájában a felhasználó aktuális állapotának lekéréséhez a paraméterek argumentum értékeként megadott objektum tulajdonságainak értékei a következők:

• Azonosító: "54D382A4-2050-4C03-94D1-E769F1D15682"
• SchemaIdentifier: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

4. példa. A frissíteni kívánt referenciaattribútum értékének lekérdezése

A Microsoft Entra ID a frissítés előtt ellenőrzi az identitástároló aktuális attribútumértékét. Azonban csak a kezelő attribútum van bejelölve először a felhasználók számára. Íme egy példa egy kérésre, amely meghatározza, hogy egy felhasználói objektum kezelő attribútuma jelenleg rendelkezik-e bizonyos értékkel: A mintakódban a kérés a szolgáltatás szolgáltatójának QueryAsync metódusára irányuló hívássá lesz lefordítva. A paraméterek argumentum értékeként megadott objektum tulajdonságainak értéke a következő:

• Paraméterek. AlternateFilters.Count: 2
• Paraméterek. AlternateFilters.ElementAt(x). AttributePath: "ID"
• Paraméterek. AlternateFilters.ElementAt(x). ComparisonOperator: ComparisonOperator.Equals
• Paraméterek. AlternateFilter.ElementAt(x). ComparisonValue: "54D382A4-2050-4C03-94D1-E769F1D15682"
• Paraméterek. AlternateFilters.ElementAt(y). AttributePath: "manager"
• Paraméterek. AlternateFilters.ElementAt(y). ComparisonOperator: ComparisonOperator.Equals
• Paraméterek. AlternateFilter.ElementAt(y). ComparisonValue: "2819c223-7f76-453a-919d-413861904646"
• Paraméterek. RequestedAttributePaths.ElementAt(0): "ID"
• Paraméterek. SchemaIdentifier: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Az x index értéke lehet 0 , az index értéke pedig y lehet 1. Vagy az x értéke lehet 1 , és az y értéke lehet 0. Ez a szűrő lekérdezési paraméter kifejezéseinek sorrendjétől függ.

5. példa. Microsoft Entra-azonosító kérése SCIM-végpontra a felhasználó frissítéséhez

Íme egy példa a Microsoft Entra ID-tól egy SCIM-végpontra irányuló kérésre a felhasználó frissítéséhez:

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

A mintakódban a kérés a szolgáltatás szolgáltatójának UpdateAsync metódusára irányuló hívássá lesz lefordítva. Ennek a módszernek az aláírása a következő:

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

Egy felhasználó frissítésére vonatkozó kérés példájában a javítás argumentum értékeként megadott objektum a következő tulajdonságértékekkel rendelkezik:

Argumentum	Value
ResourceIdentifier.Identifier	"54D382A4-2050-4C03-94D1-E769F1D15682"
ResourceIdentifier.SchemaIdentifier	urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
(PatchRequest as PatchRequest2).Operations.Count	0
(PatchRequest as PatchRequest2).Operations.ElementAt(0).OperationName	OperationName.Add
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Path.AttributePath	Kezelő
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.Count	0
(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

6. példa. Felhasználó kivonása

Ha egy felhasználót egy SCIM-végpont előtt lévő identitástárolóból szeretne megszüntetni, a Microsoft Entra ID a következő kéréseket küldi el:

DELETE ~/scim/Users/54D382A4-2050-4C03-94D1-E769F1D15682 HTTP/1.1
Authorization: Bearer ...

A mintakódban a rendszer a kérést a szolgáltatás szolgáltatójának DeleteAsync metódusára irányuló hívásra fordítja le. Ennek a módszernek az aláírása a következő:

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

A resourceIdentifier argumentum értékeként megadott objektum az alábbi tulajdonságértékekkel rendelkezik egy felhasználó kivonására irányuló kérés példájában:

• ResourceIdentifier.Identifier: "54D382A4-2050-4C03-94D1-E769F1D15682"
• ResourceIdentifier.SchemaIdentifier: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

SCIM-végpont integrálása a Microsoft Entra kiépítési szolgáltatással

A Microsoft Entra-azonosító konfigurálható úgy, hogy automatikusan kiépítse a hozzárendelt felhasználókat és csoportokat az SCIM 2.0 protokoll egy adott profilját implementáló alkalmazásokhoz. A profil sajátosságait a Microsoft Entra SCIM implementációjának ismertetése ismerteti.

A követelményekkel való kompatibilitásról az alkalmazásszolgáltatónál vagy az alkalmazásszolgáltató dokumentációjában talál információt.

Első lépések

A cikkben ismertetett SCIM-profilt támogató alkalmazások a Microsoft Entra alkalmazáskatalógusában található "nem katalógusbeli alkalmazás" funkcióval csatlakoztathatók a Microsoft Entra-azonosítóhoz. A csatlakozás után a Microsoft Entra ID szinkronizálási folyamatot futtat. A folyamat 40 percenként fut. A folyamat lekérdezi az alkalmazás SCIM-végpontját a hozzárendelt felhasználók és csoportok számára, és létrehozza vagy módosítja őket a hozzárendelés részleteinek megfelelően.

ScIM-t támogató alkalmazás csatlakoztatása:

1. Jelentkezzen be a Microsoft Entra felügyeleti központba legalább alkalmazásként Rendszergazda istratorként.

2. Keresse meg az Identity>Applications>Enterprise-alkalmazásokat.

3. Megjelenik az összes konfigurált alkalmazás listája, beleértve a katalógusból felvett alkalmazásokat is.

4. Válassza az + Új alkalmazás>+ Saját alkalmazás létrehozása lehetőséget.

5. Adja meg az alkalmazás nevét, válassza az "integrálhatja a katalógusban nem található egyéb alkalmazásokat" lehetőséget, és válassza a Hozzáadás lehetőséget egy alkalmazásobjektum létrehozásához. Az új alkalmazás felkerül a vállalati alkalmazások listájára, és megnyílik az alkalmazásfelügyeleti képernyőn.

   Az alábbi képernyőképen a Microsoft Entra alkalmazásgyűjtemény látható:

   

6. Az alkalmazásfelügyeleti képernyőn válassza a Kiépítés lehetőséget a bal oldali panelen.

7. A Kiépítési mód menüben válassza az Automatikus lehetőséget.

   Az alábbi képernyőképen a Kiépítési beállítások konfigurálása látható a Microsoft Entra Felügyeleti központban:

   

8. A Bérlő URL-cím mezőjében adja meg az alkalmazás SCIM-végpontjának URL-címét. Példa: https://api.contoso.com/scim/

9. Ha az SCIM-végponthoz a Microsoft Entra-azonosítótól eltérő kiállítótól származó OAuth-tulajdonosi jogkivonat szükséges, másolja a szükséges OAuth-tulajdonosi jogkivonatot az opcionális Titkos jogkivonat mezőbe. Ha ez a mező üres, a Microsoft Entra ID minden kéréshez tartalmaz egy OAuth-tulajdonosi jogkivonatot, amelyet a Microsoft Entra ID-tól adnak ki. A Microsoft Entra-azonosítót identitásszolgáltatóként használó alkalmazások érvényesíthetik ezt a Microsoft Entra-azonosítóval kiállított jogkivonatot.

   Feljegyzés

   Nem ajánlott üresen hagyni ezt a mezőt, és a Microsoft Entra ID által létrehozott jogkivonatra támaszkodni. Ez a lehetőség elsősorban tesztelési célokra érhető el.

10. Válassza a Tesztelési Csatlakozás lehetőséget, ha a Microsoft Entra ID megkísérli csatlakozni az SCIM-végponthoz. Ha a kísérlet sikertelen, hibaüzenet jelenik meg.

    Feljegyzés

    A tesztelési Csatlakozás ion lekérdezi egy nem létező felhasználó SCIM-végpontját egy véletlenszerű GUID használatával a Microsoft Entra-konfigurációban kiválasztott egyező tulajdonságként. A várt helyes válasz a HTTP 200 OK egy üres SCIM ListResponse üzenettel.

11. Ha az alkalmazáshoz való csatlakozás sikeres volt, a rendszergazdai hitelesítő adatok mentéséhez válassza a Mentés lehetőséget.

12. A Leképezések szakaszban két választható attribútumleképezés-készlet található: egyet a felhasználói objektumokhoz, egyet pedig a csoportobjektumokhoz. Jelölje ki mindegyiket a Microsoft Entra-azonosítóból az alkalmazásba szinkronizált attribútumok áttekintéséhez. Az egyező tulajdonságokként kiválasztott attribútumok az alkalmazás felhasználóinak és csoportjainak frissítési műveletekhez való egyeztetésére szolgálnak. A módosítások véglegesítéséhez válassza a Mentés lehetőséget.

    Feljegyzés

    A csoportobjektumok szinkronizálását a "csoportok" leképezés letiltásával is letilthatja.

13. A Gépház alatt a Hatókör mező határozza meg, hogy mely felhasználók és csoportok szinkronizálódnak. Válassza a Csak a hozzárendelt felhasználók és csoportok szinkronizálása (ajánlott) lehetőséget a Felhasználók és csoportok lapon hozzárendelt felhasználók és csoportok szinkronizálásához.

14. A konfiguráció befejezése után állítsa be a kiépítési állapotot Be értékre.

15. Válassza a Mentés lehetőséget a Microsoft Entra kiépítési szolgáltatás elindításához.

16. Ha csak a hozzárendelt felhasználók és csoportok szinkronizálása (ajánlott), válassza a Felhasználók és csoportok lapot. Ezután rendelje hozzá a szinkronizálni kívánt felhasználókat vagy csoportokat.

Miután a kezdeti ciklus elindult, a bal oldali panelen kiválaszthatja a kiépítési naplókat a folyamat figyeléséhez, amely megjeleníti az alkalmazás kiépítési szolgáltatása által végzett összes műveletet. A Microsoft Entra kiépítési naplóinak olvasásával kapcsolatos további információkért lásd : Jelentéskészítés az automatikus felhasználói fiókok kiépítéséről.

Az alkalmazás közzététele a Microsoft Entra alkalmazáskatalógusában

Ha egynél több bérlő által használt alkalmazást készít, tegye elérhetővé a Microsoft Entra alkalmazáskatalógusában. A szervezetek könnyen felfedezhetik az alkalmazást, és konfigurálhatja a kiépítést. Az alkalmazás közzététele a Microsoft Entra katalógusában és a kiépítés mások számára való elérhetővé tétele egyszerű. Tekintse meg a lépéseket itt. A Microsoft önnel együttműködve integrálja az alkalmazást a katalógusba, teszteli a végpontot, és kiadja az előkészítési dokumentációt az ügyfelek számára.

Katalógus előkészítési ellenőrzőlistája

Az ellenőrzőlistával gyorsan előkészítheti az alkalmazást, és az ügyfelek zökkenőmentes üzembe helyezést érhetnek el. Az információk a katalógusba való előkészítéskor lesznek összegyűjtve.

Az összekötők üzembe helyezésének engedélyezése az alkalmazáskatalógusban

Az SCIM-specifikáció nem határoz meg SCIM-specifikus sémát a hitelesítéshez és az engedélyezéshez, és a meglévő iparági szabványok használatára támaszkodik.

Engedélyezési módszer	Előnyök	Hátrányok	Támogatás
Felhasználónév és jelszó (a Microsoft Entra ID nem javasolja vagy támogatja)	Könnyen implementálható	Nem biztonságos – A Pa$$word nem számít	Nem támogatott új katalógusbeli vagy nem katalógusbeli alkalmazásokhoz.
Hosszú élettartamú tulajdonosi jogkivonat	A hosszú élettartamú jogkivonatokhoz nincs szükség arra, hogy egy felhasználó jelen legyen. A rendszergazdák egyszerűen használhatják őket a kiépítés beállításakor.	A hosszú élettartamú jogkivonatok nehezen oszthatók meg egy rendszergazdával anélkül, hogy nem biztonságos módszereket, például e-maileket használnak.	Katalógusbeli és nem katalógusbeli alkalmazások esetén támogatott.
OAuth engedélyezési kód megadása	A hozzáférési jogkivonatok élettartama rövidebb, mint a jelszavaké, és olyan automatikus frissítési mechanizmussal rendelkeznek, amellyel a hosszú élettartamú jogkivonatok nem rendelkeznek. A valódi felhasználónak jelen kell lennie a kezdeti engedélyezés során, és hozzá kell adnia az elszámoltathatóság szintjét.	A felhasználónak jelen kell lennie. Ha a felhasználó elhagyja a szervezetet, a jogkivonat érvénytelen, és az engedélyezést újra be kell fejezni.	Katalógusalkalmazások esetén támogatott, nem katalógusbeli alkalmazások esetén azonban nem. Rövid távú tesztelési célokra azonban megadhat egy hozzáférési jogkivonatot a felhasználói felületen titkos jogkivonatként. A katalóguson kívüli OAuth-kód megadásának támogatása a katalógusalkalmazás konfigurálható hitelesítési /jogkivonat-URL-címeinek támogatása mellett a hátralékunkban található.
OAuth-ügyfél hitelesítő adatainak megadása	A hozzáférési jogkivonatok élettartama rövidebb, mint a jelszavaké, és olyan automatikus frissítési mechanizmussal rendelkeznek, amellyel a hosszú élettartamú jogkivonatok nem rendelkeznek. Az engedélyezési kód megadása és az ügyfél hitelesítő adatai is ugyanazt a hozzáférési jogkivonatot hozzák létre, így a metódusok közötti váltás átlátható az API számára. A kiépítés automatizálható, és az új jogkivonatok felhasználói beavatkozás nélkül csendesen kérhetők.		Katalógusalkalmazások esetén támogatott, nem katalógusbeli alkalmazások esetén azonban nem. Rövid távú tesztelési célokra azonban megadhat egy hozzáférési jogkivonatot a felhasználói felületen titkos jogkivonatként. Az OAuth-ügyfél hitelesítő adatainak nem katalógusban való megadásának támogatása a hátralékunkban található.

OAuth-kód engedélyezési folyamata

A kiépítési szolgáltatás támogatja az engedélyezési kód megadását , és miután elküldte az alkalmazás katalógusban való közzétételére vonatkozó kérését, csapatunk együttműködik Önnel az alábbi információk gyűjtésében:

• Engedélyezési URL-cím, az ügyfél url-címe, amely a felhasználó-ügynök átirányításával kér engedélyt az erőforrás tulajdonosától. A rendszer átirányítja a felhasználót erre az URL-címre a hozzáférés engedélyezéséhez.

• Jogkivonatcsere URL-címe, amely az ügyfél url-címe egy hozzáférési jogkivonat engedélyezési engedélyének cseréjéhez, jellemzően ügyfél-hitelesítéssel.

• Az ügyfélazonosító, az engedélyezési kiszolgáló egy ügyfélazonosítót ad ki a regisztrált ügyfélnek, amely egy egyedi sztring, amely az ügyfél által megadott regisztrációs adatokat jelöli. Az ügyfélazonosító nem titkos; az erőforrás tulajdonosa számára van közzétéve, és nem használható egyedül az ügyfélhitelesítéshez.

• Ügyfél titkos kódja, az engedélyezési kiszolgáló által létrehozott titkos kód, amelynek csak az engedélyezési kiszolgáló számára ismert egyedi értéknek kell lennie.

Ajánlott, de nem kötelező, hogy több titkos kulcs is támogatott legyen az állásidő nélküli egyszerű megújításhoz.

OAuth-kód engedélyezési folyamatának beállítása

1. Jelentkezzen be a Microsoft Entra felügyeleti központba legalább alkalmazásként Rendszergazda istratorként.

2. Keresse meg az Identity>Applications>Enterprise-alkalmazások>alkalmazáskiosztását>, és válassza az Engedélyezés lehetőséget.

3. Jelentkezzen be a Microsoft Entra felügyeleti központba legalább alkalmazásként Rendszergazda istratorként.

4. Keresse meg az Identity>Applications>Enterprise-alkalmazásokat.

5. Válassza ki az alkalmazást, és lépjen a Kiépítés elemre.

6. Válassza az Engedélyezés lehetőséget.

   1. A rendszer átirányítja a felhasználókat az engedélyezési URL-címre (a külső alkalmazás bejelentkezési oldalára).

   2. Rendszergazda hitelesítő adatokat biztosít a külső alkalmazásnak.

   3. A harmadik féltől származó alkalmazás visszairányítja a felhasználót, és megadja a támogatási kódot

   4. A kiépítési szolgáltatás meghívja a jogkivonat URL-címét, és megadja a támogatási kódot. A külső alkalmazás a hozzáférési jogkivonattal, a frissítési jogkivonattal és a lejárati dátummal válaszol

7. A kiépítési ciklus kezdetekor a szolgáltatás ellenőrzi, hogy az aktuális hozzáférési jogkivonat érvényes-e, és szükség esetén kicseréli azt egy új jogkivonatra. A hozzáférési jogkivonatot minden, az alkalmazásnak küldött kérés tartalmazza, és a kérés érvényességét minden kérés előtt ellenőrzi a rendszer.

Hosszú élettartamú OAuth-tulajdonosi jogkivonatok: Ha az alkalmazás nem támogatja az OAuth engedélyezési kód engedélyezési folyamatát, hozzon létre egy hosszú élettartamú OAuth-tulajdonosi jogkivonatot, amelyet a rendszergazda a kiépítési integráció beállításához használhat. A jogkivonatnak állandónak kell lennie, különben a kiépítési feladat karanténba kerül, amikor a jogkivonat lejár.

További hitelesítési és engedélyezési módszerekért tudassa velünk a UserVoice-on.

A katalógus piacra lépési indítási ellenőrzőlistája

A közös integráció tudatosságának és igényének növelése érdekében javasoljuk, hogy frissítse a meglévő dokumentációt, és erősítse az integrációt a marketingcsatornáiban. Javasoljuk, hogy az indítás támogatásához töltse ki az alábbi ellenőrzőlistát:

Következő lépések