Руководство. Разработка и планирование подготовки конечной точки SCIM в идентификаторе Microsoft Entra
Разработчиком приложений можно использовать API управления пользователями (SCIM) системы управления междоменных удостоверений (SCIM), чтобы включить автоматическую подготовку пользователей и групп между приложением и идентификатором Microsoft Entra. В этой статье описывается, как создать конечную точку SCIM и интегрировать ее со службой подготовки Microsoft Entra. Спецификация SCIM предоставляет общую схему пользователя для подготовки. При использовании со стандартами федерации, такими как SAML или OpenID Connect, SCIM предоставляет администраторам комплексное решение для управления доступом на основе стандартов.
SCIM 2.0 — это стандартизированное определение двух конечных точек: /Users и /Groups. В нем используются конечные точки REST API для создания, обновления и удаления объектов. SCIM состоит из предопределенной схемы для распространенных атрибутов, таких как имя группы, имя пользователя, имя пользователя, фамилия и электронная почта.
Приложения, которые предоставляют REST API SCIM 2.0, могут сократить или устранить трудности при работе с API управления пользователями. Например, любой совместимый клиент SCIM знает, как выполнить команду HTTP POST объекта JSON в конечную точку /Users для создания новой записи пользователя. Вместо того, чтобы использовать несколько других API для одних и тех же основных действий, приложения, которые соответствуют стандарту SCIM, могут мгновенно воспользоваться преимуществами существующих клиентов, средств и кода.
Стандартная схема объектов пользователя и API-интерфейсы для управления, определенные в SCIM 2.0 (RFC 7642, 7643, 7644), упрощают интеграцию поставщиков удостоверений с приложениями. Разработчики приложений, которые создают конечную точку SCIM, могут интегрироваться с любым клиентом, совместимым с SCIM, без необходимости выполнять роботу по настройке.
Чтобы автоматизировать подготовку приложения, требуется создание и интеграция конечной точки SCIM, доступ к которым осуществляется службой подготовки Microsoft Entra. Воспользуйтесь приведенными ниже инструкциями, чтобы начать подготовку пользователей и групп в приложении.
Проектируйте схему пользователя и группы. Определите объекты и атрибуты приложения, чтобы определить, как они сопоставляются с схемой пользователя и группы, поддерживаемой реализацией Microsoft Entra SCIM.
Ознакомьтесь с реализацией Microsoft Entra SCIM. Узнайте, как служба подготовки Microsoft Entra реализована для моделирования обработки и ответа запросов протокола SCIM.
Создание конечной точки SCIM — конечная точка должна быть совместима с SCIM 2.0 для интеграции со службой подготовки Microsoft Entra. Дополнительно для создания конечной точки можно использовать библиотеки Microsoft Common Language Infrastructure (CLI) и примеры кода. Эти примеры предназначены только для справки и тестирования. Мы не рекомендуем применять их в качестве зависимостей для приложения, которое используется в рабочей среде.
Интеграция конечной точки SCIM с службой подготовки Microsoft Entra. Идентификатор Microsoft Entra поддерживает несколько сторонних приложений, реализующих SCIM 2.0. Если вы используете одно из этих приложений, вы можете быстро автоматизировать подготовку и отмену подготовки пользователей и групп.
[Необязательно] Опубликуйте приложение в коллекции приложений Microsoft Entra. Чтобы пользователи могли легко обнаруживать приложение и легко настраивать подготовку.
Проектирование схемы пользователей и групп
Для создания пользователя или группы в каждом приложении требуются разные атрибуты. Запустите интеграцию, определив необходимые объекты (пользователи, группы) и атрибуты (имя, менеджер, название задания и т. д.), необходимые приложению.
Стандарт SCIM определяет схему для управления пользователями и группами.
Для основной схемы пользователя требуется только три атрибута (все остальные являются необязательными):
id— определенный поставщиком службы идентификатор;userName— уникальный идентификатор пользователя (обычно сопоставляется с именем участника-пользователя Microsoft Entra)meta— метаданные только для чтения, поддерживаемые поставщиком службы.
Помимо основной схемы пользователя, стандарт SCIM определяет расширение корпоративного пользователя с моделью расширения пользовательской схемы в соответствии с потребностями приложения.
Например, если приложению требуется как электронная почта пользователя, так и менеджер пользователя, используйте базовую схему для сбора электронной почты пользователя и корпоративной схемы пользователя для сбора диспетчера пользователя.
Чтобы спроектировать схему, выполните следующие действия:
Выведите список атрибутов, требуемых приложению, а затем классифицируйте атрибуты, необходимые для проверки подлинности (например, loginName и email). Атрибуты необходимы для управления жизненным циклом пользователя (например, состоянием или активностью), а также всеми прочими атрибутами, которые нужны приложению для работы (например, диспетчер, тег).
Проверьте, определены ли уже эти атрибуты в основной схеме пользователя или схеме пользователя предприятия. Если нет, необходимо определить для схемы пользователя расширение, которое охватывает отсутствующие атрибуты. См. пример расширения для пользователя, чтобы разрешить подготовку пользователя
tag.Сопоставление атрибутов SCIM с атрибутами пользователя в идентификаторе Microsoft Entra. Если один из атрибутов, определенных в конечной точке SCIM, не имеет четкого аналога в схеме пользователя Microsoft Entra, укажите администратору клиента расширение или используйте атрибут расширения, как показано в примере свойства
tags.
В следующей таблице приведен пример обязательных атрибутов.
| Обязательный атрибут приложения или пример | Сопоставляемый атрибут SCIM | Сопоставленный атрибут Microsoft Entra |
|---|---|---|
| loginName | userName | userPrincipalName |
| firstName | name.givenName | givenName |
| lastName | name.familyName | surName |
| workMail | emails[type eq "work"].value | Почта |
| manager | manager | manager |
| тег | urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User:tag |
extensionAttribute1 |
| статус | active | isSoftDeleted (вычисленное значение не хранится на пользователе) |
В приведенных ниже полезных данных JSON показан пример схемы SCIM.
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
"urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User"],
"userName":"bjensen@testuser.com",
"id": "48af03ac28ad4fb88478",
"externalId":"bjensen",
"name":{
"familyName":"Jensen",
"givenName":"Barbara"
},
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"manager": "123456"
},
"urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User": {
"tag": "701984",
},
"meta": {
"resourceType": "User",
"created": "2010-01-23T04:56:22Z",
"lastModified": "2011-05-13T04:42:34Z",
"version": "W\/\"3694e05e9dff591\"",
"location":
"https://example.com/v2/Users/00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
}
}
Примечание.
В дополнение к атрибутам, необходимым для приложения, представление JSON содержит обязательные атрибуты id, externalId и meta.
Он помогает классифицировать атрибуты пользователей по умолчанию в идентификаторе Microsoft Entra с RFC SCIM, чтобы узнать, как настроить атрибуты сопоставляются между /User /Group идентификатором Microsoft Entra и конечной точкой SCIM.
В следующей таблице приведен пример атрибутов пользователя.
| Пользователь Microsoft Entra | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User |
|---|---|
| IsSoftDeleted | active |
| department | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department |
| displayName | displayName |
| employeeId | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber |
| Facsimile-TelephoneNumber | phoneNumbers[type eq "fax"].value |
| givenName | name.givenName |
| jobTitle | title |
| emails[type eq "work"].value | |
| mailNickname | externalId |
| manager | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager |
| мобильный | phoneNumbers[type eq "mobile"].value |
| postalCode | addresses[type eq "work"].postalCode |
| proxy-Addresses | emails[type eq "other"].Value |
| physical-Delivery-OfficeName | addresses[type eq "other"].Formatted |
| streetAddress | addresses[type eq "work"].streetAddress |
| surname; | name.familyName |
| telephone-Number | phoneNumbers[type eq "work"].value |
| user-PrincipalName | userName |
В следующей таблице приведен пример атрибутов группы.
| Группа Microsoft Entra | urn:ietf:params:scim:schemas:core:2.0:Group |
|---|---|
| displayName | displayName |
| members | members |
| objectId | externalId |
Примечание.
Вам не требуется поддерживать как пользователей, так и группы или все атрибуты, показанные здесь, это только ссылка на то, как атрибуты в идентификаторе Microsoft Entra часто сопоставляются со свойствами в протоколе SCIM.
В RFC SCIM определено несколько конечных точек. Вы можете начать с конечной точки /User и двигаться от нее дальше. Некоторые конечные точки SCIM приведены в следующей таблице.
| Конечная точка | Description |
|---|---|
| /User | Выполнение операций CRUD с объектом пользователя. |
| /Group | Выполнение операций CRUD с объектом группы. |
| /Schemas | Набор атрибутов, поддерживаемых каждым клиентом и поставщиком служб, может различаться. Один поставщик услуг может включать name, title и emails, а другой — name, title и phoneNumbers. Конечная точка schemas позволяет обнаруживать поддерживаемые атрибуты. |
| /Bulk | Групповые операции позволяют одновременно работать с большой коллекцией объектов ресурсов (например, обновлять членство для большой группы). |
| /ServiceProviderConfig | Предоставляет сведения о поддерживаемых функциях стандарта SCIM, например о поддерживаемых ресурсах и о способе проверки подлинности. |
| /ResourceTypes | Указывает метаданные для каждого ресурса. |
Примечание.
Используйте конечную точку /Schemas для поддержки настраиваемых атрибутов или в случае частого изменения схемы, так как эта конечная точка позволяет клиенту автоматически получать самую актуальную схему. Для поддержки групп используйте конечную точку /Bulk.
Общие сведения о реализации MICROSOFT Entra SCIM
Служба подготовки Microsoft Entra предназначена для поддержки API управления пользователями SCIM 2.0.
Внимание
Поведение реализации Microsoft Entra SCIM было обновлено 18 декабря 2018 г. Сведения о том, что изменилось, см. в статье о соответствии протокола SCIM 2.0 службы подготовки пользователей Microsoft Entra.
В рамках спецификации протокола SCIM 2.0 приложения должны соответствовать следующим требованиям:
| Требование | Справочные примечания (протокол SCIM) |
|---|---|
| Создание пользователей и (при необходимости) групп | Раздел 3.3 |
| Изменение пользователей или групп с использованием запросов PATCH | Раздел 3.5.2. Поддержка гарантирует, что группы и пользователи подготавливаются к работе эффективно. |
| Получение известного ресурса для созданного ранее пользователя или группы | Раздел 3.4.1 |
| Запрашивание объектов пользователей или групп | Раздел 3.4.2. По умолчанию пользователи получаются с id их запросами и запрашиваются вместе displayNameс username externalIdгруппами. |
| Применение фильтра excludedAttributes=members при запрашивании ресурса группы | Раздел 3.4.2.2 |
| Поддержка перечисления пользователей и разбиения на страницы | Раздел 3.4.2.4. |
Обратимое удаление пользователя active=false и восстановление пользователя active=true |
Объект пользователя должен возвращаться в запросе независимо от активности пользователя. Пользователь не должен возвращаться, только если он необратимо удален из приложения. |
| Поддержка конечной точки /Schemas | Раздел 7 . Конечная точка обнаружения схем используется для обнаружения дополнительных атрибутов. |
| Примите один маркер носителя для проверки подлинности и авторизации идентификатора Microsoft Entra в приложении. |
Используйте общие рекомендации при реализации конечной точки SCIM, чтобы обеспечить совместимость с идентификатором Microsoft Entra:
Общие сведения:
idявляется обязательным свойством для всех ресурсов. Каждый ответ, возвращающий ресурс, должен гарантировать наличие этого свойства у каждого ресурса, за исключениемListResponseс нулевым числом элементов.- Значения, отправленные, должны храниться в том же формате, который они были отправлены. Недопустимые значения должны быть отклонены с информативным и практичным сообщением об ошибке. Преобразования данных не должны происходить между данными из идентификатора Microsoft Entra и данных, хранящихся в приложении SCIM. (например, номер телефона, отправленный как 55555555555, не должен быть сохранен и затем возвращен как + 5 (555) 555-5555)
- Не обязательно включать весь ресурс в ответ PATCH.
- Не требуйте совпадения с учетом регистра для структурных элементов в SCIM, в частности для значений операций
opPATCH, как определено в разделе 3.5.2. Идентификатор Microsoft Entra выдает значения в виде "Добавить", "Заменить" и "Удалить".op - Идентификатор Microsoft Entra выполняет запросы на получение случайного пользователя и группы, чтобы убедиться, что конечная точка и учетные данные действительны. Он также выполняется как часть потока тестового подключения .
- Поддержка HTTPS на конечной точке SCIM.
- Пользовательские сложные и многозначные атрибуты поддерживаются, но идентификатор Microsoft Entra ID не имеет много сложных структур данных для извлечения данных из этих случаев. Атрибуты имени и значения можно легко сопоставить, но поток данных с сложными атрибутами с тремя или более подзатратами не поддерживается.
- Значения податрибута type для многозначных сложных атрибутов должны быть уникальными. Например, не может быть двух разных адресов электронной почты с подтипом work.
- Заголовок для всех ответов должен иметь content-Type: application/scim+json
Извлечение ресурсов:
- Ответ на запрос или запрос фильтра всегда должен быть
ListResponse. - Microsoft Entra использует следующие операторы:
eqand - Атрибут, на который можно запросить ресурсы, должен быть задан как соответствующий атрибут в приложении, см. в разделе "Настройка сопоставлений атрибутов подготовки пользователей".
/Users:
- Атрибут прав не поддерживается.
- Все атрибуты, которые обеспечивают уникальность пользователей, должны поддерживать использование в запросе с фильтрацией. Например, если оценка уникальности пользователей выполняется и для userName, и для emails[type eq "work"], то запрос GET к /Users с фильтром должен разрешать оба запроса: userName eq "user@contoso.com" и emails[type eq "work"].value eq "user@contoso.com".
/Groups:
- Группы являются необязательными, но они поддерживаются только в том случае, если реализация SCIM поддерживает запросы PATCH.
- Группы должны иметь уникальность в значении displayName для сопоставления с идентификатором Microsoft Entra и приложением SCIM. Уникальность не является требованием протокола SCIM, но является обязательным требованием для интеграции конечной точки SCIM с идентификатором Microsoft Entra.
/Schemas (обнаружение схемы):
- Пример запроса и ответа
- Обнаружение схем используется в определенных приложениях коллекции. Обнаружение схемы является единственным методом для добавления дополнительных атрибутов в схему существующего приложения SCIM коллекции. Обнаружение схем в настоящее время не поддерживается в пользовательском приложении SCIM, отличном от коллекции.
- Если значение отсутствует, не отправляйте значения NULL.
- Значения свойств нужно задавать без знаков препинания и пробелов (например, readWrite).
- В ответе должен возвращаться список.
- Служба подготовки Microsoft Entra запрашивает /schemas при сохранении конфигурации подготовки. Запрос также выполняется при открытии страницы подготовки редактирования. Другие обнаруженные атрибуты отображаются клиентам в сопоставлениях атрибутов в списке целевых атрибутов. Обнаружение схемы приводит только к добавлению дополнительных целевых атрибутов. Атрибуты не удаляются.
Подготовка и отмена подготовки пользователей
На следующей схеме показаны сообщения, которые идентификатор Microsoft Entra отправляет в конечную точку SCIM для управления жизненным циклом пользователя в хранилище удостоверений приложения.
Подготовка и отмена подготовки группы
Подготовка и отмена подготовки групп являются необязательными. При реализации и включении на следующем рисунке показаны сообщения, отправляемые идентификатором Microsoft Entra в конечную точку SCIM для управления жизненным циклом группы в хранилище удостоверений приложения. Эти сообщения отличаются от сообщений о пользователях по двум причинам.
- Запросы на получение групп указывают, что атрибут членов должен быть исключен из любого ресурса, предоставленного в ответ на запрос.
- Запросы, которые должны определить, имеет ли ссылочный атрибут указанное значение, применяются в отношении атрибута members.
На следующей схеме показана последовательность отзыва группы.
Запросы и ответы протокола SCIM
В этой статье приведены примеры запросов SCIM, создаваемых службой подготовки Microsoft Entra и примерами ожидаемых ответов. Чтобы получить наилучшие результаты, следует закодировать приложение, чтобы обрабатывать эти запросы в этом формате и выдавать ожидаемые ответы.
Внимание
Сведения о том, как и когда служба подготовки пользователей Microsoft Entra выдает операции, описанные в примере, см. в разделе " Циклы подготовки: начальный и добавочный " в разделе "Принципы подготовки".
- Создание пользователя (Запрос / Ответ)
- Получение пользователя (Запрос / Ответ)
- Получение пользователя по запросу (Запрос / Ответ)
- Получение пользователя по запросу — нет результатов (Запрос / Ответ)
- Обновление пользователя [Многозначные свойства] (Запрос / Ответ)
- Обновление пользователя [Однозначные свойства] (Запрос / Ответ)
- Отключение пользователя (Запрос / Ответ)
- Удаление пользователя (Запрос / Ответ)
- Создание группы (Запрос / Ответ)
- Получение группы (Запрос / Ответ)
- Получение группы по displayName (Запрос / Ответ)
- Обновление группы [атрибуты, не относящиеся к элементу] (Запрос / Ответ)
- Обновление группы [добавить элементы] (Запрос / Ответ)
- Обновление группы [удалить элементы] (Запрос / Ответ)
- Удаление группы (Запрос / Ответ)
- обнаружение схемы (запрос / ответ).
Операции пользователя
- Использование
userNameилиemails[type eq "work"]атрибуты для запроса пользователей.
Создание пользователя
Запросить
POST /Users
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
"externalId": "0a21f0f2-8d2a-4f8e-bf98-7363c4aed4ef",
"userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"active": true,
"emails": [{
"primary": true,
"type": "work",
"value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com"
}],
"meta": {
"resourceType": "User"
},
"name": {
"formatted": "givenName familyName",
"familyName": "familyName",
"givenName": "givenName"
},
"roles": []
}
Response
HTTP/1.1 201 Created
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "48af03ac28ad4fb88478",
"externalId": "0a21f0f2-8d2a-4f8e-bf98-7363c4aed4ef",
"meta": {
"resourceType": "User",
"created": "2018-03-27T19:59:26.000Z",
"lastModified": "2018-03-27T19:59:26.000Z"
},
"userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": {
"formatted": "givenName familyName",
"familyName": "familyName",
"givenName": "givenName",
},
"active": true,
"emails": [{
"value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com",
"type": "work",
"primary": true
}]
}
Получить пользователя
Запросить
GET /Users/5d48a0a8e9f04aa38008
Ответ (найден пользователь)
HTTP/1.1 200 OK
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "5d48a0a8e9f04aa38008",
"externalId": "58342554-38d6-4ec8-948c-50044d0a33fd",
"meta": {
"resourceType": "User",
"created": "2018-03-27T19:59:26.000Z",
"lastModified": "2018-03-27T19:59:26.000Z"
},
"userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": {
"formatted": "givenName familyName",
"familyName": "familyName",
"givenName": "givenName",
},
"active": true,
"emails": [{
"value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com",
"type": "work",
"primary": true
}]
}
Запросить
GET /Users/5171a35d82074e068ce2
Ответ (Пользователь не найден. Подробности не обязательны, важно только состояние.)
HTTP/1.1 404 не найден
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:Error"
],
"status": "404",
"detail": "Resource 23B51B0E5D7AE9110A49411D@7cca31655d49f3640a494224 not found"
}
Получение пользователя по запросу
Запросить
GET /Users?filter=userName eq "Test_User_00aa00aa-bb11-cc22-dd33-44ee4ee4ee44ee4ee4ee4ee"
Response
HTTP/1.1 200 OK
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults": 1,
"Resources": [{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "2441309d85324e7793ae",
"externalId": "7fce0092-d52e-4f76-b727-3955bd72c939",
"meta": {
"resourceType": "User",
"created": "2018-03-27T19:59:26.000Z",
"lastModified": "2018-03-27T19:59:26.000Z"
},
"userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": {
"familyName": "familyName",
"givenName": "givenName"
},
"active": true,
"emails": [{
"value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com",
"type": "work",
"primary": true
}]
}],
"startIndex": 1,
"itemsPerPage": 20
}
Получение пользователя по запросу — 0 результатов
Запросить
GET /Users?filter=userName eq "non-existent user"
Response
HTTP/1.1 200 OK
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults": 0,
"Resources": [],
"startIndex": 1,
"itemsPerPage": 20
}
Обновление пользователя [Многозначные свойства]
Запросить
PATCH /Users/6764549bef60420686bc HTTP/1.1
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [
{
"op": "Replace",
"path": "emails[type eq \"work\"].value",
"value": "updatedEmail@microsoft.com"
},
{
"op": "Replace",
"path": "name.familyName",
"value": "updatedFamilyName"
}
]
}
Response
HTTP/1.1 200 OK
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "6764549bef60420686bc",
"externalId": "6c75de36-30fa-4d2d-a196-6bdcdb6b6539",
"meta": {
"resourceType": "User",
"created": "2018-03-27T19:59:26.000Z",
"lastModified": "2018-03-27T19:59:26.000Z"
},
"userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": {
"formatted": "givenName updatedFamilyName",
"familyName": "updatedFamilyName",
"givenName": "givenName"
},
"active": true,
"emails": [{
"value": "updatedEmail@microsoft.com",
"type": "work",
"primary": true
}]
}
Обновить пользователя [Свойства с одним значением]
Запросить
PATCH /Users/5171a35d82074e068ce2 HTTP/1.1
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op": "Replace",
"path": "userName",
"value": "5b50642d-79fc-4410-9e90-4c077cdd1a59@testuser.com"
}]
}
Response
HTTP/1.1 200 OK
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "5171a35d82074e068ce2",
"externalId": "aa1eca08-7179-4eeb-a0be-a519f7e5cd1a",
"meta": {
"resourceType": "User",
"created": "2018-03-27T19:59:26.000Z",
"lastModified": "2018-03-27T19:59:26.000Z"
},
"userName": "5b50642d-79fc-4410-9e90-4c077cdd1a59@testuser.com",
"name": {
"formatted": "givenName familyName",
"familyName": "familyName",
"givenName": "givenName",
},
"active": true,
"emails": [{
"value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com",
"type": "work",
"primary": true
}]
}
Отключение пользователя
Запросить
PATCH /Users/5171a35d82074e068ce2 HTTP/1.1
{
"Operations": [
{
"op": "Replace",
"path": "active",
"value": false
}
],
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
]
}
Response
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "CEC50F275D83C4530A495FCF@834d0e1e5d8235f90a495fda",
"userName": "deanruiz@testuser.com",
"name": {
"familyName": "Harris",
"givenName": "Larry"
},
"active": false,
"emails": [
{
"value": "gloversuzanne@testuser.com",
"type": "work",
"primary": true
}
],
"addresses": [
{
"country": "ML",
"type": "work",
"primary": true
}
],
"meta": {
"resourceType": "Users",
"location": "/scim/5171a35d82074e068ce2/Users/CEC50F265D83B4530B495FCF@5171a35d82074e068ce2"
}
}
Удаление пользователя
Запросить
DELETE /Users/5171a35d82074e068ce2 HTTP/1.1
Response
HTTP/1.1 204 No Content
Операции с группой
- Группы создаются с пустым списком участников.
displayNameИспользуйте атрибут для запроса групп.- Обновление запроса группы исправления в ответ должно приостановить HTTP 204 No Content. Не рекомендуется возвращать текст со списком всех членов.
- Поддержка возвращения всех членов группы не нужна.
Создать группу
Запросить
POST /Groups HTTP/1.1
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group", "http://schemas.microsoft.com/2006/11/ResourceManagement/ADSCIM/2.0/Group"],
"externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159",
"displayName": "displayName",
"meta": {
"resourceType": "Group"
}
}
Response
HTTP/1.1 201 Created
{
"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": []
}
Получить группу
Запросить
GET /Groups/40734ae655284ad3abcc?excludedAttributes=members HTTP/1.1
Response
HTTP/1.1 200 OK
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"id": "40734ae655284ad3abcc",
"externalId": "60f1bb27-2e1e-402d-bcc4-ec999564a194",
"meta": {
"resourceType": "Group",
"created": "2018-03-27T19:59:26.000Z",
"lastModified": "2018-03-27T19:59:26.000Z"
},
"displayName": "displayName",
}
Получить группу по displayName
Запросить
GET /Groups?excludedAttributes=members&filter=displayName eq "displayName" HTTP/1.1
Response
HTTP/1.1 200 OK
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults": 1,
"Resources": [{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"id": "8c601452cc934a9ebef9",
"externalId": "0db508eb-91e2-46e4-809c-30dcbda0c685",
"meta": {
"resourceType": "Group",
"created": "2018-03-27T22:02:32.000Z",
"lastModified": "2018-03-27T22:02:32.000Z",
},
"displayName": "displayName",
}],
"startIndex": 1,
"itemsPerPage": 20
}
Обновление группы [Нет атрибутов пользователей]
Запросить
PATCH /Groups/fa2ce26709934589afc5 HTTP/1.1
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op": "Replace",
"path": "displayName",
"value": "1879db59-3bdf-4490-ad68-ab880a269474updatedDisplayName"
}]
}
Response
HTTP/1.1 204 No Content
Обновить группу [Добавить элементы]
Запросить
PATCH /Groups/a99962b9f99d4c4fac67 HTTP/1.1
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op": "Add",
"path": "members",
"value": [{
"$ref": null,
"value": "f648f8d5ea4e4cd38e9c"
}]
}]
}
Response
HTTP/1.1 204 No Content
Обновление группы [Удаление элементов]
Запросить
PATCH /Groups/a99962b9f99d4c4fac67 HTTP/1.1
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op": "Remove",
"path": "members",
"value": [{
"$ref": null,
"value": "f648f8d5ea4e4cd38e9c"
}]
}]
}
Response
HTTP/1.1 204 No Content
Удалить группу
Запросить
DELETE /Groups/cdb1ce18f65944079d37 HTTP/1.1
Response
HTTP/1.1 204 No Content
Обнаружение схем
Обнаружение схемы
Запросить
GET /Schemas
Response
HTTP/1.1 200 OK
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"itemsPerPage": 50,
"startIndex": 1,
"totalResults": 3,
"Resources": [
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
"id" : "urn:ietf:params:scim:schemas:core:2.0:User",
"name" : "User",
"description" : "User Account",
"attributes" : [
{
"name" : "userName",
"type" : "string",
"multiValued" : false,
"description" : "Unique identifier for the User, typically
used by the user to directly authenticate to the service provider.
Each User MUST include a non-empty userName value. This identifier
MUST be unique across the service provider's entire set of Users.
REQUIRED.",
"required" : true,
"caseExact" : false,
"mutability" : "readWrite",
"returned" : "default",
"uniqueness" : "server"
},
],
"meta" : {
"resourceType" : "Schema",
"location" :
"/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:User"
}
},
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
"id" : "urn:ietf:params:scim:schemas:core:2.0:Group",
"name" : "Group",
"description" : "Group",
"attributes" : [
{
"name" : "displayName",
"type" : "string",
"multiValued" : false,
"description" : "A human-readable name for the Group.
REQUIRED.",
"required" : false,
"caseExact" : false,
"mutability" : "readWrite",
"returned" : "default",
"uniqueness" : "none"
},
],
"meta" : {
"resourceType" : "Schema",
"location" :
"/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:Group"
}
},
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
"id" : "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
"name" : "EnterpriseUser",
"description" : "Enterprise User",
"attributes" : [
{
"name" : "employeeNumber",
"type" : "string",
"multiValued" : false,
"description" : "Numeric or alphanumeric identifier assigned
to a person, typically based on order of hire or association with an
organization.",
"required" : false,
"caseExact" : false,
"mutability" : "readWrite",
"returned" : "default",
"uniqueness" : "none"
},
],
"meta" : {
"resourceType" : "Schema",
"location" :
"/v2/Schemas/urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
}
}
]
}
Требования к безопасности
Версии протокола TLS
Единственной приемлемой версией протокола является TLS 1.2. Другая версия SSL/TLS не разрешена.
- Ключи RSA должны составлять не менее 2 048 бит.
- Ключи ECC должны иметь по крайней мере 256 бит, созданных с помощью допустимой эллиптической кривой
Длина ключей
Все службы должны использовать сертификаты X. 509, созданные с использованием криптографических ключей достаточной длины, то есть:
Комплекты шифров
Все службы должны быть настроены для использования следующих наборов шифров в точном порядке, указанном в примере. Если у вас есть только сертификат RSA, установленные наборы шифров ECDSA не оказывают никакого влияния.
Минимальная строка наборов шифров 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
Диапазоны IP-адресов
Служба подготовки Microsoft Entra в настоящее время работает под диапазонами IP-адресов для идентификатора Microsoft Entra, как показано здесь. Можно добавить диапазоны IP-адресов, перечисленные в теге AzureActiveDirectory , чтобы разрешить трафик из службы подготовки Microsoft Entra в приложение. Необходимо тщательно просмотреть список диапазонов IP-адресов для вычисляемых адресов. Например, адрес 40.126.25.32 может быть представлен в списке диапазонов IP-адресов как 40.126.0.0/18. Список диапазонов IP-адресов можно также получить программно, используя приведенный ниже API.
Идентификатор Microsoft Entra также поддерживает решение на основе агента для обеспечения подключения к приложениям в частных сетях (локальных, размещенных в Azure, размещенных в AWS и т. д.). Клиенты могут развернуть упрощенный агент, который обеспечивает подключение к идентификатору Microsoft Entra, не открывая входящие порты на сервере в частной сети. Подробнее см. здесь.
Создание конечной точки SCIM
Теперь, когда вы разработали схему и поняли реализацию MICROSOFT Entra SCIM, вы можете приступить к разработке конечной точки SCIM. Вместо того чтобы начинать с нуля и самостоятельно создавать реализацию, вы можете использовать ряд библиотек SCIM с открытым кодом, опубликованных сообществом SCIM.
Сведения о создании конечной точки SCIM, а также примеры см. в руководстве Разработка примера конечной точки SCIM.
Пример справочного кода открытый код .NET Core, опубликованный командой подготовки Microsoft Entra, является одним из таких ресурсов, которые могут начать разработку. Создайте конечную точку SCIM, а затем протестируйте ее, выполнив примеры запросов и ответов.
Примечание.
Справочный код предназначен для того, чтобы приступить к созданию конечной точки SCIM и предоставить "как есть". Вклады из сообщества помогут вам собрать и поддерживать код.
Решение состоит из двух проектов: Microsoft. SCIM и Microsoft.SCIM.WebHostSample.
Проект Microsoft. SCIM — это библиотека, которая определяет компоненты веб-службы, которые соответствуют характеристике SCIM. Он объявляет интерфейс Microsoft.SCIM.IProvider, запросы преобразуются в вызовы методов поставщика, которые будут запрограммированы для работы в хранилище удостоверений.
Проект Microsoft.SCIM.WebHostSample — это веб-приложение ASP.NET Core, в основе которого лежит пустой шаблон. Он позволяет развертывать пример кода изолированно, размещать его в контейнерах или в службах IIS. Он также реализует интерфейс Microsoft. SCIM.IProvider, хранящий классы в памяти в качестве примера хранилища удостоверений.
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();
}
...
Создание пользовательской конечной точки SCIM
Конечная точка SCIM должна иметь HTTP-адрес и сертификат проверки подлинности сервера, выданный одним из следующих корневых центров сертификации:
- CNNIC;
- Comodo;
- CyberTrust;
- DigiCert
- GeoTrust;
- GlobalSign
- Go Daddy;
- VeriSign;
- WoSign.
- Корневой ЦС X3 DST
Пакет SDK для .NET Core включает сертификат разработки HTTPS, используемый во время разработки. Сертификат устанавливается в рамках первого запуска. В зависимости от способа запуска веб-приложения ASP.NET Core он прослушивает другой порт:
- Microsoft.SCIM.WebHostSample:
https://localhost:5001 - IIS Express:
https://localhost:44359
Дополнительные сведения о HTTPS в ASP.NET Core см. по следующей ссылке: принудительное применение HTTPS в ASP.NET Core
Обработка аутентификации на конечной точке
Запросы от службы подготовки Microsoft Entra включают маркер носителя OAuth 2.0. Сервер авторизации выдает маркер носителя. Идентификатор Microsoft Entra — пример доверенного сервера авторизации. Настройте службу подготовки Microsoft Entra для использования одного из следующих маркеров:
Маркер носителя с длительным сроком действия. Если конечная точка SCIM требует маркер носителя OAuth от издателя, отличного от идентификатора Microsoft Entra, скопируйте требуемый маркер носителя OAuth в необязательное поле секретного токена . В среде разработки можно использовать маркер тестирования из конечной точки
/scim/token. Маркеры тестирования не следует использовать в рабочих средах.Токен носителя Microsoft Entra. Если поле "Секретный маркер" остается пустым, идентификатор Microsoft Entra ID включает маркер носителя OAuth, выданный идентификатором Microsoft Entra с каждым запросом. Приложения, использующие идентификатор Microsoft Entra в качестве поставщика удостоверений, могут проверить выданный идентификатором Майкрософт маркер.
- Приложение, которое получает запросы, должно проверить издателя токена как идентификатор Microsoft Entra для ожидаемого клиента Microsoft Entra.
- Утверждение
issопределяет издателя маркера. Например,"iss":"https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/". В этом примере базовый адрес значенияhttps://sts.windows.netутверждения определяет идентификатор Microsoft Entra в качестве издателя, а относительный сегмент адресов aaaabbbb-0000-cccc-1111-dd222eeee является уникальным идентификатором клиента Microsoft Entra, для которого был выдан маркер. - Аудитория маркера — это идентификатор приложения из коллекции. Приложения, зарегистрированные в одном клиенте, с запросами SCIM получают одно и то же утверждение
iss. Для всех пользовательских приложений используется идентификатор 8adf8e6e-67b2-4cf2-a259-e3dc5476c621. Маркер, созданный идентификатором Microsoft Entra, должен использоваться только для тестирования. Его не следует применять в рабочих средах.
В примере кода, запросы проходят аутентификацию с помощью пакета Microsoft.AspNetCore.Authentication.JwtBearer. Следующий код принудительно применяет запросы к любой из конечных точек службы, прошедших проверку подлинности с помощью маркера носителя, выданного идентификатором Microsoft Entra для указанного клиента:
public void ConfigureServices(IServiceCollection services)
{
if (_env.IsDevelopment())
{
...
}
else
{
services.AddAuthentication(options =>
{
options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
})
.AddJwtBearer(options =>
{
options.Authority = " https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/";
options.Audience = "8adf8e6e-67b2-4cf2-a259-e3dc5476c621";
...
});
}
...
}
public void Configure(IApplicationBuilder app)
{
...
app.UseAuthentication();
app.UseAuthorization();
...
}
Пример кода использует среды ASP.NET Core для изменения параметров проверки подлинности на этапе разработки и включения использования самозаверяющего токена.
Дополнительные сведения см. в статье Использование нескольких сред в ASP.NET Core.
Следующий код принудительно применяет запросы к любой из конечных точек службы, прошедших проверку подлинности с помощью маркера носителя, подписанного пользовательским ключом:
public void ConfigureServices(IServiceCollection services)
{
if (_env.IsDevelopment())
{
services.AddAuthentication(options =>
{
options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
})
.AddJwtBearer(options =>
{
options.TokenValidationParameters =
new TokenValidationParameters
{
ValidateIssuer = false,
ValidateAudience = false,
ValidateLifetime = false,
ValidateIssuerSigningKey = false,
ValidIssuer = "Microsoft.Security.Bearer",
ValidAudience = "Microsoft.Security.Bearer",
IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("A1B2C3D4E5F6A1B2C3D4E5F6"))
};
});
}
...
Отправьте запрос GET на контроллер токена, чтобы получить действительный маркер носителя. Метод GenerateJSONWebToken отвечает за создание маркера, соответствующего параметрам, настроенным для разработки:
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;
}
Обработка подготовки и отмены подготовки пользователей
Пример 1. Запрос службы для соответствующего пользователя
Идентификатор Microsoft Entra запрашивает службу для пользователя со externalId значением атрибута, соответствующим значению атрибута mailNickname пользователя в идентификаторе Microsoft Entra. Запрос выражается как http-запрос гипертекстового протокола передачи (HTTP), например в этом примере, где jyoung является примером почтового имени пользователя в идентификаторе Microsoft Entra.
Примечание.
Это только пример. Не все пользователи будут иметь атрибут mailNickname, а значение пользователя может не быть уникальным в каталоге. Кроме того, атрибут, используемый для сопоставления (в данном случае externalId) можно настроить в сопоставлениях атрибутов Microsoft Entra.
GET https://.../scim/Users?filter=externalId eq jyoung HTTP/1.1
Authorization: Bearer ...
В примере кода запрос преобразуется в вызов метода QueryAsync поставщика службы. Подпись этого метода будет выглядеть так:
// 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);
В примере запроса для пользователя с заданным значением для атрибута externalId, значения аргументов, переданных в метод QueryAsync, будут следующими:
- parameters.AlternateFilters.Count: 1
- parameters.AlternateFilters.ElementAt(0).AttributePath: "externalId"
- parameters.AlternateFilters.ElementAt(0).ComparisonOperator: ComparisonOperator.Equals
- parameters.AlternateFilter.ElementAt(0).ComparisonValue: "jyoung"
Пример 2. Подготовка пользователя
Если ответ на запрос к конечной точке SCIM для пользователя со externalId значением атрибута, соответствующим значению атрибута mailNickname пользователя, не возвращает никаких пользователей, идентификатор Microsoft Entra ID запрашивает, что служба подготавливает пользователя, соответствующего одному из них в идентификаторе Microsoft Entra. Вот пример такого запроса:
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}
В примере кода запрос преобразуется в вызов метода CreateAsync поставщика службы. Подпись этого метода будет выглядеть так:
// 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);
В запросе на подготовку пользователей значение аргумента ресурса является экземпляром Microsoft.SCIM.Core2EnterpriseUser класса. Этот класс определен в библиотеке Microsoft.SCIM.Schemas . Если запрос на подготовку пользователя выполнен успешно, то реализация метода, как ожидается, возвращает экземпляр Microsoft.SCIM.Core2EnterpriseUser класса. Значение свойства присваивается уникальному идентификатору только что Identifier подготовленного пользователя.
Пример 3. Запрос текущего состояния пользователя
Идентификатор Microsoft Entra запрашивает текущее состояние указанного пользователя из службы с таким запросом, как:
GET ~/scim/Users/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 HTTP/1.1
Authorization: Bearer ...
В примере кода запрос преобразуется в вызов метода GetAsync поставщика службы. Подпись этого метода будет выглядеть так:
// 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);
В примере запроса, чтобы получить текущее состояние пользователя, значения свойств объекта, предоставленного в качестве значения аргумента параметров, приведены следующим образом:
- Идентификатор: "a0a0a0a0-bbbb-cccc-dd-e1e1e1e1e1e1e1e1e1"
- SchemaIdentifier:
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
Пример 4. Запрос значения обновляемого атрибута ссылки
Идентификатор Microsoft Entra проверяет текущее значение атрибута в хранилище удостоверений перед обновлением. Однако только атрибут диспетчера является проверенным первым для пользователей. Ниже приведен пример запроса, чтобы определить, имеет ли в настоящее время атрибут диспетчера объекта пользователя определенное значение: в примере кода запрос преобразуется в вызов метода QueryAsync поставщика службы. В нем передается аргумент parameters, значением которого будет объект со следующими свойствами.
- parameters.AlternateFilters.Count: 2
- parameters.AlternateFilters.ElementAt(x).AttributePath: "ID"
- parameters.AlternateFilters.ElementAt(x).ComparisonOperator: ComparisonOperator.Equals
- Параметры. AlternateFilter.ElementAt(x). ComparisonValue: "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1e1e1e1"
- parameters.AlternateFilters.ElementAt(y).AttributePath: "manager"
- parameters.AlternateFilters.ElementAt(y).ComparisonOperator: ComparisonOperator.Equals
- Параметры. AlternateFilter.ElementAt(y). ComparisonValue: "00aa00aa-bb11-cc22-dd33-44ee4ee44ee4ee4ee4ee"
- parameters.RequestedAttributePaths.ElementAt(0): "ID"
- parameters.SchemaIdentifier:
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
Значением индекса x может быть 0, а значением индекса y может быть 1. Либо значением x может быть 1, а значением y может быть 0. Это зависит от порядка выражений в параметре запроса фильтра.
Пример 5. Запрос от идентификатора Microsoft Entra к конечной точке SCIM для обновления пользователя
Ниже приведен пример запроса от идентификатора Microsoft Entra к конечной точке SCIM для обновления пользователя:
PATCH ~/scim/Users/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 HTTP/1.1
Authorization: Bearer ...
Content-type: application/scim+json
{
"schemas":
[
"urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations":
[
{
"op":"Add",
"path":"manager",
"value":
[
{
"$ref":"http://.../scim/Users/00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"value":"00aa00aa-bb11-cc22-dd33-44ee44ee44ee"}]}]}
В примере кода запрос преобразуется в вызов метода UpdateAsync поставщика службы. Подпись этого метода будет выглядеть так:
// 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);
В примере запроса на обновление пользователя объект, предоставленный в качестве значения аргумента исправления, имеет следующие значения свойств:
| Аргумент | Значение |
|---|---|
ResourceIdentifier.Identifier |
"a0a0a0a0-bbbb-cccc-ddddd-e1e1e1e1e1e1e1e1" |
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 |
Manager |
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.Count |
1 |
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.ElementAt(0).Reference |
http://.../scim/Users/00aa00aa-bb11-cc22-dd33-44ee44ee44ee |
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.ElementAt(0).Value |
00aa00aa-bb11-cc22-dd33-44ee4ee4ee4ee4ee4ee4ee |
Пример 6. Отмена подготовки пользователя
Чтобы отменить подготовку пользователя из хранилища удостоверений, созданного конечной точкой SCIM, идентификатор Microsoft Entra отправляет такой запрос, как:
DELETE ~/scim/Users/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 HTTP/1.1
Authorization: Bearer ...
В примере кода запрос преобразуется в вызов метода DeleteAsync поставщика службы. Подпись этого метода будет выглядеть так:
// 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);
В примере запроса на отзыв пользователя в качестве значения аргумента resourceIdentifier передается объект со следующими значениями свойств.
- ResourceIdentifier.Identifier: "a0a0a0a0-bbbb-cccc-ddd-e1e1e1e1e1e1e1e1"
- ResourceIdentifier.SchemaIdentifier:
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
Интеграция конечной точки SCIM с службой подготовки Microsoft Entra
Идентификатор Microsoft Entra можно настроить для автоматической подготовки назначенных пользователей и групп для приложений , реализующих определенный профиль протокола SCIM 2.0. Особенности профиля описаны в реализации Microsoft Entra SCIM.
Рекомендуется связаться с поставщиком приложения или ознакомиться с документацией поставщика для получения подтверждения соответствия этим требованиям.
Внимание
Реализация MICROSOFT Entra SCIM основана на службе подготовки пользователей Microsoft Entra, которая предназначена для постоянной синхронизации пользователей между идентификатором Microsoft Entra и целевым приложением и реализует очень конкретный набор стандартных операций. Важно понимать это поведение, чтобы понять поведение службы подготовки Microsoft Entra. Дополнительные сведения см. в разделе "Циклы подготовки: начальное и добавочное" в разделе "Работа подготовки".
Начало работы
Совет
Действия, описанные в этой статье, могут немного отличаться на портале, с который вы начинаете работу.
Приложения, поддерживающие профиль SCIM, описанный в этой статье, можно подключить к идентификатору Microsoft Entra с помощью функции приложения, отличного от коллекции приложений Microsoft Entra. После подключения идентификатор Microsoft Entra запускает процесс синхронизации. Процесс выполняется каждые 40 минут. Процесс запрашивает конечную точку SCIM приложения для назначенных пользователей и групп и создает или изменяет их в соответствии с сведениями о назначении.
Подключение приложения, поддерживающего SCIM:
Войдите в Центр администрирования Microsoft Entra как минимум администратор приложений.
Перейдите к приложениям Identity>Applications>Enterprise.
Отобразится список всех настроенных приложений, включая приложения, добавленные из коллекции.
Выберите Новое приложение>Создайте собственное приложение.
Введите имя приложения, выберите параметр "Интеграция с любыми другими приложениями, которых нет в коллекции", а затем — Добавить, чтобы создать объект приложения. Новое приложение добавлено в список корпоративных приложений и открывается на экране управления приложениями.
На следующем снимка экрана показана коллекция приложений Microsoft Entra:
На экране управления приложениями выберите Подготовка на панели слева.
В меню Режим подготовки к работе выберите Автоматический.
На следующем снимке экрана показана настройка параметров подготовки в Центре администрирования Microsoft Entra:
В поле URL-адрес клиента введите URL-адрес конечной точки SCIM приложения. Пример:
https://api.contoso.com/scim/Если конечная точка SCIM требует маркер носителя OAuth от издателя, отличного от идентификатора Microsoft Entra, скопируйте требуемый маркер носителя OAuth в необязательное поле секретного токена . Если это поле остается пустым, идентификатор Microsoft Entra содержит маркер носителя OAuth, выданный идентификатором Microsoft Entra ID с каждым запросом. Приложения, использующие идентификатор Microsoft Entra в качестве поставщика удостоверений, могут проверить выданный идентификатором Майкрософт маркер.
Примечание.
Не рекомендуется оставить это поле пустым и полагаться на токен, созданный идентификатором Microsoft Entra. Этот вариант в основном доступен для целей тестирования.
Выберите "Проверить подключение", чтобы идентификатор Microsoft Entra пытался подключиться к конечной точке SCIM. Если подключиться не удастся, отобразятся сведения об ошибке.
Примечание.
Проверка подключения запрашивает конечную точку SCIM для пользователя, который не существует, используя случайный GUID в качестве соответствующего свойства, выбранного в конфигурации Microsoft Entra. Ожидаемый правильный ответ — HTTP 200 OK с пустым сообщением ListResponse SCIM.
Если подключиться к приложению удалось, выберите Сохранить, чтобы сохранить учетные данные администратора.
В разделе Сопоставления доступны на выбор два набора сопоставлений атрибутов: для объектов пользователей и для объектов групп. Выберите каждый из них, чтобы просмотреть атрибуты, синхронизированные с идентификатором Microsoft Entra с приложением. Атрибуты, выбранные как свойства Matching, используются для сопоставления пользователей и групп в вашем приложении для операций обновления. Чтобы зафиксировать изменения, щелкните Сохранить.
Примечание.
При необходимости можно отключить синхронизацию объектов групп, отключив сопоставление групп.
Поле Область в разделе Параметры определяет, какие пользователи и группы синхронизируются. Если выбрать параметр Синхронизация только назначенных пользователей и групп (рекомендуется), то будут синхронизированы только пользователи и группы, назначенные на вкладке Пользователи и группы.
После завершения настройки установите для параметра Состояние подготовки значение Включено.
Нажмите кнопку "Сохранить", чтобы запустить службу подготовки Microsoft Entra.
Если используется синхронизация только назначенных пользователей и групп (рекомендуется), откройте вкладку Пользователи и группы и назначьте пользователей или группы, которые нужно синхронизировать.
После запуска начальной синхронизации для отслеживания хода выполнения можно использовать вкладку Журналы подготовки. На ней отображаются все действия, выполняемые службой подготовки с приложением. Дополнительные сведения о том, как читать журналы подготовки Microsoft Entra, см. в разделе "Отчеты о автоматической подготовке учетных записей пользователей".
Примечание.
Начальная операция синхронизации занимает больше времени, чем последующие. Последующие операции синхронизации выполняются примерно каждые 40 минут при условии, что служба запущена.
Публикация приложения в коллекции приложений Microsoft Entra
Если вы создаете приложение, используемое несколькими клиентами, сделайте его доступным в коллекции приложений Microsoft Entra. Это упростит организациям поиск приложения и настройку подготовки. Публикация приложения в коллекции Microsoft Entra и предоставление доступа к подготовке другим пользователям легко. Узнайте здесь, как это сделать. Корпорация Майкрософт работает с вами для интеграции приложения в коллекцию, тестирования конечной точки и выпуска документации по подключению для клиентов.
Контрольный список для подключения коллекции
Контрольный список поможет подключить приложение и предоставить клиентам возможность беспрепятственного развертывания. Сведения собираются от вас при подключении к коллекции.
- Поддержка конечной точки SCIM 2.0 пользователя и группы (требуется только одна, но рекомендуются обе).
- Поддержка по меньшей мере 25 запросов в секунду на каждого клиента, чтобы обеспечить подготовку и отмену подготовки без задержки для пользователей и групп (обязательно).
- Создание контактов по проектированию и поддержке для направления клиентов при подключению коллекции (обязательно)
- 3 тестовых учетных данных без истечения срока действия для приложения (обязательно)
- Поддержка предоставления кода авторизации OAuth или маркера длительного существования, как описано в примере (обязательный)
- Приложения OIDC должны иметь по крайней мере 1 роль (пользовательская или по умолчанию)
- Создание точки по проектированию и поддержке для поддержки клиентов после подключения коллекции (обязательно)
- Поддержка обнаружения схемы (обязательно)
- Поддержка обновления нескольких членств в группах с использованием одного запроса PATCH
- Общедоступное документирование конечной точки SCIM
Авторизация для использования соединителей подготовки в коллекции приложений
Спецификация SCIM не определяет схему для аутентификации и авторизации, характерную для SCIM, и основывается на использовании существующих отраслевых стандартов.
| Метод авторизации | Плюсы | Минусы | Поддержка |
|---|---|---|---|
| Имя пользователя и пароль (не рекомендуется или поддерживается идентификатором Microsoft Entra ID) | Простота реализации | Небезопасный. Этот пароль не подходит | Не поддерживается для новых приложений как из коллекции, так и не из коллекции. |
| Маркер носителя с длительным сроком действия | Для маркеров с длительным сроком действия не требуется наличие пользователя. Администраторы могут легко использовать их при настройке подготовки. | Обмен маркерами с длительным сроком действия с администратором может быть трудным, если только вы не используете незащищенные методы, такие как электронная почта. | Поддерживается для приложений как из коллекции, так и не из коллекции. |
| Предоставление кода авторизации OAuth | Маркеры доступа имеют более короткую жизнь, чем пароли, и имеют механизм автоматического обновления, который не имеет маркеров носителя. Реальный пользователь должен присутствовать во время начальной авторизации для добавления уровня ответственности. | Требуется наличие пользователя. Если пользователь покидает организацию, маркер недопустим, а авторизация должна быть завершена снова. | Поддерживается только для приложений из коллекции. Но для краткосрочных целей тестирования можно предоставить в пользовательском интерфейсе маркер доступа в качестве секретного маркера. Поддержка предоставления кода OAuth для приложений не из коллекции уже включена в список ожидаемых работ, как и поддержка настраиваемых URL-адресов для маркеров и проверки подлинности в приложениях из коллекции. |
| Предоставление учетных данных клиента OAuth | Маркеры доступа имеют более короткую жизнь, чем пароли, и имеют механизм автоматического обновления, который не имеет маркеров носителя. Предоставление кода авторизации и предоставление учетных данных клиента создают одинаковый тип маркера доступа, поэтому перемещение между этими методами прозрачно для API. Подготовку можно автоматизировать, а новые маркеры могут запрашиваться без вмешательства пользователя. | Поддерживается только для приложений из коллекции. Но для краткосрочных целей тестирования можно предоставить в пользовательском интерфейсе маркер доступа в качестве секретного маркера. Поддержка предоставления учетных данных клиента OAuth для приложений не из коллекции включена в наш список невыполненных работ. |
Примечание.
Не рекомендуется оставить поле маркера пустым в пользовательском пользовательском интерфейсе приложения для подготовки Microsoft Entra. Создаваемый маркер в основном доступен для целей тестирования.
Поток предоставления кода OAuth
Служба подготовки поддерживает предоставление кода авторизации. После отправки запроса на публикацию вашего приложения в коллекции, наша команда обратится к вам, чтобы собрать следующую информацию:
URL-адрес авторизации. URL-адрес клиента для получения авторизации от владельца ресурса через перенаправление агента пользователя. Пользователь переходит по этому URL-адресу для авторизации доступа.
URL-адрес для обмена маркерами. URL-адрес клиента для обмена данными авторизации для маркера доступа, обычно с аутентификацией клиента.
Идентификатор клиента. Сервер авторизации выдает зарегистрированному клиенту идентификатор клиента, который представляет собой уникальную строку с предоставленными клиентом сведениями о регистрации. Идентификатор клиента не является секретом. Он предоставляется владельцу ресурса, и не должен использоваться сам по себе для проверки подлинности клиента.
Секрет клиента. Секрет, созданный сервером авторизации. Это должно быть уникальное значение, известное только серверу авторизации.
Примечание.
URL-адрес авторизации и URL-адрес обмена маркерами сейчас не настраиваются для каждого клиента.
Примечание.
OAuth версии 1 не поддерживается из-за уязвимости секрета клиента. Поддерживается протокол OAuth версии 2.
При использовании потока предоставления кода OAuth необходимо поддерживать модель, в которой каждый клиент будет отправлять собственный идентификатор клиента и секрет клиента при настройке экземпляра подготовки. Не поддерживается отдельная пара идентификатора клиента и секрета клиента.
Настройка потока предоставления кода OAuth
Войдите в Центр администрирования Microsoft Entra как минимум администратор приложений.
Перейдите к >подготовке приложений>>identity Enterprise>и выберите "Авторизовать".
Войдите в Центр администрирования Microsoft Entra как минимум администратор приложений.
Перейдите к приложениям Identity>Applications>Enterprise.
Выберите приложение и перейдите к подготовке.
Выберите Разрешить.
Пользователи перенаправляются по URL-адресу авторизации (страница входа для стороннего приложения).
Администратор предоставляет стороннему приложению данные для входа.
Стороннее приложение перенаправляет пользователя обратно и предоставляет код предоставления
Служба подготовки вызывает URL-адрес маркера и предоставляет код предоставления. Стороннее приложение в ответ передает маркер доступа, маркер обновления и дату истечения срока действия маркера.
Когда начинается очередной цикл подготовки, служба проверяет допустимость текущего маркера и при необходимости обменивает его на новый. Маркер доступа передается в каждом запросе к приложению, и перед каждым из них проверяется допустимость запроса.
Примечание.
Пока нельзя настроить OAuth в приложении, не входящем в коллекцию, но вы можете вручную создать на сервере авторизации маркер доступа и ввести его как секретный маркер для приложения не из коллекции. Это позволяет проверить совместимость сервера SCIM со службой подготовки Microsoft Entra перед подключением к коллекции приложений, которая поддерживает предоставление кода OAuth.
Маркеры носителя OAuth с длительным сроком действия. Если приложение не поддерживает поток предоставления кода авторизации OAuth, создайте маркер носителя OAuth с длительным сроком действия, чтобы администратор мог использовать его для настройки интеграции подготовки. Маркер должен быть бессрочным или в противном случае задание подготовки помещается в карантин при истечении срока действия маркера.
Если вас интересуют другие способы проверки подлинности и авторизации, сообщите нам на UserVoice.
Контрольный список для запуска вывода коллекции на рынок
Чтобы повысить осведомленность и спрос на нашу совместную интеграцию, мы рекомендуем вам обновить существующую документацию и усилить эффективность интеграции в ваших маркетинговых каналах. Для поддержки запуска рекомендуется заполнить следующий контрольный список:
- Убедитесь, что команды по продажам и поддержке клиентов осведомлены о возможностях интеграции, надлежащим образом подготовлены и могут рассказать о таких возможностях. Кратко опишите все своим командам, предоставьте им ответы на часто задаваемые вопросы и материалы по продажам.
- Создание записи блога или пресс-релиза, описывающих совместную интеграцию, преимущества и способы начала работы. Пример: Imprivata и Microsoft Entra Press Release
- Используйте социальные медиа, такие как X, Facebook или LinkedIn, чтобы повысить интеграцию с клиентами. Обязательно включите @Microsoft идентификатор записи, чтобы мы могли повторить запись. Пример: Imprivata X Post
- Создайте или обновите маркетинговые страницы или веб-сайт (например, страницу интеграции, страницу партнера, страницу цен и т. д.), чтобы включить доступность совместной интеграции. Пример: страница интеграции с Pingboard, страница интеграции Smartsheet, страница цен Monday.com
- Создайте статью центра справки или техническую документацию о том, как клиенты могут приступить к работе. Пример: интеграция Envoy + Microsoft Entra.
- Оповещать клиентов о новой интеграции через взаимодействие с клиентами (ежемесячные информационные бюллетени, кампании по электронной почте, заметки о выпусках продуктов).
Следующие шаги
Разработка примера конечной точки SCIMАвтоматизация подготовки пользователей и ее отмены в приложениях SaaSНастройка сопоставлений атрибутов для подготовки пользователейНаписание выражений для сопоставления атрибутовФильтры области для подготовки пользователейУведомления, касающиеся подготовки учетной записиСписок руководств по интеграции приложений SaaS