Nota
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
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 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 la 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 el esquema de usuario y grupo : identifique los objetos y atributos de la aplicación para determinar cómo se asignan al esquema de usuario y grupo compatible con la implementación de SCIM de Microsoft Entra.
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 SCIM.
Compilación de un punto de conexión 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.
Integre el punto de conexión 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 : facilita a los clientes detectar la aplicación y configurar fácilmente el aprovisionamiento.
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 los atributos (nombre, administrador, puesto, etc.) necesarios que requiera la aplicación.
El estándar SCIM define un esquema para administrar usuarios y grupos.
El esquema de usuario principal solo requiere tres atributos (todos los demás atributos son opcionales):
-
id, identificador definido por el proveedor de servicios -
userName, un identificador único del 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 con un modelo para extender el esquema de usuario para satisfacer las necesidades de la aplicación.
Por ejemplo, si la aplicación requiere tanto el correo electrónico de un usuario como el administrador del 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, 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).
Compruebe si los 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.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 |
|---|---|---|
| nombre de usuario | nombre de usuario | nombre principal de usuario |
| firstName | name.givenName | givenName |
| lastName | name.familyName | surName |
| workMail | emails[type eq "work"].value | |
| gerente | gerente | gerente |
| etiqueta | urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User:tag |
extensionAttribute1 |
| estado | activo | 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.
Ayuda a clasificar entre /User y /Group y mapear los atributos predeterminados de usuario de Microsoft Entra ID con el RFC de SCIM, consulte cómo se mapean los 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 | activo |
| departamento | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department |
| displayName | displayName |
| ID de empleado | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber |
| Facsimile-TelephoneNumber | phoneNumbers[type eq "fax"].value |
| givenName | name.givenName |
| título del trabajo | título |
| correo | emails[type eq "work"].value |
| mailNickname | externalId |
| gerente | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager |
| móvil | phoneNumbers[type eq "mobile"].value |
| Código postal | 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 |
| apellido | name.familyName |
| número de teléfono | phoneNumbers[type eq "work"].value |
| user-PrincipalName | nombre de usuario |
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 |
| Miembros | Miembros |
| 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 |
|---|---|
| /Usuario | Realiza operaciones CRUD en un objeto de usuario. |
| /Grupo | Realiza operaciones CRUD en un objeto de grupo. |
| /Esquemas | 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). Aunque hoy no se admite SCIM /Bulk, esto es algo que pretendemos admitir en el futuro para ayudar a mejorar el rendimiento. |
| /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. Aunque hoy no se admite el punto de conexión /Bulk, esto es algo que pretendemos admitir en el futuro para ayudar a mejorar el rendimiento.
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 lo que ha cambiado, consulte Cumplimiento del protocolo 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 detección 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 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 todo el recurso en la respuesta PATCH .
- No exige una coincidencia de mayúsculas y minúsculas en los elementos estructurales de SCIM, en particular en los valores de operación PATCH
op, tal 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 para tener la seguridad de que el punto de conexión y las credenciales sean válidas. También se hace como parte del flujo de Prueba de 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 una
ListResponse. - Microsoft Entra solo usa los siguientes operadores:
eq,and - El atributo por el que se pueden consultar los recursos debe establecerse como un atributo coincidente en la aplicación. Consulte Personalización de las asignaciones de atributos para el aprovisionamiento de usuarios.
/Usuarios:
- 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 (por ejemplo, si se evalúa la unicidad del usuario tanto para userName como para correos electrónicos[type eq "work"], una solicitud GET a /Users con un filtro debe permitir tanto las consultas userName eq "user@contoso.com" como emails[type eq "work"].value eq "user@contoso.com".
/Grupos:
- 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 o 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 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 descritas en el ejemplo, consulte la sección Ciclos de aprovisionamiento: Inicial e incremental en Funcionamiento del aprovisionamiento.
- Crear usuario (respuesta de solicitud / )
- Obtener usuario (Solicitud / Respuesta)
- Obtener usuario por consulta (Solicitud / Respuesta)
- Obtener usuario por consulta: cero resultados (Solicitud / Respuesta)
- Actualizar usuario [propiedades multivalor] (Request / Response)
- Actualizar usuario [propiedades con valores únicos] (respuesta de solicitud / )
- Deshabilitar usuario (respuesta de solicitud / )
- Eliminar usuario (respuesta de solicitud / )
- Crear grupo (respuesta de solicitud / )
- Obtener grupo (Solicitud / Respuesta)
- Obtener grupo por displayName (Solicitud / Respuesta)
- Actualizar grupo [atributos no miembros] (Solicitud / Respuesta)
- Actualizar grupo [Agregar miembros] (respuesta de solicitud / )
- Actualizar grupo [Quitar miembros] (respuesta de solicitud / )
- Eliminar grupo (respuesta de solicitud / )
Operaciones de usuario
- Use atributos
userNameoemails[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_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
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_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
}]
}
Solicitud
GET /Users/5171a35d82074e068ce2
Respuesta (Usuario no encontrado. El detalle no es necesario, solo el estado).
No se encontró HTTP/1.1 404
{
"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_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
Solicitud
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]
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"
}
]
}
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]
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"
}]
}
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
Solicitud
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
Solicitud
DELETE /Users/5171a35d82074e068ce2 HTTP/1.1
Respuesta
HTTP/1.1 204 Sin contenido
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
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"
}
}
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
Solicitud
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
Solicitud
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"
}]
}
Respuesta
HTTP/1.1 204 Sin contenido
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"
}]
}]
}
Respuesta
HTTP/1.1 204 Sin contenido
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"
}]
}]
}
Respuesta
HTTP/1.1 204 Sin contenido
Eliminar grupo
Solicitud
DELETE /Groups/cdb1ce18f65944079d37 HTTP/1.1
Respuesta
HTTP/1.1 204 Sin contenido
Detección de esquemas
Detección de esquema
Solicitud
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 TLS
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.
Longitudes de clave
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 AzureActiveDirectory para permitir el tráfico del 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 mediante programación la lista de intervalos IP mediante 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. 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 SCIM, incluidos ejemplos, consulte Desarrollo de un punto de conexión SCIM de ejemplo.
El ejemplo de código de referencia de .NET Core de código abierto publicado por el equipo de aprovisionamiento de Microsoft Entra es un recurso de este tipo que puede iniciar el desarrollo. Compile un punto de conexión SCIM y, a continuación, pruárelo 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 convierten en llamadas a los métodos del proveedor, los cuales se programarán para operar en un almacén de identidades.
El proyecto Microsoft.SCIM.WebHostSample es una aplicación web principal de ASP.NET, basada en la plantilla Vacía . 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 vínculo siguiente: 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 SCIM requiere un token de portador de OAuth desde un emisor distinto de Microsoft Entra ID, copie el token de portador de OAuth necesario en el campo Token secreto opcional. 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 el campo Token secreto 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.
- 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,https://sts.windows.netidentifica el identificador de Microsoft Entra 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 de 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 obtener más información sobre varios entornos en 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 token para obtener un token de portador válido, el método GenerateJSONWebToken es 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 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 usado para buscar coincidencias (que en este caso es externalId) se puede configurar 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:
- Parámetros.FiltrosAlternativos.Cantidad: 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"
- IdentificadorDeEsquema:
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:
- Parámetros.FiltrosAlternativos.Cantidad: 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 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:
| Argumento | 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 |
Administrador |
(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 aprovisionar automáticamente usuarios y grupos asignados a las aplicaciones que implementan un perfil específico del protocolo SCIM 2.0. Los detalles del perfil se documentan en Comprender 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
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 admita SCIM:
Inicie sesión en el Centro de administración de Microsoft Entra como al menos un administrador de aplicaciones.
Vaya a Entra ID>Aplicaciones empresariales.
Se muestra una lista de las aplicaciones configuradas, incluidas aquellas que se han agregado desde la galería.
Seleccione + Nueva aplicación>+ Crear su propia aplicación.
Escriba un nombre para la aplicación, elija la opción "integrar cualquier otra aplicación que no 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 aplicaciones, seleccione Aprovisionamiento en el panel izquierdo.
Seleccione + Nueva configuración.
En el campo 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 SCIM requiere un token de portador de OAuth desde un emisor distinto de Microsoft Entra ID, copie el token de portador de OAuth necesario en el campo Token secreto opcional. 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 y confiar en un token generado por el identificador de Entra de Microsoft. 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 misma propiedad 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 el intento de conectarse a la aplicación se realiza correctamente, seleccione Crear para crear el trabajo de aprovisionamiento.
Si solo se sincronizan usuarios y grupos asignados (recomendado), seleccione la pestaña Usuarios y grupos . A continuación, asigne los usuarios o grupos que desea sincronizar.
Seleccione Asignación de atributos en el panel izquierdo. Hay dos conjuntos seleccionables de asignaciones de atributos: una para los objetos de usuario y otra 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. Seleccione Guardar para confirmar los cambios.
Opcionalmente, puede deshabilitar la sincronización de objetos de grupo deshabilitando la asignación de "grupos".
Seleccione Aprovisionar a petición en el panel izquierdo. Busque un usuario que esté dentro del ámbito de aprovisionamiento y aprovisiónelo a petición. Repita con otros usuarios con los que desea probar el aprovisionamiento.
Una vez completada la configuración, seleccione Información general en el panel izquierdo.
Seleccione Propiedades.
Seleccione el lápiz para editar las propiedades. Habilite los correos electrónicos de notificación y proporcione un correo electrónico para recibir correos electrónicos de cuarentena. Habilitación de la prevención de eliminaciones accidentales. Haga clic en Aplicar para guardar los cambios.
Seleccione Iniciar aprovisionamiento para iniciar el servicio de aprovisionamiento de Microsoft Entra.
Una vez iniciado el ciclo inicial, puede seleccionar Registros de aprovisionamiento en el panel izquierdo para supervisar el progreso, que muestra todas las acciones realizadas por el servicio de aprovisionamiento en la aplicación. Para obtener más información sobre cómo leer los registros de aprovisionamiento de Microsoft Entra, consulte 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.
Publicar 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 que se indican aquí. Microsoft trabaja con usted para integrar la aplicación en la galería, probar el punto de conexión y publicar la documentación de incorporación 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.
- Soportar un punto de conexión para usuario y grupo de SCIM 2.0 (solo se requiere uno, pero se recomiendan ambos)
- 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
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 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 de 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 siguiente información:
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.
URL de intercambio de tokens, una URL proporcionada por el cliente para intercambiar una concesión de autorización por un token de acceso, generalmente con autenticación del cliente.
Id. 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 proporcionada por el cliente. El identificador de cliente no es un secreto; se expone al propietario del recurso y no se debe usar solo para la autenticación de cliente.
Secreto de cliente, un secreto generado por el servidor de autorización que debe ser un valor único conocido solo para 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.
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 identificador 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 como al menos un administrador de aplicaciones.
Vaya a Entra ID>Aplicaciones empresariales>Aplicación>Aprovisionamiento y seleccione Autorizar.
Inicie sesión en el Centro de administración de Microsoft Entra como al menos un administrador de aplicaciones.
Vaya a Entra ID>Aplicaciones empresariales.
Seleccione la 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 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 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.
Para obtener más métodos de autenticación y autorización, háganoslo saber 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: Imprivata y Comunicado de prensa de Microsoft Entra
- Aproveche sus redes sociales como X, Facebook o LinkedIn para fomentar la integración en sus clientes. Asegúrese de incluir @Microsoft Entra ID para que podamos retuitear la publicación. Ejemplo: Imprivata X Post
- 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, Monday.com página de precios
- 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
Desarrollar un punto de conexión SCIM de ejemploAutomatizar el aprovisionamiento y desaprovisionamiento de usuarios en aplicaciones SaaSPersonalizar las asignaciones de atributos para el aprovisionamiento de usuariosEscribir expresiones para las asignaciones de atributosFiltros de ámbito para el aprovisionamiento de usuariosNotificaciones de aprovisionamiento de cuentasLista de tutoriales sobre cómo integrar aplicaciones SaaS