Sdílet prostřednictvím

Kurz: Vývoj a plánování zřizování pro koncový bod SCIM v Microsoft Entra ID

  • Článek

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.

Zřizování z Microsoft Entra ID pro aplikaci pomocí SCIM

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.

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

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

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

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

  5. [Volitelné] Publikujte aplikaci do galerie aplikací Microsoft Entra – Zákazníci snadno zjistí vaši aplikaci a snadno nakonfigurují zřizování.

Diagram znázorňující požadované kroky pro integraci koncového bodu SCIM s ID Microsoft Entra

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žeb
  • userName, 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:

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

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

  3. 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
firstName name.givenName givenName
lastName name.familyName příjmení
pracovní pošta email[type eq "work"].value Pošta
manažer manažer manažer
značka urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User:tag extensionAttribute1
stav aktivní 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é idatributy externalIda 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 aktivní
oddělení 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 titul
pošta email[type eq "work"].value
mailNickname externalId
manažer urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager
mobilní phoneNumbers[type eq "mobile"].value
PSČ 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
příjmení 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:

Zakončení Popis
/Uživatel 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, titlea emails, zatímco jiný poskytovatel služeb používá name, titlea 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ýjimkou ListResponse 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í PATCHop, 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 hodnoty op 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.

Diagram znázorňující posloupnost zrušení zřízení uživatele

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:

Diagram znázorňující posloupnost 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í.

Operace uživatelů

Operace skupiny

Zjišťování schématu

Operace uživatelů

  • Použití userName nebo emails[type eq "work"] atributy k dotazování uživatelů.

Vytvořit uživatele

Prosba

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": []
}
Odpověď

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ískat uživatele

Prosba

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

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

Prosba

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

Odpověď

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

Prosba

GET /Users?filter=userName eq "neexistující uživatel"

Odpověď

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]

Prosba

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"
            }
    ]
}
Odpověď

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]

Prosba

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"
    }]
}
Odpověď

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

Prosba

PATCH /Users/5171a35d82074e068ce2 HTTP/1.1

{
    "Operations": [
        {
            "op": "Replace",
            "path": "active",
            "value": false
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ]
}
Odpověď
{
    "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"
    }
}

Odstranit uživatele

Prosba

DELETE /Users/5171a35d82074e068ce2 HTTP/1.1

Odpověď

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

Prosba

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"
    }
}
Odpověď

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

Prosba

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

Odpověď

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

Prosba

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

Odpověď

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]

Prosba

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"
    }]
}
Odpověď

HTTP/1.1 204 Bez obsahu

Aktualizovat skupinu [Přidat členy]

Prosba

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"
        }]
    }]
}
Odpověď

HTTP/1.1 204 Bez obsahu

Aktualizovat skupinu [Odebrat členy]

Prosba

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"
        }]
    }]
}
Odpověď

HTTP/1.1 204 Bez obsahu

Odstranit skupinu

Prosba

DELETE /Groups/cdb1ce18f65944079d37 HTTP/1.1

Odpověď

HTTP/1.1 204 Bez obsahu

Zjišťování schématu

Zjišťování schématu

Prosba

GET /Schemas

Odpověď

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 AzureActiveDirectory , 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 tady.

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. Sestavte koncový bod SCIM a pak ho otestujte spuštěním ukázkových požadavků nebo odpovědí.

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.

Rozpis: Požadavek přeložený na volání metod poskytovatele

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 hodnoty https://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();
    ...
}

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ě ) externalIdje 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 1
(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 1
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.ElementAt(0).Reference http://.../scim/Users/00aa00aa-bb11-cc22-dd33-44ee44ee44ee
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.ElementAt(0).Value 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

Spropitné

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:

  1. Přihlaste se do Centra pro správu Microsoft Entra jako alespoň správce aplikací.

  2. Přejděte k podnikovým aplikacím> identit.>

  3. Zobrazí se seznam všech nakonfigurovaných aplikací, včetně aplikací přidaných z galerie.

  4. Vyberte + Nová aplikace> + Vytvořit vlastní aplikaci.

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

    Snímek obrazovky znázorňující galerii aplikací Microsoft Entra

  6. Na obrazovce správy aplikací vyberte na levém panelu zřizování .

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

    Snímek obrazovky se stránkou zřizování aplikací v Centru pro správu Microsoft Entra

  8. Do pole Adresa URL tenanta zadejte adresu URL koncového bodu SCIM aplikace. Příklad: https://api.contoso.com/scim/

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

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

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

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

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

  14. Po dokončení konfigurace nastavte stav zřizování na Zapnuto.

  15. Výběrem možnosti Uložit spusťte službu zřizování Microsoft Entra.

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

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.

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.

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 Profesionálové Nevýhody 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

  1. Přihlaste se do Centra pro správu Microsoft Entra jako alespoň správce aplikací.

  2. Přejděte na Zřizovací aplikaci Podnikové aplikace>>Identita>>a vyberte Autorizovat.

  3. Přihlaste se do Centra pro správu Microsoft Entra jako alespoň správce aplikací.

  4. Přejděte k podnikovým aplikacím> identit.>

  5. Vyberte aplikaci a přejděte na Zřizování.

  6. Vyberte Autorizovat.

    1. Uživatelé se přesměrují na autorizační adresu URL (přihlašovací stránka aplikace třetí strany).

    2. Správce poskytne přihlašovací údaje k aplikaci třetí strany.

    3. Aplikace třetí strany přesměruje uživatele zpět a poskytne kód udělení.

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

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

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 X, Facebook nebo LinkedIn, a propagujte integraci se svými zákazníky. Nezapomeňte uvést @Microsoft ID Entra, abychom mohli váš příspěvek retweetovat. Příklad: Imprivata X 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).

Další kroky

Vývoj ukázkového koncového boduSCIM Automate zřizování a rušení zřizování uživatelů pro aplikaceSaaS – Přizpůsobení mapování atributů pro zřizování výrazů zápisu uživatelůpro filtrymapování atributů pro seznam oznámenío zřizování účtů zřizování uživatelů– Seznam kurzů pro integraci aplikací SaaS