Kurz: Vývoj a plánování zřizování pro koncový bod SCIM v Azure Active Directory

Jako vývojář aplikací můžete pomocí rozhraní API pro správu uživatelů SCIM (System for Cross-Domain Identity Management) povolit automatické zřizování uživatelů a skupin mezi vaší aplikací a službou Azure Active Directory (Azure AD). Tento článek popisuje, jak vytvořit koncový bod SCIM a integrovat ho se službou zřizování Azure AD. Specifikace SCIM poskytuje běžné uživatelské schéma pro zřizování. Při použití s federačními standardy, jako jsou SAML nebo OpenID Connect, poskytuje SCIM správcům komplexní řešení pro správu přístupu založené na standardech.

Zřizování z Azure AD do aplikace pomocí SCIM

SCIM 2.0 je standardizovaná definice dvou koncových bodů: koncového /Users 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ých schémat pro běžné atributy, jako je název skupiny, uživatelské jméno, jméno, příjmení a e-mail.

Aplikace, které nabízejí rozhraní SCIM 2.0 REST API, můžou snížit nebo eliminovat potíže 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 koncového /Users bodu a vytvořit tak novou položku uživatele. Místo toho, aby pro stejné základní akce potřebovaly trochu jiné rozhraní API, můžou aplikace, které vyhovují standardu SCIM, okamžitě využít výhod již existujících klientů, nástrojů a kódu.

Standardní schéma objektů uživatele 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í mezi sebou. Vývojáři aplikací, kteří sestavují koncový bod SCIM, se můžou integrovat s libovolným klientem kompatibilním s SCIM, aniž by museli provádět vlastní práci.

K automatizaci zřizování pro aplikaci je potřeba vytvořit a integrovat koncový bod SCIM, ke kterému přistupuje služba Azure AD Provisioning. Pomocí následujícího postupu můžete v aplikaci začít zřizovat uživatele a skupiny.

  1. Návrh schématu uživatele a skupiny – Identifikujte objekty a atributy aplikace a určete, jak se mapují na schéma uživatele a skupiny podporované implementací Azure AD SCIM.

  2. Seznamte se s implementací Azure AD SCIM – Seznamte se s implementací služby Azure AD Provisioning Pro modelování zpracování požadavků protokolu SCIM a odpovědí na ně.

  3. Sestavení koncového bodu SCIM – Koncový bod musí být kompatibilní se SCIM 2.0, aby se integrovali se službou zřizování Azure AD. K sestavení koncového bodu můžete použít Microsoft knihovny a ukázky kódu služby Common Language Infrastructure (CLI). Tyto vzorky jsou 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 Azure AD Provisioning. Pokud vaše organizace používá aplikaci třetí strany k implementaci profilu SCIM 2.0, který Azure AD podporuje, můžete rychle automatizovat zřizování i zrušení zřízení uživatelů a skupin.

  5. [Volitelné] Publikování aplikace do galerie Azure AD aplikací – Umožňuje zákazníkům usnadnit zjišťování vaší aplikace a snadnou konfiguraci zřizování.

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

Návrh schématu uživatelů a skupin

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 Azure AD hlavní název uživatele)
  • meta, metadata jen pro čtení udržovaná poskytovatelem služeb

Kromě základního uživatelského schématu definuje standard SCIM rozšíření podnikového uživatele s modelem pro rozšíření uživatelského schématu 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 shromažďování e-mailů uživatele a schéma podnikového uživatele ke shromáždění správce uživatele.

Při návrhu schématu postupujte takto:

  1. Uveďte atributy, které vaše aplikace vyžaduje, a potom je kategorizujte 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é k tomu, aby aplikace fungovala (například manager, značka).

  2. Zkontrolujte, jestli jsou atributy už definované ve schématu základního uživatele nebo schématu podnikového uživatele. Pokud ne, musíte definovat rozšíření uživatelského schématu, které pokrývá chybějící atributy. V následujícím příkladu najdete rozšíření pro uživatele, které umožňuje zřízení uživatele tag.

  3. Namapujte atributy SCIM na atributy uživatele v Azure AD. Pokud některý z atributů, které jste definovali v koncovém bodu SCIM, nemá jasný protějšek Azure AD schématu uživatele, požádejte správce tenanta o rozšíření schématu nebo použijte pro vlastnost atribut rozšíření, jak je znázorněno nížetags.

Následující tabulka uvádí příklad požadovaných atributů:

Požadovaný atribut aplikace Mapovaný atribut SCIM Mapovaný atribut Azure AD
Loginname userName userPrincipalName (Hlavní název uživatele)
firstName name.givenName givenName
lastName name.familyName Příjmení
pracovní pošta email[type eq "work"].value Poštovní
manager manager manager
značka urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User:tag atribut extensionAttribute1
status active isSoftDeleted (vypočítaná hodnota není uložená u uživatele)

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

Poznámka

Kromě atributů požadovaných pro aplikaci zahrnuje reprezentace JSON také požadované idatributy , externalIda meta .

Pomáhá kategorizovat mezi /User a /Group mapovat všechny výchozí atributy uživatele v Azure AD na SCIM RFC. Podívejte se, jak se vlastní atributy mapují mezi Azure AD a koncovým bodem SCIM.

Následující tabulka uvádí příklad atributů uživatele:

Uživatel služby Azure AD urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
IsSoftDeleted active
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 title
pošta emails[type eq "work"].value
mailNickname externalId
manager urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager
mobil phoneNumbers[type eq "mobile"].value
postalCode addresses[type eq "work"].POSTALCode
proxy adresy email[type eq "other"]. Hodnotu
physical-Delivery-OfficeName addresses[type eq "other"]. Formá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 Azure AD urn:ietf:params:scim:schemas:core:2.0:Group
displayName displayName
členy členy
objectId externalId

Poznámka

Nemusíte podporovat uživatele i skupiny nebo všechny zde uvedené atributy. Je to jenom odkaz na to, jak se atributy v Azure AD často mapují na vlastnosti v protokolu SCIM.

V dokumentu SCIM RFC je definováno několik koncových bodů. Můžete začít s koncovým bodem a pak rozbalit odsud /User . V následující tabulce jsou uvedeny některé koncové body SCIM:

Koncový bod Popis
/Uživatele Provádění operací CRUD s objektem uživatele.
/Skupiny Provádění operací CRUD u objektu skupiny.
/Schémata Sada atributů podporovaných jednotlivými klienty a poskytovateli 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 zjišťování podporovaných atributů.
/Hromadné Hromadné operace umožňují provádět operace s velkou kolekcí objektů prostředků v rámci jedné operace (například aktualizovat členství pro velkou skupinu).
/ServiceProviderConfig Poskytuje podrobnosti o podporovaných funkcích standardu SCIM, například o podporovaných prostředcích a metodě ověřování.
/ResourceTypes Určuje metadata o jednotlivých prostředcích.

Poznámka

/Schemas Použijte koncový bod k podpoře vlastních atributů nebo pokud se vaše schéma často mění, protože umožňuje klientovi automaticky načíst nejaktuálnější schéma. /Bulk Použijte koncový bod pro podporu skupin.

Vysvětlení Azure AD implementace SCIM

Pro podporu rozhraní API pro správu uživatelů SCIM 2.0 tato část popisuje, jak je implementována služba Azure AD Provisioning Service, a ukazuje, jak modelovat zpracování a odpovědi na požadavky protokolu SCIM.

Důležité

Chování implementace Azure AD SCIM bylo naposledy aktualizováno 18. prosince 2018. Informace o tom, co se změnilo, najdete v tématu Dodržování předpisů protokolu SCIM 2.0 služby Azure AD User Provisioning.

V rámci specifikace 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í pomocí svých id uživatelů a dotazují se jejich username a externalIda skupiny se dotazují pomocí displayName.
Filtr excludedAttributes=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 jeho obnovení active=true Objekt uživatele by měl být vrácen v požadavku bez ohledu na to, jestli je uživatel aktivní nebo ne. Uživatel by se neměl vrátit jenom tehdy, když je z aplikace trvale odstraněný.
Podpora koncového bodu /Schemas Oddíl 7 Koncový bod zjišťování schématu se použije ke zjištění dalších atributů.
Přijměte jeden nosný token pro ověřování a autorizaci Azure AD do vaší aplikace.

Při implementaci koncového bodu SCIM použijte obecné pokyny k zajištění kompatibility s Azure AD:

Obecné:

  • id je povinná vlastnost pro všechny prostředky. Každá odpověď, která vrátí prostředek, by měla zajistit, že každý prostředek má tuto vlastnost, s výjimkou ListResponse s nulovými prvky.
  • 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 akcemi. Transformace dat by neměly probíhat mezi daty odesílaných Azure AD a daty uloženými v aplikaci SCIM. (například. Telefonní číslo odeslané jako 55555555555 by nemělo být uloženo nebo 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 oddílu 3.5.2, není nutné rozlišovat malá a velká písmena. Azure AD vygeneruje hodnoty opPřidat, Nahradit a Odebrat.
  • Microsoft Azure AD vyžaduje 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 toku Test připojení v Azure Portal.
  • Podpora HTTPS na koncovém bodu SCIM
  • Vlastní komplexní a vícehodnotové atributy jsou podporované, ale Azure AD v těchto případech nemá mnoho složitých datových struktur, ze kterých by bylo potřeba data načítat. Jednoduché spárované komplexní atributy typu název/hodnota se dají snadno mapovat na, ale tok dat na složité atributy se třemi nebo více dílčími atributy v tuto chvíli není dobře podporovaný.
  • Subattribute "type" hodnoty komplexních atributů s více hodnotami musí být jedinečné. Například nemůžou existovat dvě různé e-mailové adresy s podtypem "pracovní".
  • Hlavička pro všechny odpovědi by měla být content-Type: application/scim+json.

Načítání prostředků:

/Uživatelé:

  • Atribut entitlements není podporovaný.
  • Všechny atributy, které jsou zvažovány z důvodu jedinečnosti uživatele, musí být použitelné jako součást filtrovaného dotazu. (pokud se například vyhodnocuje jedinečnost uživatele pro userName i email[type eq "work"], musí get na /Users s filtrem povolit jak dotazy userName eq "user@contoso.com", tak pro email[type eq "work"].value eq "user@contoso.com" .

/Skupiny:

  • Skupiny jsou volitelné, ale podporují se jenom v případě, že implementace SCIM podporuje požadavky PATCH .
  • Skupiny musí mít jedinečnost hodnoty displayName, aby se shodovaly s Azure AD a aplikací SCIM. Jedinečnost není požadavkem protokolu SCIM, ale je požadavkem pro integraci koncového bodu SCIM s Azure AD.

/Schemas (zjišťování schémat):

  • Ukázkový požadavek/odpověď
  • Zjišťování schémat se v současné době nepodporuje ve vlastní aplikaci SCIM mimo galerii, ale používá se v některých aplikacích galerie. V budoucnu se zjišťování schématu použije jako jediná metoda pro přidání dalších atributů do schématu existující aplikace SCIM galerie.
  • Pokud hodnota neexistuje, neodesílejte hodnoty null.
  • Hodnoty vlastností by měly mít velká písmena (například readWrite).
  • Musí vrátit odpověď seznamu.
  • Požadavek /schemas provede služba Azure AD Provisioning Pokaždé, když někdo uloží konfiguraci zřizování v Azure Portal nebo pokaždé, když uživatel přejde na stránku pro úpravy zřizování v Azure Portal. Další zjištěné atributy se zákazníkům zobrazí v mapování atributů v seznamu cílových atributů. Zjišťování schématu vede pouze k přidání více cílových atributů. Nebude mít za následek odebrání atributů.

Zřizování a rušení zřizování uživatelů

Následující diagram znázorňuje zprávy, které Azure AD 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í a rušení zřízení skupin je volitelné. Při implementaci a povolení znázorňuje následující obrázek zprávy, které Azure AD 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 od zpráv o uživatelích liší dvěma způsoby:

  • Požadavky na načtení skupin určují, že atribut members má být vyloučen z jakéhokoli prostředku poskytnutého v reakci na požadavek.
  • Požadavky na určení, zda má odkaz atribut určitou hodnotu, jsou požadavky týkající se atributu members.

Následující diagram znázorňuje posloupnost 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 ukázkové požadavky SCIM generované službou zřizování Azure Active Directory (Azure AD) a příklady očekávaných odpovědí. Nejlepších výsledků dosáhnete tím, že aplikaci naprogramujete tak, aby tyto požadavky zpracovávala v tomto formátu, a vygenerujte očekávané odpovědi.

Důležité

Informace o tom, jak a kdy služba zřizování uživatelů Azure AD generuje níže popsané operace, najdete v části Cykly zřizování: Počáteční a přírůstkové v tématu Jak funguje zřizování.

Operace uživatelů

Operace skupiny

Zjišťování schématu

Operace uživatelů

  • Uživatelé se můžou dotazovat podle userName atributů nebo emails[type eq "work"] .

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

Http/1.1 201 Vytvořeno

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "48af03ac28ad4fb88478",
    "externalId": "0a21f0f2-8d2a-4f8e-bf98-7363c4aed4ef",
    "meta": {
        "resourceType": "User",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
    },
    "userName": "Test_User_ab6490ee-1e48-479e-a20b-2d77186b5dd1",
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName",
    },
    "active": true,
    "emails": [{
        "value": "Test_User_fd0ea19b-0777-472c-9f96-4f70d2226f2e@testuser.com",
        "type": "work",
        "primary": true
    }]
}

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

GET /Users/5171a35d82074e068ce2

Odpověď (Uživatel nebyl nalezen. Podrobnosti nejsou povinné, pouze stav.)
{
    "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_dfeef4c5-5681-4387-b016-bdf221e82081"

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

Získání uživatele podle dotazu – nulové výsledky

Žádost

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]

Žá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"
            }
    ]
}
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_fbb9dda4-fcde-4f98-a68b-6c5599e17c27",
    "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"
    }]
}
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_49dc1090-aada-4657-8434-4995c25a00f7@testuser.com",
        "type": "work",
        "primary": true
    }]
}

Zakázání 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"
    ]
}
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"
    }
}

Odstranění uživatele

Žádost

DELETE /Users/5171a35d82074e068ce2 HTTP/1.1

Odpověď

HTTP/1.1 204 Žádný obsah

Operace skupiny

  • Skupiny musí být vždy vytvořeny s prázdným seznamem členů.
  • Pomocí atributu lze dotazovat skupiny displayName .
  • Aktualizace na požadavek PATCH skupiny by měla v odpovědi přinést http 204 Žádný obsah . Vrácení textu se seznamem všech členů není vhodné.
  • Není nutné podporovat vrácení všech členů skupiny.

Vytvoření skupiny

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

Http/1.1 201 Vytvořeno

{
    "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ískání skupiny

Žádost

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

Žádost

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
}

Aktualizovat skupinu [Atributy, které nejsou členy]

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

HTTP/1.1 204 Žádný obsah

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

HTTP/1.1 204 Žádný obsah

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

HTTP/1.1 204 Žádný obsah

Odstranění skupiny

Žádost

DELETE /Groups/cdb1ce18f65944079d37 HTTP/1.1

Odpověď

HTTP/1.1 204 Žádný obsah

Zjišťování schématu

Zjišťování schématu

Žádost

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 TLS jsou TLS 1.2 a TLS 1.3. Nejsou povoleny žádné jiné verze protokolu TLS. Není povolena žádná verze PROTOKOLU SSL.

  • Klíče RSA musí mít alespoň 2 048 bitů.
  • Klíče ECC musí mít minimálně 256 bitů vygenerované pomocí schválené eliptické křivky.

Délky klíčů

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 níže. Pokud máte pouze certifikát RSA, nemají nainstalované šifrovací sady ECDSA žádný vliv.

Minimální pruh šifrovacích sad protokolu 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í Azure AD v současné době funguje v rámci rozsahů IP adres pro AzureActiveDirectory, jak je uvedeno tady. Můžete přidat rozsahy IP adres uvedené pod značkou AzureActiveDirectory a povolit tak provoz ze služby zřizování Azure AD do vaší aplikace. Pro vypočítané adresy budete muset pečlivě zkontrolovat seznam rozsahů IP adres. Adresa jako "40.126.25.32" může být v seznamu rozsahů IP adres reprezentována jako "40.126.0.0/18". Seznam rozsahů IP adres můžete také načíst prostřednictvím kódu programu pomocí následujícího rozhraní API.

Azure AD také podporuje řešení založené na agentech, které poskytuje připojení k aplikacím v privátních sítích (místní sítě, hostované v Azure, hostované v AWS atd.). Zákazníci můžou nasadit zjednodušeného agenta, který poskytuje připojení k Azure AD bez otevření příchozích portů, na server v jejich privátní síti. Další informace najdete tady.

Sestavení koncového bodu SCIM

Teď, když jste navrhli schéma a pochopili Azure AD implementaci SCIM, můžete začít s vývojem koncového bodu SCIM. Místo toho, abyste začali úplně od začátku a zcela sami vytvářeli implementaci, můžete se spolehnout na mnoho open source 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ý zřizovacím týmem Azure AD je jedním z takových prostředků, které mohou nastartovat váš vývoj. Jakmile vytvoříte koncový bod SCIM, budete ho chtít otestovat. Můžete použít kolekci testů Postman poskytovaných jako součást referenčního kódu nebo projít ukázkové požadavky a odpovědi uvedené výše.

Poznámka

Referenční kód je určený k tomu, aby vám pomohl začít vytvářet koncový bod SCIM a poskytuje se tak, jak je. Příspěvky od komunity jsou vítány, aby vám pomohly vytvářet a udržovat kód.

Řešení se skládá ze dvou projektů, Microsoft. SCIM a Microsoft. SCIM. WebHostSample.

Microsoft. Projekt SCIM je knihovna, která definuje komponenty webové služby, které odpovídají specifikaci SCIM. Deklaruje Microsoft rozhraní. SCIM. IProvider, požadavky se překládají do volání metod zprostředkovatele, které by byly naprogramovány tak, aby fungovaly v úložišti identit.

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

Microsoft. SCIM. Projekt WebHostSample je webová aplikace ASP.NET Core založená na prázdné šabloně. Umožňuje nasazení ukázkového kódu jako samostatného hostovaného v kontejnerech nebo v rámci Internetové informační služby. Implementuje také Microsoft. SCIM. Rozhraní IProvider 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 má jeden z následujících názvů:

  • CNNIC
  • Comodo
  • CyberTrust
  • DigiCert
  • Geotrust
  • GlobalSign
  • Jdi tatínek
  • Verisign
  • WoSign
  • Kořenová certifikační autorita pro DST X3

Sada .NET Core SDK obsahuje vývojový certifikát HTTPS, který se dá použít během vývoje. Certifikát se nainstaluje jako součást prostředí při prvním spuštění. V závislosti na tom, jak spustíte ASP.NET Core webovou aplikaci, bude naslouchat 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í protokolu HTTPS v ASP.NET Core

Zpracování ověřování koncových bodů

Požadavky ze služby Azure AD Provisioning zahrnují nosný token OAuth 2.0. Nosný token je token zabezpečení vydaný autorizačním serverem, například Azure AD, a který je vaší aplikací důvěryhodný. Službu Azure AD provision můžete nakonfigurovat 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ž Azure AD, zkopírujte požadovaný nosný token OAuth do volitelného pole Token tajného kódu. Ve vývojovém prostředí můžete použít testovací token z koncového /scim/token bodu. Testovací tokeny by se neměly používat v produkčních prostředích.

  • Azure AD nosný token. Pokud je pole Token tajného kódu prázdné, Azure AD obsahuje nosný token OAuth vydaný z Azure AD s jednotlivými požadavky. Aplikace, které používají Azure AD jako zprostředkovatele identity, můžou tento token vydaný Azure AD ověřit.

    • Aplikace, která přijímá požadavky, by měla ověřit, že vystavitel tokenu je Azure AD pro očekávaného tenanta Azure AD.
    • V tokenu je vystavitel identifikován deklarací iss identity. Například, "iss":"https://sts.windows.net/12345678-0000-0000-0000-000000000000/". V tomto příkladu základní adresa hodnoty https://sts.windows.net deklarace identity identifikuje Azure AD jako vystavitele, zatímco relativní segment adres, 12345678-0000-0000-0000-000000000000000, je jedinečný identifikátor Azure AD tenanta, pro kterého byl token vystaven.
    • Cílová skupina tokenu je ID aplikace 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ý službou zřizování Azure AD by se měl používat pouze k testování. Neměl by se používat v produkčních prostředích.

V ukázkovém kódu se požadavky ověřují pomocí Microsoft. Balíček AspNetCore.Authentication.JwtBearer. Následující kód vynucuje ověření požadavků na libovolný koncový bod služby pomocí nosného tokenu vydaného Azure AD 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/12345678-0000-0000-0000-000000000000/";
                options.Audience = "8adf8e6e-67b2-4cf2-a259-e3dc5476c621";
                ...
            });
    }
    ...
}

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

Nosný token se také vyžaduje pro použití zadaných testů Postman a provádění místního ladění pomocí localhost. Ukázkový kód používá ASP.NET Core prostředí 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 ověření požadavků na libovolný koncový bod služby 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 požadavek GET kontroleru tokenů, abyste získali platný nosný token. Metoda GenerateJSONWebToken je zodpovědná 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řízení uživatelů

Příklad 1: Dotazování služby na odpovídajícího uživatele

Azure AD dotazuje službu na uživatele s hodnotou atributu externalId odpovídající hodnotě atributu mailNickname uživatele v Azure AD. Dotaz je vyjádřen jako požadavek HTTP (Hypertext Transfer Protocol), jako je tento příklad, kde jyoung je ukázka mailNickname uživatele v Azure AD.

Poznámka

Toto je pouze příklad. Ne všichni uživatelé budou mít atribut mailNickname a hodnota, kterou uživatel má, nemusí být v adresáři jedinečná. Atribut použitý pro porovnávání (což je externalIdv tomto případě ) je také konfigurovatelný v mapování atributů Azure AD.

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

V ukázkovém kódu se požadavek přeloží na 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 pro uživatele s danou hodnotou atributu externalId hodnoty argumentů předané metodě QueryAsync:

  • 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 koncového bodu SCIM pro uživatele s hodnotou atributuexternalId, která odpovídá hodnotě atributu mailNickname uživatele, nevrátí žádné uživatele, pak Azure AD žádost, aby služba zřídila uživatele odpovídajícího uživateli v Azure AD. 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ží na volání metody CreateAsync 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 is defined in 
// Microsoft.SCIM.Schemas.  

Task<Resource> CreateAsync(IRequest<Resource> request);

V požadavku na zřizování uživatele je hodnotou argumentu prostředku instance Microsoft. SCIM. Třída Core2EnterpriseUser definovaná v Microsoft. SCIM. Knihovna schémat. Pokud je požadavek na zřízení uživatele úspěšný, pak se očekává, že implementace metody vrátí instanci Microsoft. SCIM. Třída Core2EnterpriseUser s hodnotou vlastnosti Identifier nastavenou na jedinečný identifikátor nově zřízeného uživatele.

Příklad 3: Dotazování aktuálního stavu uživatele

Pokud chcete aktualizovat uživatele, o jehož existenci je známo, že existuje v úložišti identit, které používá SCIM, Azure AD pokračuje tak, že ze služby požádá o aktuální stav tohoto uživatele pomocí požadavku, například:

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

V ukázkovém kódu se požadavek přeloží na 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 na načtení aktuálního stavu uživatele jsou hodnoty vlastností objektu zadané jako hodnota argumentu parameters následující:

  • Identifikátor: "54D382A4-2050-4C03-94D1-E769F1D15682"
  • SchemaIdentifier: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Příklad 4: Dotaz na hodnotu atributu odkazu, který se má aktualizovat

Pokud se má aktualizovat atribut odkazu, pak Azure AD dotazuje službu, aby určila, jestli aktuální hodnota atributu odkazu v úložišti identit, před kterým je služba, již odpovídá hodnotě tohoto atributu v Azure AD. Pro uživatele je jediným atributem, jehož aktuální hodnota je dotazována tímto způsobem, 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ží na volání metody QueryAsync zprostředkovatele služby. Hodnota vlastností objektu zadaných jako hodnota argumentu parameters je 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: "54D382A4-2050-4C03-94D1-E769F1D15682"
  • Parametry. AlternateFilters.ElementAt(y). AttributePath: "manager"
  • Parametry. AlternateFilters.ElementAt(y). ComparisonOperator: ComparisonOperator.Equals
  • Parametry. AlternateFilter.ElementAt(y). ComparisonValue: "2819c223-7f76-453a-919d-413861904646"
  • 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 může být 1 hodnota x a hodnota y může být 0. Závisí na pořadí výrazů parametru dotazu filtru.

Příklad 5: Žádost o aktualizaci uživatele z Azure AD na koncový bod SCIM

Tady je příklad požadavku z Azure AD na koncový bod SCIM o aktualizaci uživatele:

PATCH ~/scim/Users/54D382A4-2050-4C03-94D1-E769F1D15682 HTTP/1.1
Authorization: Bearer ...
Content-type: application/scim+json
{
    "schemas": 
    [
      "urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations":
    [
      {
        "op":"Add",
        "path":"manager",
        "value":
          [
            {
              "$ref":"http://.../scim/Users/2819c223-7f76-453a-919d-413861904646",
              "value":"2819c223-7f76-453a-919d-413861904646"}]}]}

V ukázkovém kódu se požadavek přeloží na volání metody UpdateAsync zprostředkovatele 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 na aktualizaci uživatele má objekt zadaný jako hodnotu argumentu patch tyto hodnoty vlastností:

Argument Hodnota
ResourceIdentifier.Identifier "54D382A4-2050-4C03-94D1-E769F1D15682"
ResourceIdentifier.SchemaIdentifier urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
(PatchRequest as PatchRequest2).Operations.Count 1
(PatchRequest as PatchRequest2).Operations.ElementAt(0).OperationName OperationName.Add
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Path.AttributePath Manažer
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.Count 1
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.ElementAt(0).Reference http://.../scim/Users/2819c223-7f76-453a-919d-413861904646
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.ElementAt(0).Value 2819c223-7f76-453a-919d-413861904646

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, Azure AD odešle požadavek, například:

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

V ukázkovém kódu se požadavek přeloží na volání metody DeleteAsync 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.IResourceIdentifier, 
// is defined in Microsoft.SCIM.Protocol. 

Task DeleteAsync(IRequest<IResourceIdentifier> request);

Objekt zadaný jako hodnota argumentu resourceIdentifier má v příkladu požadavku na zrušení zřízení uživatele tyto hodnoty vlastností:

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

Integrace koncového bodu SCIM se službou Azure AD Provisioning

Azure AD je možné nakonfigurovat tak, aby automaticky zřizovat přiřazené uživatele a skupiny pro aplikace, které implementují konkrétní profil protokolu SCIM 2.0. Specifika profilu jsou popsána v tématu Vysvětlení implementace Azure AD SCIM.

Informace o kompatibilitě s těmito požadavky vám poskytne poskytovatel aplikace nebo jeho dokumentace.

Důležité

Implementace Azure AD SCIM je postavená na službě zřizování uživatelů Azure AD, která je navržená tak, aby neustále udržovala uživatele v synchronizaci mezi Azure AD a cílovou aplikací a implementuje velmi specifickou sadu standardních operací. Toto chování je důležité pochopit, abyste pochopili chování služby Azure AD Provisioning Service. Další informace najdete v části Cykly zřizování: Počáteční a přírůstkové v tématu Jak funguje zřizování.

Začínáme

Aplikace, které podporují profil SCIM popsaný v tomto článku, je možné připojit k Azure AD pomocí funkce aplikace mimo galerii aplikací Azure AD. Po připojení Azure AD každých 40 minut spustí proces synchronizace, kdy se dotáže koncového bodu SCIM aplikace na přiřazené uživatele a skupiny a vytvoří je nebo upraví podle podrobností přiřazení.

Připojení aplikace, která podporuje SCIM:

  1. Přihlaste se k portálu Azure AD. Bezplatnou zkušební verzi pro Azure AD s licencemi P2 získáte tak, že se zaregistrujete do vývojářského programu.

  2. V levém podokně vyberte Podnikové aplikace . Zobrazí se seznam všech nakonfigurovaných aplikací, včetně aplikací přidaných z galerie.

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

  4. Zadejte název aplikace, zvolte možnost "integrovat jakoukoli jinou aplikaci, kterou nenajdete v galerii" a vyberte Přidat a vytvořte objekt aplikace. Nová aplikace se přidá do seznamu podnikových aplikací a otevře se obrazovka správy aplikací.

    Následující snímek obrazovky ukazuje galerii aplikací Azure AD:

    Snímek obrazovky znázorňující galerii aplikací Azure AD

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

  6. V nabídce Režim zřizování vyberte Automaticky.

    Následující snímek obrazovky ukazuje konfiguraci nastavení zřizování v Azure Portal:

    Snímek obrazovky se stránkou zřizování aplikací v Azure Portal

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

  8. Pokud koncový bod SCIM vyžaduje nosný token OAuth od jiného vystavitele než Azure AD, zkopírujte požadovaný nosný token OAuth do volitelného pole Token tajného kódu. Pokud je toto pole prázdné, Azure AD obsahuje nosný token OAuth vystavený z Azure AD s každou žádostí. Aplikace, které používají Azure AD jako zprostředkovatele identity, můžou tento token vydaný Azure AD ověřit.

    Poznámka

    Nedoporučuje se nechat toto pole prázdné a spoléhat se na token vygenerovaný Azure AD. Tato možnost je k dispozici primárně pro účely testování.

  9. Pokud chcete, aby se Azure AD pokusili připojit ke koncovému bodu SCIM, vyberte Test připojení. Pokud pokus selže, zobrazí se informace o chybě.

    Poznámka

    Test připojení se dotazuje koncového bodu SCIM na uživatele, který neexistuje, a použije náhodný identifikátor GUID jako odpovídající vlastnost vybranou v konfiguraci Azure AD. Očekávaná správná odpověď je HTTP 200 OK s prázdnou zprávou SCIM ListResponse.

  10. Pokud pokusy o připojení k aplikaci proběhnou úspěšně, vyberte Uložit a uložte přihlašovací údaje správce.

  11. V části Mapování jsou dvě vybratelné sady mapování atributů: jedna pro objekty uživatelů a jedna pro objekty skupiny. Vyberte každou z nich a zkontrolujte atributy, které se synchronizují z Azure AD do vaší aplikace. Atributy vybrané jako Odpovídající vlastnosti se použijí k porovnávání uživatelů a skupin ve vaší aplikaci pro operace aktualizace. Vyberte Uložit a potvrďte všechny změny.

    Poznámka

    Synchronizaci objektů skupiny můžete volitelně zakázat zakázáním mapování skupin.

  12. 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 Synchronizovat jenom přiřazené uživatele a skupiny (doporučeno).

  13. Po dokončení konfigurace nastavte Stav zřizování na Zapnuto.

  14. Výběrem možnosti Uložit spusťte službu zřizování Azure AD.

  15. Pokud synchronizujete pouze přiřazené uživatele a skupiny (doporučeno), vyberte kartu Uživatelé a skupiny . Pak přiřaďte uživatele nebo skupiny, které chcete synchronizovat.

Po zahájení počátečního cyklu můžete v levém panelu vybrat Protokoly zřizování a 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í Azure AD najdete v tématu Generování sestav automatického 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, kterou bude používat více tenantů, můžete ji zpřístupnit v galerii aplikací Azure AD. Pro organizace je snadné zjistit aplikaci a nakonfigurovat zřizování. Publikování aplikace v galerii Azure AD a zpřístupnění zřizování ostatním uživatelům je snadné. Postup najdete tady. Microsoft s vámi bude spolupracovat na integraci vaší aplikace do naší galerie, testování koncového bodu a vydání dokumentace k onboardingu, kterou můžou zákazníci používat.

Pomocí kontrolního seznamu můžete rychle nasadit aplikaci a zajistit tak bezproblémové nasazení pro zákazníky. Informace se od vás shromáždí při onboardingu do galerie.

  • Podpora koncového bodu uživatele a skupiny SCIM 2.0 (vyžaduje se pouze jeden, ale doporučuje se obojí)
  • Podpora alespoň 25 požadavků za sekundu na tenanta, aby se zajistilo, že se uživatelé a skupiny zřídí a zruší jejich zřízení bez zpoždění (povinné)
  • Navázání kontaktů na technické pracovníky a podporu, které zákazníkům po onboardingu galerie povedou (povinné)
  • 3 Testovací přihlašovací údaje pro vaši aplikaci bez vypršení platnosti (povinné)
  • Podpora udělení autorizačního kódu OAuth nebo dlouhodobého tokenu, jak je popsáno níže (povinné)
  • Vytvoření kontaktního technického a podpůrného místa pro podporu zákazníků po onboardingu galerie (povinné)
  • Podpora zjišťování schémat (povinné)
  • Podpora aktualizace členství ve více skupinách pomocí jedné opravy PATCH
  • Veřejná dokumentace koncového bodu SCIM

Specifikace SCIM nedefinuje schéma ověřování a autorizace specifické pro SCIM a spoléhá na použití stávajících oborových standardů.

Metoda autorizace Výhody Nevýhody Podpora
Uživatelské jméno a heslo (Azure AD nedoporučuje ani nepodporuje) Snadná implementace Nezabezpečené – na vaší pa$$word nezáleží Nepodporuje se pro nové aplikace z galerie nebo aplikace mimo galerii.
Dlouhodobý nosný token Dlouhodobé tokeny nevyžadují přítomnost uživatele. Správci je při nastavování zřizování snadno používají. Dlouhodobé tokeny může být obtížné sdílet se správcem bez použití nezabezpečených metod, jako je e-mail. Podporuje se pro aplikace z galerie i mimo galerii.
Udělení autorizačního kódu OAuth Přístupové tokeny jsou mnohem kratší než hesla a mají automatizovaný mechanismus aktualizace, který nemají dlouhodobé nosné tokeny. Při počáteční autorizaci musí být přítomen skutečný uživatel, který přidá úroveň odpovědnosti. Vyžaduje přítomnost uživatele. Pokud uživatel organizaci opustí, token je neplatný a autorizace se bude muset dokončit znovu. Podporuje se pro aplikace z galerie, ale ne pro aplikace mimo galerii. Přístupový token ale můžete v uživatelském rozhraní poskytnout jako token tajného kódu pro účely krátkodobého testování. Kromě podpory konfigurovatelných ověřovacích adres URL a adres URL tokenů v aplikaci galerie je v backlogu podpora pro udělení kódu OAuth pro jiné než galerii.
Udělení přihlašovacích údajů klienta OAuth Přístupové tokeny jsou mnohem kratší než hesla a mají automatizovaný mechanismus aktualizace, který nemají dlouhodobé nosné tokeny. Udělení autorizačního kódu i udělení přihlašovacích údajů klienta vytváří 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 nové tokeny lze bez zásahu uživatele bez zásahu uživatele bezobslužně vyžádat. Podporuje se pro aplikace z galerie, ale ne pro aplikace mimo galerii. Přístupový token ale můžete v uživatelském rozhraní poskytnout jako token tajného kódu pro účely krátkodobého testování. Podpora udělení přihlašovacích údajů klienta OAuth pro jiné než galerie je v našem backlogu.

Poznámka

V uživatelském rozhraní vlastní aplikace konfigurace zřizování Azure AD se nedoporučuje nechat pole tokenu prázdné. Vygenerovaný token je primárně k dispozici pro účely testování.

Tok udělení kódu OAuth

Zřizovací služba podporuje udělení autorizačního kódu a po odeslání žádosti o publikování vaší aplikace v galerii s vámi náš tým bude spolupracovat na shromáždění následujících informací:

  • Autorizační adresa URL– adresa URL klienta pro získání autorizace od vlastníka prostředku prostřednictvím přesměrování uživatelského agenta. Uživatel je přesměrován na tuto adresu URL pro autorizaci přístupu.

  • Adresa URL výměny tokenů, adresa URL klienta pro výměnu autorizačního oprávnění pro přístupový token, obvykle s ověřováním klienta.

  • ID klienta, autorizační server vydá registrovanému klientovi 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í se používat samostatně 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

Autorizační adresu URL a adresu URL pro výměnu tokenů se v současné době nedají konfigurovat pro jednotlivé tenanty.

Poznámka

OAuth v1 se nepodporuje kvůli odhalení tajného klíče klienta. Podporuje se OAuth v2.

Osvědčené postupy (doporučené, ale nepožadované):

  • Podpora více adres URL pro přesměrování Správci můžou nakonfigurovat zřizování z portal.azure.com i aad.portal.azure.com. Podpora více adres URL přesměrování zajistí, že uživatelé budou moct autorizovat přístup z obou portálů.
  • Podpora více tajných kódů pro snadné obnovení bez výpadků

Nastavení toku udělení kódu OAuth

  1. Přihlaste se k Azure Portal, přejděte naZřizovánípodnikových>aplikací> a vyberte Autorizovat.

    1. Azure Portal přesměruje uživatele na autorizační adresu URL (přihlašovací stránka aplikace třetí strany).

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

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

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

  2. Když začíná cyklus 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ém požadavku na aplikaci a platnost žádosti se kontroluje před každým požadavkem.

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 token tajného kódu do aplikace mimo galerii. To vám umožní ověřit kompatibilitu serveru SCIM se službou Azure AD Provisioning Service před registrací do galerie aplikací, která podporuje udělení kódu OAuth.

Nosné tokeny OAuth s dlouhou životností: Pokud vaše aplikace nepodporuje tok udělení autorizačního kódu OAuth, místo toho vygenerujte 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ý, jinak bude úloha zřizování po vypršení platnosti tokenu umístěna do karantény .

Pokud chcete získat další metody ověřování a autorizace, dejte nám vědět na UserVoice.

Abychom pomohli zvýšit povědomí o naší společné integraci a zvýšit poptávku po naší společné integraci, doporučujeme aktualizovat stávající dokumentaci a rozšířit integraci ve vašich marketingových kanálech. Doporučujeme, abyste pro podporu spuštění dokončili následující kontrolní seznam:

  • Ujistěte se, že vaše prodejní týmy a týmy zákaznické podpory jsou o možnostech integrace připravené a dokážou s nimi mluvit. Popište své týmy, poskytněte jim nejčastější dotazy a zahrňte je do svých prodejních materiálů.
  • Vytvořte blogový příspěvek nebo tiskovou zprávu, která popisuje společnou integraci, výhody a způsob, jak začít. Příklad: Tisková zpráva Imprivata a Azure AD
  • Využijte své sociální sítě, jako je Twitter, Facebook nebo LinkedIn, a propagujte integraci u svých zákazníků. Nezapomeňte přidat @AzureAD , abychom mohli váš příspěvek retweetovat. Příklad: Imprivata Twitter Post
  • Vytvořte nebo aktualizujte marketingové stránky nebo web (např. stránku integrace, stránku partnera, stránku s cenami atd.) tak, aby zahrnovaly dostupnost společné integrace. Příklad: Stránka integrace Pingboardu, stránka integrace smartsheetuMonday.com stránka s cenami
  • Vytvořte článek centra nápovědy nebo technickou dokumentaci o tom, jak můžou zákazníci začít. Příklad: Envoy + integrace Microsoft Azure AD.
  • 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