Kurz: Vývoj a plánování zřizování pro koncový bod SCIM v Microsoft Entra ID
Jako vývojář aplikací můžete použít rozhraní API pro správu uživatelů SCIM (System for Cross-Domain Identity Management) k povolení automatického zřizování uživatelů a skupin mezi vaší aplikací a ID Microsoft Entra. Tento článek popisuje, jak vytvořit koncový bod SCIM a integrovat se službou Microsoft Entra provisioning. Specifikace SCIM poskytuje společné uživatelské schéma pro zřizování. Při použití se standardy federace, jako je SAML nebo OpenID Connect, poskytuje SCIM správcům ucelené řešení založené na standardech pro správu přístupu.
SCIM 2.0 je standardizovaná definice dvou koncových bodů: /Users
koncového bodu a koncového /Groups
bodu. K vytváření, aktualizaci a odstraňování objektů používá běžné koncové body rozhraní REST API. SCIM se skládá z předdefinovaného schématu pro běžné atributy, jako je název skupiny, uživatelské jméno, křestní jméno, příjmení a e-mail.
Aplikace, které nabízejí rozhraní REST API SCIM 2.0, můžou snížit nebo eliminovat bolest při práci s vlastním rozhraním API pro správu uživatelů. Každý kompatibilní klient SCIM například ví, jak vytvořit HTTP POST objektu JSON do /Users
koncového bodu pro vytvoření nové položky uživatele. Aplikace, které odpovídají standardu SCIM, nemusí pro stejné základní akce potřebovat trochu jiné rozhraní API, můžou okamžitě využívat stávající klienty, nástroje a kód.
Standardní uživatelské objektové schéma a rozhraní REST API pro správu definované v SCIM 2.0 (RFC 7642, 7643, 7644) umožňují snadnější integraci zprostředkovatelů identit a aplikací. Vývojáři aplikací, kteří vytvářejí koncový bod SCIM, se můžou integrovat s libovolným klientem kompatibilním s SCIM, aniž by museli provádět vlastní práci.
Aby bylo možné automatizovat zřizování pro aplikaci, vyžaduje sestavení a integraci koncového bodu SCIM, ke kterému má služba Microsoft Entra provisioning přístup. Pomocí následujícího postupu můžete začít zřizovat uživatele a skupiny do vaší aplikace.
Navrhněte schéma uživatele a skupiny – Identifikujte objekty a atributy aplikace a určete, jak se mapují na schéma uživatele a skupiny podporované implementací Microsoft Entra SCIM.
Seznamte se s implementací Microsoft Entra SCIM – zjistěte, jak se implementuje služba zřizování Microsoft Entra, která modeluje zpracování a odpovědi na požadavky protokolu SCIM.
Sestavení koncového bodu SCIM – Koncový bod musí být kompatibilní s SCIM 2.0, aby se integrovali se službou Microsoft Entra Provisioning. Jako možnost použijte knihovny Microsoft Common Language Infrastructure (CLI) a ukázky kódu k sestavení koncového bodu. Tyto ukázky jsou určené pouze pro referenci a testování; doporučujeme je používat jako závislosti v produkční aplikaci.
Integrujte koncový bod SCIM se službou Microsoft Entra Provisioning. Microsoft Entra ID podporuje několik aplikací třetích stran, které implementují SCIM 2.0. Pokud používáte některou z těchto aplikací, můžete rychle automatizovat zřizování i rušení zřizování uživatelů a skupin.
[Volitelné] Publikujte aplikaci do galerie aplikací Microsoft Entra – Zákazníci snadno zjistí vaši aplikaci a snadno nakonfigurují zřizování.
Návrh schématu uživatele a skupiny
Každá aplikace vyžaduje k vytvoření uživatele nebo skupiny různé atributy. Zahajte integraci tím, že identifikujete požadované objekty (uživatele, skupiny) a atributy (název, manažer, pracovní pozice atd.), které vaše aplikace potřebuje.
Standard SCIM definuje schéma pro správu uživatelů a skupin.
Základní uživatelské schéma vyžaduje pouze tři atributy (všechny ostatní atributy jsou volitelné):
id
, identifikátor definovaný poskytovatelem služebuserName
, jedinečný identifikátor uživatele (obecně se mapuje na hlavní název uživatele Microsoft Entra)meta
, metadata jen pro čtení, která spravuje poskytovatel služeb
Kromě základního uživatelského schématu standard SCIM definuje rozšíření podnikového uživatele s modelem pro rozšíření schématu uživatele tak, aby vyhovovalo potřebám vaší aplikace.
Pokud například vaše aplikace vyžaduje e-mail uživatele i správce uživatele, použijte základní schéma ke shromáždění e-mailů uživatele a schématu podnikových uživatelů ke shromáždění správce uživatele.
Chcete-li navrhnout schéma, postupujte takto:
Uveďte atributy, které vaše aplikace vyžaduje, a pak kategorizovat jako atributy potřebné k ověření (například loginName a e-mail). Atributy jsou potřeba ke správě životního cyklu uživatele (například stav / aktivní) a všechny ostatní atributy potřebné pro fungování aplikace (například správce, značka).
Zkontrolujte, jestli jsou atributy již definovány ve schématu základního uživatele nebo schématu podnikového uživatele. Pokud ne, musíte definovat rozšíření schématu uživatele, které pokrývá chybějící atributy. Viz příklad rozšíření pro uživatele, aby bylo možné zřídit uživatele
tag
.Namapujte atributy SCIM na atributy uživatele v Microsoft Entra ID. Pokud některý z atributů, které jste definovali v koncovém bodu SCIM, nemá jasný protějšek schématu uživatele Microsoft Entra, požádejte správce tenanta o rozšíření schématu nebo použijte atribut rozšíření, jak je znázorněno v příkladu
tags
vlastnosti.
Následující tabulka uvádí příklad požadovaných atributů:
Požadovaný atribut nebo příklad aplikace | Mapovaný atribut SCIM | Mapovaný atribut Microsoft Entra |
---|---|---|
loginName | userName | userPrincipalName (Hlavní název uživatele) |
firstName | name.givenName | givenName |
lastName | name.familyName | příjmení |
pracovní pošta | emails[type eq "work"].value | Pošta |
manager | manager | manager |
značka | urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User:tag |
extensionAttribute1 |
stav | active | isSoftDeleted (vypočítaná hodnota není uložená na uživateli) |
Následující datová část JSON ukazuje příklad schématu SCIM:
{
"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"
}
}
Poznámka:
Kromě atributů požadovaných pro aplikaci zahrnuje reprezentace JSON také požadované id
atributy externalId
a meta
atributy.
Pomáhá kategorizovat mezi /User
a /Group
mapovat všechny výchozí atributy uživatele v Microsoft Entra ID na SCIM RFC, podívejte se, jak jsou vlastní atributy mapovány mezi Microsoft Entra ID a vaším koncovým bodem SCIM.
Následující tabulka uvádí příklad atributů uživatele:
Uživatel Microsoft Entra | 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 | title |
pošta | emails[type eq "work"].value |
mailNickname | externalId |
manager | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager |
mobilní | phoneNumbers[type eq "mobile"].value |
postalCode | addresses[type eq "work"].postalCode |
proxy adresy | email[type eq "other"]. Hodnota |
physical-Delivery-OfficeName | addresses[type eq "other"]. Naformátovaný |
streetAddress | addresses[type eq "work"].streetAddress |
surname | name.familyName |
telefonní číslo | phoneNumbers[type eq "work"].value |
user-PrincipalName | userName |
Následující tabulka uvádí příklad atributů skupiny:
Skupina Microsoft Entra | urn:ietf:params:scim:schemas:core:2.0:Group |
---|---|
displayName | displayName |
členové | členové |
objectId | externalId |
Poznámka:
Není nutné podporovat uživatele i skupiny nebo všechny atributy, které jsou zde uvedeny, je to pouze odkaz na to, jak jsou atributy v Microsoft Entra ID často mapovány na vlastnosti v protokolu SCIM.
V dokumentu RFC SCIM je definováno několik koncových bodů. Můžete začít s /User
koncovým bodem a pak ho rozbalit. V následující tabulce jsou uvedeny některé koncové body SCIM:
Koncový bod | Popis |
---|---|
na uživatele | Proveďte operace CRUD s objektem uživatele. |
/Skupina | Provádění operací CRUD u objektu skupiny |
/Schémata | Sada atributů podporovaných každým klientem a poskytovatelem služeb se může lišit. Jeden poskytovatel služeb může zahrnovat name , title a emails , zatímco jiný poskytovatel služeb používá name , title a phoneNumbers . Koncový bod schémat umožňuje zjistit podporované atributy. |
/Množství | Hromadné operace umožňují provádět operace s velkou kolekcí objektů prostředků v jedné operaci (například aktualizovat členství pro velkou skupinu). |
/ServiceProviderConfig | Poskytuje podrobnosti o funkcích standardu SCIM, které jsou podporovány, například prostředky, které jsou podporovány, a metodu ověřování. |
/ResourceTypes | Určuje metadata o jednotlivých prostředcích. |
Poznámka:
Pomocí koncového /Schemas
bodu můžete podporovat vlastní atributy nebo pokud se schéma často mění, protože umožňuje klientovi automaticky načíst nejaktuálnější schéma. Pomocí koncového /Bulk
bodu můžete podporovat skupiny.
Vysvětlení implementace Microsoft Entra SCIM
Služba zřizování Microsoft Entra je navržená tak, aby podporovala rozhraní API pro správu uživatelů SCIM 2.0.
Důležité
Chování implementace Microsoft Entra SCIM bylo naposledy aktualizováno 18. prosince 2018. Informace o tom, co se změnilo, naleznete v tématu Dodržování předpisů protokolu SCIM 2.0 služby zřizování uživatelů Microsoft Entra.
Ve specifikaci protokolu SCIM 2.0 musí vaše aplikace podporovat tyto požadavky:
Požadavek | Referenční poznámky (protokol SCIM) |
---|---|
Vytváření uživatelů a volitelně také skupin | Oddíl 3.3 |
Úprava uživatelů nebo skupin pomocí požadavků PATCH | Oddíl 3.5.2. Podpora zajišťuje, že se skupiny a uživatelé zřídí výkonným způsobem. |
Načtení známého prostředku pro uživatele nebo skupinu vytvořenou dříve | Oddíl 3.4.1 |
Dotazování uživatelů nebo skupin | Oddíl 3.4.2. Ve výchozím nastavení se uživatelé načítají se svými id a dotazovanými username se svými a externalId , a skupiny se dotazují s displayName . |
Filtr vyloučenýAttributes=members při dotazování prostředku skupiny | Oddíl 3.4.2.2 |
Podpora výpisu uživatelů a stránkování | Oddíl 3.4.2.4. |
Obnovitelné odstranění uživatele active=false a obnovení uživatele active=true |
Objekt uživatele by měl být vrácen v požadavku bez ohledu na to, jestli je uživatel aktivní. Jediný čas, kdy by uživatel neměl být vrácen, je, když je pevně odstraněn z aplikace. |
Podpora koncového bodu /Schemas | Část 7 Koncový bod zjišťování schématu se používá ke zjišťování dalších atributů. |
Přijměte jeden nosný token pro ověřování a autorizaci ID Microsoft Entra pro vaši aplikaci. |
Při implementaci koncového bodu SCIM použijte obecné pokyny k zajištění kompatibility s ID Microsoft Entra:
Obecné:
id
je požadovaná vlastnost pro všechny prostředky. Každá odpověď, která vrací prostředek, by měla zajistit, aby každý prostředek měl tuto vlastnost s výjimkouListResponse
nulových prvků.- Odeslané hodnoty by měly být uloženy ve stejném formátu, ve jakém byly odeslány. Neplatné hodnoty by měly být odmítnuty s popisnou chybovou zprávou s možností akce. Transformace dat by neměly probíhat mezi daty z Microsoft Entra ID a dat uloženými v aplikaci SCIM. (například. Telefonní číslo odeslané jako 55555555555 by nemělo být uloženo/vráceno jako +5 (555) 555-5555)
- Do odpovědi PATCH není nutné zahrnout celý prostředek.
- U strukturálních prvků v SCIM, zejména hodnot operací PATCH
op
, jak je definováno v bodě 3.5.2, nevyžadují shodu s rozlišováním malých a velkých písmen. Microsoft Entra ID vygeneruje hodnotyop
jako Přidat, Nahradit a Odebrat. - Microsoft Entra ID provádí požadavky na načtení náhodného uživatele a skupiny, aby se zajistilo, že koncový bod a přihlašovací údaje jsou platné. Provádí se také jako součást testovacího toku připojení .
- Podpora HTTPS na koncovém bodu SCIM
- Vlastní komplexní a vícehodnotové atributy jsou podporované, ale Microsoft Entra ID nemá mnoho složitých datových struktur, ze kterých by bylo v těchto případech potřeba načítat data. Atributy name/value je možné snadno namapovat, ale tok dat do složitých atributů se třemi nebo více dílčími atributy se nepodporuje.
- Subattribute hodnoty "type" komplexních atributů s více hodnotami musí být jedinečné. Například podtyp "práce" nemůže existovat dvě různé e-mailové adresy.
- Hlavička všech odpovědí by měla být content-Type: application/scim+json
Načítání prostředků:
- Odpověď na požadavek dotazu nebo filtru by vždy měla být .
ListResponse
- Microsoft Entra-only používá následující operátory:
eq
,and
- Atribut, na který lze prostředky dotazovat, by měl být nastaven jako odpovídající atribut v aplikaci, viz Přizpůsobení mapování atributů zřizování uživatelů.
/Uživatelé:
- Atribut nároků není podporován.
- Všechny atributy, které jsou považovány za jedinečnost uživatele, musí být použitelné jako součást filtrovaného dotazu. (Například pokud se pro uživatelské jméno i e-maily vyhodnotí jedinečnost uživatele[typ eq "work"], musí být pro dotazy userName eq "user@contoso.com" i e-maily[type eq"].value eq "" povoleny dotazy GET to /Users s filtrem.[type eq "work"].value eq "user@contoso.com" .
/Skupiny:
- Skupiny jsou volitelné, ale podporují se pouze v případě, že implementace SCIM podporuje požadavky PATCH .
- Skupiny musí mít jedinečnost v hodnotě displayName, aby se shodovaly s Id Microsoft Entra a aplikací SCIM. Jedinečnost není požadavkem protokolu SCIM, ale je to požadavek na integraci koncového bodu SCIM s Microsoft Entra ID.
/Schemas (zjišťování schémat):
- Ukázkový požadavek nebo odpověď
- Zjišťování schématu se používá v určitých aplikacích galerie. Zjišťování schématu je jedinou metodou pro přidání dalších atributů do schématu existující aplikace SCIM galerie. Ve vlastní aplikaci SCIM mimo galerii se v současné době nepodporuje zjišťování schématu.
- Pokud hodnota není k dispozici, neodesílejte hodnoty null.
- Hodnoty vlastností by měly být velkých a velkých písmen (například readWrite).
- Musí vrátit odpověď seznamu.
- Služba zřizování Microsoft Entra vytvoří požadavek /schemas při uložení konfigurace zřizování. Požadavek se také provede při otevření stránky pro zřizování úprav. Zjištěné další atributy se zobrazí zákazníkům v mapování atributů v seznamu cílových atributů. Zjišťování schématu vede pouze k přidání dalších cílových atributů. Atributy se neodeberou.
Zřizování a rušení zřizování uživatelů
Následující diagram znázorňuje zprávy, které Microsoft Entra ID odesílá do koncového bodu SCIM za účelem správy životního cyklu uživatele v úložišti identit vaší aplikace.
Zřizování a rušení zřizování skupin
Zřizování skupin a zrušení zřízení jsou volitelné. Při implementaci a povolení ukazuje následující obrázek zprávy, které Microsoft Entra ID odesílá do koncového bodu SCIM za účelem správy životního cyklu skupiny v úložišti identit vaší aplikace. Tyto zprávy se liší od zpráv o uživatelích dvěma způsoby:
- Požadavky na načtení skupin určují, že atribut člena má být vyloučen z jakéhokoli prostředku poskytnutého v reakci na požadavek.
- Žádosti o určení, jestli má atribut odkazu určitou hodnotu, jsou požadavky na atribut člena.
Následující diagram znázorňuje sekvenci zrušení zřízení skupiny:
Požadavky a odpovědi protokolu SCIM
Tento článek obsahuje příklad požadavků SCIM vygenerovaných službou Zřizování Microsoft Entra a příkladem očekávaných odpovědí. Nejlepších výsledků dosáhnete, když aplikaci naprogramujete tak, aby zpracovávala tyto požadavky v tomto formátu a vygeneruje očekávané odpovědi.
Důležité
Informace o tom, jak a kdy služba zřizování uživatelů Microsoft Entra generuje operace popsané v příkladu, najdete v části Cykly zřizování: Počáteční a přírůstkové v části Jak funguje zřizování.
- Vytvoření uživatele (odpověď požadavku / )
- Získání uživatele (odpověď požadavku / )
- Získání uživatele podle dotazu (odpověď požadavku / )
- Získání uživatele podle dotazu – nulové výsledky (odpověď požadavku / )
- Aktualizace uživatele [Vlastnosti s více hodnotami] (Odpověď požadavku / )
- Aktualizace uživatele [vlastnosti s jednou hodnotou] (odpověď požadavku / )
- Zakázat uživatele (odpověď na žádost / )
- Odstranit uživatele (odpověď požadavku / )
- Vytvoření skupiny (odpověď požadavku / )
- Získání skupiny (odpověď požadavku / )
- Získání skupiny podle displayName (odpověď požadavku / )
- Update Group [Non-member attributes] (Request / Response)
- Update Group [Add Members] (Request / Response)
- Update Group [Remove Members] (Request / Response)
- Odstranit skupinu (odpověď požadavku / )
Operace uživatelů
- Použití
userName
neboemails[type eq "work"]
atributy k dotazování uživatelů.
Vytvoření uživatele
Žádost
POST /Users
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
"externalId": "0a21f0f2-8d2a-4f8e-bf98-7363c4aed4ef",
"userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"active": true,
"emails": [{
"primary": true,
"type": "work",
"value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com"
}],
"meta": {
"resourceType": "User"
},
"name": {
"formatted": "givenName familyName",
"familyName": "familyName",
"givenName": "givenName"
},
"roles": []
}
Response
Vytvořeno http/1.1 201
{
"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
}]
}
Získání uživatele
Žádost
GET /Users/5d48a0a8e9f04aa38008
Odpověď (uživatel byl nalezen)
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
}]
}
Žádost
GET /Users/5171a35d82074e068ce2
Odpověď (uživatel nebyl nalezen. Podrobnosti nejsou povinné, pouze stav.)
HTTP/1.1 404 Nenalezena
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:Error"
],
"status": "404",
"detail": "Resource 23B51B0E5D7AE9110A49411D@7cca31655d49f3640a494224 not found"
}
Získání uživatele podle dotazu
Žádost
GET /Users?filter=userName eq "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee4e4ee4ee"
Response
HTTP/1.1 200 OK
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults": 1,
"Resources": [{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "2441309d85324e7793ae",
"externalId": "7fce0092-d52e-4f76-b727-3955bd72c939",
"meta": {
"resourceType": "User",
"created": "2018-03-27T19:59:26.000Z",
"lastModified": "2018-03-27T19:59:26.000Z"
},
"userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": {
"familyName": "familyName",
"givenName": "givenName"
},
"active": true,
"emails": [{
"value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com",
"type": "work",
"primary": true
}]
}],
"startIndex": 1,
"itemsPerPage": 20
}
Získání uživatele podle dotazu – nulové výsledky
Žádost
GET /Users?filter=userName eq "neexistující uživatel"
Response
HTTP/1.1 200 OK
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults": 0,
"Resources": [],
"startIndex": 1,
"itemsPerPage": 20
}
Aktualizovat uživatele [Vlastnosti s více hodnotami]
Žádost
PATCH /Users/6764549bef60420686bc HTTP/1.1
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [
{
"op": "Replace",
"path": "emails[type eq \"work\"].value",
"value": "updatedEmail@microsoft.com"
},
{
"op": "Replace",
"path": "name.familyName",
"value": "updatedFamilyName"
}
]
}
Response
HTTP/1.1 200 OK
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "6764549bef60420686bc",
"externalId": "6c75de36-30fa-4d2d-a196-6bdcdb6b6539",
"meta": {
"resourceType": "User",
"created": "2018-03-27T19:59:26.000Z",
"lastModified": "2018-03-27T19:59:26.000Z"
},
"userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": {
"formatted": "givenName updatedFamilyName",
"familyName": "updatedFamilyName",
"givenName": "givenName"
},
"active": true,
"emails": [{
"value": "updatedEmail@microsoft.com",
"type": "work",
"primary": true
}]
}
Aktualizovat uživatele [Vlastnosti s jednou hodnotou]
Žádost
PATCH /Users/5171a35d82074e068ce2 HTTP/1.1
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op": "Replace",
"path": "userName",
"value": "5b50642d-79fc-4410-9e90-4c077cdd1a59@testuser.com"
}]
}
Response
HTTP/1.1 200 OK
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "5171a35d82074e068ce2",
"externalId": "aa1eca08-7179-4eeb-a0be-a519f7e5cd1a",
"meta": {
"resourceType": "User",
"created": "2018-03-27T19:59:26.000Z",
"lastModified": "2018-03-27T19:59:26.000Z"
},
"userName": "5b50642d-79fc-4410-9e90-4c077cdd1a59@testuser.com",
"name": {
"formatted": "givenName familyName",
"familyName": "familyName",
"givenName": "givenName",
},
"active": true,
"emails": [{
"value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com",
"type": "work",
"primary": true
}]
}
Zakázat uživatele
Žádost
PATCH /Users/5171a35d82074e068ce2 HTTP/1.1
{
"Operations": [
{
"op": "Replace",
"path": "active",
"value": false
}
],
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
]
}
Response
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "CEC50F275D83C4530A495FCF@834d0e1e5d8235f90a495fda",
"userName": "deanruiz@testuser.com",
"name": {
"familyName": "Harris",
"givenName": "Larry"
},
"active": false,
"emails": [
{
"value": "gloversuzanne@testuser.com",
"type": "work",
"primary": true
}
],
"addresses": [
{
"country": "ML",
"type": "work",
"primary": true
}
],
"meta": {
"resourceType": "Users",
"location": "/scim/5171a35d82074e068ce2/Users/CEC50F265D83B4530B495FCF@5171a35d82074e068ce2"
}
}
Odstranění uživatele
Žádost
DELETE /Users/5171a35d82074e068ce2 HTTP/1.1
Response
HTTP/1.1 204 Bez obsahu
Operace skupiny
- Skupiny se vytvoří se seznamem prázdných členů.
- Pomocí atributu
displayName
se můžete dotazovat na skupiny. - Aktualizace na požadavek PATCH skupiny by měla v odpovědi přinést HTTP 204 Bez obsahu . Vrácení těla se seznamem všech členů se nedoporučuje.
- Není nutné podporovat vrácení všech členů skupiny.
Vytvořit skupinu
Žádost
POST /Groups HTTP/1.1
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group", "http://schemas.microsoft.com/2006/11/ResourceManagement/ADSCIM/2.0/Group"],
"externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159",
"displayName": "displayName",
"meta": {
"resourceType": "Group"
}
}
Response
Vytvořeno http/1.1 201
{
"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": []
}
Získat skupinu
Žádost
GET /Groups/40734ae655284ad3abcc?excludedAttributes=members HTTP/1.1
Response
HTTP/1.1 200 OK
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"id": "40734ae655284ad3abcc",
"externalId": "60f1bb27-2e1e-402d-bcc4-ec999564a194",
"meta": {
"resourceType": "Group",
"created": "2018-03-27T19:59:26.000Z",
"lastModified": "2018-03-27T19:59:26.000Z"
},
"displayName": "displayName",
}
Získání skupiny podle displayName
Žádost
GET /Groups?excludedAttributes=members&filter=displayName eq "displayName" HTTP/1.1
Response
HTTP/1.1 200 OK
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults": 1,
"Resources": [{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"id": "8c601452cc934a9ebef9",
"externalId": "0db508eb-91e2-46e4-809c-30dcbda0c685",
"meta": {
"resourceType": "Group",
"created": "2018-03-27T22:02:32.000Z",
"lastModified": "2018-03-27T22:02:32.000Z",
},
"displayName": "displayName",
}],
"startIndex": 1,
"itemsPerPage": 20
}
Update Group [Non-member attributes]
Žádost
PATCH /Groups/fa2ce26709934589afc5 HTTP/1.1
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op": "Replace",
"path": "displayName",
"value": "1879db59-3bdf-4490-ad68-ab880a269474updatedDisplayName"
}]
}
Response
HTTP/1.1 204 Bez obsahu
Aktualizovat skupinu [Přidat členy]
Žádost
PATCH /Groups/a99962b9f99d4c4fac67 HTTP/1.1
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op": "Add",
"path": "members",
"value": [{
"$ref": null,
"value": "f648f8d5ea4e4cd38e9c"
}]
}]
}
Response
HTTP/1.1 204 Bez obsahu
Aktualizovat skupinu [Odebrat členy]
Žádost
PATCH /Groups/a99962b9f99d4c4fac67 HTTP/1.1
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op": "Remove",
"path": "members",
"value": [{
"$ref": null,
"value": "f648f8d5ea4e4cd38e9c"
}]
}]
}
Response
HTTP/1.1 204 Bez obsahu
Odstranění skupiny
Žádost
DELETE /Groups/cdb1ce18f65944079d37 HTTP/1.1
Response
HTTP/1.1 204 Bez obsahu
Zjišťování schématu
Zjišťování schématu
Žádost
GET /Schemas
Response
HTTP/1.1 200 OK
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"itemsPerPage": 50,
"startIndex": 1,
"totalResults": 3,
"Resources": [
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
"id" : "urn:ietf:params:scim:schemas:core:2.0:User",
"name" : "User",
"description" : "User Account",
"attributes" : [
{
"name" : "userName",
"type" : "string",
"multiValued" : false,
"description" : "Unique identifier for the User, typically
used by the user to directly authenticate to the service provider.
Each User MUST include a non-empty userName value. This identifier
MUST be unique across the service provider's entire set of Users.
REQUIRED.",
"required" : true,
"caseExact" : false,
"mutability" : "readWrite",
"returned" : "default",
"uniqueness" : "server"
},
],
"meta" : {
"resourceType" : "Schema",
"location" :
"/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:User"
}
},
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
"id" : "urn:ietf:params:scim:schemas:core:2.0:Group",
"name" : "Group",
"description" : "Group",
"attributes" : [
{
"name" : "displayName",
"type" : "string",
"multiValued" : false,
"description" : "A human-readable name for the Group.
REQUIRED.",
"required" : false,
"caseExact" : false,
"mutability" : "readWrite",
"returned" : "default",
"uniqueness" : "none"
},
],
"meta" : {
"resourceType" : "Schema",
"location" :
"/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:Group"
}
},
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
"id" : "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
"name" : "EnterpriseUser",
"description" : "Enterprise User",
"attributes" : [
{
"name" : "employeeNumber",
"type" : "string",
"multiValued" : false,
"description" : "Numeric or alphanumeric identifier assigned
to a person, typically based on order of hire or association with an
organization.",
"required" : false,
"caseExact" : false,
"mutability" : "readWrite",
"returned" : "default",
"uniqueness" : "none"
},
],
"meta" : {
"resourceType" : "Schema",
"location" :
"/v2/Schemas/urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
}
}
]
}
Požadavky na zabezpečení
Verze protokolu TLS
Jediná přijatelná verze protokolu je TLS 1.2. Není povolená žádná jiná verze protokolu SSL/TLS.
- Klíče RSA musí mít alespoň 2 048 bitů.
- Klíče ECC musí mít alespoň 256 bitů, vygenerované pomocí schválené eliptické křivky.
Délky kláves
Všechny služby musí používat certifikáty X.509 vygenerované pomocí kryptografických klíčů s dostatečnou délkou, což znamená:
Šifrovací sady
Všechny služby musí být nakonfigurované tak, aby používaly následující šifrovací sady v přesném pořadí uvedeném v příkladu. Pokud máte jenom certifikát RSA, nainstalované šifrovací sady ECDSA nemají žádný vliv.
Minimální pruh šifrovacích sad TLS 1.2:
- 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
Rozsahy IP adres
Služba zřizování Microsoft Entra v současné době funguje v rámci rozsahů IP adres pro ID Microsoft Entra, jak je uvedeno zde. Můžete přidat rozsahy IP adres uvedené pod značkou ID Microsoft Entra, abyste umožnili provoz ze služby zřizování Microsoft Entra do vaší aplikace. Pro vypočítané adresy je potřeba pečlivě zkontrolovat seznam rozsahů IP adres. V seznamu rozsahu IP adres může být reprezentována adresa 40.126.25.32 jako 40.126.0.0/18. Pomocí následujícího rozhraní API můžete také programově načíst seznam rozsahů IP adres.
Microsoft Entra ID také podporuje řešení založené na agentech, které poskytuje připojení k aplikacím v privátních sítích (místně, hostované v Azure, hostované v AWS atd.). Zákazníci můžou nasadit odlehčeného agenta, který poskytuje připojení k Microsoft Entra ID bez otevření příchozích portů na serveru ve své privátní síti. Další informace najdete zde.
Vytvoření koncového bodu SCIM
Teď, když jste navrhli schéma a porozuměli implementaci Microsoft Entra SCIM, můžete začít s vývojem koncového bodu SCIM. Místo toho, abyste začali úplně od začátku a zcela vytvářeli implementaci, můžete se spolehnout na mnoho opensourcových knihoven SCIM publikovaných komunitou SCIM.
Pokyny k vytvoření koncového bodu SCIM včetně příkladů najdete v tématu Vývoj ukázkového koncového bodu SCIM.
Příklad referenčního kódu open source .NET Core publikovaný týmem zřizování Microsoft Entra je jedním z prostředků, které můžou začít s vývojem. Vytvořte koncový bod SCIM a pak ho otestujte. Použijte kolekci testů Postman poskytovaných jako součást referenčního kódu nebo projděte si zadané ukázkové požadavky nebo odpovědi.
Poznámka:
Referenční kód vám pomůže začít sestavovat koncový bod SCIM a poskytuje se "AS IS". Příspěvky od komunity jsou vítány, aby pomohly sestavovat a udržovat kód.
Řešení se skládá ze dvou projektů, Microsoft.SCIM a Microsoft.SCIM.WebHostSample.
Projekt Microsoft.SCIM je knihovna, která definuje komponenty webové služby, které odpovídají specifikaci SCIM. Deklaruje rozhraní Microsoft.SCIM.IProvider, požadavky se překládají do volání metod poskytovatele, které by byly naprogramovány tak, aby fungovaly v úložišti identit.
Projekt Microsoft.SCIM.WebHostSample je webová aplikace ASP.NET Core založená na prázdné šabloně. Umožňuje, aby se ukázkový kód nasadil jako samostatný, hostovaný v kontejnerech nebo v rámci Internetová informační služba. Implementuje také rozhraní Microsoft.SCIM.IProvider , které uchovává třídy v paměti jako ukázkové úložiště identit.
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();
}
...
Vytvoření vlastního koncového bodu SCIM
Koncový bod SCIM musí mít adresu HTTP a ověřovací certifikát serveru, jehož kořenová certifikační autorita je jedním z následujících názvů:
- CNNIC
- Comodo
- CyberTrust
- DigiCert
- GeoTrust
- GlobalSign
- Go Daddy
- VeriSign
- WoSign
- Kořenová CA DST X3
Sada .NET Core SDK obsahuje vývojový certifikát HTTPS, který se používá při vývoji. Certifikát se nainstaluje jako součást prostředí prvního spuštění. V závislosti na tom, jak spustíte webovou aplikaci ASP.NET Core, naslouchá jinému portu:
- Microsoft.SCIM.WebHostSample:
https://localhost:5001
- IIS Express:
https://localhost:44359
Další informace o HTTPS v ASP.NET Core najdete na následujícím odkazu: Vynucení HTTPS v ASP.NET Core
Zpracování ověřování koncových bodů
Požadavky ze služby zřizování Microsoft Entra zahrnují nosný token OAuth 2.0. Autorizační server vydává nosný token. Microsoft Entra ID je příkladem důvěryhodného autorizačního serveru. Nakonfigurujte službu zřizování Microsoft Entra tak, aby používala jeden z následujících tokenů:
Dlouhodobý nosný token. Pokud koncový bod SCIM vyžaduje nosný token OAuth od jiného vystavitele než Microsoft Entra ID, zkopírujte požadovaný nosný token OAuth do pole volitelného tajného tokenu . Ve vývojovém prostředí můžete použít testovací token z koncového
/scim/token
bodu. V produkčních prostředích by se neměly používat testovací tokeny.Nosný token Microsoft Entra. Pokud je pole Token tajného kódu prázdné, obsahuje ID Microsoft Entra nosný token OAuth vydaný z Microsoft Entra ID s každou žádostí. Aplikace, které jako zprostředkovatele identity používají ID Microsoft Entra, můžou ověřit tento token vydaný id Microsoft Entra.
- Aplikace, která přijímá požadavky, by měla ověřit vystavitele tokenu jako ID Microsoft Entra pro očekávaného tenanta Microsoft Entra.
- Deklarace
iss
identity identifikuje vystavitele tokenu. Například"iss":"https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/"
. V tomto příkladu základní adresa hodnotyhttps://sts.windows.net
deklarace identity identifikuje ID Microsoft Entra jako vystavitele, zatímco relativní segment adresy aaaabbbb-0000-cccc-1111-dddd2222eeee, je jedinečný identifikátor tenanta Microsoft Entra, pro který byl token vydán. - Cílová skupina tokenu je ID aplikace pro aplikaci v galerii. Aplikace zaregistrované v jednom tenantovi obdrží stejnou
iss
deklaraci identity s požadavky SCIM. ID aplikace pro všechny vlastní aplikace je 8adf8e6e-67b2-4cf2-a259-e3dc5476c621. Token vygenerovaný ID Microsoft Entra by se měl použít pouze k testování. Nemělo by se používat v produkčních prostředích.
V ukázkovém kódu se požadavky ověřují pomocí balíčku Microsoft.AspNetCore.Authentication.JwtBearer. Následující kód vynucuje, aby se požadavky na všechny koncové body služby ověřovaly pomocí nosného tokenu vydaného ID Microsoft Entra pro zadaného tenanta:
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();
...
}
Nosný token je také nutný k použití poskytnutých testů Postman a provádění místního ladění pomocí localhost. Ukázkový kód používá prostředí ASP.NET Core ke změně možností ověřování během fáze vývoje a povolení použití tokenu podepsaného svým držitelem.
Další informace o více prostředích v ASP.NET Core najdete v tématu Použití více prostředí v ASP.NET Core.
Následující kód vynucuje, aby se požadavky na všechny koncové body služby ověřovaly pomocí nosného tokenu podepsaného vlastním klíčem:
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"))
};
});
}
...
Odešlete na kontroler tokenu požadavek GET, aby získal platný nosný token, metoda GenerateJSONWebToken zodpovídá za vytvoření tokenu odpovídajícího parametrům nakonfigurovaným pro vývoj:
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;
}
Zpracování zřizování a rušení zřizování uživatelů
Příklad 1. Dotazování služby na odpovídajícího uživatele
Microsoft Entra ID dotazuje službu pro uživatele s hodnotou atributu externalId
odpovídající hodnotě atributu mailNickname uživatele v Microsoft Entra ID. Dotaz se vyjadřuje jako požadavek HTTP (Hypertext Transfer Protocol), například v tomto příkladu, kde jyoung je vzorek mailNickname uživatele v Microsoft Entra ID.
Poznámka:
Toto je jenom příklad. Ne všichni uživatelé budou mít atribut mailNickname a hodnota, kterou uživatel nemusí být v adresáři jedinečný. Atribut použitý pro porovnávání (v tomto případě ) externalId
je také konfigurovatelný v mapování atributů Microsoft Entra.
GET https://.../scim/Users?filter=externalId eq jyoung HTTP/1.1
Authorization: Bearer ...
V ukázkovém kódu se požadavek přeloží do volání metody QueryAsync poskytovatele služby. Tady je podpis této metody:
// 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);
V ukázkovém dotazu jsou hodnoty argumentů předaných metodě QueryAsync pro uživatele s danou hodnotou atributu externalId
:
- parametry. AlternateFilters.Count: 1
- parametry. AlternateFilters.ElementAt(0). AttributePath: "externalId"
- parametry. AlternateFilters.ElementAt(0). ComparisonOperator: ComparisonOperator.Equals
- parametry. AlternateFilter.ElementAt(0). ComparisonValue: "jyoung"
Příklad 2. Zřízení uživatele
Pokud odpověď na dotaz na koncový bod SCIM pro uživatele s hodnotou atributu externalId
, která odpovídá hodnotě atributu mailNickname uživatele, nevrací žádné uživatele, Microsoft Entra ID požádá, aby služba zřídila uživatele odpovídající té v Microsoft Entra ID. Tady je příklad takového požadavku:
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}
V ukázkovém kódu se požadavek přeloží do volání metody CreateAsync poskytovatele služby. Tady je podpis této metody:
// 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);
V požadavku na zřizování uživatele je hodnota argumentu prostředku instancí Microsoft.SCIM.Core2EnterpriseUser
třídy. Tato třída je definována v knihovně Microsoft.SCIM.Schemas
. Pokud požadavek na zřízení uživatele proběhne úspěšně, očekává se, že implementace metody vrátí instanci Microsoft.SCIM.Core2EnterpriseUser
třídy. Hodnota Identifier
vlastnosti je nastavena na jedinečný identifikátor nově zřízeného uživatele.
Příklad 3. Dotazování aktuálního stavu uživatele
Microsoft Entra ID požaduje aktuální stav zadaného uživatele ze služby s požadavkem, například:
GET ~/scim/Users/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 HTTP/1.1
Authorization: Bearer ...
V ukázkovém kódu se požadavek přeloží do volání metody RetrieveAsync zprostředkovatele služby. Tady je podpis této metody:
// 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);
V příkladu požadavku pro načtení aktuálního stavu uživatele jsou hodnoty vlastností objektu zadané jako hodnota argumentu parametrů následující:
- Identifikátor: "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1e1e1e1"
- SchemaIdentifier:
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
Příklad 4. Zadejte dotaz na hodnotu referenčního atributu, který se má aktualizovat.
Id Microsoft Entra před aktualizací zkontroluje aktuální hodnotu atributu v úložišti identit. Pro uživatele je ale nejprve zaškrtnuto pouze atribut správce. Tady je příklad požadavku, který určuje, jestli má atribut správce objektu uživatele aktuálně určitou hodnotu: V ukázkovém kódu se požadavek přeloží do volání metody QueryAsync poskytovatele služby. Hodnota vlastností objektu zadaného jako hodnota argumentu parametrů jsou následující:
- parametry. AlternateFilters.Count: 2
- parametry. AlternateFilters.ElementAt(x). AttributePath: "ID"
- parametry. AlternateFilters.ElementAt(x). ComparisonOperator: ComparisonOperator.Equals
- parametry. AlternateFilter.ElementAt(x). ComparisonValue: "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1e1e1e1"
- parametry. AlternateFilters.ElementAt(y). AttributePath: "manager"
- parametry. AlternateFilters.ElementAt(y). ComparisonOperator: ComparisonOperator.Equals
- parametry. AlternateFilter.ElementAt(y). ComparisonValue: "00aa0aa-bb11-cc22-dd33-44ee4ee4e4e4ee4ee"
- parametry. RequestedAttributePaths.ElementAt(0): "ID"
- parametry. SchemaIdentifier:
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
Hodnota indexu x může být 0
a hodnota indexu y může být 1
. Nebo hodnota x může být 1
a hodnota y může být 0
. Závisí na pořadí výrazů parametru dotazu filtru.
Příklad 5. Žádost o ID Microsoft Entra do koncového bodu SCIM za účelem aktualizace uživatele
Tady je příklad požadavku z Id Microsoft Entra do koncového bodu SCIM pro aktualizaci uživatele:
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"}]}]}
V ukázkovém kódu se požadavek přeloží do volání metody UpdateAsync poskytovatele služby. Tady je podpis této metody:
// 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);
V příkladu požadavku má objekt zadaný jako hodnotu argumentu patch tyto hodnoty vlastností:
Argument | Hodnota |
---|---|
ResourceIdentifier.Identifier |
"a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1e1e1e1" |
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 |
Manažer |
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.Count |
0 |
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.ElementAt(0).Reference |
http://.../scim/Users/00aa00aa-bb11-cc22-dd33-44ee44ee44ee |
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.ElementAt(0).Value |
00a-bb11-cc22-dd33-44ee44ee4e4ee |
Příklad 6. Zrušení zřízení uživatele
Pokud chcete zrušit zřízení uživatele z úložiště identit před koncovým bodem SCIM, microsoft Entra ID odešle požadavek, například:
DELETE ~/scim/Users/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 HTTP/1.1
Authorization: Bearer ...
V ukázkovém kódu se požadavek přeloží do volání metody DeleteAsync poskytovatele služby. Tady je podpis této metody:
// 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);
Objekt zadaný jako hodnota argumentu resourceIdentifier má tyto hodnoty vlastnosti v příkladu požadavku na zrušení zřízení uživatele:
- ResourceIdentifier.Identifier: "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1e1e1"
- ResourceIdentifier.SchemaIdentifier:
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
Integrace koncového bodu SCIM se službou Zřizování Microsoft Entra
Microsoft Entra ID lze nakonfigurovat tak, aby automaticky zřizovat přiřazené uživatele a skupiny aplikacím, které implementují konkrétní profil protokolu SCIM 2.0. Specifika profilu jsou zdokumentovaná v části Vysvětlení implementace Microsoft Entra SCIM.
Informace o kompatibilitě s těmito požadavky vám poskytne poskytovatel aplikace nebo dokumentace poskytovatele aplikace.
Důležité
Implementace Microsoft Entra SCIM je založená na službě zřizování uživatelů Microsoft Entra, která je navržená tak, aby neustále synchronizovala uživatele mezi ID Microsoft Entra a cílovou aplikací a implementuje velmi specifickou sadu standardních operací. Je důležité porozumět těmto chováním, abyste porozuměli chování služby Microsoft Entra provisioning. Další informace najdete v části Cykly zřizování: Počáteční a přírůstkové v části Jak funguje zřizování.
Začínáme
Tip
Postup v tomto článku se může mírně lišit v závislosti na portálu, od který začínáte.
Aplikace, které podporují profil SCIM popsaný v tomto článku, mohou být připojeny k Microsoft Entra ID pomocí funkce "aplikace mimo galerii" v galerii aplikací Microsoft Entra. Po připojení spustí ID Microsoft Entra proces synchronizace. Proces se spustí každých 40 minut. Proces se dotazuje koncového bodu SCIM aplikace na přiřazené uživatele a skupiny a vytvoří je nebo upraví podle podrobností o přiřazení.
Připojení aplikace, která podporuje SCIM:
Přihlaste se do Centra pro správu Microsoft Entra jako alespoň správce aplikací.
Přejděte k podnikovým aplikacím> identit.>
Zobrazí se seznam všech nakonfigurovaných aplikací, včetně aplikací přidaných z galerie.
Vyberte + Nová aplikace> + Vytvořit vlastní aplikaci.
Zadejte název aplikace, zvolte možnost Integrovat jakoukoli jinou aplikaci, kterou v galerii nenajdete, a výběrem možnosti Přidat vytvořte objekt aplikace. Nová aplikace se přidá do seznamu podnikových aplikací a otevře se na obrazovce správy aplikací.
Následující snímek obrazovky ukazuje galerii aplikací Microsoft Entra:
Na obrazovce správy aplikací vyberte na levém panelu zřizování .
V nabídce Režim zřizování vyberte Automaticky.
Následující snímek obrazovky ukazuje konfiguraci nastavení zřizování v Centru pro správu Microsoft Entra:
Do pole Adresa URL tenanta zadejte adresu URL koncového bodu SCIM aplikace. Příklad:
https://api.contoso.com/scim/
Pokud koncový bod SCIM vyžaduje nosný token OAuth od jiného vystavitele než Microsoft Entra ID, zkopírujte požadovaný nosný token OAuth do pole volitelného tajného tokenu . Pokud toto pole zůstane prázdné, obsahuje ID Microsoft Entra nosný token OAuth vydaný z Microsoft Entra ID s každou žádostí. Aplikace, které jako zprostředkovatele identity používají ID Microsoft Entra, můžou ověřit tento token vydaný id Microsoft Entra.
Poznámka:
Toto pole se nedoporučuje nechat prázdné a spoléhat se na token vygenerovaný id Microsoft Entra. Tato možnost je primárně k dispozici pro účely testování.
Vyberte Test připojení , aby se microsoft Entra ID pokusil připojit ke koncovému bodu SCIM. Pokud pokus selže, zobrazí se informace o chybě.
Poznámka:
Test Connection se dotazuje koncového bodu SCIM pro uživatele, který neexistuje, pomocí náhodného identifikátoru GUID jako odpovídající vlastnosti vybrané v konfiguraci Microsoft Entra. Očekávaná správná odpověď je HTTP 200 OK s prázdnou zprávou SCIM ListResponse.
Pokud se pokusy o připojení k aplikaci úspěšně připojí, uložte přihlašovací údaje správce výběrem možnosti Uložit .
V části Mapování existují dvě selektovatelné sady mapování atributů: jednu pro objekty uživatele a jednu pro objekty skupiny. Vyberte každý z nich a zkontrolujte atributy, které jsou synchronizované z Microsoft Entra ID do vaší aplikace. Atributy vybrané jako Odpovídající vlastnosti se používají ke shodě uživatelů a skupin v aplikaci pro operace aktualizace. Výběrem možnosti Uložit potvrďte všechny změny.
Poznámka:
Synchronizaci objektů skupiny můžete volitelně zakázat zakázáním mapování skupin.
V části Nastavení pole Obor definuje, kteří uživatelé a skupiny se synchronizují. Pokud chcete synchronizovat jenom uživatele a skupiny přiřazené na kartě Uživatelé a skupiny, vyberte Možnost Synchronizovat pouze přiřazené uživatele a skupiny.
Po dokončení konfigurace nastavte stav zřizování na Zapnuto.
Výběrem možnosti Uložit spusťte službu zřizování Microsoft Entra.
Pokud synchronizujete jenom přiřazené uživatele a skupiny (doporučeno), vyberte kartu Uživatelé a skupiny . Potom přiřaďte uživatele nebo skupiny, které chcete synchronizovat.
Po spuštění počátečního cyklu můžete na levém panelu vybrat protokoly zřizování, abyste mohli sledovat průběh, který zobrazuje všechny akce prováděné službou zřizování ve vaší aplikaci. Další informace o tom, jak číst protokoly zřizování Microsoft Entra, najdete v tématu Vytváření sestav o automatickém zřizování uživatelských účtů.
Poznámka:
Počáteční cyklus trvá déle než pozdější synchronizace, ke kterým dochází přibližně každých 40 minut, pokud je služba spuštěná.
Publikování aplikace do galerie aplikací Microsoft Entra
Pokud vytváříte aplikaci používanou více než jedním tenantem, zpřístupnit ji v galerii aplikací Microsoft Entra. Organizace snadno zjistí aplikaci a nakonfigurují zřizování. Publikování aplikace v galerii Microsoft Entra a zpřístupnění zřizování ostatním uživatelům je snadné. Podívejte se na postup tady. Microsoft s vámi spolupracuje na integraci vaší aplikace do galerie, otestování koncového bodu a dokumentaci k onboardingu vydaných verzí pro zákazníky.
Kontrolní seznam pro onboarding galerie
Pomocí kontrolního seznamu můžete rychle připojit aplikaci a zákazníci mají bezproblémové prostředí nasazení. Informace se shromáždí od vás při onboardingu do galerie.
- Podpora koncového bodu uživatele a skupiny SCIM 2.0 (vyžaduje se jenom jeden, ale doporučuje se obojí)
- Podpora alespoň 25 požadavků za sekundu za tenanta, aby se zajistilo, že se uživatelé a skupiny zřídí a zruší jejich zřízení bez zpoždění (povinné)
- Vytvořte technické kontakty a kontakty podpory, které povedou zákazníky k onboardingu z galerie (povinné)
- 3 Neúspěšné testovací přihlašovací údaje pro vaši aplikaci (povinné)
- Podpora udělení autorizačního kódu OAuth nebo dlouhodobého tokenu, jak je popsáno v příkladu (povinné)
- Aplikace OIDC musí mít definovanou alespoň 1 roli (vlastní nebo výchozí).
- Vytvoření technického a kontaktního bodu podpory pro podporu zákazníků po registraci galerie (povinné)
- Podpora zjišťování schématu (povinné)
- Podpora aktualizace více členství ve skupinách pomocí jediné opravy
- Veřejné zdokumentujte koncový bod SCIM.
Autorizace zřizování konektorů v galerii aplikací
Specifikace SCIM nedefinuje schéma specifické pro SCIM pro ověřování a autorizaci a spoléhá na použití stávajících oborových standardů.
Metoda autorizace | Výhody | Nevýhody | Technická podpora |
---|---|---|---|
Uživatelské jméno a heslo (nedoporučuje se nebo nepodporuje ID Microsoft Entra) | Snadná implementace | Nezabezpečená – váš pa$$word nezáleží | Nepodporuje se pro nové galerie nebo aplikace mimo galerii. |
Dlouhodobý nosný token | Dlouhodobé tokeny nevyžadují, aby byl uživatel přítomný. Správci se můžou snadno používat při nastavování zřizování. | Dlouhodobé tokeny můžou být obtížné sdílet s správcem bez použití nezabezpečených metod, jako je e-mail. | Podporováno pro aplikace z galerie a mimo galerii. |
Udělení autorizačního kódu OAuth | Přístupové tokeny mají kratší životnost než hesla a mají automatizovaný mechanismus aktualizace, který dlouhodobé nosné tokeny nemají. Skutečný uživatel musí být přítomný během počáteční autorizace a přidat úroveň odpovědnosti. | Vyžaduje, aby byl uživatel přítomný. Pokud uživatel opustí organizaci, token je neplatný a autorizace se musí dokončit znovu. | Podporováno pro aplikace z galerie, ale ne pro aplikace mimo galerii. Přístupový token ale můžete poskytnout v uživatelském rozhraní jako token tajného kódu pro účely krátkodobého testování. Podpora udělení kódu OAuth v jiné galerii je v našem backlogu, kromě podpory konfigurovatelných adres URL ověřování a tokenů v aplikaci galerie. |
Udělení přihlašovacích údajů klienta OAuth | Přístupové tokeny mají kratší životnost než hesla a mají automatizovaný mechanismus aktualizace, který dlouhodobé nosné tokeny nemají. Autorizační kód grant i přihlašovací údaje klienta udělují stejný typ přístupového tokenu, takže přechod mezi těmito metodami je pro rozhraní API transparentní. Zřizování je možné automatizovat a bez zásahu uživatele je možné bezobslužně požadovat nové tokeny. | Podporováno pro aplikace z galerie, ale ne pro aplikace mimo galerii. Přístupový token ale můžete poskytnout v uživatelském rozhraní jako token tajného kódu pro účely krátkodobého testování. Podpora udělení přihlašovacích údajů klienta OAuth v jiné galerii je v našem backlogu. |
Poznámka:
V uživatelském rozhraní vlastní aplikace pro zřizování Microsoft Entra se nedoporučuje ponechat pole tokenu prázdné. Vygenerovaný token je primárně k dispozici pro účely testování.
Tok udělení kódu OAuth
Služba zřizování podporuje udělení autorizačního kódu a po odeslání vaší žádosti o publikování vaší aplikace v galerii vám náš tým pomůže shromáždit následující informace:
Adresa URL autorizace, kterou klient získá autorizaci od vlastníka prostředku prostřednictvím přesměrování uživatelského agenta. Uživatel se přesměruje na tuto adresu URL pro autorizaci přístupu.
Adresa URL výměny tokenů, což je adresa URL klienta pro výměnu autorizačního grantu pro přístupový token, obvykle s ověřováním klienta.
ID klienta, autorizační server vydává registrovaný klient identifikátor klienta, což je jedinečný řetězec představující registrační informace poskytnuté klientem. Identifikátor klienta není tajný kód; je vystavený vlastníkovi prostředku a nesmí být použit sám pro ověřování klientů.
Tajný klíč klienta, tajný klíč vygenerovaný autorizačním serverem, který by měl být jedinečnou hodnotou známou pouze autorizačnímu serveru.
Poznámka:
Adresa URL autorizace a adresa URL výměny tokenů se momentálně nedají konfigurovat pro jednotlivé tenanty.
Poznámka:
OAuth v1 se nepodporuje kvůli vystavení tajného klíče klienta. Podporuje se OAuth v2.
Při použití toku udělení kódu OAuth je nutné podporovat model, ve kterém každý zákazník při nastavování instance zřizování odešle vlastní ID klienta a tajný klíč klienta. Jeden pár ID klienta nebo tajného klíče klienta pro celou aplikaci se nepodporuje.
Jak nastavit tok udělení kódu OAuth
Přihlaste se do Centra pro správu Microsoft Entra jako alespoň správce aplikací.
Přejděte na Zřizovací aplikaci Podnikové aplikace>>Identita>>a vyberte Autorizovat.
Přihlaste se do Centra pro správu Microsoft Entra jako alespoň správce aplikací.
Přejděte k podnikovým aplikacím> identit.>
Vyberte aplikaci a přejděte na Zřizování.
Vyberte Autorizovat.
Uživatelé se přesměrují na autorizační adresu URL (přihlašovací stránka aplikace třetí strany).
Správce poskytne přihlašovací údaje k aplikaci třetí strany.
Aplikace třetí strany přesměruje uživatele zpět a poskytne kód udělení.
Služba zřizování volá adresu URL tokenu a poskytuje kód udělení. Aplikace třetí strany odpoví přístupovým tokenem, obnovovacím tokenem a datem vypršení platnosti.
Při zahájení cyklu zřizování služba zkontroluje, jestli je aktuální přístupový token platný, a v případě potřeby ho vymění za nový token. Přístupový token se poskytuje v každé žádosti provedené v aplikaci a platnost požadavku se kontroluje před jednotlivými žádostmi.
Poznámka:
I když není možné nastavit OAuth pro aplikace mimo galerii, můžete ručně vygenerovat přístupový token z autorizačního serveru a zadat ho jako tajný token do aplikace mimo galerii. To vám umožní ověřit kompatibilitu serveru SCIM se službou Zřizování Microsoft Entra před onboardingem do galerie aplikací, která podporuje udělení kódu OAuth.
Dlouhodobé nosné tokeny OAuth: Pokud vaše aplikace nepodporuje tok udělení autorizačního kódu OAuth, vygenerujte místo toho dlouhodobý nosný token OAuth, který může správce použít k nastavení integrace zřizování. Token by měl být časově neomezený nebo jinak se úloha zřizování umístí do karantény, když vyprší platnost tokenu.
Další metody ověřování a autorizace dejte nám vědět na UserVoice.
Seznam kontroly uvedení galerie na trh
Pokud chcete zvýšit povědomí a poptávku po naší společné integraci, doporučujeme aktualizovat stávající dokumentaci a rozšířit integraci do marketingových kanálů. Doporučujeme, abyste dokončili následující kontrolní seznam pro podporu spuštění:
- Zajistěte, aby týmy prodeje a zákaznické podpory věděli, připravili a mohli mluvit s možnostmi integrace. Popište své týmy, poskytněte jim nejčastější dotazy a zahrňte integraci do prodejních materiálů.
- Vytvořte blogový příspěvek nebo tiskové zprávy, které popisují společnou integraci, výhody a způsob zahájení práce. Příklad: Imprivata a Microsoft Entra Press Release
- Využijte svoje sociální média, jako je Twitter, Facebook nebo LinkedIn, k propagaci integrace pro vaše zákazníky. Nezapomeňte uvést @Microsoft ID Entra, abychom mohli váš příspěvek retweetovat. Příklad: Imprivata Twitter Post
- Vytvořte nebo aktualizujte marketingové stránky nebo web (například stránku integrace, stránku partnera, stránku s cenami atd.), aby zahrnovaly dostupnost společné integrace. Příklad: Stránka integrace pingboardu, stránka integrace Smartsheet, Monday.com cenová stránka
- Vytvoření článku centra nápovědy nebo technické dokumentace o tom, jak můžou zákazníci začít. Příklad: Integrace envoy + Microsoft Entra.
- Upozorněte zákazníky na novou integraci prostřednictvím komunikace se zákazníky (měsíční bulletiny, e-mailové kampaně, poznámky k verzi produktu).