Руководство. Разработка и планирование подготовки конечной точки 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, могут мгновенно воспользоваться преимуществами существующих клиентов, инструментов и кода.

Стандартная схема объектов пользователя и интерфейсы REST API для управления, определенные в SCIM 2.0 (RFC 7642, 7643, 7644) позволяют поставщикам удостоверений и приложениям более легко интегрироваться друг с другом. Разработчики приложений, создающие конечную точку SCIM, могут интегрироваться с любым клиентом, совместимым с SCIM, без необходимости выполнять пользовательскую работу.

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

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

2. Ознакомьтесь с реализацией Microsoft Entra SCIM. Узнайте, как служба подготовки Microsoft Entra реализована для моделирования обработки и ответа запросов протокола SCIM.

3. Создание конечной точки SCIM — конечная точка должна быть совместима с SCIM 2.0 для интеграции со службой подготовки Microsoft Entra. В качестве варианта используйте библиотеки и примеры кода microsoft Common Language Infrastructure (CLI) для создания конечной точки. Эти примеры предназначены только для справки и тестирования; Рекомендуется использовать их в качестве зависимостей в рабочем приложении.

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

5. [Необязательно] Опубликуйте приложение в коллекции приложений Microsoft Entra. Чтобы пользователи могли легко обнаруживать приложение и легко настраивать подготовку.

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

Для каждого приложения требуются различные атрибуты для создания пользователя или группы. Запустите интеграцию, определив необходимые объекты (пользователи, группы) и атрибуты (имя, менеджер, название задания и т. д.), необходимые приложению.

Стандарт SCIM определяет схему для управления пользователями и группами.

Для основной схемы пользователя требуются только три атрибута (все остальные атрибуты являются необязательными):

• id, определенный идентификатор поставщика услуг
• userName— уникальный идентификатор пользователя (обычно сопоставляется с именем участника-пользователя Microsoft Entra)
• meta, метаданные только для чтения, поддерживаемые поставщиком услуг

Помимо основной схемы пользователя, стандарт SCIM определяет расширение корпоративного пользователя с моделью расширения пользовательской схемы в соответствии с потребностями приложения.

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

Чтобы создать схему, выполните следующие действия.

1. Перечислите необходимые атрибуты, а затем классифицируйте атрибуты, необходимые для проверки подлинности (например, loginName и email). Атрибуты необходимы для управления жизненным циклом пользователя (например, состоянием или активным) и всеми другими атрибутами, необходимыми для работы приложения (например, диспетчера, тега).

2. Проверьте, определены ли атрибуты в основной пользовательской схеме или корпоративной схеме пользователей. В противном случае необходимо определить расширение для пользовательской схемы, которая охватывает отсутствующие атрибуты. См. пример расширения для пользователя, чтобы разрешить подготовку пользователя tag.

3. Сопоставление атрибутов 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":"[email protected]",
     "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"
   }
}   

Он помогает классифицировать атрибуты пользователей по умолчанию в идентификаторе 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

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

Конечная точка	Описание
/Пользователь	Выполнение операций CRUD с объектом пользователя.
/Группа	Выполнение операций CRUD с объектом группы.
/Схемы	Набор атрибутов, поддерживаемых каждым клиентом и поставщиком услуг, может отличаться. Один поставщик услуг может включать name, titleи, в то время как другой поставщик услуг использует name, titleи emailsphoneNumbers. Конечная точка схем позволяет обнаружить поддерживаемые атрибуты.
/Масса	Массовые операции позволяют выполнять операции с большой коллекцией объектов ресурсов в одной операции (например, обновление членства в большой группе).
/ServiceProviderConfig	Содержит сведения о функциях стандарта SCIM, которые поддерживаются, например, ресурсы, поддерживаемые и метод проверки подлинности.
/ResourceTypes	Задает метаданные о каждом ресурсе.

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

Служба подготовки Microsoft Entra предназначена для поддержки API управления пользователями SCIM 2.0.

В спецификации протокола 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"[email protected], так и сообщения электронной почты[тип eq "work"].value eq "[email protected]".

/Группы:

• Группы являются необязательными, но поддерживаются только в том случае, если реализация 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 и примерами ожидаемых ответов. Для получения наилучших результатов следует закодировать приложение для обработки этих запросов в этом формате и выдавать ожидаемые ответы.

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

• Создание пользователя (ответ запроса / )
• Получение пользователя (ответ запроса / )
• Получение пользователя по запросу (ответ запроса / )
• Получение пользователя по запросу — ноль результатов (ответ на запрос / )
• Обновление пользователей [свойства с несколькими значениями] (ответ запроса / )
• Обновление пользователей [свойства с одним значением] (ответ запроса / )
• Отключение пользователя (ответ запроса / )
• Удаление пользователя (ответ запроса / )

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

• Создание группы (ответ запроса / )
• Получение группы (ответ запроса / )
• Получение группы по 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": "[email protected]"
    }],
    "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": "[email protected]",
        "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": "[email protected]",
        "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": "[email protected]",
            "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": "[email protected]"
            },
            {
            "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": "[email protected]",
        "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": "[email protected]"
    }]
}

Ответ

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": "[email protected]",
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName",
    },
    "active": true,
    "emails": [{
        "value": "[email protected]",
        "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": "[email protected]",
    "name": {
        "familyName": "Harris",
        "givenName": "Larry"
    },
    "active": false,
    "emails": [
        {
            "value": "[email protected]",
            "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, а затем протестируйте ее, выполнив примеры запросов и ответов.

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

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":"[email protected]",
   "active":true,
   "addresses":null,
   "displayName":"Joy Young",
   "emails": [
     {
       "type":"work",
       "value":"[email protected]",
       "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.

Обратитесь к поставщику приложений или документации поставщика приложений, чтобы узнать о совместимости с этими требованиями.

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

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

Чтобы подключить приложение, поддерживающее SCIM, выполните следующие действия.

1. Войдите в Центр администрирования Microsoft Entra как минимум администратор приложений.

2. Перейдите к приложениям Identity>Applications>Enterprise.

3. Отображается список всех настроенных приложений, включая приложения, добавленные из коллекции.

4. Выберите +Создать приложение>+ Создать собственное приложение.

5. Введите имя приложения, выберите параметр "Интегрировать любое другое приложение, которое вы не найдете в коллекции" и нажмите кнопку "Добавить ", чтобы создать объект приложения. Новое приложение добавляется в список корпоративных приложений и открывается на экране управления приложениями.

   На следующем снимка экрана показана коллекция приложений Microsoft Entra:

   

6. На экране управления приложениями выберите "Подготовка " на левой панели.

7. В меню "Режим подготовки" выберите "Автоматически".

   На следующем снимке экрана показана настройка параметров подготовки в Центре администрирования Microsoft Entra:

   

8. В поле URL-адрес клиента введите URL-адрес конечной точки SCIM приложения. Пример: https://api.contoso.com/scim/

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

   Заметка

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

10. Выберите "Проверить подключение", чтобы идентификатор Microsoft Entra пытался подключиться к конечной точке SCIM. Если попытка завершается ошибкой, отображается информация об ошибке.

    Заметка

    Проверка подключения запрашивает конечную точку SCIM для пользователя, который не существует, используя случайный GUID в качестве соответствующего свойства, выбранного в конфигурации Microsoft Entra. Ожидаемый правильный ответ — HTTP 200 OK с пустым сообщением SCIM ListResponse.

11. Если попытка подключиться к приложению выполнена успешно, нажмите кнопку "Сохранить ", чтобы сохранить учетные данные администратора.

12. В разделе "Сопоставления" есть два настраиваемых набора сопоставлений атрибутов: один для пользовательских объектов и один для объектов группы. Выберите каждый из них, чтобы просмотреть атрибуты, синхронизированные с идентификатором Microsoft Entra с приложением. Атрибуты, выбранные в качестве свойств сопоставления , используются для сопоставления пользователей и групп в приложении для операций обновления. Нажмите кнопку "Сохранить", чтобы зафиксировать любые изменения.

    Заметка

    При необходимости можно отключить синхронизацию объектов группы, отключив сопоставление "группы".

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

14. После завершения настройки задайте для параметра "Состояние подготовки" значение "Вкл.".

15. Нажмите кнопку "Сохранить", чтобы запустить службу подготовки Microsoft Entra.

16. При синхронизации только назначенных пользователей и групп (рекомендуется), выберите вкладку "Пользователи и группы ". Затем назначьте пользователей или группы, которые вы хотите синхронизировать.

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

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

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

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

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

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

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

Метод авторизации	Плюсы	Минусы	Поддержка
Имя пользователя и пароль (не рекомендуется или поддерживается идентификатором Microsoft Entra ID)	Простота реализации	Небезопасный - Ваш Pa$$word не имеет значения	Не поддерживается для новых приложений коллекции или не из коллекции.
Долгоживущие маркеры носителя	Долгоживущие маркеры не требуют наличия пользователя. Они легко используются администраторами при настройке подготовки.	Долгоживущие маркеры могут быть трудно поделиться с администратором без использования небезопасных методов, таких как электронная почта.	Поддерживается для приложений коллекции и не из коллекции.
Предоставление кода авторизации OAuth	Маркеры доступа имеют более короткую жизнь, чем пароли, и имеют механизм автоматического обновления, который не имеет маркеров носителя. Реальный пользователь должен присутствовать во время первоначальной авторизации, добавив уровень подотчетности.	Требуется, чтобы пользователь присутствовал. Если пользователь покидает организацию, маркер недопустим, а авторизация должна быть завершена снова.	Поддерживается для приложений коллекции, но не для приложений, отличных от коллекции. Однако вы можете предоставить маркер доступа в пользовательском интерфейсе в качестве секретного маркера для краткосрочных целей тестирования. Поддержка предоставления кода OAuth в коллекции находится в невыполненной работе, помимо поддержки настраиваемых URL-адресов проверки подлинности или маркеров в приложении коллекции.
Предоставление учетных данных клиента OAuth	Маркеры доступа имеют более короткую жизнь, чем пароли, и имеют механизм автоматического обновления, который не имеет маркеров носителя. Предоставление кода авторизации и предоставление учетных данных клиента создают один и тот же тип маркера доступа, поэтому переход между этими методами является прозрачным для API. Подготовка может быть автоматизирована, а новые маркеры можно автоматически запрашивать без взаимодействия с пользователем.		Поддерживается для приложений коллекции, но не для приложений, отличных от коллекции. Однако вы можете предоставить маркер доступа в пользовательском интерфейсе в качестве секретного маркера для краткосрочных целей тестирования. Поддержка предоставления учетных данных клиента OAuth в коллекции, отличной от коллекции, находится в нашем невыполненной работе.

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

Служба подготовки поддерживает предоставление кода авторизации и после отправки запроса на публикацию приложения в коллекции наша команда будет работать с вами, чтобы получить следующие сведения:

• URL-адрес авторизации, URL-адрес клиента для получения авторизации от владельца ресурса с помощью перенаправления агента пользователя. Пользователь перенаправляется на этот URL-адрес для авторизации доступа.

• URL-адрес обмена маркерами, URL-адрес клиента для обмена предоставлением авторизации для маркера доступа, как правило, с проверкой подлинности клиента.

• Идентификатор клиента, сервер авторизации выдает зарегистрированный клиент идентификатор клиента, который является уникальной строкой, представляющей сведения о регистрации, предоставленные клиентом. Идентификатор клиента не является секретом; он предоставляется владельцу ресурса и не должен использоваться только для проверки подлинности клиента.

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

При использовании потока предоставления кода OAuth необходимо поддерживать модель, в которой каждый клиент будет отправлять собственный идентификатор клиента и секрет клиента при настройке экземпляра подготовки. Не поддерживается отдельная пара идентификатора клиента и секрета клиента.

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

1. Войдите в Центр администрирования Microsoft Entra как минимум администратор приложений.

2. Перейдите к >подготовке приложений>>identity Enterprise>и выберите "Авторизовать".

3. Войдите в Центр администрирования Microsoft Entra как минимум администратор приложений.

4. Перейдите к приложениям Identity>Applications>Enterprise.

5. Выберите приложение и перейдите к подготовке.

6. Выберите "Авторизовать".

   1. Пользователи перенаправляются по URL-адресу авторизации (страница входа для стороннего приложения).

   2. Администратор предоставляет учетные данные стороннему приложению.

   3. Стороннее приложение перенаправляет пользователя обратно и предоставляет код предоставления

   4. Служба подготовки вызывает URL-адрес маркера и предоставляет код предоставления. Стороннее приложение отвечает с помощью маркера доступа, маркера обновления и даты окончания срока действия.

7. Когда начинается цикл подготовки, служба проверяет, является ли текущий маркер доступа допустимым и обменивается им на новый маркер при необходимости. Маркер доступа предоставляется в каждом запросе, сделанном приложению, и срок действия запроса проверяется перед каждым запросом.

Долгоживущие маркеры носителя OAuth. Если приложение не поддерживает поток предоставления кода авторизации OAuth, вместо этого создайте маркер носителя OAuth, который администратор может использовать для настройки интеграции подготовки. Маркер должен быть бессрочным или в противном случае задание подготовки помещается в карантин при истечении срока действия маркера.

Для получения дополнительных методов проверки подлинности и авторизации сообщите нам о UserVoice.

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

Чтобы повысить осведомленность и спрос на совместную интеграцию, мы рекомендуем обновить существующую документацию и повысить интеграцию в маркетинговых каналах. Рекомендуется выполнить следующий контрольный список для поддержки запуска:

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