Руководство. Разработка и планирование подготовки конечной точки SCIM в идентификаторе Microsoft Entra

Мақала
09/18/2024

Разработчиком приложений можно использовать API управления пользователями (SCIM) системы управления междоменных удостоверений (SCIM), чтобы включить автоматическую подготовку пользователей и групп между приложением и идентификатором Microsoft Entra. В этой статье описывается, как создать конечную точку SCIM и интегрировать ее со службой подготовки Microsoft Entra. Спецификация SCIM предоставляет общую схему пользователя для подготовки. При использовании с стандартами федерации, такими как SAML или OpenID Connect, SCIM предоставляет администраторам комплексное решение на основе стандартов для управления доступом.

Подготовка из идентификатора Microsoft Entra в приложение с помощью SCIM

SCIM 2.0 — это стандартизированное определение двух конечных точек: конечной /Users точки и конечной /Groups точки. В ней используются общие конечные точки REST API для создания, обновления и удаления объектов. SCIM состоит из предопределенной схемы для распространенных атрибутов, таких как имя группы, имя пользователя, имя пользователя, фамилия и электронная почта.

Приложения, которые предлагают REST API SCIM 2.0, могут уменьшить или устранить боль в работе с собственным API управления пользователями. Например, любой совместимый клиент SCIM знает, как сделать HTTP POST объекта JSON в конечной точке /Users для создания новой записи пользователя. Вместо того, чтобы использовать немного другой API для одних и того же основных действий, приложения, соответствующие стандарту SCIM, могут мгновенно воспользоваться преимуществами существующих клиентов, инструментов и кода.

Стандартная схема объектов пользователя и интерфейсы REST 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 с идентификатором 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	фамилия
workMail	emails[type eq "work"].value	Почта
управляющий	управляющий	управляющий
ярлык	`urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User:tag`	extensionAttribute1
статус	активный	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 также включает необходимые idexternalIdатрибуты и meta атрибуты.

Он помогает классифицировать атрибуты пользователей по умолчанию в идентификаторе Microsoft Entra с RFC SCIM, чтобы узнать, как настроить атрибуты сопоставляются между /User /Group идентификатором Microsoft Entra и конечной точкой SCIM.

В следующей таблице приведен пример атрибутов пользователя:

Пользователь Microsoft Entra	`urn:ietf:params:scim:schemas:extension:enterprise:2.0:User`
IsSoftDeleted	активный
отдел	`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 "факс"].value
givenName	name.givenName
jobTitle	титул
почта	emails[type eq "work"].value
mailNickname	externalId
управляющий	`urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager`
мобильный	phoneNumbers[type eq "mobile"].value
почтовый код	addresses[type eq "work"].postalCode
прокси-адреса	emails[type eq "other"]. Ценность
physical-Delivery-OfficeName	addresses[type eq "other"]. Форматированные
streetAddress	addresses[type eq "work"].streetAddress
фамилия	name.familyName
номер телефона	phoneNumbers[type eq "work"].value
user-PrincipalName	userName

В следующей таблице приведен пример атрибутов группы:

Группа Microsoft Entra	`urn:ietf:params:scim:schemas:core:2.0:Group`
displayName	displayName
члены	члены
objectId	externalId

Заметка

Вам не требуется поддерживать как пользователей, так и группы или все атрибуты, показанные здесь, это только ссылка на то, как атрибуты в идентификаторе Microsoft Entra часто сопоставляются со свойствами в протоколе SCIM.

Существует несколько конечных точек, определенных в RFC SCIM. Вы можете начать с конечной /User точки, а затем развернуть ее. В следующей таблице перечислены некоторые конечные точки SCIM:

Конечная точка	Описание
/Пользователь	Выполнение операций CRUD с объектом пользователя.
/Группа	Выполнение операций CRUD с объектом группы.
/Схемы	Набор атрибутов, поддерживаемых каждым клиентом и поставщиком услуг, может отличаться. Один поставщик услуг может включать `name`, `title`и, в то время как другой поставщик услуг использует `name`, `title`и `emailsphoneNumbers`. Конечная точка схем позволяет обнаружить поддерживаемые атрибуты.
/Масса	Массовые операции позволяют выполнять операции с большой коллекцией объектов ресурсов в одной операции (например, обновление членства в большой группе).
/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`группами.
Фильтр исключенныйAttributes=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, в частности значения операций PATCHop, как определено в разделе 3.5.2. Идентификатор Microsoft Entra выдает значения в виде "Добавить", "Заменить" и "Удалить".op
Идентификатор Microsoft Entra выполняет запросы на получение случайного пользователя и группы, чтобы убедиться, что конечная точка и учетные данные действительны. Он также выполняется как часть потока тестового подключения .
Поддержка HTTPS в конечной точке SCIM.
Пользовательские сложные и многозначные атрибуты поддерживаются, но идентификатор Microsoft Entra ID не имеет много сложных структур данных для извлечения данных из этих случаев. Атрибуты имени и значения можно легко сопоставить, но поток данных с сложными атрибутами с тремя или более подзатратами не поддерживается.
Значения подзаписи типа многозначных сложных атрибутов должны быть уникальными. Например, не может быть два разных адреса электронной почты с подтипом work.
Заголовок для всех ответов должен иметь тип контента: application/scim+json

Получение ресурсов:

Ответ на запрос или фильтрацию всегда должен быть ListResponse.
Microsoft Entra использует следующие операторы: eqand
Атрибут, на который можно запросить ресурсы, должен быть задан как соответствующий атрибут в приложении, см. в разделе "Настройка сопоставлений атрибутов подготовки пользователей".

/Пользователей:

Атрибут прав не поддерживается.
Все атрибуты, которые считаются уникальными пользователями, должны использоваться в рамках отфильтрованного запроса. (например, если уникальность пользователя оценивается как для имени пользователя, так и для электронной почты[тип eq "work"], get to /Users с фильтром должен разрешать как имя пользователя eq"user@contoso.com, так и сообщения электронной почты[тип eq "work"].value eq "user@contoso.com".

/Группы:

Группы являются необязательными, но поддерживаются только в том случае, если реализация SCIM поддерживает запросы PATCH .
Группы должны иметь уникальность в значении displayName для сопоставления с идентификатором Microsoft Entra и приложением SCIM. Уникальность не является требованием протокола SCIM, но является обязательным требованием для интеграции конечной точки SCIM с идентификатором Microsoft Entra.

/Schemas (обнаружение схемы):

Пример запроса и ответа
Обнаружение схем используется в определенных приложениях коллекции. Обнаружение схемы является единственным методом для добавления дополнительных атрибутов в схему существующего приложения SCIM коллекции. Обнаружение схем в настоящее время не поддерживается в пользовательском приложении SCIM, отличном от коллекции.
Если значение отсутствует, не отправляйте значения NULL.
Значения свойств должны быть регистрироваться верблюжьими буквами (например, readWrite).
Должен возвращать ответ списка.
Служба подготовки Microsoft Entra запрашивает /schemas при сохранении конфигурации подготовки. Запрос также выполняется при открытии страницы подготовки редактирования. Другие обнаруженные атрибуты отображаются клиентам в сопоставлениях атрибутов в списке целевых атрибутов. Обнаружение схем приводит только к добавлению дополнительных целевых атрибутов. Атрибуты не удаляются.

Подготовка пользователей и отмена подготовки пользователей

На следующей схеме показаны сообщения, которые идентификатор Microsoft Entra отправляет в конечную точку SCIM для управления жизненным циклом пользователя в хранилище удостоверений приложения.

Подготовка групп и отмена подготовки

Подготовка групп и отмена подготовки являются необязательными. При реализации и включении на следующем рисунке показаны сообщения, отправляемые идентификатором Microsoft Entra в конечную точку SCIM для управления жизненным циклом группы в хранилище удостоверений приложения. Эти сообщения отличаются от сообщений о пользователях двумя способами:

Запросы на получение групп указывают, что атрибут членов должен быть исключен из любого ресурса, предоставленного в ответ на запрос.
Запросы, чтобы определить, имеет ли ссылочный атрибут определенное значение, запросы к атрибуту членов.

На следующей схеме показана последовательность отмены подготовки группы:

Запросы и ответы протокола 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": []
}

Ответ

Создано HTTP/1.1 201

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "48af03ac28ad4fb88478",
    "externalId": "0a21f0f2-8d2a-4f8e-bf98-7363c4aed4ef",
    "meta": {
        "resourceType": "User",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
    },
    "userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName",
    },
    "active": true,
    "emails": [{
        "value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com",
        "type": "work",
        "primary": true
    }]
}

Получение пользователя

Просьба

GET /Users/5d48a0a0a8e9f04aa38008

Ответ (пользователь найден)

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"

Ответ

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
}

Получение пользователя по запросу — ноль результатов

Просьба

GET /Users?filter=userName eq "несуществующий пользователь"

Ответ

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

Ответ

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

Ответ

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

Ответ

{
    "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

Ответ

HTTP/1.1 204 Без содержимого

Групповые операции

Группы создаются с пустым списком участников.
displayName Используйте атрибут для запроса групп.
Обновление запроса PATCH группы должно получить 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"
    }
}

Ответ

Создано HTTP/1.1 201

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "id": "927fa2c08dcb4a7fae9e",
    "externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159",
    "meta": {
        "resourceType": "Group",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
        
    },
    "displayName": "displayName",
    "members": []
}

Получение группы

Просьба

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

Ответ

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=displayName eq "displayName" HTTP/1.1

Ответ

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

Ответ

HTTP/1.1 204 Без содержимого

Обновить группу [добавить участников]

Просьба

PATCH /Groups/a9962b9f99d4c4fac67 HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "Add",
        "path": "members",
        "value": [{
            "$ref": null,
            "value": "f648f8d5ea4e4cd38e9c"
        }]
    }]
}

Ответ

HTTP/1.1 204 Без содержимого

Обновить группу [Удалить участников]

Просьба

PATCH /Groups/a9962b9f99d4c4fac67 HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "Remove",
        "path": "members",
        "value": [{
            "$ref": null,
            "value": "f648f8d5ea4e4cd38e9c"
        }]
    }]
}

Ответ

HTTP/1.1 204 Без содержимого

Удаление группы

Просьба

DELETE /Groups/cdb1ce18f6594079d37 HTTP/1.1

Ответ

HTTP/1.1 204 Без содержимого

Обнаружение схемы

Просьба

GET /Schemas

Ответ

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 должны быть не менее 2048 бит.
Ключи 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 и предоставляется "AS IS". Взносы сообщества приветствуются для создания и поддержания кода.

Решение состоит из двух проектов, 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
DST Root CA X3

Пакет 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, для которого был выдан маркер.
- Аудитория маркера — это идентификатор приложения для приложения в коллекции. Приложения, зарегистрированные в одном клиенте, получают то же iss утверждение с запросами SCIM. Идентификатор приложения для всех пользовательских приложений — 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 основных средах для изменения параметров проверки подлинности на этапе разработки и включения самозаверяющего маркера.

Дополнительные сведения о нескольких средах в 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, являются:

Параметры. AlternateFilters.Count: 1
Параметры. AlternateFilters.ElementAt(0). AttributePath: externalId
Параметры. AlternateFilters.ElementAt(0). ComparisonOperator: ComparisonOperator.Equals
Параметры. 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 поставщика службы. Значение свойств объекта, предоставленного в качестве значения аргумента параметров, выглядит следующим образом:

Параметры. AlternateFilters.Count: 2
Параметры. AlternateFilters.ElementAt(x). AttributePath: "ID"
Параметры. AlternateFilters.ElementAt(x). ComparisonOperator: ComparisonOperator.Equals
Параметры. AlternateFilter.ElementAt(x). ComparisonValue: "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1e1e1e1"
Параметры. AlternateFilters.ElementAt(y). AttributePath: "manager"
Параметры. AlternateFilters.ElementAt(y). ComparisonOperator: ComparisonOperator.Equals
Параметры. AlternateFilter.ElementAt(y). ComparisonValue: "00aa00aa-bb11-cc22-dd33-44ee4ee44ee4ee4ee4ee"
Параметры. RequestedAttributePaths.ElementAt(0): "ID"
Параметры. 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`	Управляющий
`(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 с пустым сообщением SCIM ListResponse.
Если попытка подключиться к приложению выполнена успешно, нажмите кнопку "Сохранить ", чтобы сохранить учетные данные администратора.
В разделе "Сопоставления" есть два настраиваемых набора сопоставлений атрибутов: один для пользовательских объектов и один для объектов группы. Выберите каждый из них, чтобы просмотреть атрибуты, синхронизированные с идентификатором Microsoft Entra с приложением. Атрибуты, выбранные в качестве свойств сопоставления , используются для сопоставления пользователей и групп в приложении для операций обновления. Нажмите кнопку "Сохранить", чтобы зафиксировать любые изменения.

Заметка

При необходимости можно отключить синхронизацию объектов группы, отключив сопоставление "группы".
В разделе "Параметры" поле "Область" определяет, какие пользователи и группы синхронизируются. Выберите " Синхронизация только назначенных пользователей и групп" (рекомендуется), чтобы синхронизировать только пользователей и группы , назначенные на вкладке "Пользователи и группы ".
После завершения настройки задайте для параметра "Состояние подготовки" значение "Вкл.".
Нажмите кнопку "Сохранить", чтобы запустить службу подготовки Microsoft Entra.
При синхронизации только назначенных пользователей и групп (рекомендуется), выберите вкладку "Пользователи и группы ". Затем назначьте пользователей или группы, которые вы хотите синхронизировать.

После запуска начального цикла можно выбрать журналы подготовки на левой панели, чтобы отслеживать ход выполнения, в котором показаны все действия, выполненные службой подготовки в приложении. Дополнительные сведения о том, как читать журналы подготовки Microsoft Entra, см. в разделе "Отчеты о автоматической подготовке учетных записей пользователей".

Заметка

Начальный цикл занимает больше времени для выполнения более поздних синхронизаций, которые происходят примерно каждые 40 минут до запуска службы.

Публикация приложения в коллекции приложений Microsoft Entra

Если вы создаете приложение, используемое несколькими клиентами, сделайте его доступным в коллекции приложений Microsoft Entra. Организациям легко обнаружить приложение и настроить подготовку. Публикация приложения в коллекции Microsoft Entra и предоставление доступа к подготовке другим пользователям легко. Ознакомьтесь с инструкциями здесь. Корпорация Майкрософт работает с вами для интеграции приложения в коллекцию, тестирования конечной точки и выпуска документации по подключению для клиентов.

Контрольный список для подключения коллекции

Используйте контрольный список, чтобы быстро подключить приложение, и клиенты имеют удобный интерфейс развертывания. Сведения собираются от вас при подключении к коллекции.

Поддержка конечной точки пользователя и группы SCIM 2.0 (рекомендуется только один, но оба рекомендуется).
Поддержка по крайней мере 25 запросов в секунду на клиент, чтобы обеспечить подготовку пользователей и групп без задержки (обязательно)
Создание контактов по проектированию и поддержке для управления подключением к коллекции клиентов (обязательно)
3 неисключаемые тестовые учетные данные для приложения (обязательно)
Поддержка предоставления кода авторизации OAuth или маркера длительного существования, как описано в примере (обязательный)
Приложения OIDC должны иметь по крайней мере 1 роль (пользовательская или по умолчанию)
Создание точки связи и технической поддержки для поддержки клиентов после подключения к коллекции (обязательно)
Поддержка обнаружения схемы (обязательно)
Поддержка обновления нескольких членства в группах с помощью одного ИСПРАВЛЕНИЯ
Документируйте общедоступную конечную точку SCIM

Авторизация для соединителей подготовки в коллекции приложений

Спецификация SCIM не определяет схему scIM для проверки подлинности и авторизации и зависит от использования существующих отраслевых стандартов.

Метод авторизации	Плюсы	Минусы	Поддержка
Имя пользователя и пароль (не рекомендуется или поддерживается идентификатором Microsoft Entra ID)	Простота реализации	Небезопасный - Ваш Pa$$word не имеет значения	Не поддерживается для новых приложений коллекции или не из коллекции.
Долгоживущие маркеры носителя	Долгоживущие маркеры не требуют наличия пользователя. Они легко используются администраторами при настройке подготовки.	Долгоживущие маркеры могут быть трудно поделиться с администратором без использования небезопасных методов, таких как электронная почта.	Поддерживается для приложений коллекции и не из коллекции.
Предоставление кода авторизации 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.
Выберите приложение и перейдите к подготовке.
Выберите "Авторизовать".
1. Пользователи перенаправляются по URL-адресу авторизации (страница входа для стороннего приложения).
2. Администратор предоставляет учетные данные стороннему приложению.
3. Стороннее приложение перенаправляет пользователя обратно и предоставляет код предоставления
4. Служба подготовки вызывает 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 Automate для подготовки пользователей и отмены подготовки пользователей в приложениях SaaS Настройка сопоставлений атрибутов для выражений подготовки пользователей для сопоставленияатрибутов для фильтров области подготовки пользователей для уведомлений о подготовкеучетных записей для интеграции приложений SaaS

Бөлісу құралы:

Руководство. Разработка и планирование подготовки конечной точки SCIM в идентификаторе Microsoft Entra

Проектирование схемы пользователя и группы

Общие сведения о реализации MICROSOFT Entra SCIM

Общее:

Получение ресурсов:

/Пользователей:

/Группы:

/Schemas (обнаружение схемы):

Подготовка пользователей и отмена подготовки пользователей

Подготовка групп и отмена подготовки

Запросы и ответы протокола SCIM

Операции пользователей

Создание пользователя

Просьба

Ответ

Получение пользователя

Просьба

Ответ (пользователь найден)

Просьба

Ответ (пользователь не найден. Подробные сведения не требуются, только состояние.)

Получение пользователя по запросу

Просьба

Ответ

Получение пользователя по запросу — ноль результатов

Просьба

Ответ

Обновление свойств пользователя [свойства с несколькими значениями]

Просьба

Ответ

Обновление пользователей [свойства с одним значением]

Просьба

Ответ

Отключение пользователя

Просьба

Ответ

Удаление пользователя

Просьба

Ответ

Групповые операции

Создание группы

Просьба

Ответ

Получение группы

Просьба

Ответ

Получение группы по displayName

Просьба

Ответ

Обновить группу [атрибуты, не являющиеся членами]

Просьба

Ответ

Обновить группу [добавить участников]

Просьба

Ответ

Обновить группу [Удалить участников]

Просьба

Ответ

Удаление группы

Просьба

Ответ

Обнаружение схемы

Обнаружение схемы

Просьба

Ответ

Требования к безопасности

Диапазоны IP-адресов

Создание конечной точки SCIM

Создание пользовательской конечной точки SCIM

Обработка проверки подлинности конечной точки

Обработка подготовки и отмены подготовки пользователей

Интеграция конечной точки SCIM с службой подготовки Microsoft Entra

Начало работы

Публикация приложения в коллекции приложений Microsoft Entra

Контрольный список для подключения коллекции

Авторизация для соединителей подготовки в коллекции приложений

Поток предоставления кода OAuth

Настройка потока предоставления кода OAuth

Контрольный список запуска коллекции на рынок

Дальнейшие действия