Tutorial: Aprovisionamiento del plan y desarrollo 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.
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 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 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.
Diseñar 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.
Describir 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.
Crear 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 quiere, 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.
Integrar 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.
[Opcional] Publicar la aplicación en la galería de aplicaciones de Microsoft Entra: facilite a los clientes detectar la aplicación y configurar fácilmente el aprovisionamiento.
Diseño del 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 los 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:
Enumere los atributos que requiere la aplicación y, después, clasifíquelos 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).
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. Vea el ejemplo para otorgar una extensión al usuario que permita el aprovisionamiento de un usuario
tag.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 amplíe 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 | |
| manager | manager | manager |
| tag | 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/00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
}
}
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. Vea 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 |
| 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, vea 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 manera 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. |
Eliminar temporalmente un usuario active=false y restaurar el 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:
ides una propiedad obligatoria para todos los recursos. Todas las respuestas que devuelve un recurso deben asegurarse de que cada recurso tiene esta propiedad, exceptoListResponsecon 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 procesable. 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: 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 PATCH
op, como se define en la sección 3.5.2. Microsoft Entra ID emite los valores deopcomo Agregar, Reemplazar y Quitar. - Microsoft Entra ID realiza solicitudes para recuperar un usuario y un grupo al azar a fin de 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:
- La respuesta a una solicitud de consulta o filtrado siempre debe ser un elemento
ListResponse. - Microsoft Entra solo usa los siguientes operadores:
eq,and - El atributo en el que se pueden consultar los recursos debe establecerse como un atributo coincidente en la aplicación. Vea Personalización de las asignaciones de atributos de aprovisionamiento de usuarios.
/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 de tipo 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.
- El valor "displayName" de los grupos debe ser único para que coincida con Microsoft Entra ID y la aplicación SCIM. Esta singularidad no es un requisito del protocolo SCIM, pero sí lo es 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.
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:
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 a fin de 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, vea la sección Ciclos de aprovisionamiento: inicial e incremental en Funcionamiento del aprovisionamiento.
- Crear usuario (Solicitud / Respuesta)
- Obtener usuario (Solicitud / Respuesta)
- Obtener usuario por consulta (Solicitud / Respuesta)
- Obtener usuario por consulta: cero resultados (Solicitud / Respuesta)
- Actualizar usuario [propiedades con varios valores] (Solicitud / Respuesta)
- Actualizar usuario [propiedades con un solo valor] (Solicitud / Respuesta)
- Deshabilitar usuario (Solicitud / Respuesta)
- Eliminar usuario (Solicitud / Respuesta)
- Crear grupo (Solicitud / Respuesta)
- Obtener grupo (Solicitud / Respuesta)
- Obtener grupo por displayName (Solicitud / Respuesta)
- Actualizar grupo [Atributos no de miembro] (Solicitud / Respuesta)
- Actualizar grupo [Agregar miembros] (Solicitud / Respuesta)
- Actualizar grupo [Quitar miembros] (Solicitud / Respuesta)
- Eliminar grupo (Solicitud / Respuesta)
Operaciones de usuario
- Use los atributos
userNameoemails[type eq "work"]para consultar a los usuarios.
Crear usuario
Solicitar
POST /Users
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
"externalId": "0a21f0f2-8d2a-4f8e-bf98-7363c4aed4ef",
"userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"active": true,
"emails": [{
"primary": true,
"type": "work",
"value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com"
}],
"meta": {
"resourceType": "User"
},
"name": {
"formatted": "givenName familyName",
"familyName": "familyName",
"givenName": "givenName"
},
"roles": []
}
Respuesta
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
}]
}
Obtener usuario
Solicitar
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_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
}]
}
Solicitar
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
Solicitar
GET /Users?filter=userName eq "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
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: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
}
Obtener usuario por consulta: cero resultados
Solicitar
GET /Users?filter=userName eq "non-existent user"
Respuesta
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]
Solicitar
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"
}
]
}
Respuesta
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
}]
}
Actualizar usuario [propiedades de un solo valor]
Solicitar
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"
}]
}
Respuesta
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
}]
}
Deshabilitar usuario
Solicitar
PATCH /Users/5171a35d82074e068ce2 HTTP/1.1
{
"Operations": [
{
"op": "Replace",
"path": "active",
"value": false
}
],
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
]
}
Respuesta
{
"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
Solicitar
DELETE /Users/5171a35d82074e068ce2 HTTP/1.1
Respuesta
HTTP/1.1 204 No Content
Operaciones de grupo
- Los grupos se crean con una lista de miembros vacía.
- Use el atributo
displayNamepara 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
Solicitar
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"
}
}
Respuesta
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
Solicitar
GET /Groups/40734ae655284ad3abcc?excludedAttributes=members HTTP/1.1
Respuesta
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]
Solicitar
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"
}]
}
Respuesta
HTTP/1.1 204 No Content
Actualizar grupo [Agregar miembros]
Solicitar
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"
}]
}]
}
Respuesta
HTTP/1.1 204 No Content
Actualizar grupo [Eliminar miembros]
Solicitar
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"
}]
}]
}
Respuesta
HTTP/1.1 204 No Content
Eliminar grupo
Solicitar
DELETE /Groups/cdb1ce18f65944079d37 HTTP/1.1
Respuesta
HTTP/1.1 204 No Content
Detección de esquemas
Detección de esquema
Solicitar
GET /Schemas
Respuesta
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 AzureActiveDirectory 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í.
Creación de 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 que ha publicado la comunidad SCIM.
Para obtener instrucciones sobre cómo crear un punto de conexión de SCIM, incluidos ejemplos, vea 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. Cree un punto de conexión SCIM y, después, pruébelo ejecutando 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.
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 al 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
issidentifica el emisor del token. Por ejemplo,"iss":"https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/". En este ejemplo, la dirección base del valor de notificación identificahttps://sts.windows.netMicrosoft Entra ID como emisor, mientras que el segmento de dirección relativa, aaaabbbb-0000-cccc-1111-dddd2222eeee 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
isscon 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/aaaabbbb-0000-cccc-1111-dddd2222eeee/";
options.Audience = "8adf8e6e-67b2-4cf2-a259-e3dc5476c621";
...
});
}
...
}
public void Configure(IApplicationBuilder app)
{
...
app.UseAuthentication();
app.UseAuthorization();
...
}
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, vea 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/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 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: "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"
- 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. Pero 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: "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"
- parameters.AlternateFilters.ElementAt(y).AttributePath: "manager"
- parameters.AlternateFilters.ElementAt(y).ComparisonOperator: ComparisonOperator.Equals
- parameters.AlternateFilter.ElementAt(y).ComparisonValue: "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
- 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/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"}]}]}
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:
| Argument | Valor |
|---|---|
ResourceIdentifier.Identifier |
"a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1" |
ResourceIdentifier.SchemaIdentifier |
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User |
(PatchRequest as PatchRequest2).Operations.Count |
1 |
(PatchRequest as PatchRequest2).Operations.ElementAt(0).OperationName |
OperationName.Add |
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Path.AttributePath |
Manager |
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.Count |
1 |
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.ElementAt(0).Reference |
http://.../scim/Users/00aa00aa-bb11-cc22-dd33-44ee44ee44ee |
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.ElementAt(0).Value |
00aa00aa-bb11-cc22-dd33-44ee44ee44ee |
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/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 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: "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"
- 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 al 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, vea 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:
Inicie sesión en el Centro de administración de Microsoft Entra al menos como Administrador de aplicaciones.
Vaya a Aplicaciones de identidad>Aplicaciones>Empresariales.
Se muestra una lista de las aplicaciones configuradas, incluidas aquellas que se han agregado desde la galería.
Seleccione + Nueva aplicación>+ Cree su propia aplicación.
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:
En la pantalla de administración de la aplicación, seleccione Aprovisionamiento en el panel izquierdo.
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:
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/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.
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.
Si la conexión se realiza con éxito, seleccione Guardar para guardar las credenciales de administrador.
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".
En Configuración, el campo Á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.
Una vez completada la configuración, cambie el Estado de aprovisionamiento a Activado.
Seleccione Guardar para iniciar el servicio de aprovisionamiento de Microsoft Entra.
Si solo sincroniza usuarios y grupos asignados (recomendado), seleccione la pestaña Usuarios y grupos. Después, asigne los usuarios o grupos que quiera 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, vea 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.
Publicación de la aplicación en la galería de aplicaciones de Microsoft Entra
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.
Lista de comprobación de la incorporación a la galería
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)
- Establecer 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 un rol (personalizado o predeterminado) definido
- Establecer 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
- Documentar el punto de conexión de SCIM públicamente
Autorización para aprovisionar conectores en la galería de aplicaciones
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 es seguro: Tu contra$eñ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. Pero 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. Pero 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 mediante 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 v1 no se admite debido a la exposición del secreto de cliente. Se admite OAuth v2.
Al usar el flujo de concesión de código de OAuth, es necesario que admita un modelo en el que cada cliente enviará su propio id. de cliente y secreto de cliente al configurar una instancia de aprovisionamiento. No se admite un par único id. de cliente/secreto de cliente para toda la aplicación.
Configuración del flujo de concesión de código de OAuth
Inicie sesión en el Centro de administración de Microsoft Entra al menos como Administrador de aplicaciones.
Vaya a Identidad>Aplicaciones>Aplicaciones empresariales>Aplicación>Aprovisionamiento y seleccione Autorizar.
Inicie sesión en el Centro de administración de Microsoft Entra al menos como Administrador de aplicaciones.
Vaya a Aplicaciones de identidad>Aplicaciones>Empresariales.
Seleccione su aplicación y vaya a Aprovisionamiento.
Seleccione Autorizar.
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).
El administrador proporciona las credenciales a la aplicación de terceros.
La aplicación de terceros redirige al usuario de vuelta y le proporciona el código de concesión
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.
Cuando se inicia el ciclo de aprovisionamiento, el servicio comprueba si el token de acceso actual es válido y lo intercambia por uno nuevo 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.
Lista de comprobación del lanzamiento de la comercialización en la galería
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 X, Facebook o LinkedIn para promover la integración en sus clientes. Asegúrese de incluir @Microsoft Entra ID para que podamos retuitear la publicación. Ejemplo: Publicación de Imprivata en X
- Cree o actualice las páginas o el sitio web de marketing (como 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 mediante la comunicación al cliente (boletines mensuales, campañas por correo electrónico, notas de la versión del producto).
Pasos siguientes
Desarrollo de un punto de conexión de SCIM de ejemploAutomatización del aprovisionamiento y desaprovisionamiento de usuarios para aplicaciones SaaSPersonalización de las asignaciones de atributos para el aprovisionamiento de usuariosEscritura de expresiones para asignaciones de atributosDeterminación de los filtros para el aprovisionamiento de usuariosNotificaciones de aprovisionamiento de cuentasLista de tutoriales sobre cómo integrar aplicaciones SaaS