Учебник: Разработка и планирование обеспечения SCIM-ендпойнта в Microsoft Entra ID

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

3. Сопоставление атрибутов SCIM с атрибутами пользователя в Microsoft Entra ID. Если один из атрибутов, определенных в конечной точке SCIM, не имеет четкого аналога в схеме пользователя Microsoft Entra, укажите администратору клиента расширение схемы или используйте атрибут расширения, как показано в примере для свойства tags.

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

В приведенных ниже полезных данных 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"
   }
}   

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

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

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

В RFC SCIM определено несколько конечных точек. Вы можете начать с конечной точки /User и двигаться от нее дальше. Некоторые конечные точки SCIM приведены в следующей таблице.

Понимание реализации SCIM в Microsoft Entra

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

В рамках спецификации протокола SCIM 2.0 приложения должны соответствовать следующим требованиям:

Используйте общие рекомендации при реализации конечной точки SCIM, чтобы обеспечить совместимость с Microsoft Entra ID:

Общие сведения:

• id является обязательным свойством для всех ресурсов. Каждый ответ, возвращающий ресурс, должен гарантировать наличие этого свойства у каждого ресурса, за исключением ListResponse с нулевым числом элементов.
• Значения, отправленные, должны храниться в том же формате, который они были отправлены. Недопустимые значения должны быть отклонены с информативным и практичным сообщением об ошибке. Преобразования данных не должны происходить между данными из Microsoft Entra ID и данных, хранящихся в приложении SCIM. (например) номер телефона, отправленный как 55555555555, не должен быть сохранен и затем возвращен как + 5 (555) 555-5555)
• Не обязательно включать весь ресурс в ответ PATCH.
• Не требуйте совпадения с учетом регистра для структурных элементов в SCIM, в частности для значений операций PATCHop, как это указано в разделе 3.5.2. Microsoft Entra ID выдает значения op как Add, Replace и Remove.
• Microsoft Entra ID выполняет запросы на получение случайного пользователя и группы, чтобы убедиться, что конечная точка доступа и учетные данные действительны. Он также выполняется как часть потока тестового подключения .
• Поддержка HTTPS на конечной точке SCIM.
• Поддерживаются пользовательские сложные и многозначные атрибуты, но Microsoft Entra ID не обладает большим количеством сложных структур данных для извлечения данных в таких случаях. Атрибуты имени и значения можно легко сопоставить, но передача данных на сложные атрибуты с тремя или более податрибутами не поддерживается.
• Значения податрибута type для многозначных сложных атрибутов должны быть уникальными. Например, не может быть двух разных адресов электронной почты с подтипом work.
• Заголовок для всех ответов должен иметь content-Type: application/scim+json

Извлечение ресурсов:

• Ответ на запрос или запрос фильтра всегда должен быть ListResponse.
• Microsoft Entra использует исключительно следующие операторы: eq, and
• Атрибут, на основании которого можно запрашивать ресурсы, должен быть задан как соответствующий атрибут в приложении. Подробности см. в разделе «Настройка сопоставлений атрибутов для простановки пользователей».

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

• Атрибут прав не поддерживается.
• Все атрибуты, которые считаются ответственными за уникальность пользователей, должны использоваться в запросах с фильтрацией. Например, если оценка уникальности пользователей выполняется и для userName, и для emails[type eq "work"], то запрос GET к /Users с фильтром должен разрешать оба запроса: userName eq "user@contoso.com" и emails[type eq "work"].value eq "user@contoso.com".

/Группы:

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

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

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

Предоставление и удаление доступа пользователей

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

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

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

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

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

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

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

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

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

Операции с группой

• Создание группы (Запрос / Ответ)
• Получить группу (Запрос / Ответ)
• Получение группы по *displayName* (Запрос / Ответ)
• Обновление группы [атрибуты, не относящиеся к элементу] (Запрос / Ответ)
• Обновление группы [добавить элементы] (Запрос / Ответ)
• Обновление группы [удалить элементы] (Запрос / Ответ)
• Удаление группы (Запрос / Ответ)

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

• обнаружение схемы (запрос / ответ).

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

• Использование атрибутов userName или emails[type eq "work"] для запроса пользователей.

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

Запрос

POST /Пользователи

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

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

Проверки, выполняемые проверятелем SCIM

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

• POST /Users — создает нового пользователя с полными полезными данными JSON.
  • Конечная точка возвращает HTTP 201
  • Ответ POST содержит созданный идентификатор пользователя
• GET /Users?filter={joinProperty} eq "value" — проверяет создание путем фильтрации по свойству присоединения.
  • Get возвращает созданного пользователя
  • Возвращаемые значения из GET соответствуют переданным значениям из запроса POST (зависит от конечной точки).
• DELETE /Users — очищает тестового пользователя. -Вызывается только в том случае, если поддерживается жесткое удаление

Создание повторяющегося пользователя

• POST /Users — попытка создать пользователя с использованием идентичных данных (с тем же уникальным или объединяющим атрибутом), как у существующего пользователя.
  • Возврат HTTP 201 при первом запросе на создание
  • Возврат HTTP 409 во втором запросе на создание

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

Запрос

GET /Users/5d48a0a8e9f04aa38008

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

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "5d48a0a8e9f04aa38008",
    "externalId": "58342554-38d6-4ec8-948c-50044d0a33fd",
    "meta": {
        "resourceType": "User",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
    },
    "userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName",
    },
    "active": true,
    "emails": [{
        "value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com",
        "type": "work",
        "primary": true
    }]
}

Запрос

GET /Users/5171a35d82074e068ce2

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

HTTP/1.1 404 не найден

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:Error"
    ],
    "status": "404",
    "detail": "Resource 23B51B0E5D7AE9110A49411D@7cca31655d49f3640a494224 not found"
}

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

Запрос

GET /Users?filter=userName eq "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee"

Ответ

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "totalResults": 1,
    "Resources": [{
        "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
        "id": "2441309d85324e7793ae",
        "externalId": "7fce0092-d52e-4f76-b727-3955bd72c939",
        "meta": {
            "resourceType": "User",
            "created": "2018-03-27T19:59:26.000Z",
            "lastModified": "2018-03-27T19:59:26.000Z"
            
        },
        "userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "name": {
            "familyName": "familyName",
            "givenName": "givenName"
        },
        "active": true,
        "emails": [{
            "value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com",
            "type": "work",
            "primary": true
        }]
    }],
    "startIndex": 1,
    "itemsPerPage": 20
}

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

Запрос

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

Ответ

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

Проверки, выполняемые проверятелем SCIM

Добавление атрибутов

• POST /Users — создает ресурс пользователя
  • Успех HTTP 2xxx
• PATCH /Users/{id} — использует документ исправления JSON (с операцией добавления) для вставки дополнительных не обязательных атрибутов.
• GET /Users?filter={joiningProperty} eq "value" — извлекает пользователя, чтобы проверить добавленные атрибуты.
  • Пользователь возвращается
  • Вставляемые атрибуты теперь присутствуют в пользователе

Замена атрибутов пользователя

• POST /Users — создает ресурс пользователя
  • Успех HTTP 2xxx
• PATCH /Users/{id} — отправляет документ исправления JSON (с помощью операции замены) для обновления одного или нескольких атрибутов.
• GET /Users?filter={joiningProperty} eq "value" — проверяет правильность применения обновленных атрибутов.
  • Пользователь возвращается
  • Обновленные атрибуты присутствуют в пользователе

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

• POST /Users — создает ресурс пользователя
  • Успех HTTP 2xxx
• PATCH /Users/{id} — обновляет свойство присоединения (например, userName) с помощью документа исправления JSON.
• GET /Users?filter={joinProperty} eq "newValue" — подтверждает обновление свойства присоединения.
  • Свойство соединения обновляется у пользователя

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

Запрос

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

Проверки, выполняемые проверятелем SCIM

Обновление активного атрибута до false

• POST /Users/ — создает ресурс на основе схемы
  • Успех HTTP 2xxx
  • Пользователь с отключенным доступом должен быть возвращен по запросу GET
• PATCH /Users/{id} — создает документ JSON-патч, который задает для атрибута "active" значение false.
  • Успех HTTP 2xxx
• GET /Users?filter={joinProperty} eq "value" — извлекает пользователя, чтобы подтвердить, что активный атрибут теперь имеет значение false.
  • Возвращенная запись пользователя должна иметь ACTIVE=FALSE"

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

Запрос

DELETE /Users/5171a35d82074e068ce2 HTTP/1.1

Ответ

HTTP/1.1 204 No Content

Операции с группой

• Группы создаются с пустым списком участников.
• Используйте атрибут 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 Created

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

Проверки, выполняемые проверятелем SCIM

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

• POST /Groups — создает новую группу с полным JSON-пакетом.
  • Конечная точка возвращает HTTP 201
  • Ответ POST содержит созданный идентификатор группы
• GET /Group?filter={joinProperty} eq "value" — проверяет создание путем фильтрации по свойству присоединения.
  • Get возвращает созданную группу
  • Возвращаемые значения из GET соответствуют переданным значениям из запроса POST (зависит от конечной точки).
• DELETE /Groups — очищает тестового пользователя.
  • Вызывается только в том случае, если поддерживается жесткое удаление

Создание повторяющихся групп

• POST /Groups — попытка создать группу, используя одинаковый уникальный атрибут присоединения, который уже используется в существующей группе.
  • Возврат HTTP 201 при первом запросе на создание
  • Возврат HTTP 409 во втором запросе на создание

Получить группу

Запрос

GET /Groups/40734ae655284ad3abcc?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&filter=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 No Content

Проверки, выполняемые проверятелем SCIM

Обновление атрибутов группы

• POST /Groups — создает новый ресурс группы, позволяющий обновлять атрибуты
  • POST возвращает HTTP 2xx
• PATCH /Groups/{id} — отправляет документ исправления JSON с помощью операции замены для обновления одного или нескольких атрибутов существующей группы (за исключением членов).
  • PATCH возвращает успех (HTTP 2xx)
• GET /Groups?filter={joiningProperty} eq "value" — подтверждает правильность обновления атрибутов группы.
  • GET возвращает исправленную группу
  • Атрибуты группы, которая возвращается, совпадают с измененными атрибутами в запросе PATCH.

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

Запрос

PATCH /Groups/a99962b9f99d4c4fac67 HTTP/1.1

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

Ответ

HTTP/1.1 204 No Content

Проверки, выполняемые проверятелем SCIM

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

• POST /Groups — создает новый ресурс группы для добавления участника в
  • POST возвращает HTTP 2xx
• POST /Users — создает новый ресурс пользователя, который будет использоваться в качестве члена группы.
  • POST возвращает HTTP 2xx
• PATCH /Groups/{id} — добавляет идентификатор только что созданного пользователя в группу с помощью документа исправления JSON.
  • Исправление возвращает успешное выполнение

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

Запрос

PATCH /Groups/a99962b9f99d4c4fac67 HTTP/1.1

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

Ответ

HTTP/1.1 204 No Content

Удалить группу

Запрос

DELETE /Groups/cdb1ce18f65944079d37 HTTP/1.1

Ответ

HTTP/1.1 204 No Content

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

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

Запрос

GET /Схемы

Ответ

HTTP/1.1 200 OK

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "itemsPerPage": 50,
    "startIndex": 1,
    "totalResults": 3,
    "Resources": [
  {
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
    "id" : "urn:ietf:params:scim:schemas:core:2.0:User",
    "name" : "User",
    "description" : "User Account",
    "attributes" : [
      {
        "name" : "userName",
        "type" : "string",
        "multiValued" : false,
        "description" : "Unique identifier for the User, typically
used by the user to directly authenticate to the service provider.
Each User MUST include a non-empty userName value.  This identifier
MUST be unique across the service provider's entire set of Users.
REQUIRED.",
        "required" : true,
        "caseExact" : false,
        "mutability" : "readWrite",
        "returned" : "default",
        "uniqueness" : "server"
      },                
    ],
    "meta" : {
      "resourceType" : "Schema",
      "location" :
        "/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:User"
    }
  },
  {
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
    "id" : "urn:ietf:params:scim:schemas:core:2.0:Group",
    "name" : "Group",
    "description" : "Group",
    "attributes" : [
      {
        "name" : "displayName",
        "type" : "string",
        "multiValued" : false,
        "description" : "A human-readable name for the Group.
REQUIRED.",
        "required" : false,
        "caseExact" : false,
        "mutability" : "readWrite",
        "returned" : "default",
        "uniqueness" : "none"
      },
    ],
    "meta" : {
      "resourceType" : "Schema",
      "location" :
        "/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:Group"
    }
  },
  {
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
    "id" : "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
    "name" : "EnterpriseUser",
    "description" : "Enterprise User",
    "attributes" : [
      {
        "name" : "employeeNumber",
        "type" : "string",
        "multiValued" : false,
        "description" : "Numeric or alphanumeric identifier assigned
to a person, typically based on order of hire or association with an
organization.",
        "required" : false,
        "caseExact" : false,
        "mutability" : "readWrite",
        "returned" : "default",
        "uniqueness" : "none"
      },
    ],
    "meta" : {
      "resourceType" : "Schema",
      "location" :
"/v2/Schemas/urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    }
  }
]
}

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

Версии протокола TLS

Единственной приемлемой версией протокола является TLS 1.2. Другая версия SSL/TLS не разрешена.

• Ключи RSA должны составлять не менее 2 048 бит.
• Ключи ECC должны иметь по крайней мере 256 бит, созданных с помощью допустимой эллиптической кривой

Длина ключей

Все службы должны использовать сертификаты X. 509, созданные с использованием криптографических ключей достаточной длины, то есть:

Комплекты шифров

Все службы должны быть настроены для использования следующих наборов шифров в точном порядке, указанном в примере. Если у вас есть только сертификат RSA, установленные наборы шифров ECDSA не оказывают никакого влияния.

Минимальный уровень наборов шифров TLS 1.2:

• TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
• TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
• TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
• TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
• TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
• TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
• TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
• TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384

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

В настоящее время служба предоставления Microsoft Entra работает в диапазонах IP-адресов для Microsoft Entra ID, как указано здесь. Можно добавить диапазоны IP-адресов, перечисленные в теге AzureActiveDirectory, для разрешения трафика из службы подготовки Microsoft Entra в приложение. Необходимо тщательно просмотреть список диапазонов IP-адресов для вычисления адресов. Например, адрес 40.126.25.32 может быть представлен в списке диапазонов IP-адресов как 40.126.0.0/18. Список диапазонов IP-адресов можно также получить программно, используя приведенный ниже API.

Microsoft Entra ID также поддерживает решение на основе агента для обеспечения подключения к приложениям в частных сетях (локальных, размещенных в Azure, размещенных в AWS и т. д.). Клиенты могут развернуть упрощенный агент, который обеспечивает подключение к Microsoft Entra ID без открытия входящих портов на сервере в частной сети. Подробнее см. здесь.

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

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

Сведения о создании конечной точки SCIM, а также примеры см. в руководстве Разработка примера конечной точки SCIM.

Пример кода открытый код .NET Core reference, опубликованный командой подготовки Microsoft Entra, является одним из таких ресурсов, которые могут начать разработку. Создайте конечную точку SCIM, а затем протестируйте ее, выполнив примеры запросов и ответов.

Решение состоит из двух проектов, Майкрософт. SCIM и Майкрософт. SCIM. WebHostSample.

Майкрософт. Проект SCIM — это библиотека, которая определяет компоненты веб-службы, соответствующие спецификации SCIM. Он объявляет интерфейс Майкрософт. SCIM. IProvider, запросы преобразуются в вызовы методов поставщика, которые будут запрограммированы для работы в хранилище удостоверений.

Проект Майкрософт.SCIM.WebHostSample — это веб-приложение ASP.NET Core, основанное на шаблоне Empty. Он позволяет развертывать пример кода как автономный, размещенный в контейнерах или в Internet Information Services. Он также реализует интерфейс Майкрософт.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;
• ГлобалСайн
• Go Daddy
• VeriSign;
• WoSign.
• Корневой ЦС X3 DST

Пакет SDK для .NET Core включает сертификат разработки HTTPS, используемый во время разработки. Сертификат устанавливается в рамках первого сеанса запуска. В зависимости от того, как вы запускаете веб-приложение ASP.NET Core, прослушивает другой порт:

• Майкрософт. SCIM. WebHostSample: https://localhost:5001
• IIS Express: https://localhost:44359

Дополнительные сведения о HTTPS в ASP.NET Core см. по следующей ссылке: Enforce HTTPS в ASP.NET Core

Обработка аутентификации на конечной точке

Запросы от службы подготовки Microsoft Entra включают токен носителя OAuth 2.0. Сервер авторизации выдает маркер носителя. Microsoft Entra ID является примером доверенного сервера авторизации. Настройте службу подготовки Microsoft Entra для использования одного из следующих токенов.

• Токен с долговечным сроком действия. Если для конечной точки SCIM требуется маркер носителя OAuth от издателя, отличного от Microsoft Entra ID, скопируйте необходимый маркер носителя OAuth в необязательное поле Secret Token. В среде разработки можно использовать маркер тестирования из конечной точки /scim/token. Маркеры тестирования не следует использовать в рабочих средах.

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

  • Приложение, которое получает запросы, должно убедиться, что издателем токена является Microsoft Entra ID для ожидаемого арендатора Microsoft Entra.
  • Утверждение iss идентифицирует издателя токена. Например, "iss":"https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/". В этом примере основной адрес для значения утверждения https://sts.windows.net указывает Microsoft Entra ID как издателя, в то время как относительный сегмент адреса aaaabbbb-0000-cccc-1111-dddd2222eeee является уникальным идентификатором клиента Microsoft Entra, для которого был выдан токен.
  • Аудитория маркера — это идентификатор приложения для приложения в галерее. Приложения, зарегистрированные в одном клиенте, получают одно и то же iss заявление вместе с запросами SCIM. Для всех пользовательских приложений используется идентификатор 8adf8e6e-67b2-4cf2-a259-e3dc5476c621. Маркер, созданный Microsoft Entra ID, должен использоваться только для тестирования. Его не следует применять в рабочих средах.

В примере кода запросы проверяются подлинность с помощью пакета Майкрософт.AspNetCore.Authentication.JwtBearer. Следующий код обеспечивает, что запросы к любому из конечных точек службы аутентифицируются с помощью токена доступа, выданного Microsoft Entra ID для указанного арендатора.

public void ConfigureServices(IServiceCollection services)
{
    if (_env.IsDevelopment())
    {
        ...
    }
    else
    {
        services.AddAuthentication(options =>
        {
            options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
            options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
        })
            .AddJwtBearer(options =>
            {
                options.Authority = " https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/";
                options.Audience = "8adf8e6e-67b2-4cf2-a259-e3dc5476c621";
                ...
            });
    }
    ...
}

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

Пример кода использует среды ASP.NET Core для изменения параметров аутентификации на этапе разработки и использования самоподписанного токена.

Дополнительные сведения о нескольких средах в ASP.NET Core см. в разделе Использовать несколько сред в 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 ID запрашивает службу для пользователя с значением атрибута externalId, соответствующим значению атрибута mailNickname пользователя в Microsoft Entra ID. Запрос выражается как запрос HTTP (протокол передачи гипертекста), например, где jyoung представляет собой пример почтового псевдонима пользователя в Microsoft Entra ID.

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: Оператор сравнения.Равно
• Параметры.AlternateFilter.ElementAt(0).ComparisonValue: "jyoung"

Пример 2. Подготовка пользователя

Если ответ на запрос к конечной точке SCIM для пользователя со значением атрибута externalId, которое соответствует значению атрибута mailNickname пользователя, не возвращает никаких пользователей, то Microsoft Entra ID запрашивает у службы подготовить пользователя, соответствующего пользователю в Microsoft Entra ID. Вот пример такого запроса:

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);

В запросе на подготовку пользователей значение аргумента ресурса является экземпляром класса Майкрософт.SCIM.Core2EnterpriseUser. Этот класс определен в библиотеке Майкрософт.SCIM.Schemas. Если запрос на подготовку пользователя выполнен успешно, то реализация метода, как ожидается, возвращает экземпляр класса Майкрософт.SCIM.Core2EnterpriseUser. Значение свойства присваивается уникальному идентификатору только что Identifier созданного пользователя.

Пример 3. Запрос текущего состояния пользователя

Microsoft Entra ID запрашивает текущее состояние указанного пользователя из службы с таким запросом, как:

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-dddd-e1e1e1e1e1e1"
• ИдентификаторСхемы: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Пример 4. Запрос значения обновляемого атрибута ссылки

Microsoft Entra ID проверяет текущее значение атрибута в хранилище идентификационных данных перед обновлением. Однако в первую очередь проверяется только атрибут менеджера для пользователей. Ниже приведен пример запроса, чтобы определить, имеет ли в настоящее время атрибут диспетчера объекта пользователя определенное значение: в примере кода запрос преобразуется в вызов метода QueryAsync поставщика службы. Значения свойств объекта, предоставленного в качестве значения аргумента parameters, следующие:

• Параметры. Альтернативные фильтры.Количеcтвo: 2
• Параметры. AlternateFilters.ElementAt(x). AttributePath: "ID"
• Параметры. альтернативные фильтры. элемент в позиции x. оператор сравнения: оператор сравнения.Equals
• Параметры.AlternateFilter.ElementAt(x).ComparisonValue: "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"
• Параметры. AlternateFilters.ElementAt(y). AttributePath: "manager"
• Параметры.AlternateFilters.ElementAt(y).ОператорСравнения: ОператорСравнения.Равно
• Параметры.AlternateFilter.ElementAt(y).ComparisonValue: "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
• Параметры.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 ID к конечной точке SCIM для обновления пользователя

Ниже приведен пример запроса от Microsoft Entra ID к конечной точке 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);

В примере запроса на обновление пользователя объект, предоставленный в качестве значения аргумента исправления, имеет следующие значения свойств:

Пример 6. Отключение пользователя

Чтобы деавторизовать пользователя из хранилища удостоверений, представленного конечной точкой SCIM, Microsoft Entra ID отправляет такой запрос, как:

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-dddd-e1e1e1e1e1e1"
• ResourceIdentifier.SchemaIdentifier: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

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

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

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

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

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

Подключение приложения, поддерживающего SCIM:

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

2. Перейдите на Entra ID>Enterprise apps.

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

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

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

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

   

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

7. Выберите + Новая конфигурация.

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

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

   Примечание.

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

10. Выберите Test Connection, чтобы Microsoft Entra ID попытаться подключиться к конечной точке SCIM. Если подключиться не удастся, отобразятся сведения об ошибке.

    Примечание.

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

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

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

    Внимание

    Служба подготовки Microsoft Entra подготавливает только пользователей и группы, которые назначены в приложение (если для диапазона установлено значение Синхронизировать только назначенных пользователей и группы). Если вы не назначаете пользователей или группы, подготовка не выполняется. Прежде чем приступить к подготовке, обязательно выполните этот шаг.

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

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

14. Выберите предоставление по запросу на левой панели. Найдите пользователя, который попадает в рамки настройки, и настройте его по требованию. Повторите с другими пользователями, с которыми вы хотите протестировать предоставление доступа.

15. После завершения настройки выберите Обзор на левой панели.

16. Выберите Свойства.

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

18. Выберите Начать подготовку, чтобы запустить службу подготовки Microsoft Entra.

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

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

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

Контрольный список для ввода в эксплуатацию галереи

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

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

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

Если вас интересуют другие способы проверки подлинности и авторизации, сообщите нам на UserVoice.

Поток предоставления учетных данных клиента OAuth 2.0

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

• URL-адрес клиента: Это URL-адрес конечной точки API SCIM, предоставленный поставщиком услуг. Например, это может быть что-то подобное https://example.test/scim.
• Конечная точка токена: Это URL-адрес маркера OAuth2. Это конечная точка, которую служба предоставления будет использовать для обмена учетными данными клиента на токен доступа. Например, это может быть что-то подобное https://example.test/oauth2/token.
• Идентификатор клиента: Это уникальный идентификатор, назначенный приложению поставщиком услуг.
• Секрет клиента: Это долгоживующий маркер, имеющий необходимые разрешения для API. Он используется для проверки подлинности приложения при запросе токена доступа.

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

Настройка учетных данных клиента

1. Войдите в Центр администрирования Microsoft Entra как минимум с правами администратора приложений.
2. Перейдите на Entra ID>Enterprise apps.
3. Выберите приложение и перейдите к управлению ресурсами.
4. Для метода проверки подлинности учетных данных администратора выберите предоставление учетных > данныхклиента OAuth2.
5. Введите сведения для оставшихся полей:
   • URL-адрес клиента
   • Конечная точка токена
   • Идентификатор клиента
   • Секрет клиента.
6. Нажмите кнопку Проверить подключение.

Если вас интересуют другие способы проверки подлинности и авторизации, сообщите нам на UserVoice.

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

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

Следующие шаги