Tutorial: Desarrollo y planeación del aprovisionamiento de un punto de conexión de SCIM en Microsoft Entra ID

Como desarrollador de aplicaciones, puede usar la API de administración de usuarios de System for Cross-domain Identity Management (SCIM) para permitir el aprovisionamiento automático de usuarios y grupos entre la aplicación y Microsoft Entra ID. En este artículo se describe cómo crear un punto de conexión de SCIM e integrarlo con el servicio de aprovisionamiento de Microsoft Entra. La especificación SCIM proporciona un esquema de usuario común para el aprovisionamiento. Cuando se usa con estándares de federación como SAML u OpenID Connect, SCIM ofrece a los administradores una solución de un extremo a otro basada en estándares para la administración del acceso.

Provisioning from Microsoft Entra ID to an app with SCIM

SCIM 2.0 es una definición estándar de dos puntos de conexión: /Users y /Groups. Usa puntos de conexión comunes de la API de REST para crear, actualizar y eliminar objetos. El SCIM consiste en un esquema predefinido para atributos comunes como el nombre del grupo, el nombre de usuario, el nombre, el apellido y el correo electrónico.

Las aplicaciones que ofrecen una API REST de SCIM 2.0 pueden reducir o eliminar la molestia de trabajar con una API de administración de usuarios propia. Por ejemplo, cualquier cliente SCIM compatible sabe cómo crear una entrada HTTP POST de un objeto JSON para el punto de conexión /Users a fin de crear una nueva entrada de usuario. En lugar de necesitar una API ligeramente diferente para las mismas acciones básicas, las aplicaciones que cumplan con el estándar SCIM pueden aprovechar al instante los clientes, herramientas y código ya existentes.

El esquema de objetos de usuario estándar y las API REST para administración definidas en SCIM 2.0 (RFC 7642, 7643, 7644) permiten que los proveedores de identidades y las aplicaciones se integren más fácilmente entre sí. Los desarrolladores de aplicaciones que crean un punto de conexión SCIM se pueden integrar con cualquier cliente compatible con SCIM sin tener que realizar ningún trabajo personalizado.

Para automatizar el aprovisionamiento en una aplicación, requiere la creación e integración de un punto de conexión de SCIM al que accede el servicio de aprovisionamiento de Microsoft Entra. Para iniciar el aprovisionamiento de usuarios y grupos en la aplicación, realice los pasos siguientes.

  1. Diseñe su esquema de usuarios y grupos: identifique los objetos y atributos de la aplicación para determinar cómo se asignan al esquema de usuarios y grupos que se admite por la implementación de SCIM de Microsoft Entra.

  2. Descripción de la implementación de SCIM de Microsoft Entra: comprenda cómo se implementa el servicio de aprovisionamiento de Microsoft Entra para modelar el control y las respuestas de las solicitudes del protocolo de SCIM.

  3. Cree un punto de conexión de SCIM: un punto de conexión debe ser compatible con SCIM 2.0 para integrarse con el servicio de aprovisionamiento de Microsoft Entra. Si lo desea, puede usar las bibliotecas de Microsoft Common Language Infrastructure (CLI) y los ejemplos de código para crear el punto de conexión. Estos ejemplos sirven solo como referencia y prueba y no se recomienda usarlos como dependencias en la aplicación de producción.

  4. Integre el punto de conexión de SCIM con el servicio de aprovisionamiento de Microsoft Entra. Microsoft Entra ID admite varias aplicaciones de terceros que implementan SCIM 2.0. Si usa una de estas aplicaciones, podrá automatizar rápidamente tanto el aprovisionamiento como el desaprovisionamiento de usuarios y grupos.

  5. [Opcional] Publique la aplicación en la galería de aplicaciones de Microsoft Entra: facilita a los clientes detectar la aplicación y configurar fácilmente el aprovisionamiento.

Diagram that shows the required steps for integrating a SCIM endpoint with Microsoft Entra ID.

Diseñe el esquema de grupos y usuarios

Cada aplicación requiere atributos diferentes para crear un usuario o un grupo. Para iniciar la integración, identifique los objetos (usuarios, grupos) y atributos (nombre, administrador, puesto, etc.) necesarios que requiera la aplicación.

El estándar SCIM define un esquema para administrar usuarios y grupos.

En el esquema de usuario principal solo hacen falta tres atributos (todos los demás son opcionales):

  • id, identificador definido por el proveedor de servicios.
  • userName, un identificador único para el usuario (normalmente se asigna al nombre principal de usuario de Microsoft Entra)
  • meta, metadatos de solo lectura mantenidos por el proveedor de servicios.

Además del esquema de usuario principal, el estándar SCIM define una extensión de usuario empresarial y un modelo para extender el esquema de usuario de modo que satisfaga las necesidades de su aplicación.

Si, por ejemplo, la aplicación necesita el correo electrónico y el administrador de un usuario, use el esquema principal para recopilar el correo electrónico del usuario y el esquema de usuario empresarial para recopilar el administrador del usuario.

Para diseñar el esquema, siga estos pasos:

  1. Enumere los atributos que requiere la aplicación y, a continuación, clasifique como atributos necesarios para la autenticación (por ejemplo, loginName y correo electrónico). Los atributos son necesarios para administrar el ciclo de vida del usuario (por ejemplo, estado o activo) y todos los demás atributos necesarios para que la aplicación funcione (por ejemplo, administrador, etiqueta).

  2. Compruebe si esos atributos ya están definidos en el esquema de usuario principal o en el esquema de usuario empresarial. Si no es así, debe definir una extensión para el esquema de usuario que abarque los atributos que faltan. Consulte el ejemplo para otorgar una extensión al usuario que permita el aprovisionamiento de un usuario tag.

  3. Asigne los atributos de SCIM a los atributos de usuario de Microsoft Entra ID. Si uno de los atributos que ha definido en el punto de conexión de SCIM no tiene un homólogo claro en el esquema de usuario de Microsoft Entra, guíe al administrador de inquilinos para que extienda su esquema o use un atributo de extensión, como se muestra en el ejemplo de la propiedad tags.

En la tabla siguiente se muestra un ejemplo de los atributos necesarios:

Atributo o ejemplo de aplicación requerido Atributo de SCIM asignado Atributo de Microsoft Entra asignado
loginName userName userPrincipalName
firstName name.givenName givenName
lastName name.familyName surName
workMail emails[type eq "work"].value Correo
manager manager manager
etiqueta urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User:tag extensionAttribute1
status active isSoftDeleted (valor calculado no almacenado en el usuario)

La siguiente carga JSON muestra un esquema SCIM de ejemplo:

{
     "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
      "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
      "urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User"],
     "userName":"bjensen@testuser.com",
     "id": "48af03ac28ad4fb88478",
     "externalId":"bjensen",
     "name":{
       "familyName":"Jensen",
       "givenName":"Barbara"
     },
     "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
     "manager": "123456"
   },
     "urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User": {
     "tag": "701984",
   },
   "meta": {
     "resourceType": "User",
     "created": "2010-01-23T04:56:22Z",
     "lastModified": "2011-05-13T04:42:34Z",
     "version": "W\/\"3694e05e9dff591\"",
     "location":
 "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646"
   }
}   

Nota:

Además de los atributos necesarios para la aplicación, la representación JSON incluye también los atributos id, externalId y meta necesarios.

Esta representación ayuda a clasificarlos entre /User y /Group para asignar los atributos de usuario predeterminados de Microsoft Entra ID al RFC de SCIM. Consulte Cómo asignar atributos personalizados entre Microsoft Entra ID y el punto de conexión de SCIM.

En la tabla siguiente se muestra un ejemplo de atributos de usuario:

Usuario de Microsoft Entra urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
IsSoftDeleted active
department urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department
DisplayName DisplayName
employeeId urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber
Facsimile-TelephoneNumber phoneNumbers[type eq "fax"].value
givenName name.givenName
jobTitle title
mail emails[type eq "work"].value
mailNickname externalId
manager urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager
mobile phoneNumbers[type eq "mobile"].value
postalCode addresses[type eq "work"].postalCode
proxy-Addresses emails[type eq "other"].Value
physical-Delivery-OfficeName addresses[type eq "other"].Formatted
streetAddress addresses[type eq "work"].streetAddress
surname name.familyName
telephone-Number phoneNumbers[type eq "work"].value
user-PrincipalName userName

En la tabla siguiente se muestra un ejemplo de atributos de grupo:

Grupo de Microsoft Entra urn:ietf:params:scim:schemas:core:2.0:Group
DisplayName DisplayName
members members
objectId externalId

Nota:

No es necesario admitir usuarios y grupos, o todos los atributos que se muestran aquí, solo es una referencia sobre cómo los atributos de Microsoft Entra ID se asignan a menudo a las propiedades del protocolo de SCIM.

Hay varios puntos de conexión definidos en el RFC de SCIM. Puede empezar con el punto de conexión /User y, luego, expandirlo desde allí. En la tabla siguiente se enumeran algunos de los puntos de conexión de SCIM:

Punto de conexión Descripción
/User Realiza operaciones CRUD en un objeto de usuario.
/Group Realiza operaciones CRUD en un objeto de grupo.
/Schemas El conjunto de atributos que admite cada cliente y proveedor de servicios puede variar. Un proveedor de servicios puede incluir name, title y emails, mientras que otro usa name, title y phoneNumbers. El punto de conexión de esquemas permite la detección de los atributos admitidos.
/Bulk Las operaciones masivas le permiten realizar operaciones en una gran colección de objetos de recursos en una sola operación (por ejemplo, actualizar las pertenencias para un grupo de gran tamaño).
/ServiceProviderConfig Proporciona detalles sobre las características del estándar SCIM que se admiten; por ejemplo, los recursos que se admiten y el método de autenticación.
/ResourceTypes Especifica los metadatos de cada recurso.

Nota:

Use el punto de conexión /Schemas para admitir atributos personalizados o si el esquema cambia con frecuencia, ya que permite que un cliente recupere el esquema más actualizado automáticamente. Use el punto de conexión /Bulk para admitir grupos.

Descripción de la implementación de SCIM de Microsoft Entra

El servicio de aprovisionamiento de Microsoft Entra está diseñado para admitir una API de administración de usuarios de SCIM 2.0.

Importante

El comportamiento de la implementación de SCIM de Microsoft Entra se actualizó por última vez el 18 de diciembre de 2018. Para obtener información sobre los cambios que se han producido, consulte Cumplimiento del protocolo de SCIM 2.0 del servicio de aprovisionamiento de usuarios de Microsoft Entra.

Dentro de la especificación del protocolo SCIM 2.0, la aplicación debe cumplir estos requisitos:

Requisito Notas de referencia (protocolo SCIM)
Crear usuarios y, opcionalmente, también grupos Sección 3.3.
Modificar usuarios o grupos con solicitudes PATCH Sección 3.5.2. La admisión garantiza que los grupos y usuarios se aprovisionan de forma eficaz.
Recuperar un recurso conocido para un usuario o un grupo creados anteriormente Sección 3.4.1.
Consultar usuarios o grupos Sección 3.4.2. De forma predeterminada, los usuarios se recuperan con sus id y se consultan con sus username y externalId, y los grupos se consultan con su displayName.
El filtro excludedAttributes=members al consultar el recurso de grupo Sección 3.4.2.2
Compatibilidad con la enumeración de usuarios y paginación Sección 3.4.2.4.
Eliminación temporal de un usuario active=false y restauración del usuario active=true El objeto de usuario se debe devolver en una solicitud tanto si el usuario está activo como si no. La única vez que el usuario no debería ser devuelto es cuando se borra de la aplicación.
Compatibilidad con el punto de conexión /Schemas sección 7 El punto de conexión de descubrimiento de esquemas se utiliza para descubrir más atributos.
Aceptar un token de portador único para la autenticación y autorización de Microsoft Entra ID en la aplicación.

Al implementar un punto de conexión de SCIM para garantizar la compatibilidad con Microsoft Entra ID, siga estas directrices generales:

General:

  • id es una propiedad obligatoria para todos los recursos. Todas las respuestas que devuelve un recurso deben asegurarse de que cada recurso tiene esta propiedad, excepto ListResponse con cero elementos.
  • Los valores enviados deberían almacenarse en el mismo formato en el que se enviaron. Los valores no válidos deben rechazarse con un mensaje de error descriptivo y accionable. Las transformaciones de datos no deberían producirse entre los datos de Microsoft Entra ID y los datos almacenados en la aplicación de SCIM. (Por ejemplo: por ejemplo, un número de teléfono enviado como 55555555555 no debe guardarse ni devolverse como +5 (555) 555-5555)
  • No es necesario incluir el recurso completo en la respuesta PATCH.
  • No exija una coincidencia entre mayúsculas y minúsculas en los elementos estructurales de SCIM, en particular en los valores de operación PATCHop, como se define en la sección 3.5.2. Microsoft Entra ID emite los valores de op como Agregar, Reemplazar y Quitar.
  • Microsoft Entra ID realiza solicitudes para recuperar un usuario y un grupo al azar para tener la seguridad de que el punto de conexión y las credenciales sean válidas. También las realiza como parte del flujo de Probar conexión.
  • Compatibilidad con HTTPS en el punto de conexión de SCIM.
  • Se admiten atributos complejos y de varios valores personalizados, pero Microsoft Entra ID no tiene muchas estructuras de datos complejas de las que extraer datos en estos casos. Los atributos nombre/valor se pueden asignar fácilmente, pero no se admite el flujo de datos a atributos complejos con tres o más atributos secundarios.
  • Los valores de subatributo "type" de los atributos complejos de varios valores deben ser únicos. Por ejemplo, no puede haber dos direcciones de correo electrónico diferentes con el subtipo "work".
  • El encabezado de todas las respuestas debe ser Content-Type: application/scim+json

Recuperación de recursos:

/Users:

  • No se admite el atributo de derechos.
  • Los atributos que se tengan en cuenta por la singularidad del usuario deben usarse como parte de una consulta filtrada (p. ej., si la singularidad del usuario se evalúa tanto para userName como para emails[type eq "work"], debe permitirse una solicitud GET a /Users con un filtro tanto para una consulta userName eq "user@contoso.com" como para una consulta emails[type eq "work"].value eq "user@contoso.com".

/Groups:

  • Los grupos son opcionales, pero solo se admiten si la implementación de SCIM admite solicitudes PATCH.
  • Los grupos deben tener unicidad en el valor "displayName" para que coincida con Microsoft Entra ID y la aplicación SCIM. Esta singularidad no es un requisito del protocolo SCIM, pero es un requisito para integrar un punto de conexión de SCIM con Microsoft Entra ID.

/Schemas (detección de esquemas):

  • Solicitud/respuesta de ejemplo
  • Actualmente se usa la detección de esquemas en determinadas aplicaciones de la galería. La detección de esquemas es el único método para agregar más atributos al esquema de una aplicación SCIM de la galería existente. Actualmente no se admite la detección de esquemas en aplicaciones SCIM personalizadas que no sean de la galería.
  • Si un valor no está presente, no envíe valores NULL.
  • Los valores de propiedad deben tener mayúsculas y minúsculas (por ejemplo, readWrite).
  • Debe devolver una respuesta de lista.
  • El servicio de aprovisionamiento de Microsoft Entra realiza la solicitud /schemas al guardar la configuración de aprovisionamiento. La solicitud también se realiza al abrir la página de edición de aprovisionamiento. Otros atributos detectados se mostrarán a los clientes en las asignaciones de atributos en la lista de atributos de destino. El descubrimiento del esquema solo hace que se agreguen más atributos de destino. Los atributos no se quitan.

Aprovisionamiento y desaprovisionamiento de usuarios

El siguiente diagrama muestra los mensajes que Microsoft Entra ID envía a un punto de conexión de SCIM para administrar el ciclo de vida de un usuario en el almacén de identidades de su aplicación.

Diagram that shows the user deprovisioning sequence.

Aprovisionamiento y desaprovisionamiento de grupos

El aprovisionamiento y desaprovisionamiento de grupos son opcionales. Cuando se implementa y habilita, la siguiente ilustración muestra los mensajes que Microsoft Entra ID envía a un punto de conexión de SCIM para administrar el ciclo de vida de un grupo en el almacén de identidades de su aplicación. Esos mensajes se diferencian de los mensajes sobre los usuarios de dos maneras:

  • Las solicitudes para recuperar grupos especifican que el atributo members se excluya de cualquier recurso proporcionado en respuesta a la solicitud.
  • Las solicitudes para determinar si un atributo de referencia tiene un valor determinado son solicitudes sobre el atributo members.

En el diagrama siguiente se muestra la secuencia de desaprovisionamiento de grupos:

Diagram that shows the group deprovisioning sequence.

Modificación de solicitudes y respuestas de protocolo SCIM

En este artículo se proporcionan solicitudes de SCIM de ejemplo emitidas por el servicio de aprovisionamiento de Microsoft Entra y respuestas esperadas de ejemplo. Para obtener mejores resultados, debe codificar la aplicación para controlar estas solicitudes en este formato y emitir las respuestas esperadas.

Importante

Para comprender cómo y cuándo el servicio de aprovisionamiento de usuarios de Microsoft Entra emite las operaciones que se describen en el ejemplo, consulte Ciclos de aprovisionamiento: inicial e incremental en Funcionamiento del aprovisionamiento.

Operaciones de usuario

Operaciones de grupo

Detección de esquemas

Operaciones de usuario

  • Use atributos userName o emails[type eq "work"] para consultar a los usuarios.

Crear usuario

Solicitud

POST /Users

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
    "externalId": "0a21f0f2-8d2a-4f8e-bf98-7363c4aed4ef",
    "userName": "Test_User_ab6490ee-1e48-479e-a20b-2d77186b5dd1",
    "active": true,
    "emails": [{
        "primary": true,
        "type": "work",
        "value": "Test_User_fd0ea19b-0777-472c-9f96-4f70d2226f2e@testuser.com"
    }],
    "meta": {
        "resourceType": "User"
    },
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName"
    },
    "roles": []
}
Response

HTTP/1.1 201 Created

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "48af03ac28ad4fb88478",
    "externalId": "0a21f0f2-8d2a-4f8e-bf98-7363c4aed4ef",
    "meta": {
        "resourceType": "User",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
    },
    "userName": "Test_User_ab6490ee-1e48-479e-a20b-2d77186b5dd1",
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName",
    },
    "active": true,
    "emails": [{
        "value": "Test_User_fd0ea19b-0777-472c-9f96-4f70d2226f2e@testuser.com",
        "type": "work",
        "primary": true
    }]
}

Obtener usuario

Solicitud

GET /Users/5d48a0a8e9f04aa38008

Respuesta (Se encontró el usuario)

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "5d48a0a8e9f04aa38008",
    "externalId": "58342554-38d6-4ec8-948c-50044d0a33fd",
    "meta": {
        "resourceType": "User",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
    },
    "userName": "Test_User_feed3ace-693c-4e5a-82e2-694be1b39934",
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName",
    },
    "active": true,
    "emails": [{
        "value": "Test_User_22370c1a-9012-42b2-bf64-86099c2a1c22@testuser.com",
        "type": "work",
        "primary": true
    }]
}
Solicitud

GET /Users/5171a35d82074e068ce2

Respuesta (Usuario no encontrado. El detalle no es necesario, solo el estado).

HTTP/1.1 404 no encontrado

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

Obtener usuario por consulta

Solicitud

GET /Users?filter=userName eq "Test_User_dfeef4c5-5681-4387-b016-bdf221e82081"

Response

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "totalResults": 1,
    "Resources": [{
        "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
        "id": "2441309d85324e7793ae",
        "externalId": "7fce0092-d52e-4f76-b727-3955bd72c939",
        "meta": {
            "resourceType": "User",
            "created": "2018-03-27T19:59:26.000Z",
            "lastModified": "2018-03-27T19:59:26.000Z"
            
        },
        "userName": "Test_User_dfeef4c5-5681-4387-b016-bdf221e82081",
        "name": {
            "familyName": "familyName",
            "givenName": "givenName"
        },
        "active": true,
        "emails": [{
            "value": "Test_User_91b67701-697b-46de-b864-bd0bbe4f99c1@testuser.com",
            "type": "work",
            "primary": true
        }]
    }],
    "startIndex": 1,
    "itemsPerPage": 20
}

Obtener usuario por consulta: cero resultados

Solicitud

GET /Users?filter=userName eq "non-existent user"

Response

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "totalResults": 0,
    "Resources": [],
    "startIndex": 1,
    "itemsPerPage": 20
}

Actualizar usuario [propiedades con varios valores]

Solicitud

PATCH /Users/6764549bef60420686bc HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
            {
            "op": "Replace",
            "path": "emails[type eq \"work\"].value",
            "value": "updatedEmail@microsoft.com"
            },
            {
            "op": "Replace",
            "path": "name.familyName",
            "value": "updatedFamilyName"
            }
    ]
}
Response

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "6764549bef60420686bc",
    "externalId": "6c75de36-30fa-4d2d-a196-6bdcdb6b6539",
    "meta": {
        "resourceType": "User",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
    },
    "userName": "Test_User_fbb9dda4-fcde-4f98-a68b-6c5599e17c27",
    "name": {
        "formatted": "givenName updatedFamilyName",
        "familyName": "updatedFamilyName",
        "givenName": "givenName"
    },
    "active": true,
    "emails": [{
        "value": "updatedEmail@microsoft.com",
        "type": "work",
        "primary": true
    }]
}

Actualizar usuario [propiedades de un solo valor]

Solicitud

PATCH /Users/5171a35d82074e068ce2 HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "Replace",
        "path": "userName",
        "value": "5b50642d-79fc-4410-9e90-4c077cdd1a59@testuser.com"
    }]
}
Response

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "5171a35d82074e068ce2",
    "externalId": "aa1eca08-7179-4eeb-a0be-a519f7e5cd1a",
    "meta": {
        "resourceType": "User",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
        
    },
    "userName": "5b50642d-79fc-4410-9e90-4c077cdd1a59@testuser.com",
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName",
    },
    "active": true,
    "emails": [{
        "value": "Test_User_49dc1090-aada-4657-8434-4995c25a00f7@testuser.com",
        "type": "work",
        "primary": true
    }]
}

Deshabilitar usuario

Solicitud

PATCH /Users/5171a35d82074e068ce2 HTTP/1.1

{
    "Operations": [
        {
            "op": "Replace",
            "path": "active",
            "value": false
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ]
}
Response
{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "id": "CEC50F275D83C4530A495FCF@834d0e1e5d8235f90a495fda",
    "userName": "deanruiz@testuser.com",
    "name": {
        "familyName": "Harris",
        "givenName": "Larry"
    },
    "active": false,
    "emails": [
        {
            "value": "gloversuzanne@testuser.com",
            "type": "work",
            "primary": true
        }
    ],
    "addresses": [
        {
            "country": "ML",
            "type": "work",
            "primary": true
        }
    ],
    "meta": {
        "resourceType": "Users",
        "location": "/scim/5171a35d82074e068ce2/Users/CEC50F265D83B4530B495FCF@5171a35d82074e068ce2"
    }
}

Eliminar usuario

Solicitud

DELETE /Users/5171a35d82074e068ce2 HTTP/1.1

Response

HTTP/1.1 204 No Content

Operaciones de grupo

  • Los grupos se crean con una lista de miembros vacía.
  • Use el atributo displayName para consultar grupos.
  • La actualización de la solicitud de PATCH del grupo debe producir un HTTP 204 No Content en la respuesta. La devolución de un cuerpo con una lista de todos los miembros no es aconsejable.
  • No es necesario admitir la devolución de todos los miembros del grupo.

Crear grupo

Solicitud

POST /Groups HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group", "http://schemas.microsoft.com/2006/11/ResourceManagement/ADSCIM/2.0/Group"],
    "externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159",
    "displayName": "displayName",
    "meta": {
        "resourceType": "Group"
    }
}
Response

HTTP/1.1 201 Created

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

Obtener grupo

Solicitud

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

Response

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "id": "40734ae655284ad3abcc",
    "externalId": "60f1bb27-2e1e-402d-bcc4-ec999564a194",
    "meta": {
        "resourceType": "Group",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
    },
    "displayName": "displayName",
}

Obtener grupo por displayName

Solicitar

GET /Groups?excludedAttributes=members&filter=displayName eq "displayName" HTTP/1.1

Respuesta

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
}

Actualizar grupo [atributos no de miembro]

Solicitud

PATCH /Groups/fa2ce26709934589afc5 HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "Replace",
        "path": "displayName",
        "value": "1879db59-3bdf-4490-ad68-ab880a269474updatedDisplayName"
    }]
}
Response

HTTP/1.1 204 No Content

Actualizar grupo [Agregar miembros]

Solicitud

PATCH /Groups/a99962b9f99d4c4fac67 HTTP/1.1

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

HTTP/1.1 204 No Content

Actualizar grupo [Eliminar miembros]

Solicitud

PATCH /Groups/a99962b9f99d4c4fac67 HTTP/1.1

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

HTTP/1.1 204 No Content

Eliminar grupo

Solicitud

DELETE /Groups/cdb1ce18f65944079d37 HTTP/1.1

Response

HTTP/1.1 204 No Content

Detección de esquemas

Detección de esquema

Solicitud

GET /Schemas

Response

HTTP/1.1 200 OK

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

Requisitos de seguridad

Versiones del protocolo SSL

La única versión de protocolo aceptable es TLS 1.2. No se permite ninguna otra versión de SSL/TLS.

  • Las claves RSA deben ser de al menos 2048 bits.
  • Las claves ECC deben ser de al menos 256 bits, generadas mediante una curva elíptica aprobada.

Longitud de las claves

Todos los servicios deben usar certificados X.509 generados con claves criptográficas de una longitud suficiente, lo que significa:

Conjuntos de cifrado

Todos los servicios deberán configurarse para usar los siguientes conjuntos de cifrado en el orden exacto que se especifica en el ejemplo. Si solo tiene un certificado RSA instalado, los conjuntos de cifrado ECDSA no tienen ningún efecto.

Barra mínima de conjuntos de cifrado 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

Intervalos IP

El servicio de aprovisionamiento de Microsoft Entra funciona actualmente en los intervalos IP para Microsoft Entra ID como se muestra aquí. Puede agregar los intervalos IP que aparecen en la etiqueta de Microsoft Entra ID para permitir el tráfico desde el servicio de aprovisionamiento de Microsoft Entra a la aplicación. Deberá revisar detenidamente la lista de intervalos IP para direcciones procesadas. Una dirección como "40.126.25.32" podría aparecer en la lista de intervalos IP como "40.126.0.0/18". También puede recuperar la lista de intervalos IP mediante programación con la siguiente API.

Microsoft Entra ID también admite una solución basada en agente para proporcionar conectividad a aplicaciones en redes privadas (locales, hospedadas en Azure, hospedadas en AWS, etc.). Los clientes pueden implementar un agente ligero, que proporciona conectividad a Microsoft Entra ID sin abrir puertos de entrada en un servidor de su red privada. Obtenga más información aquí.

Cree un punto de conexión SCIM

Ahora que ha diseñado el esquema y comprendido la implementación de SCIM de Microsoft Entra, puede empezar a desarrollar el punto de conexión de SCIM. En lugar de empezar desde cero y compilar la implementación completamente por su cuenta, puede confiar en muchas bibliotecas SCIM de código abierto publicadas por la comunidad SCIM.

Para obtener instrucciones sobre cómo crear un punto de conexión de SCIM, incluidos ejemplos, consulte Desarrollo de un punto de conexión SCIM de ejemplo.

El código de referencia de ejemplo de .NET Core de código abierto publicado por el equipo de aprovisionamiento de Microsoft Entra es uno de esos recursos que puede impulsar su desarrollo. Compile un punto de conexión de SCIM y pruébelo. Use la colección de pruebas de Postman proporcionadas como parte del código de referencia o ejecute las solicitudes o respuestas de ejemplo proporcionadas.

Nota:

El código de referencia está pensado para ayudarle a empezar a crear el punto de conexión de SCIM y se proporciona "TAL CUAL". Las contribuciones de la comunidad son bienvenidas para ayudar a crear y mantener el código.

La solución se compone de dos proyectos: Microsoft.SCIM y Microsoft.SCIM.WebHostSample.

El proyecto Microsoft.SCIM es la biblioteca que define los componentes del servicio web que se ajusta a la especificación SCIM. Declara la interfaz Microsoft.SCIM.IProvider. Las solicitudes se traducen en llamadas a los métodos del proveedor, que se programan para funcionar en un almacén de identidades.

Breakdown: A request translated into calls to the provider's methods

El proyecto Microsoft.SCIM.WebHostSample es una aplicación web ASP.NET Core, basada en la plantilla Empty. Permite implementar el código de ejemplo como independiente, hospedado en contenedores o en Internet Information Services. También implementa la interfaz Microsoft.SCIM.IProvider, que mantiene las clases en memoria como almacén de identidades de ejemplo.

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();
    }
    ...

Creación de un punto de conexión SCIM personalizado

El punto de conexión SCIM debe tener una dirección HTTP y un certificado de autenticación de servidor para el que la entidad de certificación raíz tenga uno de los siguientes nombres:

  • CNNIC
  • Comodo
  • CyberTrust
  • DigiCert
  • GeoTrust
  • GlobalSign
  • Go Daddy
  • VeriSign
  • WoSign
  • DST Root CA X3

El SDK de .NET Core incluye un certificado de desarrollo HTTPS que se usa durante el desarrollo. El certificado se instala como parte de la experiencia de primera ejecución. En función de cómo ejecute la aplicación web ASP.NET Core, escuchará en un puerto diferente:

  • Microsoft.SCIM.WebHostSample: https://localhost:5001
  • IIS Express: https://localhost:44359

Para obtener más información sobre HTTPS en ASP.NET Core, use el siguiente vínculo: Aplicar HTTPS en ASP.NET Core.

Control de la autenticación de puntos de conexión

Las solicitudes del servicio de aprovisionamiento de Microsoft Entra incluyen un token de portador de OAuth 2.0. Un servidor de autorización emite el token de portador. Microsoft Entra ID es un ejemplo de un servidor de autorización de confianza. Puede configurar el servicio de aprovisionamiento de Microsoft Entra para usar uno de los siguientes tokens:

  • Una ficha al portador de larga duración. Si el punto de conexión de SCIM requiere un token de portador OAuth de un emisor que no sea Microsoft Entra ID, copie el token de portador OAuth necesario en el campo Token secreto. En un entorno de desarrollo, puede usar el token de prueba desde el punto de conexión /scim/token. Los tokens de prueba no se deben usar en entornos de producción.

  • Token de portador de Microsoft Entra. Si este campo de token secreto se deja en blanco, Microsoft Entra ID incluye un token de portador OAuth emitido desde Microsoft Entra ID con cada solicitud. Las aplicaciones que usan Microsoft Entra ID como proveedor de identidades pueden validar este token emitido por Microsoft Entra ID.

    • La aplicación que recibe solicitudes debe validar el emisor de tokens como Microsoft Entra ID para un inquilino de Microsoft Entra esperado.
    • Una notificación de iss identifica el emisor del token. Por ejemplo, "iss":"https://sts.windows.net/12345678-0000-0000-0000-000000000000/". En este ejemplo, la dirección base del valor de notificación identifica https://sts.windows.net Microsoft Entra ID como emisor, mientras que el segmento de dirección relativa, 12345678-0000-0000-0000-000000000000 es un identificador único del inquilino de Microsoft Entra para el que se emitió el token.
    • La audiencia de un token es el identificador de aplicación de la aplicación en la galería. Las aplicaciones registradas en un único inquilino reciben la misma notificación iss con las solicitudes SCIM. El identificador de aplicación para todas las aplicaciones personalizadas es 8adf8e6e-67b2-4cf2-a259-e3dc5476c621. El token generado por Microsoft Entra ID solo debe utilizarse para pruebas. No debe usarse en entornos de producción.

En el código de ejemplo, las solicitudes se autentican mediante el paquete Microsoft.AspNetCore.Authentication.JwtBearer. El código siguiente exige que las solicitudes a cualquiera de los puntos de conexión del servicio se autentiquen mediante el token de portador emitido por Microsoft Entra ID para un inquilino concreto:

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

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

También se requiere un token de portador para usar las pruebas de Postman proporcionadas y realizar la depuración local con localhost. El código de ejemplo usa entornos ASP.NET Core para cambiar las opciones de autenticación durante la fase de desarrollo y habilitar el uso de un token autofirmado.

Para más información sobre varios entornos de ASP.NET Core, consulte Uso de varios entornos en ASP.NET Core.

El código siguiente exige que las solicitudes a cualquier punto de conexión del servicio se autentiquen mediante un token de portador firmado con una clave personalizada:

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"))
                };
        });
    }
...

Envíe una solicitud GET al controlador de tokens para obtener un token de portador válido. El método GenerateJSONWebToken es el responsable de crear un token que coincida con los parámetros configurados para el desarrollo:

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

Control del aprovisionamiento y desaprovisionamiento de usuarios

Ejemplo 1. Consulta del servicio para buscar un usuario coincidente

Microsoft Entra ID consulta el servicio para buscar un usuario con un valor de atributo externalId que coincida con el valor de atributo mailNickname de un usuario de Microsoft Entra ID. La consulta se expresa como una solicitud de Protocolo de transferencia de hipertexto (HTTP) como la de este ejemplo, donde jyoung es un ejemplo de un mailNickname de un usuario en Microsoft Entra ID.

Nota:

Esto es solo un ejemplo. No todos los usuarios tendrán un atributo mailNickname, y el valor que tiene un usuario no puede ser único en el directorio. Además, el atributo utilizado para la coincidencia (que en este caso es externalId) es configurable en las asignaciones de atributos de Microsoft Entra.

GET https://.../scim/Users?filter=externalId eq jyoung HTTP/1.1
 Authorization: Bearer ...

En el código de ejemplo, la solicitud se traduce en una llamada al método QueryAsync del proveedor del servicio. Esta es la firma de ese método:

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

En la consulta de ejemplo, en el caso de un usuario con un valor especificado para el atributo externalId, los valores de los argumentos pasados al método QueryAsync serán los siguientes:

  • parameters.AlternateFilters.Count: 1
  • parameters.AlternateFilters.ElementAt(0).AttributePath: "externalId"
  • parameters.AlternateFilters.ElementAt(0).ComparisonOperator: ComparisonOperator.Equals
  • parameters.AlternateFilter.ElementAt(0).ComparisonValue: "jyoung"

Ejemplo 2. Aprovisionamiento de un usuario

Si la respuesta a una consulta al punto de conexión de SCIM relativo a un usuario con un valor de atributo externalId que coincide con el valor de atributo mailNickname de un usuario no devuelve ningún usuario, Microsoft Entra ID solicita al servicio que aprovisione un usuario correspondiente al de Microsoft Entra ID. Este es un ejemplo de dicha solicitud:

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}

En el código de ejemplo, la solicitud se traduce en una llamada al método CreateAsync del proveedor del servicio. Esta es la firma de ese método:

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

En una solicitud de aprovisionamiento de usuarios, el valor del argumento resource es una instancia de la clase Microsoft.SCIM.Core2EnterpriseUser. Esta clase se define en la biblioteca Microsoft.SCIM.Schemas. Si la solicitud para aprovisionar el usuario se realiza correctamente, se espera que la implementación del método devuelva una instancia de la clase Microsoft.SCIM.Core2EnterpriseUser. El valor de la propiedad Identifier se establece en el identificador único del usuario recién aprovisionado.

Ejemplo 3. Consulta del estado actual de un usuario

Microsoft Entra ID solicita el estado actual del usuario especificado desde el servicio con una solicitud como:

GET ~/scim/Users/54D382A4-2050-4C03-94D1-E769F1D15682 HTTP/1.1
Authorization: Bearer ...

En el código de ejemplo, la solicitud se traduce en una llamada al método RetrieveAsync del proveedor del servicio. Esta es la firma de ese método:

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

En el ejemplo anterior de una solicitud para recuperar el estado actual de un usuario, los valores de las propiedades del objeto proporcionados como el valor del argumento parameters son los siguientes:

  • Identificador: "54D382A4-2050-4C03-94D1-E769F1D15682"
  • SchemaIdentifier: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Ejemplo 4. Consulta del valor de un atributo de referencia que se va a actualizar

Microsoft Entra ID comprueba el valor del atributo actual en el almacén de identidades antes de actualizarlo. Sin embargo, solo el atributo manager es el que se comprueba primero para los usuarios. Este es un ejemplo de una solicitud para determinar si el atributo de administrador de un objeto de usuario tiene, actualmente, un determinado valor: En el código de ejemplo, la solicitud se traduce en una llamada al método QueryAsync del proveedor del servicio. El valor de las propiedades del objeto proporcionado como el valor del argumento parameters es el siguiente:

  • parameters.AlternateFilters.Count: 2
  • parameters.AlternateFilters.ElementAt(x).AttributePath: "ID"
  • parameters.AlternateFilters.ElementAt(x).ComparisonOperator: ComparisonOperator.Equals
  • parameters.AlternateFilter.ElementAt(x).ComparisonValue: "54D382A4-2050-4C03-94D1-E769F1D15682"
  • parameters.AlternateFilters.ElementAt(y).AttributePath: "manager"
  • parameters.AlternateFilters.ElementAt(y).ComparisonOperator: ComparisonOperator.Equals
  • parameters.AlternateFilter.ElementAt(y).ComparisonValue: "2819c223-7f76-453a-919d-413861904646"
  • parameters.RequestedAttributePaths.ElementAt(0): "ID"
  • parameters.SchemaIdentifier: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

El valor del índice x puede ser 0 y el valor del índice y puede ser 1. O bien, el valor de x puede ser 1 y el valor de y puede ser 0. Depende del orden de las expresiones del parámetro de consulta de filtro.

Ejemplo 5. Solicitud de Microsoft Entra ID a un punto de conexión de SCIM para actualizar un usuario

Este es un ejemplo de una solicitud de Microsoft Entra ID a un punto de conexión SCIM para actualizar un usuario:

PATCH ~/scim/Users/54D382A4-2050-4C03-94D1-E769F1D15682 HTTP/1.1
Authorization: Bearer ...
Content-type: application/scim+json
{
    "schemas": 
    [
      "urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations":
    [
      {
        "op":"Add",
        "path":"manager",
        "value":
          [
            {
              "$ref":"http://.../scim/Users/2819c223-7f76-453a-919d-413861904646",
              "value":"2819c223-7f76-453a-919d-413861904646"}]}]}

En el código de ejemplo, la solicitud se traduce en una llamada al método UpdateAsync del proveedor del servicio. Esta es la firma de ese método:

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

En el ejemplo de una solicitud para actualizar un usuario, el objeto proporcionado como el valor del argumento patch tiene estos valores de propiedad:

Argumento Value
ResourceIdentifier.Identifier "54D382A4-2050-4C03-94D1-E769F1D15682"
ResourceIdentifier.SchemaIdentifier urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
(PatchRequest as PatchRequest2).Operations.Count 1
(PatchRequest as PatchRequest2).Operations.ElementAt(0).OperationName OperationName.Add
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Path.AttributePath Manager
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.Count 1
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.ElementAt(0).Reference http://.../scim/Users/2819c223-7f76-453a-919d-413861904646
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.ElementAt(0).Value 2819c223-7f76-453a-919d-413861904646

Ejemplo 6. Desaprovisionamiento de un usuario

Para desaprovisionar a un usuario de un almacén de identidades liderado por un punto de conexión de SCIM, Microsoft Entra ID envía una solicitud como:

DELETE ~/scim/Users/54D382A4-2050-4C03-94D1-E769F1D15682 HTTP/1.1
Authorization: Bearer ...

En el código de ejemplo, la solicitud se traduce en una llamada al método DeleteAsync del proveedor del servicio. Esta es la firma de ese método:

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

El objeto proporcionado como el valor del argumento resourceIdentifier tiene estos valores de propiedad en el ejemplo de una solicitud para desaprovisionar a un usuario:

  • ResourceIdentifier.Identifier: "54D382A4-2050-4C03-94D1-E769F1D15682"
  • ResourceIdentifier.SchemaIdentifier: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Integración del punto de conexión de SCIM con el servicio de aprovisionamiento de Microsoft Entra

Microsoft Entra ID se puede configurar para que aprovisione automáticamente usuarios y grupos asignados a aplicaciones que implementan un perfil específico del Protocolo SCIM 2.0. Los detalles del perfil están documentados en Información sobre la implementación de SCIM de Microsoft Entra.

Consulte a su proveedor de la aplicación o la documentación que se incluye con la aplicación para ver si existen declaraciones de compatibilidad con estos requisitos.

Importante

La implementación de SCIM de Microsoft Entra se basa en el servicio de aprovisionamiento de usuarios de Microsoft Entra, que está diseñado para mantener a los usuarios constantemente sincronizados entre Microsoft Entra ID y la aplicación de destino, y que implementa un conjunto muy específico de operaciones estándar. Es importante entender estos comportamientos para comprender el comportamiento del servicio de aprovisionamiento de Microsoft Entra. Para obtener más información, consulte la sección Ciclos de aprovisionamiento: inicial e incremental en Funcionamiento del aprovisionamiento.

Introducción

Sugerencia

Los pasos de este artículo pueden variar ligeramente en función del portal desde donde comienza.

Las aplicaciones que admiten el perfil SCIM descrito en este artículo se pueden conectar a Microsoft Entra ID mediante la característica de "aplicación situada fuera de la galería" de la galería de aplicaciones de Microsoft Entra. Una vez conectado, Microsoft Entra ID ejecuta un proceso de sincronización. Este proceso se ejecuta cada 40 minutos. El proceso consulta el punto de conexión SCIM de la aplicación para ver los usuarios y grupos asignados, y los crea o modifica según los detalles de asignación.

Para conectar una aplicación que admite SCIM:

  1. Inicie sesión en el Centro de administración de Microsoft Entra al menos como Administrador de aplicaciones.

  2. Vaya a Aplicaciones de identidad>Aplicaciones>Empresariales.

  3. Se muestra una lista de las aplicaciones configuradas, incluidas aquellas que se han agregado desde la galería.

  4. Seleccione + Nueva aplicación>+ Cree su propia aplicación.

  5. Escriba un nombre para la aplicación, elija la opción "Integrar cualquier otra aplicación que no se encuentre en la galería" y seleccione Agregar para crear un objeto de aplicación. La nueva aplicación se agrega a la lista de aplicaciones empresariales y se abre en su pantalla de administración de la aplicación.

    En la captura de pantalla siguiente se muestra la galería de aplicaciones de Microsoft Entra:

    Screenshot shows the Microsoft Entra application gallery.

  6. En la pantalla de administración de la aplicación, seleccione Aprovisionamiento en el panel izquierdo.

  7. En el menú Modo de aprovisionamiento, seleccione Automático.

    La siguiente captura de pantalla muestra la configuración de los ajustes de aprovisionamiento en el centro de administración de Microsoft Entra:

    Screenshot of app provisioning page in the Microsoft Entra admin center.

  8. En el campo Dirección URL del inquilino, escriba la dirección URL del punto de conexión SCIM de la aplicación. Ejemplo: https://api.contoso.com/scim/

  9. Si el punto de conexión de SCIM requiere un token de portador OAuth de un emisor que no sea Microsoft Entra ID, copie el token de portador OAuth necesario en el campo Token secreto. Si este campo se deja en blanco, Microsoft Entra ID. incluye un token de portador de OAuth emitido desde Microsoft Entra ID con cada solicitud. Las aplicaciones que usan Microsoft Entra ID como proveedor de identidades pueden validar este token emitido por Microsoft Entra ID.

    Nota:

    No se recomienda dejar este campo en blanco ni confiar en un token generado por Microsoft Entra ID. Esta opción está disponible principalmente para fines de prueba.

  10. Seleccione Probar conexión para que Microsoft Entra ID intente conectarse al punto de conexión de SCIM. Si se produce un error en el intento, se muestra la información de error.

    Nota:

    La prueba de conexión consulta el punto de conexión de SCIM de un usuario que no existe mediante un GUID aleatorio, como la propiedad de coincidencia seleccionada en la configuración de Microsoft Entra. La respuesta correcta esperada es HTTP 200 OK con un mensaje ListResponse de SCIM vacío.

  11. Si la conexión se realiza con éxito, a continuación, seleccione Guardar para guardar las credenciales de administrador.

  12. En la sección Asignaciones, hay dos conjuntos seleccionables de asignaciones de atributos: uno para los objetos de usuario y otro para los objetos de grupo. Seleccione cada uno de ellos para revisar los atributos que se sincronizan desde Microsoft Entra ID a la aplicación. Los atributos seleccionados como propiedades de Coincidencia se usan para buscar coincidencias con los usuarios y grupos de la aplicación con el objetivo de realizar operaciones de actualización. Para confirmar los cambios, seleccione Guardar.

    Nota:

    Opcionalmente, puede deshabilitar la sincronización de objetos de grupo deshabilitando la asignación de "grupos".

  13. En Settings (Configuración), el campo Scope (Ámbito) define qué usuarios y grupos se sincronizan. Seleccione Sincronizar solo los usuarios y grupos asignados (recomendado) para que se sincronicen solamente los usuarios y los grupos asignados en la pestaña Usuarios y grupos.

  14. Una vez completada la configuración, cambie el Estado de aprovisionamiento a Activado.

  15. Seleccione Guardar para iniciar el servicio de aprovisionamiento de Microsoft Entra.

  16. Si solo sincroniza usuarios y grupos asignados (recomendado), seleccione la pestaña Usuarios y grupos. A continuación, asigne los usuarios o grupos que desee sincronizar.

Una vez que haya empezado el ciclo inicial, puede seleccionar Registros de aprovisionamiento en el panel izquierdo para supervisar el progreso; con esto se muestran todas las acciones realizadas por el servicio de aprovisionamiento en la aplicación. Para más información sobre cómo leer los registros de aprovisionamiento de Microsoft Entra, consulte Creación de informes sobre el aprovisionamiento automático de cuentas de usuario.

Nota:

El ciclo inicial tarda más tiempo en realizarse que las sincronizaciones posteriores, que se producen aproximadamente cada 40 minutos si se está ejecutando el servicio.

Si va a crear una aplicación que usará más de un inquilino, haga que esté disponible en la galería de aplicaciones de Microsoft Entra. Es fácil para las organizaciones descubrir la aplicación y configurar el aprovisionamiento. Publicar la aplicación en la galería de Microsoft Entra y hacer que el aprovisionamiento esté disponible para otros usuarios es fácil. Consulte los pasos aquí. Microsoft colaborará con usted a fin de integrar su aplicación en nuestra galería, probar su punto de conexión y publicar la documentación de incorporación de versiones para los clientes.

Use la lista de comprobación para incorporar la aplicación rápidamente y que los clientes tengan una experiencia de implementación fluida. La información se recopilará en el momento en que se incorpore a la galería.

  • Admitir un punto de conexión de grupo y usuario de SCIM 2.0 (solo se requiere uno, pero se recomiendan los dos)
  • Admitir al menos 25 solicitudes por segundo por inquilino para asegurarse de que los usuarios y grupos se aprovisionan y desaprovisionan sin retraso (obligatorio)
  • Establecimiento de contactos de ingeniería y soporte técnico para guiar la incorporación de clientes a la galería (obligatorio)
  • Tres credenciales de prueba sin expiración para la aplicación (obligatorio)
  • Compatibilidad con la concesión de código de autorización de OAuth o un token de larga duración, tal y como se describe en el ejemplo (obligatorio)
  • Las aplicaciones OIDC deben tener al menos 1 rol (personalizado o predeterminado) definido
  • Establecimiento de un punto de contacto de ingeniería y soporte técnico para respaldar la incorporación de clientes a la galería (obligatorio)
  • Compatibilidad con la detección de esquemas (obligatorio)
  • Compatibilidad con la actualización de varias pertenencias a grupos con una única instrucción PATCH
  • Documentación del punto de conexión de SCIM públicamente

La especificación SCIM no define un esquema específico de SCIM para la autenticación y autorización, sino que se basa en el uso de los estándares del sector existentes.

Método de autorización Ventajas Desventajas Soporte técnico
Nombre de usuario y contraseña (no recomendado ni compatible con Microsoft Entra ID) Fácil de implementar No seguro: Tu contraseña no importa No se admite para nuevas aplicaciones de la galería o que no son de la galería.
Token de portador de larga duración Los tokens de larga duración no requieren que haya un usuario presente. Son fáciles de usar para los administradores al configurar el aprovisionamiento. Los tokens de larga duración pueden ser difíciles de compartir con un administrador sin usar métodos no seguros como el correo electrónico. Compatibles con las aplicaciones de la galería y las que no forman parte de ella.
Concesión de código de autorización de OAuth Los tokens de acceso tienen una duración muy inferior a las contraseñas y tienen un mecanismo de actualización automatizado que los tokens de portador de larga duración no tienen. Un usuario real debe estar presente durante la autorización inicial, lo que añade un nivel de responsabilidad. Requiere que haya un usuario presente. Si el usuario deja la organización, el token no es válido y es necesario volver a realizar la autorización. Compatible con aplicaciones de la galería, pero no con aplicaciones que no son de la galería. Sin embargo, puede proporcionar un token de acceso a la interfaz de usuario como el token secreto para la realización de pruebas a corto plazo. La compatibilidad con la concesión de código de OAuth en aplicaciones que no son de la galería es un trabajo pendiente, al igual que la compatibilidad con direcciones URL de token o autenticación configurables en aplicaciones de la galería.
Concesión de credenciales del cliente de OAuth Los tokens de acceso tienen una duración muy inferior a las contraseñas y tienen un mecanismo de actualización automatizado que los tokens de portador de larga duración no tienen. Tanto la concesión de código de autorización como la concesión de credenciales de cliente crean el mismo tipo de token de acceso, por lo que el cambio entre estos métodos es transparente para la API. El aprovisionamiento se puede automatizar y los nuevos tokens se pueden solicitar silenciosamente sin la interacción del usuario. Compatible con aplicaciones de la galería, pero no con aplicaciones que no son de la galería. Sin embargo, puede proporcionar un token de acceso a la interfaz de usuario como el token secreto para la realización de pruebas a corto plazo. La compatibilidad de la concesión de credenciales de cliente de OAuth con aplicaciones que no son de la galería es un trabajo pendiente.

Nota:

No se recomienda dejar en blanco el campo de token en la interfaz de usuario de aplicaciones personalizada de la configuración de aprovisionamiento de Microsoft Entra. El token generado está disponible principalmente para fines de prueba.

Flujo de concesión de código de OAuth

El servicio de aprovisionamiento admite la concesión del código de autorización y, después de enviar la solicitud de publicación de la aplicación en la galería, nuestro equipo trabajará con usted para recopilar la información siguiente:

  • Dirección URL de autorización: una dirección URL del cliente para obtener la autorización del propietario del recurso a través de la redirección del agente de usuario. Se redirige al usuario a esta dirección URL para autorizar el acceso.

  • Dirección URL de intercambio de token: una dirección URL del cliente para intercambiar una concesión de autorización por un token de acceso, normalmente con autenticación del cliente.

  • Identificador de cliente: el servidor de autorización emite al cliente registrado un identificador de cliente, que es una cadena única que representa la información de registro que proporciona el cliente. El identificador de cliente no es un secreto; se expone al propietario del recurso y no debe usarse solo para la autenticación del cliente.

  • Secreto de cliente: un secreto generado por el servidor de autorización que debe ser un valor único que solo conoce el servidor de autorización.

Nota:

La dirección URL de autorización y la dirección URL de intercambio de tokens no se pueden configurar actualmente por inquilino.

Nota:

OAuth 1 no se admite debido a la exposición del secreto de cliente. Se admite OAuth v2.

Se recomienda, pero no es necesario, que admita varios secretos para facilitar la renovación sin tiempo de inactividad.

Configuración del flujo de concesión de código de OAuth

  1. Inicie sesión en el Centro de administración de Microsoft Entra al menos como Administrador de aplicaciones.

  2. Vaya a Identidad>Aplicaciones>Aplicaciones empresariales>Aplicación>Aprovisionamiento y seleccione Autorizar.

  3. Inicie sesión en el Centro de administración de Microsoft Entra al menos como Administrador de aplicaciones.

  4. Vaya a Aplicaciones de identidad>Aplicaciones>Empresariales.

  5. Seleccione su aplicación y, a continuación vaya a Aprovisionamiento.

  6. Seleccione Autorizar.

    1. Los usuarios se redirigen a la dirección URL de autorización (página de inicio de sesión de la aplicación de terceros).

    2. El administrador proporciona las credenciales a la aplicación de terceros.

    3. La aplicación de terceros redirige al usuario de vuelta y le proporciona el código de concesión

    4. Los servicios de aprovisionamiento llaman a la dirección URL del token y proporciona el código de concesión. La aplicación de terceros responde con el token de acceso, el token de actualización y la fecha de expiración.

  7. Cuando se inicia el ciclo de aprovisionamiento, el servicio comprueba si el token de acceso actual es válido y lo intercambia por un nuevo token si es necesario. El token de acceso se proporciona en cada solicitud realizada a la aplicación; asimismo, se comprueba la validez de la solicitud antes de cada solicitud.

Nota:

Aunque no es posible configurar OAuth en las aplicaciones que no son de la galería, puede generar un token de acceso manualmente desde el servidor de autorización y especificarlo como token de secreto en una aplicación que no pertenezca a la galería. Esto le permite verificar la compatibilidad de su servidor de SCIM con el servicio de aprovisionamiento de Microsoft Entra antes de incorporarse a la galería de aplicaciones, que sí admite la concesión de código OAuth.

Tokens de portador OAuth de larga duración: si la aplicación no admite el flujo de concesión de código de autorización de OAuth, también puede generar un token de portador de OAuth de larga duración que un administrador puede usar para configurar la integración del aprovisionamiento. El token debe ser perpetuo o, de lo contrario, el trabajo de aprovisionamiento se pondrá en cuarentena cuando expire el token.

Puede solicitar más métodos de autenticación y autorización en UserVoice.

Para ayudar a impulsar el reconocimiento y la demanda de nuestra integración conjunta, se recomienda actualizar la documentación existente y ampliar la integración en los canales de marketing. Se recomienda completar la siguiente lista de comprobación para admitir el inicio:

  • Asegúrese de que sus equipos de ventas y de atención al cliente estén enterados y preparados y puedan hablar con las funcionalidades de integración. Informe a los equipos, proporcióneles las preguntas frecuentes e incluya la integración en sus materiales de ventas.
  • Cree una entrada de blog o un comunicado de prensa que describan la integración conjunta, las ventajas y cómo empezar. Ejemplo: comunicado de prensa de Imprivata y Microsoft Entra
  • Aproveche sus redes sociales como Twitter, Facebook o LinkedIn para promover la integración en sus clientes. Asegúrese de incluir @Microsoft Entra ID para que podamos retwittear la publicación. Ejemplo: Publicación de Twitter de Imprivata
  • Cree o actualice las páginas o el sitio web de marketing (por ejemplo, la página de integración, la página de asociados, la página de precios, etc.) para incluir la disponibilidad de la integración conjunta. Ejemplo: Página de integración de Pingboard, Página de integración de Smartsheet, Página de precios de Monday.com
  • Cree un artículo en el centro de ayuda o documentación técnica sobre cómo pueden empezar los clientes. Ejemplo: Integración de Envoy + Microsoft Entra.
  • Avise a los clientes de la nueva integración a través de la comunicación al cliente (boletines mensuales, campañas por correo electrónico, notas de la versión del producto).

Pasos siguientes