Referencia de la API SCIM de Microsoft Entra ID

Use esta guía de referencia para aprovisionar (sincronizar) usuarios y grupos en Microsoft Entra ID mediante el protocolo System for Cross-domain Identity Management (SCIM) v2.0.

Introducción a la API de SCIM

La implementación de SCIM de Microsoft Entra ID se basa en los siguientes borradores de IETF:

• RFC 7642: Sistema para administración de identidades entre dominios: definiciones, información general, conceptos y requisitos
• RFC 7643: System for Cross-domain Identity Management: Core Schema
• RFC 7644: Sistema para administración de identidades entre dominios: protocolo
• RFC 9865: paginación basada en cursores de recursos SCIM

Todos los puntos de conexión de LA API de SCIM se encuentran en la dirección URL base: https://graph.microsoft.com/rp/scim

Las secciones siguientes contienen ejemplos de solicitudes de API y respuestas que se admiten actualmente en la implementación de SCIM de Microsoft Entra ID, junto con notas y restricciones importantes que se deben tener en cuenta en el diseño.

Invocación de las API de SCIM

Para poder llamar a los puntos de conexión de LA API de SCIM descritos en este artículo, debe habilitar la característica DE API de aprovisionamiento de SCIM, configurar la facturación, configurar las credenciales y obtener un token de acceso. Para obtener instrucciones paso a paso, consulte Enable la API de aprovisionamiento de SCIM en Microsoft Entra ID.

Si usa el punto de conexión de Microsoft Graph en la nube de la Administración Pública de EE. UU., use https://graph.microsoft.us/rp/scim como dirección URL base para las solicitudes de API de SCIM. En los ejemplos de este artículo se usa https://graph.microsoft.com para ilustrar el punto de conexión de la nube global.

Mapeo de las propiedades de usuario y grupo de Graph

Para obtener información sobre cómo las propiedades de usuario y grupo de Microsoft Graph se asignan a los atributos de usuario y grupo de SCIM, refiérase al esquema de referencia de la API SCIM de Microsoft Entra ID.

Throttling

Las mismas directrices de limitación y los mismos límites de limitación específicos del servicio que se aplican a las API de Microsoft Graph también se aplican a las API SCIM de Microsoft Entra ID. Para conocer las directivas de limitación que se aplican a las API de usuario y grupo de Microsoft Graph, consulte la guía de limitación de Microsoft Graph y los límites de limitación específicos del servicio de Microsoft Graph para las API de identidad y acceso.

Errors

Para obtener una lista de los códigos de error comunes devueltos por los puntos de conexión de la API de SCIM, consulte Referencia de códigos de error de la API de SCIM.

Obtener la configuración del proveedor de servicios

Utilice el /ServiceProviderConfig punto de conexión para ver información adicional sobre la implementación de SCIM de Microsoft Entra ID. El /ServiceProviderConfig punto de conexión es de solo lectura.

Punto de conexión de API:https://graph.microsoft.com/rp/scim/serviceproviderconfig

Tras la operación correcta, la API devuelve el estado HTTP 200.

Permisos

Ejemplo 1: solicitud de configuración del proveedor de servicios

Solicitud:

GET https://graph.microsoft.com/rp/scim/serviceproviderconfig
Authorization: Bearer {token}
Accept: application/json

Respuesta (200 OK):

La respuesta se trunca para mejorar la legibilidad.

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"],
  "documentationUri": "/graph/overview",
  "pagination": {
    "cursor": true,
    "index": false,
    "defaultPaginationMethod": "cursor",
    "defaultPageSize": 100,
    "maxPageSize": 1000
  },
  "patch": {
    "supported": true
  },
  "bulk": {
    "supported": false,
    "maxOperations": 0,
    "maxPayloadSize": 0
  },
  "filter": {
    "supported": true,
    "maxResults": 200
  }
}

Enumerar tipos de recursos

Para recuperar información sobre los tipos de recursos admitidos, realice una solicitud al punto de conexión /resourcetypes.

Puntos de conexión de API:

• https://graph.microsoft.com/rp/scim/resourcetypes
• https://graph.microsoft.com/rp/scim/resourcetypes/{identifier}

Tras la operación correcta, la API devuelve el estado HTTP 200.

Permisos

Ejemplo 1: Solicitud de todos los tipos de recursos

Solicitud:

GET https://graph.microsoft.com/rp/scim/resourcetypes
Authorization: Bearer {token}
Accept: application/json

Respuesta (200 OK):

La respuesta se trunca para mejorar la legibilidad.

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 2,
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
      "id": "User",
      "name": "User",
      "endpoint": "/Users",
      "description": "User Account",
      "schema": "urn:ietf:params:scim:schemas:core:2.0:User",
      "schemaExtensions": [
        {
          "schema": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
          "required": false
        },
        {
          "schema": "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User",
          "required": false
        }
      ],
      "meta": {
        "location": "/resourcetypes/user",
        "resourceType": "resourceType"
      }
    },
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
      "id": "Group",
      "name": "Group",
      "endpoint": "/Groups",
      "description": "Group",
      "schema": "urn:ietf:params:scim:schemas:core:2.0:Group",
      "schemaExtensions": [
        {
          "schema": "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group",
          "required": true
        }
      ],
      "meta": {
        "location": "/resourcetypes/group",
        "resourceType": "resourceType"
      }
    }
  ]
}

Ejemplo 2: Solicitud del tipo de recurso de usuario

Solicitud:

GET https://graph.microsoft.com/rp/scim/resourcetype/User
Authorization: Bearer {token}
Accept: application/json

Respuesta (200 OK):

La respuesta se trunca para mejorar la legibilidad.

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
  "id": "User",
  "name": "User",
  "endpoint": "/Users",
  "description": "User Account",
  "schema": "urn:ietf:params:scim:schemas:core:2.0:User",
  "schemaExtensions": [
    {
      "schema": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
      "required": false
    }
  ],
  "meta": {
    "location": "/resourcetypes/user",
    "resourceType": "resourceType"
  }
}

Obtener esquema

Para obtener información sobre los esquemas SCIM admitidos, realice una solicitud al punto de conexión /schemas.

Puntos de conexión de API:

• https://graph.microsoft.com/rp/scim/schemas
• https://graph.microsoft.com/rp/scim/schemas/{identifier}

Tras la operación correcta, la API devuelve el estado HTTP 200.

Permisos

Ejemplo 1: Solicitud de todos los esquemas

Solicitud:

GET https://graph.microsoft.com/rp/scim/schemas
Authorization: Bearer {token}
Accept: application/json

Respuesta (200 OK):

La respuesta se trunca para mejorar la legibilidad.

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 5,
  "Resources": [
    {
      "id": "urn:ietf:params:scim:schemas:core:2.0:User",
      "name": "User",
      "description": "User Account",
      "attributes": [...]
    },
    {
      "id": "urn:ietf:params:scim:schemas:core:2.0:Group",
      "name": "Group",
      "description": "Group",
      "attributes": [...]
    }
  ]
}

Ejemplo 2: Solicitud del esquema de usuario

Solicitud:

GET https://graph.microsoft.com/rp/scim/schemas/urn:ietf:params:scim:schemas:core:2.0:User
Authorization: Bearer {token}
Accept: application/json

Respuesta (200 OK):

La respuesta se trunca para mejorar la legibilidad.

{
  "id": "urn:ietf:params:scim:schemas:core:2.0:User",
  "name": "User",
  "description": "User Account",
  "attributes": [...]
}

Ejemplo 3: Solicitud del esquema de atributos de seguridad personalizados

Solicitud:

GET https://graph.microsoft.com/rp/scim/schemas/urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:CustomSecurityAttributes
Authorization: Bearer {token}
Accept: application/json

Respuesta (200 OK):

La respuesta se trunca para mejorar la legibilidad.

{
  "id": "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:CustomSecurityAttributes",
  "name": "MicrosoftEntraCustomSecurityAttributes",
  "description": "Microsoft Entra Custom Security Attributes",
  "attributes": [
    {
      "name": "Project",
      "type": "complex",
      "multiValued": false,
      "description": "Projects assigned to the user",
      "required": false,
      "caseExact": false,
      "subAttributes": [
        {
          "name": "ProjectName",
          "type": "String",
          "multiValued": false,
          "description": "Name of the project",
          "required": false,
          "caseExact": false,
          "mutability": "readWrite",
          "returned": "default",
          "uniqueness": "none"
        }
      ],
      "mutability": "readWrite",
      "returned": "request",
      "uniqueness": "none"
    }, …
]
}

Listar usuarios

Use el /users punto de conexión para realizar las siguientes operaciones:

• Obtener todos los usuarios del inquilino (con paginación).

• Obtener usuarios que coincidan con criterios de filtro específicos.

Punto de conexión de API:

https://graph.microsoft.com/rp/scim/users

Tras la operación correcta, la API devuelve el estado HTTP 200.

Si la respuesta contiene varias páginas, use la paginación basada en cursores para recuperar todas las páginas del resultado.

Permisos

Parámetros de consulta para enumerar usuarios

Los siguientes parámetros de consulta SCIM se pueden usar con este punto de conexión de API:

• filter : para especificar criterios de filtro que se van a aplicar

• atributos : para especificar qué atributos de usuario debe devolver el servidor.

• excludedAttributes : para especificar qué atributos de usuario debe excluir el servidor.

• count : para especificar el número de resultados que se van a recuperar. El valor predeterminado es 100. Las solicitudes proyectadas más grandes admiten un valor de hasta 999, sujeto a las restricciones de la sección siguiente.

• cursor : para avanzar a la página de resultados siguiente

Restricciones para los usuarios de lista

La implementación de SCIM de Microsoft Entra ID tiene las siguientes restricciones:

• El tamaño de página predeterminado es 100 entradas por página.

• Para solicitar entre 101 y 999 usuarios por página, especifique attributes y no incluya urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager en la proyección.

• Si la attributes proyección incluye urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager, el servicio omite un count valor mayor que 100 y usa el tamaño de página predeterminado de 100.

• Se permiten los siguientes atributos de usuario para el operador de eq comparación:

  • active. Los valores booleanos no distinguen entre mayúsculas y minúsculas, incluyendo true, false, TRUE y FALSE.
  • userName
  • externalId
  • id
  • groups.value
  • urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User:mailNickname
  • urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User:ownedGroups.value

• Se permiten los siguientes atributos de usuario para el ew operador de comparación (termina con):

  • userName
  • urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User:mailNickname

• Use el not operador para negar una ew comparación en userName o mailNickname. Use el and operador lógico para combinar filtros admitidos.

• Los espacios en blanco codificados o sin codificar en la cadena de consulta alrededor de "=" conducen a rechazar la solicitud con un error "BadRequest". Esto se aplica a todos los parámetros de consulta: filtro, atributos, excludedAttributes, count y cursor.

• El filtro combinado no es compatible para su uso con el atributo externalId. Por ejemplo, no se puede usar el siguiente filtro de combinación:

GET https://graph.microsoft.com/rp/scim/users?filter=externalId eq '12345' and userName eq 'user@contoso.com' 

Los ejemplos siguientes solo incluyen los detalles de la solicitud. La respuesta no se incluye por motivos de brevedad. Se ajusta a la carga de respuesta SCIM estándar.

Ejemplo 1A: Obtener todos los usuarios

Solicitud:

GET https://graph.microsoft.com/rp/scim/users
Authorization: Bearer {token}
Accept: application/json

Respuesta (200 OK):

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "itemsPerPage": 100,
  "nextCursor": "RFNwdAIAAQAAAB06MTAyMDE4QHhmcDFiLm9ubWljcm9zb2Z0LmNvbS...",
  "resources": [
    {
      "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:Microsoft:Entra:2.0:User"
      ],
      "id": "d3d3d3d3-eeee-ffff-aaaa-b4b4b4b4b4b4",
      "active": true,
      "displayName": "Ellen Reckert",
      "name": {
        "familyName": "Reckert",
        "givenName": "Ellen"
      },
      "userName": "100009@contoso.com",
      "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "department": "Human Resources US",
        "employeeNumber": "100009",
        "manager": {
          "value": "bbbbbbbb-7777-8888-9999-cccccccccccc"
        }
      },
      "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User": {
        "mailNickname": "100009",
        "userType": "Member"
      },
      "meta": {
        "location": "/users/d3d3d3d3-eeee-ffff-aaaa-b4b4b4b4b4b4",
        "resourceType": "user"
      }
    },
    { ... }
  ]
}

Ejemplo 1B: recuperar la página siguiente para listar todos los usuarios

La consulta anterior devuelve de forma predeterminada 100 usuarios por página. Si tienes más de 100 usuarios en tu inquilino, utiliza la paginación para recuperar el siguiente conjunto de usuarios estableciendo el parámetro de consulta cursor en el valor nextCursor recibido en la respuesta.

GET https://graph.microsoft.com/rp/scim/users?cursor=RFNwdAIAAQAAAB06MTAyMDE4QHhmcDFiLm9ubWljcm9zb2Z0LmNvbS...
Authorization: Bearer {token}
Accept: application/json

Ejemplo 1C: Uso del parámetro count para controlar los usuarios devueltos

Puede solicitar hasta 999 usuarios por página cuando especifique una attributes proyección que no incluya el urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager atributo .

GET https://graph.microsoft.com/rp/scim/users?filter=active eq true&count=999&attributes=userName,id,displayName
Authorization: Bearer {token}
Accept: application/json

GET https://graph.microsoft.com/rp/scim/users?filter=active eq true&count=999&attributes=userName,id,displayName&cursor=RFNwdAIAAQAAAB06MTAyMDE4QHhmcDFiLm9ubWljcm9zb2Z0LmNvbS...
Authorization: Bearer {token}
Accept: application/json

Ejemplo 2: Obtener usuario por ID con atributos específicos

Solicitud:

GET https://graph.microsoft.com/rp/scim/users?filter=id eq "97c0abe1-14f7-417b-951c-bc8e2a17f200"&attributes=name.familyName,displayName
Authorization: Bearer {token}

Ejemplo 3: Obtención de usuarios con un conjunto de atributos de seguridad personalizado

Solicitud:

GET https://graph.microsoft.com/rp/scim/users?attributes=urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:CustomSecurityAttributes:attributeSetName
Authorization: Bearer {token}

Ejemplo 4 - Obtener usuario por ID con atributos excluidos

Solicitud:

GET https://graph.microsoft.com/rp/scim/users?filter=id eq "97c0abe1-14f7-417b-951c-bc8e2a17f200"&excludedAttributes=name.familyName,displayName
Authorization: Bearer {token}

Ejemplo 5: Obtener usuario por mailNickname

Solicitud:

GET https://graph.microsoft.com/rp/scim/users?filter=urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User:mailNickname eq "100009"&attributes=displayName
Authorization: Bearer {token}

Respuesta (200 OK):

La respuesta se trunca para mejorar la legibilidad.

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User"
      ],
      "id": "f5f5f5f5-aaaa-bbbb-cccc-d6d6d6d6d6d6",
      "displayName": "Ellen Reckert",
      "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User": {
        "mailNickname": "100009"
      },
      "meta": {
        "location": "/users/f5f5f5f5-aaaa-bbbb-cccc-d6d6d6d6d6d6",
        "resourceType": "user"
      }
    }
  ]
}

Ejemplo 6: Obtener usuario por nombre de usuario

Solicitud:

GET https://graph.microsoft.com/rp/scim/users?filter=userName eq "AdeleV@contoso.com"
Authorization: Bearer {token}

Ejemplo 7: Obtener usuarios activos

El active filtro booleano no distingue mayúsculas de minúsculas.

Solicitud:

GET https://graph.microsoft.com/rp/scim/users?filter=active eq true
Authorization: Bearer {token}

Ejemplo 8: excluir usuarios por sufijo mailNickname y filtrar por sufijo userName

Use not para negar las comparaciones admitidas ew y and para combinar los filtros.

Solicitud:

GET https://graph.microsoft.com/rp/scim/users?filter=not(urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User:mailNickname ew "-admin") and not(urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User:mailNickname ew "-ga") and userName ew "@contoso.com"
Authorization: Bearer {token}

Ejemplo 9: Obtención de usuarios por identificador de grupo

Solicitud:

Use el ID de objeto de grupo de Microsoft Entra para la propiedad groups.value para recuperar los miembros directos de un grupo. Use esta consulta en lugar de solicitar el members atributo de GET /groups/{id}.

GET https://graph.microsoft.com/rp/scim/users?filter=groups.value eq "c2c2c2c2-dddd-eeee-ffff-a3a3a3a3a3a3"&attributes=displayName
Authorization: Bearer {token}

Respuesta (200 OK) Respuesta truncada para mejorar la legibilidad.

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "id": "d3d3d3d3-eeee-ffff-aaaa-b4b4b4b4b4b4",
      "displayName": "Ellen Reckert",
      "meta": {
        "location": "/users/d3d3d3d3-eeee-ffff-aaaa-b4b4b4b4b4b4",
        "resourceType": "user"
      }
    }
  ]
}

Ejemplo 10: Obtención de usuarios propietarios de un grupo

Aunque ownedGroups no se devuelve en los cuerpos de las respuestas de usuario, puede usar su subatributo value como destino de filtro. Especifique el espacio de nombres completo de la extensión de usuario de Microsoft Entra.

Solicitud:

GET https://graph.microsoft.com/rp/scim/users?filter=urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User:ownedGroups.value eq "c2c2c2c2-dddd-eeee-ffff-a3a3a3a3a3a3"
Authorization: Bearer {token}

Ejemplo 11: Recuperación de atributos de seguridad personalizados específicos para un usuario

GET https://graph.microsoft.com/rp/scim/users?filter=userName eq "AdeleV@contoso.com"&attributes=urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:CustomSecurityAttributes:Project
Authorization: Bearer {token}

Respuesta (200 OK) Respuesta truncada para mejorar la legibilidad.

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:CustomSecurityAttributes"
      ],
      "id": "b1b1b1b1-cccc-dddd-eeee-f2f2f2f2f2f2",
      "userName": "AdeleV@contoso.com",
      "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:CustomSecurityAttributes": {
        "Project": {
          "ProjectName": "IdentityHub"
        }
      },
      "meta": {
        "location": "/users/b1b1b1b1-cccc-dddd-eeee-f2f2f2f2f2f2",
        "resourceType": "user"
      }
    }
  ]
}

Obtener usuario por ID

Los usuarios existentes se pueden recuperar realizando una solicitud GET al punto de conexión /users con un identificador de usuario.

Puntos de conexión de API:

https://graph.microsoft.com/rp/scim/users/{id}

Tras la operación correcta, la API devuelve el estado HTTP 200.

Permisos

Parámetros de consulta para Obtener usuario por identificador

Los siguientes parámetros de consulta SCIM se pueden usar con este punto de conexión de API:

• atributos: para especificar qué atributos de usuario debe devolver el servidor.

• excludedAttributes: para especificar qué atributos de usuario debe excluir el servidor.

Ejemplo 1: Obtener usuario por ID con atributos específicos

Solicitud:

GET https://graph.microsoft.com/rp/scim/users/aaaaaaaa-6666-7777-8888-bbbbbbbbbbbb?attributes=displayName,userName
Authorization: Bearer {token}

Respuesta (200 OK):

La respuesta se trunca para mejorar la legibilidad.

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "aaaaaaaa-6666-7777-8888-bbbbbbbbbbbb",
  "displayName": "Adele Vance",
  "userName": "AdeleV@contoso.com",
  "meta": {
    "location": "/users/aaaaaaaa-6666-7777-8888-bbbbbbbbbbbb",
    "resourceType": "user"
  }
}

Creación de un usuario

Puede crear un nuevo usuario en Microsoft Entra ID enviando una solicitud POST al punto de conexión /users.

Puntos de conexión de API:

PUBLICAR https://graph.microsoft.com/rp/scim/users

Tras la operación correcta, la API devuelve el estado HTTP 201.

Permisos

Atributos necesarios para crear un usuario

Los atributos siguientes son necesarios para la creación correcta del usuario:

• userName

• password

• name.familyName

• name.givenName

• active

• displayName

Ejemplo 1: Creación de un nuevo usuario

Solicitud:

POST https://graph.microsoft.com/rp/scim/users
Authorization: Bearer {token}
Content-Type: application/scim+json

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "active": true,
  "displayName": "Example User",
  "userName": "abc123@contoso.com",
  "password": "password",
  "name": {
    "familyName": "Example familyName",
    "givenName": "Example givenName"
  }
}

Respuesta (201 creada):

Devuelve la representación SCIM del usuario creado.

En este ejemplo, Microsoft Entra ID deriva el mailNickname valor abc123 de userName.

Actualizar un usuario

El punto de conexión /users permite realizar una solicitud PATCH para actualizar un perfil de usuario existente.

Puntos de conexión de API:

PATCH https://graph.microsoft.com/rp/scim/users/{id}

Tras la operación correcta, la API devuelve el estado HTTP 204.

Permisos

Restricciones para actualizar un usuario

• En el caso de las operaciones PATCH, al actualizar atributos complejos con varios valores como direcciones, la propiedad path solo admite el filtro "[type eq " work"]".

• Una vez creado un usuario, el mailNickname atributo no se puede quitar mediante una operación PATCH.

Ejemplo 1: actualización de un valor de atributo

Solicitud:

PATCH https://graph.microsoft.com/rp/scim/users/ec3f07a3-2aa4-4666-b2fd-90e479428791
Authorization: Bearer {token}
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "displayName",
      "value": "Johnathan Doe"
    }
  ]
}

Respuesta (204 Sin contenido):

La respuesta se ajusta a la especificación SCIM.

Ejemplo 2: actualización de un valor complejo

Solicitud:

PATCH https://graph.microsoft.com/rp/scim/users/ec3f07a3-2aa4-4666-b2fd-90e479428791
Authorization: Bearer {token}
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "operations": [
    {
      "op": "replace",
      "path": "urn:ietf:params:scim:schemas:core:2.0:User:name",
      "value": {
        "familyName": "Jane",
        "givenName": "Doe"
      }
    }
  ]
}

Respuesta (204 Sin contenido):

La respuesta se ajusta a la especificación SCIM.

Ejemplo 3: Actualización del atributo complejo multivalor

Solicitud:

PATCH https://graph.microsoft.com/rp/scim/users/ec3f07a3-2aa4-4666-b2fd-90e479428791
Authorization: Bearer {token}
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "operations": [
    {
      "op": "replace",
      "path": "urn:ietf:params:scim:schemas:core:2.0:User:addresses",
      "value": [
        {
          "type": "work",
          "streetAddress": "4567 Main Street",
          "locality": "Buffalo",
          "region": "NY",
          "postalCode": "98052",
          "country/region": "United States"
        }
      ]
    }
  ]
}

Respuesta (204 Sin contenido):

La respuesta se ajusta a la especificación SCIM.

Ejemplo 4: actualización de un atributo complejo multivalor con filtro

Solicitud:

PATCH https://graph.microsoft.com/rp/scim/users/ec3f07a3-2aa4-4666-b2fd-90e479428791
Authorization: Bearer {token}
Content-Type: application/scim+json

{
  "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
  "operations": [
    {
      "op": "replace",
      "path": "emails[type eq \"work\" and primary eq true].value",         
      "value": "{edited_username}@{{tenant_domain}}"      
    }
  ]
}

Respuesta (204 Sin contenido):

La respuesta se ajusta a la especificación SCIM.

Ejemplo 5: actualización del administrador de usuarios

Solicitud:

PATCH https://graph.microsoft.com/rp/scim/users/ec3f07a3-2aa4-4666-b2fd-90e479428791
Authorization: Bearer {token}
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "operations": [
    {
      "op": "replace",
      "path": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager",
      "value": {
        "value": "915f96af-ea85-4687-b972-b26f69d719f9"
      }
    }
  ]
}

Respuesta (204 Sin contenido):

La respuesta se ajusta a la especificación SCIM.

Ejemplo 6: Actualización de atributos de seguridad personalizados

Solicitud:

PATCH https://graph.microsoft.com/rp/scim/users/ec3f07a3-2aa4-4666-b2fd-90e479428791
Authorization: Bearer {token}
Content-Type: application/scim+json

{
  "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
  "operations": [
    {
      "op": "add",
      "path": "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:CustomSecurityAttributes:Project.ProjectName",
      "value": "IdentityHubV2"
    }
  ]
}

Respuesta (204 Sin contenido): La respuesta se ajusta a la especificación SCIM.

Eliminar un usuario

Para eliminar a un usuario, se puede realizar una solicitud de tipo DELETE al endpoint /users con un ID de usuario existente.

Puntos de conexión de API:

ELIMINAR https://graph.microsoft.com/rp/scim/users/{id}

Tras la operación correcta, la API devuelve el estado HTTP 204.

Permisos

Ejemplo 1: Eliminación de un usuario

Solicitud:

DELETE https://graph.microsoft.com/rp/scim/users/ec3f07a3-2aa4-4666-b2fd-90e479428791
Authorization: Bearer {token}

Respuesta (204 Sin contenido):

La respuesta se ajusta a la especificación SCIM.

Enumerar grupos

Utiliza el extremo /groups para realizar las siguientes operaciones:

• Obtener todos los grupos del inquilino (con paginación).

• Obtiene grupos que coinciden con criterios de filtro específicos.

Puntos de conexión de API:

https://graph.microsoft.com/rp/scim/groups

Tras la operación correcta, la API devuelve el estado HTTP 200.

Si la respuesta contiene varias páginas, use la paginación basada en cursores para recuperar todas las páginas del resultado.

Permisos

Parámetros de consulta para grupos de lista

Los siguientes parámetros de consulta SCIM se pueden usar con este punto de conexión de API:

• filter : para especificar criterios de filtro que se van a aplicar

• attributes : para especificar qué atributos de grupo deben devolver el servidor.

• excludedAttributes : para especificar qué atributos de grupo deben excluir el servidor.

• count : para especificar el número de resultados que se van a recuperar (default=100)

• cursor : para avanzar a la siguiente página de resultados

Restricciones para grupos de lista

La implementación de SCIM de Microsoft Entra ID tiene las siguientes restricciones:

• Cuando hay varias páginas implicadas en el resultado:

  • Tamaño de página predeterminado de 100 entradas por página.

  • El tamaño máximo de página es de 1000 entradas por página.

• En el filter parámetro de consulta, solo se admite el and operador lógico para combinar filtros. Se permiten los siguientes atributos de grupo para el operador de eq comparación:

  • displayName: Establece este atributo en un nombre para mostrar válido de un grupo de Microsoft Entra.
  • id: Establezca este atributo en un ID de objeto de grupo (GUID) válido de Microsoft Entra en su inquilino.
  • members.value: Establezca este atributo en un ID de objeto de usuario (GUID) válido de Microsoft Entra en su inquilino.
  • urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group:securityEnabled: establezca este atributo en un valor booleano que no distingue mayúsculas de minúsculas, incluidos true, false, TRUEo FALSE.
  • urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group:mailEnabled: establezca este atributo en un valor booleano que no distingue mayúsculas de minúsculas, incluidos true, false, TRUEo FALSE.
  • urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group:owners.value: Establezca este atributo en un ID de objeto de usuario (GUID) válido de Microsoft Entra en su inquilino.

• Se permiten los siguientes atributos de grupo para el operador de comparación "ew" (endsWith)

  • displayName

• La pertenencia a grupos anidados no se evalúa al usar el member.value filtro. Solo se evalúan las pertenencias directas.

Ejemplos

Los ejemplos siguientes solo incluyen los detalles de la solicitud. La respuesta no se incluye por brevedad. Se ajusta a la carga de respuesta SCIM estándar.

Ejemplo 1: Obtener todos los grupos

Solicitud:

GET https://graph.microsoft.com/rp/scim/groups
Authorization: Bearer {token}

Respuesta (200 OK):

Si el número de grupos es superior a 100, la respuesta incluirá la itemsPerPage propiedad y nextCursor . Use el nextCursor valor para recuperar la página siguiente del resultado.

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "itemsPerPage": 100,
  "nextCursor": "RFNwdAIAAQAAACpHcm91cF8zMDhiMzNkOC0wNjkxLTQzZTktOTA4Mi1kNG...",
  "resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group",
        "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group"
      ],
      "id": "c2c2c2c2-dddd-eeee-ffff-a3a3a3a3a3a3",
      "displayName": "Sales and Marketing",
      "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group": {
        "description": "Description of Sales and Marketing",
        "groupTypes": [
          "Unified"
        ],
        "mailEnabled": true,
        "mailNickname": "SalesandMarketing",
        "securityEnabled": false,
        "securityIdentifier": "ffffffff-5a5a-6b6b-7c7c-888888888888"
      },
      "meta": {
        "created": "2022-01-11T01:23:26+00:00",
        "location": "/groups/c2c2c2c2-dddd-eeee-ffff-a3a3a3a3a3a3",
        "resourceType": "group"
      }
    },    
    { ... }
  ]
}

Ejemplo 1B: recuperación de la página siguiente para obtener todos los grupos

La consulta anterior devuelve de forma predeterminada 100 grupos por página. Si tiene más de 100 grupos en su inquilino, utilice la paginación para recuperar el siguiente conjunto de grupos estableciendo el parámetro de consulta cursor en el valor nextCursor recibido en la respuesta.

GET https://graph.microsoft.com/rp/scim/groups?cursor=RFNwdAIAAQAAACpHcm91cF8zMDhiMzNkOC0wNjkxLTQzZTktOTA4Mi1kNG...
Authorization: Bearer {token}
Accept: application/json

Ejemplo 1C: Uso del parámetro count para controlar grupos devueltos

Puede usar el count parámetro para recuperar un número determinado de grupos.

GET https://graph.microsoft.com/rp/scim/groups?count=1000
Authorization: Bearer {token}
Accept: application/json

GET https://graph.microsoft.com/rp/scim/groups?count=1000&cursor=RFNwdAIAAQAAACpHcm91cF8zMDhiMzNkOC0wNjkxLTQzZTktOTA4Mi1kNG...
Authorization: Bearer {token}
Accept: application/json

Ejemplo 2: Obtención del grupo por ID con atributos específicos

Solicitud:

GET https://graph.microsoft.com/rp/scim/groups?filter=id eq "dddddddd-3333-4444-5555-eeeeeeeeeeee"&attributes=displayName
Authorization: Bearer {token}

Ejemplo 3: Obtener grupo por ID con atributos excluidos

Solicitud:

GET https://graph.microsoft.com/rp/scim/groups?filter=id eq "dddddddd-3333-4444-5555-eeeeeeeeeeee"&excludedAttributes=displayName
Authorization: Bearer {token}

Ejemplo 4: Obtener grupo por displayName

Solicitud:

GET https://graph.microsoft.com/rp/scim/groups?filter=displayName eq "GroupA"
Authorization: Bearer {token}

Respuesta (200 OK):

La respuesta se trunca para mejorar la legibilidad.

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
      ],
      "id": "a6a6a6a6-bbbb-cccc-dddd-e7e7e7e7e7e7",
      "displayName": "GroupA",
      "meta": {
        "location": "/groups/a6a6a6a6-bbbb-cccc-dddd-e7e7e7e7e7e7",
        "resourceType": "group"
      }
    }
  ]
}

Ejemplo 5: Obtener grupo por miembro

Solicitud:

GET https://graph.microsoft.com/rp/scim/groups?filter=members.value eq "d4b34e9e-0ad7-42df-b1f6-401b41fe1bee"
Authorization: Bearer {token}

Respuesta (200 OK):

La respuesta incluye grupos asignados y dinámicos donde el usuario es miembro.

Ejemplo 6: Obtención de grupos habilitados para seguridad

Solicitud:

GET https://graph.microsoft.com/rp/scim/groups?filter=urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group:securityEnabled eq true
Authorization: Bearer {token}

Ejemplo 7 – Obtener grupos habilitados para correo

Solicitud:

GET https://graph.microsoft.com/rp/scim/groups?filter=urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group:mailEnabled eq true
Authorization: Bearer {token}

Ejemplo 8: Obtener grupos propiedad de un usuario

Aunque owners no se devuelve en los cuerpos de respuesta del grupo, puede usar su subatributo value como destino de filtro. Especifique el espacio de nombres completo de la extensión de grupo de Microsoft Entra.

Solicitud:

GET https://graph.microsoft.com/rp/scim/groups?filter=urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group:owners.value eq "d3d3d3d3-eeee-ffff-aaaa-b4b4b4b4b4b4"
Authorization: Bearer {token}

Obtener grupo por identificador

Los grupos existentes se recuperan mediante la realización de una solicitud GET al punto de conexión /groups con un identificador de grupo.

Puntos de conexión de API:

https://graph.microsoft.com/rp/scim/groups/{id}

Tras la operación correcta, la API devuelve el estado HTTP 200.

Permisos

Restricciones para Obtener grupo por identificador

• Esta llamada a la API no devuelve los miembros del grupo. La especificación de paginación basada en cursor no admite la paginación de nivel de atributo, por lo que la API no puede usarla para devolver colecciones de miembros grandes. Para recuperar los miembros directos de un grupo, use GET /users?filter=groups.value eq "{groupId}".

Parámetros de consulta para Obtener grupo por identificador

Los siguientes parámetros de consulta SCIM se pueden usar con este punto de conexión de API:

• attributes : para especificar qué atributos de grupo debe devolver el servidor.

• excludedAttributes : para especificar qué atributos de grupo deben excluir el servidor.

Ejemplo 1: Obtener grupo por identificador

Solicitud:

GET https://graph.microsoft.com/rp/scim/groups/dddddddd-3333-4444-5555-eeeeeeeeeeee
Authorization: Bearer {token}

Respuesta (200 OK):

La respuesta se trunca para mejorar la legibilidad.

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group",
    "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group"
  ],
  "id": "dddddddd-3333-4444-5555-eeeeeeeeeeee",
  "displayName": "GroupA",
  "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group": {
    "description": "Group for All Employees - Baseline access",
    "mailEnabled": false,
    "mailNickname": "3c998a58-6",
    "securityEnabled": true,
    "securityIdentifier": "ffffffff-5a5a-6b6b-7c7c-888888888888"
  },
  "meta": {
    "created": "2024-05-23T17:21:41+00:00",
    "location": "/groups/dddddddd-3333-4444-5555-eeeeeeeeeeee",
    "resourceType": "group"
  }
}

Creación de un grupo

Puede crear un nuevo grupo en Microsoft Entra ID enviando una solicitud POST al punto de conexión /groups.

Puntos de conexión de API:

PUBLICAR https://graph.microsoft.com/rp/scim/groups

Tras la operación correcta, la API devuelve el estado HTTP 201.

Permisos

Atributos necesarios para crear un grupo

Los atributos siguientes son necesarios para la creación correcta de grupos:

• displayName

Ejemplo 1: Crear un nuevo grupo

Solicitud:

POST https://graph.microsoft.com/rp/scim/groups
Authorization: Bearer {token}
Content-Type: application/scim+json

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group",
    "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group"
  ],
  "displayName": "Test SCIM Group",
  "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group": { 
    "mailEnabled": false, 
    "mailNickname": "test-scim-group", 
    "securityEnabled": true 
  }
}

Respuesta (201 creada):

Devuelve la representación SCIM del grupo creado.

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group",
    "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group"
  ],
  "id": "66aa66aa-bb77-cc88-dd99-00ee00ee00ee",
  "displayName": "Test SCIM Group",
  "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group": {
    "mailEnabled": false,
    "mailNickname": "test-scim-group",
    "securityEnabled": true,
    "securityIdentifier": "ffffffff-5a5a-6b6b-7c7c-888888888888"
  },
  "meta": {
    "created": "2026-03-30T16:28:37+00:00",
    "location": "/groups/66aa66aa-bb77-cc88-dd99-00ee00ee00ee",
    "resourceType": "group"
  }
}

Actualizar un grupo

El /groups punto de conexión permite realizar una solicitud PATCH para actualizar un grupo existente.

Puntos de conexión de API:

PATCH https://graph.microsoft.com/rp/scim/groups/{id}

Tras la operación correcta, la API devuelve el estado HTTP 204.

Permisos

Restricciones para actualizar un grupo

• La adición de miembros a grupos debe realizarse en un único objeto PATCH Operation .  

• Al usar la API para agregar varios miembros en una solicitud, solo puede agregar hasta 20 miembros. 

• Solo puede eliminarse un miembro de un grupo por llamada PATCH.  

• La eliminación de miembros del grupo debe realizarse sin ningún otro cambio de atributo incluido en la misma llamada PATCH (incluida la adición de miembros).  

• La adición de miembros a grupos debe realizarse sin ningún otro cambio de atributo (incluida la eliminación de miembros).  

• La acción de agregar miembros al grupo se considera una operación idempotente. Si un miembro específico ya está presente en el grupo, no se devuelve ningún error y la operación se realiza correctamente siempre que todos los memberIds del grupo apunten a objetos de usuario válidos.

• Si un memberId pasado en la operación de adición o eliminación de pertenencia a grupos no es válido, se produce un error en toda la operación con el mensaje “Resource '00000000-0000-0000-0000-000000000000' de error o uno de sus objetos de propiedad de referencia consultados no están presentes".

Ejemplo 1: actualizar el nombre para mostrar del grupo

Solicitud:

PATCH https://graph.microsoft.com/rp/scim/groups/66aa66aa-bb77-cc88-dd99-00ee00ee00ee
Authorization: Bearer {token}
Content-Type: application/scim+json

{
  "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
  "operations": [
    {
      "op": "replace",
      "path": "displayName",
      "value": "SCIM Testing Group Edited"
    }
  ]
}

Respuesta (204 Sin contenido):

La respuesta se ajusta a la especificación SCIM.

Ejemplo 2: Actualización de la descripción del grupo

Solicitud:

PATCH https://graph.microsoft.com/rp/scim/groups/66aa66aa-bb77-cc88-dd99-00ee00ee00ee
Authorization: Bearer {token}
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "operations": [
    {
      "op": "replace",
      "path": "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group:description",
      "value": "Finance group"
    }
  ]
}

Respuesta (204 Sin contenido):

La respuesta se ajusta a la especificación SCIM.

Ejemplo 3: Agregar miembros del grupo

Solicitud:

PATCH https://graph.microsoft.com/rp/scim/groups/66aa66aa-bb77-cc88-dd99-00ee00ee00ee
Authorization: Bearer {token}
Content-Type: application/scim+json

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "add",
      "path": "members",
      "value": [
        {
          "value": "756b18d2-023a-4fa8-845e-9ac8b524100f"
        },
        {
          "value": "0e4c70dd-c015-48db-bb5a-6264d215ca8e"
        }
      ]
    }
  ]
}

Respuesta (204 Sin contenido):

La respuesta se ajusta a la especificación SCIM.

Ejemplo 4: Quitar miembros del grupo

Solicitud:

PATCH https://graph.microsoft.com/rp/scim/groups/66aa66aa-bb77-cc88-dd99-00ee00ee00ee
Authorization: Bearer {token}
Content-Type: application/scim+json

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "remove",
      "path": "members[value eq \"aaaaaaaa-6666-7777-8888-bbbbbbbbbbbb\"]"
    }
  ]
}

Respuesta (204 Sin contenido):

La respuesta se ajusta a la especificación SCIM.

Eliminar un grupo

Se puede eliminar un grupo realizando una solicitud DELETE al punto de conexión /groups con un ID de grupo existente.

Puntos de conexión de API:

ELIMINAR https://graph.microsoft.com/rp/scim/groups/{id}

Tras la operación correcta, la API devuelve el estado HTTP 204.

Permisos

Ejemplo 1: Eliminación de un grupo

Solicitud:

DELETE https://graph.microsoft.com/rp/scim/groups/66aa66aa-bb77-cc88-dd99-00ee00ee00ee
Authorization: Bearer {token}

Respuesta (204 Sin contenido):

La respuesta se ajusta a la especificación SCIM.

Contenido relacionado

• Enable la API de aprovisionamiento de SCIM en Microsoft Entra ID
• compatibilidad con SCIM en Microsoft Entra ID
• Solucionar problemas de errores de la API SCIM de Microsoft Entra ID