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.
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.
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.
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ě.
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.
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.
[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í.
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žebuserName, 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:
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).
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.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íže
tags.
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é:
idje 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ýjimkouListResponses 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í PATCH
op, jak je definováno v oddílu 3.5.2, není nutné rozlišovat malá a velká písmena. Azure AD vygeneruje hodnotyopPř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ů:
- Odpověď na požadavek dotazu nebo filtru by vždy měla být .
ListResponse - Microsoft Azure AD používá pouze následující operátory:
eq,and - Atribut, na který lze dotazovat prostředky, by měl být nastaven jako odpovídající atribut aplikace v Azure Portal, viz Přizpůsobení mapování atributů zřizování uživatelů.
/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.
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:
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í.
- Vytvořit uživatele (odpověď na žádost / )
- Získat uživatele (odpověď na žádost / )
- Získání uživatele podle dotazu (odpověď na žádost / )
- Získání uživatele podle dotazu – nulové výsledky (odpověď na žádost / )
- Aktualizovat uživatele [vlastnosti s více hodnotami] (odpověď na žádost / )
- Aktualizovat uživatele [Vlastnosti s jednou hodnotou] (odpověď na žádost / )
- Zakázat uživatele (odpověď na žádost / )
- Odstranit uživatele (odpověď na žádost / )
- Vytvořit skupinu (odpověď na žádost / )
- Získání skupiny (odpověď na žádost / )
- Získání skupiny podle displayName (odpověď na žádost / )
- Aktualizovat skupinu [Atributy, které nejsou členy] (odpověď na žádost / )
- Aktualizovat skupinu [Přidat členy] (odpověď na žádost / )
- Aktualizovat skupinu [Odebrat členy] (odpověď na žádost / )
- Odstranit skupinu (odpověď na žádost / )
Operace uživatelů
- Uživatelé se můžou dotazovat podle
userNameatributů neboemails[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.
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/tokenbodu. 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í
issidentity. Například,"iss":"https://sts.windows.net/12345678-0000-0000-0000-000000000000/". V tomto příkladu základní adresa hodnotyhttps://sts.windows.netdeklarace 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
issdeklaraci 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:
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.
V levém podokně vyberte Podnikové aplikace . Zobrazí se seznam všech nakonfigurovaných aplikací, včetně aplikací přidaných z galerie.
Vyberte + Nová aplikace>+ Vytvořit vlastní aplikaci.
Zadejte název aplikace, zvolte možnost "integrovat jakoukoli jinou aplikaci, kterou 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:
Na obrazovce správy aplikací vyberte na levém panelu Zřizování .
V nabídce Režim zřizování vyberte Automaticky.
Následující snímek obrazovky ukazuje konfiguraci nastavení zřizování v Azure Portal:
Do pole Adresa URL tenanta zadejte adresu URL koncového bodu SCIM aplikace. Příklad:
https://api.contoso.com/scim/Pokud koncový bod SCIM vyžaduje nosný token OAuth od jiného vystavitele než 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í.
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.
Pokud pokusy o připojení k aplikaci proběhnou úspěšně, vyberte Uložit a uložte přihlašovací údaje správce.
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.
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).
Po dokončení konfigurace nastavte Stav zřizování na Zapnuto.
Výběrem možnosti Uložit spusťte službu zřizování Azure AD.
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á.
Publikování aplikace do galerie aplikací Azure AD
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.
Kontrolní seznam pro onboarding galerie
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
Autorizace pro zřizování konektorů v galerii aplikací
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
Přihlaste se k Azure Portal, přejděte naZřizovánípodnikových>aplikací> a vyberte Autorizovat.
Azure Portal přesměruje uživatele na autorizační adresu URL (přihlašovací stránka aplikace třetí strany).
Správa poskytuje přihlašovací údaje k aplikaci třetí strany.
Aplikace třetí strany přesměruje uživatele zpět na Azure Portal a poskytne kód pro udělení.
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.
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.
Kontrolní seznam pro uvedení na trh v galerii
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).