Tutorial: Desarrollo y planeación del aprovisionamiento de un punto de conexión de SCIMTutorial: Develop and plan provisioning for a SCIM endpoint

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 Azure AD (AAD).As an application developer, you can use the System for Cross-Domain Identity Management (SCIM) user management API to enable automatic provisioning of users and groups between your application and Azure AD (AAD). En este artículo se describe cómo crear un punto de conexión de SCIM e integrarlo con el servicio de aprovisionamiento de AAD.This article describes how to build a SCIM endpoint and integrate with the AAD provisioning service. La especificación SCIM proporciona un esquema de usuario común para el aprovisionamiento.The SCIM specification provides a common user schema for provisioning. Cuando se usa junto 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.When used in conjunction with federation standards like SAML or OpenID Connect, SCIM gives administrators an end-to-end, standards-based solution for access management.

Aprovisionamiento desde Azure AD a una aplicación con SCIM

SCIM es una definición estándar de dos puntos de conexión: /Users y /Groups.SCIM is a standardized definition of two endpoints: a /Users endpoint and a /Groups endpoint. Utiliza verbos de REST comunes para crear, actualizar y eliminar objetos, y un esquema predefinido para atributos comunes como el nombre de grupo, nombre de usuario, nombre, apellidos y correo electrónico.It uses common REST verbs to create, update, and delete objects, and a pre-defined schema for common attributes like group name, username, first name, last name and email. 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.Apps that offer a SCIM 2.0 REST API can reduce or eliminate the pain of working with a proprietary user management API. 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.For example, any compliant SCIM client knows how to make an HTTP POST of a JSON object to the /Users endpoint to create a new user entry. 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.Instead of needing a slightly different API for the same basic actions, apps that conform to the SCIM standard can instantly take advantage of pre-existing clients, tools, and code.

El esquema de objetos de usuario estándar y las API REST para administración definidas en SCIM 2.0 (RFC 7642, 7643, 7644) permiten que los proveedores de identidades y las aplicaciones se integren más fácilmente entre sí.The standard user object schema and rest APIs for management defined in SCIM 2.0 (RFC 7642, 7643, 7644) allow identity providers and apps to more easily integrate with each other. 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.Application developers that build a SCIM endpoint can integrate with any SCIM-compliant client without having to do custom work.

Para automatizar el aprovisionamiento de una aplicación, es necesario crear e integrar un punto de conexión de SCIM con el cliente de SCIM de Azure AD.To automate provisioning to an application will require building and integrating a SCIM endpoint with the Azure AD SCIM client. Para iniciar el aprovisionamiento de usuarios y grupos en la aplicación, realice los pasos siguientes.Use the following steps to start provisioning users and groups into your application.

  1. Diseñe el esquema de grupos y usuariosDesign your user and group schema

    Identifique los objetos y atributos de la aplicación para determinar cómo se asignan al esquema de usuarios y grupos que se admite con la implementación de SCIM de AAD.Identify the application's objects and attributes to determine how they map to the user and group schema supported by the AAD SCIM implementation.

  2. Implementación de SCIM de AADUnderstand the AAD SCIM implementation

    Averigüe cómo se implementa el cliente de SCIM de AAD para modelar las respuestas y el control de solicitudes del protocolo SCIM.Understand how the AAD SCIM client is implemented to model your SCIM protocol request handling and responses.

  3. Cree un punto de conexión SCIMBuild a SCIM endpoint

    Un punto de conexión debe ser compatible con SCIM 2.0 para integrarse con el servicio de aprovisionamiento de AAD.An endpoint must be SCIM 2.0-compatible to integrate with the AAD provisioning service. 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.As an option, use Microsoft Common Language Infrastructure (CLI) libraries and code samples to build your endpoint. Estos ejemplos sirven solo como referencia y prueba y no se recomienda usarlos como dependencias en la aplicación de producción.These samples are for reference and testing only; we recommend against using them as dependencies in your production app.

  4. Integración del punto de conexión de SCIM con el cliente de SCIM de AADIntegrate your SCIM endpoint with the AAD SCIM client

    Si su organización usa una aplicación de terceros para implementar un perfil de SCIM 2.0 que se admita en AAD, puede automatizar rápidamente el aprovisionamiento y el desaprovisionamiento de usuarios y grupos.If your organization uses a third-party application to implement a profile of SCIM 2.0 that AAD supports, you can quickly automate both provisioning and deprovisioning of users and groups.

  5. Publicación de la aplicación en la galería de aplicaciones de AADPublish your application to the AAD application gallery

    Facilite a los clientes la detección de la aplicación y la configuración del aprovisionamiento.Make it easy for customers to discover your application and easily configure provisioning.

Pasos para la integración de un punto de conexión SCIM con Azure AD

Diseñe el esquema de grupos y usuariosDesign your user and group schema

Cada aplicación requiere atributos diferentes para crear un usuario o un grupo.Each application requires different attributes to create a user or group. Para iniciar la integración, identifique los objetos (usuarios, grupos) y atributos (nombre, administrador, puesto, etc.) necesarios que requiera la aplicación.Start your integration by identifying the required objects (users, groups) and attributes (name, manager, job title, etc.) that your application needs.

El estándar SCIM define un esquema para administrar usuarios y grupos.The SCIM standard defines a schema for managing users and groups.

En el esquema de usuario principal solo hacen falta tres atributos (todos los demás son opcionales):The core user schema only requires three attributes (all other attributes are optional):

  • id, identificador definido por el proveedor de servicios.id, service provider defined identifier
  • userName, un identificador único para el usuario (normalmente se asigna al nombre principal de usuario de Azure AD)userName, a unique identifier for the user (generally maps to the Azure AD user principal name)
  • meta, metadatos de solo lectura mantenidos por el proveedor de servicios.meta, read-only metadata maintained by the service provider

Además del esquema de usuario principal, el estándar SCIM define una extensión de usuario empresarial y un modelo para extender el esquema de usuario de modo que satisfaga las necesidades de su aplicación.In addition to the core user schema, the SCIM standard defines an enterprise user extension with a model for extending the user schema to meet your application’s needs.

Si, por ejemplo, la aplicación necesita el correo electrónico y el administrador de un usuario, use el esquema principal para recopilar el correo electrónico del usuario y el esquema de usuario empresarial para recopilar el administrador del usuario.For example, if your application requires both a user's email and user’s manager, use the core schema to collect the user’s email and the enterprise user schema to collect the user’s manager.

Para diseñar el esquema, siga estos pasos:To design your schema, follow these steps:

  1. Enumere los atributos que requiere la aplicación y, luego, clasifíquelos como atributos necesarios para la autenticación (por ejemplo, loginName y email), atributos necesarios para administrar el ciclo de vida de los usuarios (por ejemplo, status/active) y todos los demás atributos necesarios para que funcione la aplicación (por ejemplo, manager, tag).List the attributes your application requires, then categorize as attributes needed for authentication (e.g. loginName and email), attributes needed to manage the user lifecycle (e.g. status / active), and all other attributes needed for the application to work (e.g. manager, tag).

  2. Compruebe si esos atributos ya están definidos en el esquema de usuario principal o en el esquema de usuario empresarial.Check if the attributes are already defined in the core user schema or enterprise user schema. Si no es así, debe definir una extensión para el esquema de usuario que abarque los atributos que faltan.If not, you must define an extension to the user schema that covers the missing attributes. Consulte el ejemplo siguiente para ver una extensión al usuario para permitir el aprovisionamiento del atributo tag de un usuario.See example below for an extension to the user to allow provisioning a user tag.

  3. Asigne los atributos de SCIM a los atributos de usuario de Azure AD.Map SCIM attributes to the user attributes in Azure AD. 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 Azure AD, guíe al administrador de inquilinos para que extienda su esquema o use un atributo de extensión, como se muestra a continuación para la propiedad tags.If one of the attributes you have defined in your SCIM endpoint does not have a clear counterpart on the Azure AD user schema, guide the tenant administrator to extend their schema or use an extension attribute as shown below for the tags property.

Atributo de aplicación necesarioRequired app attribute Atributo de SCIM asignadoMapped SCIM attribute Atributo de Azure AD asignadoMapped Azure AD attribute
loginNameloginName userNameuserName userPrincipalNameuserPrincipalName
firstNamefirstName name.givenNamename.givenName givenNamegivenName
lastNamelastName name.familyNamename.familyName surNamesurName
workMailworkMail emails[type eq "work"].valueemails[type eq “work”].value CorreoMail
managermanager managermanager managermanager
etiquetatag urn:ietf:params:scim:schemas:extension:2.0:CustomExtension:tagurn:ietf:params:scim:schemas:extension:2.0:CustomExtension:tag extensionAttribute1extensionAttribute1
statusstatus activeactive isSoftDeleted (valor calculado no almacenado en el usuario)isSoftDeleted (computed value not stored on user)

Ejemplo de lista de atributos necesariosExample list of required attributes

{
     "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:CustomAttribute:User": {
     "tag": "701984",
   },
   "meta": {
     "resourceType": "User",
     "created": "2010-01-23T04:56:22Z",
     "lastModified": "2011-05-13T04:42:34Z",
     "version": "W\/\"3694e05e9dff591\"",
     "location":
 "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646"
   }
}   

Esquema de ejemplo definido por una carga JSONExample schema defined by a JSON payload

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.In addition to the attributes required for the application, the JSON representation also includes the required id, externalId, and meta attributes.

Esta representación ayuda a clasificarlos entre /User y /Group para asignar los atributos de usuario predeterminados de Azure AD al RFC de SCIM. Consulte Asignación de atributos personalizados entre Azure AD y el punto de conexión de SCIM.It helps to categorize between /User and /Group to map any default user attributes in Azure AD to the SCIM RFC, see how customize attributes are mapped between Azure AD and your SCIM endpoint.

Usuario de Azure Active DirectoryAzure Active Directory user "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User""urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
IsSoftDeletedIsSoftDeleted activeactive
departmentdepartment urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:departmenturn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department
DisplayNamedisplayName DisplayNamedisplayName
employeeIdemployeeId urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumberurn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber
Facsimile-TelephoneNumberFacsimile-TelephoneNumber phoneNumbers[type eq "fax"].valuephoneNumbers[type eq "fax"].value
givenNamegivenName name.givenNamename.givenName
jobTitlejobTitle titletitle
mailmail emails[type eq "work"].valueemails[type eq "work"].value
mailNicknamemailNickname externalIdexternalId
managermanager urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:managerurn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager
mobilemobile phoneNumbers[type eq "mobile"].valuephoneNumbers[type eq "mobile"].value
postalCodepostalCode addresses[type eq "work"].postalCodeaddresses[type eq "work"].postalCode
proxy-Addressesproxy-Addresses emails[type eq "other"].Valueemails[type eq "other"].Value
physical-Delivery-OfficeNamephysical-Delivery-OfficeName addresses[type eq "other"].Formattedaddresses[type eq "other"].Formatted
streetAddressstreetAddress addresses[type eq "work"].streetAddressaddresses[type eq "work"].streetAddress
surnamesurname name.familyNamename.familyName
telephone-Numbertelephone-Number phoneNumbers[type eq "work"].valuephoneNumbers[type eq "work"].value
user-PrincipalNameuser-PrincipalName userNameuserName

Ejemplo de lista de atributos de usuario y grupoExample list of user and group attributes

Grupo de Azure Active DirectoryAzure Active Directory group urn:ietf:params:scim:schemas:core:2.0:Groupurn:ietf:params:scim:schemas:core:2.0:Group
DisplayNamedisplayName DisplayNamedisplayName
mailmail emails[type eq "work"].valueemails[type eq "work"].value
mailNicknamemailNickname DisplayNamedisplayName
membersmembers membersmembers
objectIdobjectId externalIdexternalId
proxyAddressesproxyAddresses emails[type eq "other"].Valueemails[type eq "other"].Value

Ejemplo de lista de atributos de grupoExample list of group attributes

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 Azure AD se asignan a menudo a las propiedades del protocolo SCIM.You are not required to support both users and groups, or all the attributes shown here, it's only a reference on how attributes in Azure AD are often mapped to properties in the SCIM protocol.

Hay varios puntos de conexión definidos en el RFC de SCIM.There are several endpoints defined in the SCIM RFC. Puede empezar con el punto de conexión /User y, luego, expandirlo desde allí.You can start with the /User endpoint and then expand from there.

Punto de conexiónEndpoint DescripciónDescription
/User/User Realiza operaciones CRUD en un objeto de usuario.Perform CRUD operations on a user object.
/Group/Group Realiza operaciones CRUD en un objeto de grupo.Perform CRUD operations on a group object.
/Schemas/Schemas El conjunto de atributos que admite cada cliente y proveedor de servicios puede variar.The set of attributes supported by each client and service provider can vary. Un proveedor de servicios puede incluir name, title y emails, mientras que otro usa name, title y phoneNumbers.One service provider might include name, title, and emails, while another service provider uses name, title, and phoneNumbers. El punto de conexión de esquemas permite la detección de los atributos admitidos.The schemas endpoint allows for discovery of the attributes supported.
/Bulk/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).Bulk operations allow you to perform operations on a large collection of resource objects in a single operation (e.g. update memberships for a large group).
/ServiceProviderConfig/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.Provides details about the features of the SCIM standard that are supported, for example the resources that are supported and the authentication method.
/ResourceTypes/ResourceTypes Especifica los metadatos de cada recurso.Specifies metadata about each resource.

Lista de ejemplo de puntos de conexiónExample list of endpoints

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 the /Schemas endpoint to support custom attributes or if your schema changes frequently as it enables a client to retrieve the most up-to-date schema automatically. Use el punto de conexión /Bulk para admitir grupos.Use the /Bulk endpoint to support groups.

Implementación de SCIM de AADUnderstand the AAD SCIM implementation

Para admitir una API de administración de usuarios de SCIM 2.0, en esta sección se describe cómo se implementa el cliente de SCIM de AAD y se muestra cómo modelar las respuestas y el control de solicitudes del protocolo SCIM.To support a SCIM 2.0 user management API, this section describes how the AAD SCIM client is implemented and shows how to model your SCIM protocol request handling and responses.

Importante

El comportamiento de la implementación de SCIM de Azure AD se actualizó por última vez el 18 de diciembre de 2018.The behavior of the Azure AD SCIM implementation was last updated on December 18, 2018. Para obtener información sobre los cambios que se han producido, consulte SCIM 2.0 protocol compliance of the Azure AD User Provisioning service (Cumplimiento del protocolo SCIM 2.0 del servicio de aprovisionamiento de usuarios de Azure AD).For information on what changed, see SCIM 2.0 protocol compliance of the Azure AD User Provisioning service.

Dentro de la especificación del protocolo SCIM 2.0, la aplicación debe cumplir estos requisitos:Within the SCIM 2.0 protocol specification, your application must support these requirements:

RequisitoRequirement Notas de referencia (protocolo SCIM)Reference notes (SCIM protocol)
Crear usuarios y, opcionalmente, también gruposCreate users, and optionally also groups sección 3.3section 3.3
Modificar usuarios o grupos con solicitudes PATCHModify users or groups with PATCH requests sección 3.5.2.section 3.5.2. La admisión garantiza que los grupos y usuarios se aprovisionan de forma eficaz.Supporting ensures that groups and users are provisioned in a performant manner.
Recuperar un recurso conocido para un usuario o un grupo creados anteriormenteRetrieve a known resource for a user or group created earlier sección 3.4.1section 3.4.1
Consultar usuarios o gruposQuery users or groups sección 3.4.2.section 3.4.2. De forma predeterminada, los usuarios se recuperan por sus id y se consultan por sus username y externalId, y los grupos por su displayName.By default, users are retrieved by their id and queried by their username and externalId, and groups are queried by displayName.
Consultar usuario por identificador y por administradorQuery user by ID and by manager sección 3.4.2section 3.4.2
Consultar grupos por identificador y por miembroQuery groups by ID and by member sección 3.4.2section 3.4.2
El filtro excludedAttributes=members al consultar el recurso de grupoThe filter excludedAttributes=members when querying the group resource sección 3.4.2.5section 3.4.2.5
Aceptar un token de portador único para la autenticación y autorización de AAD en la aplicaciónAccept a single bearer token for authentication and authorization of AAD to your application.
Eliminación temporal de un usuario active=false y restauración del usuario active=trueSoft-deleting a user active=false and restoring the user active=true El objeto de usuario se debe devolver en una solicitud tanto si el usuario está activo como si no.The user object should be returned in a request whether or not the user is active. La única vez que no se debe devolver el usuario es cuando se elimina de forma permanente de la aplicación.The only time the user should not be returned is when it is hard deleted from the application.
Compatibilidad con el punto de conexión /SchemasSupport the /Schemas endpoint sección 7 El punto de conexión de detección de esquemas se usa para detectar atributos adicionales.section 7 The schema discovery endpoint will be used to discover additional attributes.

Al implementar un punto de conexión de SCIM para garantizar la compatibilidad con AAD, siga estas directrices generales:Use the general guidelines when implementing a SCIM endpoint to ensure compatibility with AAD:

  • id es una propiedad obligatoria para todos los recursos.id is a required property for all resources. Todas las respuestas que devuelve un recurso deben asegurarse de que cada recurso tiene esta propiedad, excepto ListResponse con cero miembros.Every response that returns a resource should ensure each resource has this property, except for ListResponse with zero members.
  • La respuesta a una solicitud de consulta o filtrado siempre debe ser una ListResponse.Response to a query/filter request should always be a ListResponse.
  • Los grupos son opcionales, pero solo se admiten si la implementación de SCIM admite solicitudes PATCH.Groups are optional, but only supported if the SCIM implementation supports PATCH requests.
  • No es necesario incluir el recurso completo en la respuesta PATCH.It isn't necessary to include the entire resource in the PATCH response.
  • Microsoft AAD solo usa los siguientes operadores: eq, andMicrosoft AAD only uses the following operators: eq, and
  • No exija una coincidencia entre mayúsculas y minúsculas en los elementos estructurales de SCIM, en particular en los valores de operación PATCH op, como se define en la sección 3.5.2.Don't require a case-sensitive match on structural elements in SCIM, in particular PATCH op operation values, as defined in section 3.5.2. AAD emite los valores de op como Agregar, Reemplazar y Quitar.AAD emits the values of op as Add, Replace, and Remove.
  • Microsoft AAD 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.Microsoft AAD makes requests to fetch a random user and group to ensure that the endpoint and the credentials are valid. También las realiza como parte del flujo de Probar conexión de Azure Portal.It's also done as a part of the Test Connection flow in the Azure portal.
  • El atributo en el que se pueden consultar los recursos debe establecerse como un atributo coincidente en la aplicación en Azure Portal. Consulte Personalización de las asignaciones de atributos de aprovisionamiento de usuarios.The attribute that the resources can be queried on should be set as a matching attribute on the application in the Azure portal, see Customizing User Provisioning Attribute Mappings.
  • No se admite el atributo de derechos.The entitlements attribute is not supported.
  • Compatibilidad con HTTPS en el punto de conexión de SCIM.Support HTTPS on your SCIM endpoint.
  • Detección de esquemasSchema discovery
    • La detección de esquemas no se admite actualmente en la aplicación personalizada, pero se usa en determinadas aplicaciones de la galería.Schema discovery is not currently supported on the custom application, but it is being used on certain gallery applications. En el futuro, la detección de esquemas se usará como método principal para agregar atributos adicionales a un conector.Going forward, schema discovery will be used as the primary method to add additional attributes to a connector.
    • Si un valor no está presente, no envíe valores NULL.If a value is not present, do not send null values.
    • Los valores de propiedad deben tener mayúsculas y minúsculas (por ejemplo, readWrite).Property values should be camel cased (e.g. readWrite).
    • Debe devolver una respuesta de lista.Must return a list response.

Aprovisionamiento y desaprovisionamiento de usuariosUser provisioning and deprovisioning

En la siguiente ilustración se muestran los mensajes que AAD envía a un servicio SCIM para administrar el ciclo de vida de un usuario en su almacén de identidades de la aplicación.The following illustration shows the messages that AAD sends to a SCIM service to manage the lifecycle of a user in your application's identity store.

Muestra la secuencia de aprovisionamiento y desaprovisionamiento de usuariosShows the user provisioning and deprovisioning sequence
Secuencia de aprovisionamiento y desaprovisionamiento de usuariosUser provisioning and deprovisioning sequence

Aprovisionamiento y desaprovisionamiento de gruposGroup provisioning and deprovisioning

El aprovisionamiento y desaprovisionamiento de grupos son opcionales.Group provisioning and deprovisioning are optional. Cuando están implementados y habilitados, en la siguiente ilustración se muestran los mensajes que envía AAD a un servicio SCIM para administrar el ciclo de vida de un grupo en el almacén de identidades de la aplicación.When implemented and enabled, the following illustration shows the messages that AAD sends to a SCIM service to manage the lifecycle of a group in your application's identity store. Esos mensajes se diferencian de los mensajes sobre los usuarios de dos maneras:Those messages differ from the messages about users in two ways:

  • Las solicitudes para recuperar grupos especifican que el atributo members se excluya de cualquier recurso proporcionado en respuesta a la solicitud.Requests to retrieve groups specify that the members attribute is to be excluded from any resource provided in response to the request.
  • Las solicitudes para determinar si un atributo de referencia tiene un valor determinado son solicitudes sobre el atributo members.Requests to determine whether a reference attribute has a certain value are requests about the members attribute.

Muestra la secuencia de aprovisionamiento y desaprovisionamiento de gruposShows the group provisioning and deprovisioning sequence
Secuencia de aprovisionamiento y desaprovisionamiento de gruposGroup provisioning and deprovisioning sequence

Modificación de solicitudes y respuestas de protocolo SCIMSCIM protocol requests and responses

En esta sección se proporcionan solicitudes SCIM de ejemplo emitidas por el cliente de SCIM de AAD y las respuestas de ejemplo esperadas.This section provides example SCIM requests emitted by the AAD SCIM client and example expected responses. Para obtener mejores resultados, debe codificar la aplicación para controlar estas solicitudes en este formato y emitir las respuestas esperadas.For best results, you should code your app to handle these requests in this format and emit the expected responses.

Importante

Para comprender cómo y cuándo el servicio de aprovisionamiento de usuarios de AAD emite las operaciones que se describen a continuación, consulte la sección Ciclos de aprovisionamiento: inicial e incremental en Funcionamiento del aprovisionamiento.To understand how and when the AAD user provisioning service emits the operations described below, see the section Provisioning cycles: Initial and incremental in How provisioning works.

Operaciones de usuarioUser Operations

Operaciones de grupoGroup Operations

Detección de esquemasSchema discovery

Operaciones de usuarioUser Operations

  • Los usuarios pueden ser consultados por atributos userName o email[type eq "work"].Users can be queried by userName or email[type eq "work"] attributes.

Crear usuarioCreate User

SolicitudRequest

POST /UsersPOST /Users

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

HTTP/1.1 201 CreatedHTTP/1.1 201 Created

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

Obtener usuarioGet User

SolicitudRequest

GET /Users/5d48a0a8e9f04aa38008GET /Users/5d48a0a8e9f04aa38008

Respuesta (Se encontró el usuario)Response (User found)

HTTP/1.1 200 OKHTTP/1.1 200 OK

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

GET /Users/5171a35d82074e068ce2GET /Users/5171a35d82074e068ce2

Respuesta (No se encontró el usuario.Response (User not found. Observe que no se requiere el detalle, solo el estado).Note that the detail is not required, only status.)
{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:Error"
    ],
    "status": "404",
    "detail": "Resource 23B51B0E5D7AE9110A49411D@7cca31655d49f3640a494224 not found"
}

Obtener usuario por consultaGet User by query

SolicitudRequest

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

RespuestaResponse

HTTP/1.1 200 OKHTTP/1.1 200 OK

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

Obtener usuario por consulta: cero resultadosGet User by query - Zero results

SolicitudRequest

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

RespuestaResponse

HTTP/1.1 200 OKHTTP/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]Update User [Multi-valued properties]

SolicitudRequest

PATCH /Users/6764549bef60420686bc HTTP/1.1PATCH /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"
            }
    ]
}
RespuestaResponse

HTTP/1.1 200 OKHTTP/1.1 200 OK

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

Actualizar usuario [propiedades de un solo valor]Update User [Single-valued properties]

SolicitudRequest

PATCH /Users/5171a35d82074e068ce2 HTTP/1.1PATCH /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"
    }]
}
RespuestaResponse

HTTP/1.1 200 OKHTTP/1.1 200 OK

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

Deshabilitar usuarioDisable User

SolicitudRequest

PATCH /Users/5171a35d82074e068ce2 HTTP/1.1PATCH /Users/5171a35d82074e068ce2 HTTP/1.1

{
    "Operations": [
        {
            "op": "Replace",
            "path": "active",
            "value": false
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ]
}
RespuestaResponse
{
    "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 usuarioDelete User

SolicitudRequest

DELETE /Users/5171a35d82074e068ce2 HTTP/1.1DELETE /Users/5171a35d82074e068ce2 HTTP/1.1

RespuestaResponse

HTTP/1.1 204 No ContentHTTP/1.1 204 No Content

Operaciones de grupoGroup Operations

  • Los grupos deben crearse siempre con una lista de miembros vacía.Groups shall always be created with an empty members list.
  • Los grupos pueden ser consultados por el atributo displayName.Groups can be queried by the displayName attribute.
  • La actualización de la solicitud de PATCH del grupo debe producir un HTTP 204 No Content en la respuesta.Update to the group PATCH request should yield an HTTP 204 No Content in the response. La devolución de un cuerpo con una lista de todos los miembros no es aconsejable.Returning a body with a list of all the members isn't advisable.
  • No es necesario admitir la devolución de todos los miembros del grupo.It isn't necessary to support returning all the members of the group.

Crear grupoCreate Group

SolicitudRequest

POST /Groups HTTP/1.1POST /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"
    }
}
RespuestaResponse

HTTP/1.1 201 CreatedHTTP/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 grupoGet Group

SolicitudRequest

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

RespuestaResponse

HTTP/1.1 200 OKHTTP/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 displayNameGet Group by displayName

SolicitudRequest

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

RespuestaResponse

HTTP/1.1 200 OKHTTP/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]Update Group [Non-member attributes]

SolicitudRequest

PATCH /Groups/fa2ce26709934589afc5 HTTP/1.1PATCH /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"
    }]
}
RespuestaResponse

HTTP/1.1 204 No ContentHTTP/1.1 204 No Content

Actualizar grupo [Agregar miembros]Update Group [Add Members]

SolicitudRequest

PATCH /Groups/a99962b9f99d4c4fac67 HTTP/1.1PATCH /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"
        }]
    }]
}
RespuestaResponse

HTTP/1.1 204 No ContentHTTP/1.1 204 No Content

Actualizar grupo [Eliminar miembros]Update Group [Remove Members]

SolicitudRequest

PATCH /Groups/a99962b9f99d4c4fac67 HTTP/1.1PATCH /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"
        }]
    }]
}
RespuestaResponse

HTTP/1.1 204 No ContentHTTP/1.1 204 No Content

Eliminar grupoDelete Group

SolicitudRequest

DELETE /Groups/cdb1ce18f65944079d37 HTTP/1.1DELETE /Groups/cdb1ce18f65944079d37 HTTP/1.1

RespuestaResponse

HTTP/1.1 204 No ContentHTTP/1.1 204 No Content

Detección de esquemasSchema discovery

Detección de esquemaDiscover schema

SolicitudRequest

GET /SchemasGET /Schemas

RespuestaResponse

HTTP/1.1 200 OKHTTP/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 seguridadSecurity requirements

Versiones del protocolo SSLTLS Protocol Versions

Las únicas versiones aceptables del protocolo TLS son TLS 1.2 y TLS 1.3.The only acceptable TLS protocol versions are TLS 1.2 and TLS 1.3. No se permiten otras versiones de TLS.No other versions of TLS are permitted. No se permite ninguna versión de SSL.No version of SSL is permitted.

  • Las claves RSA deben ser de al menos 2048 bits.RSA keys must be at least 2,048 bits.
  • Las claves ECC deben ser de al menos 256 bits, generadas mediante una curva elíptica aprobada.ECC keys must be at least 256 bits, generated using an approved elliptic curve

Longitud de las clavesKey Lengths

Todos los servicios deben usar certificados X.509 generados con claves criptográficas de una longitud suficiente, lo que significa:All services must use X.509 certificates generated using cryptographic keys of sufficient length, meaning:

Conjuntos de cifradoCipher Suites

Todos los servicios deben configurarse para usar los siguientes conjuntos de cifrado, en el orden exacto que se especifica a continuación.All services must be configured to use the following cipher suites, in the exact order specified below. Tenga en cuenta que si solo tiene un certificado RSA instalado, los conjuntos de cifrado ECDSA no tienen ningún efecto.Note that if you only have an RSA certificate, installed the ECDSA cipher suites do not have any effect.

Barra mínima de conjuntos de cifrado TLS 1.2:TLS 1.2 Cipher Suites minimum bar:

  • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384

Intervalos IPIP Ranges

El servicio de aprovisionamiento de Azure AD actualmente opera en los intervalos IP de AzureActiveDirectory, tal y como se muestra aquí.The Azure AD provisioning service currently operates under the IP Ranges for AzureActiveDirectory as listed here. Puede agregar los intervalos IP que aparecen en la etiqueta AzureActiveDirectory para permitir el tráfico desde el servicio de aprovisionamiento de Azure AD a la aplicación.You can add the IP ranges listed under the AzureActiveDirectory tag to allow traffic from the Azure AD provisioning service into your application. Tenga en cuenta que deberá revisar detenidamente la lista de intervalos de IP para direcciones procesadas.Note that you will need to review the IP range list carefully for computed addresses. Una dirección como «40.126.25.32» podría aparecer en la lista de intervalos IP como «40.126.0.0/18».An address such as '40.126.25.32' could be represented in the IP range list as '40.126.0.0/18'. También puede recuperar la lista de intervalos IP mediante programación con la siguiente API.You can also programmatically retrieve the IP range list using the following API.

Cree un punto de conexión SCIMBuild a SCIM endpoint

Ahora que ha diseñado el esquema y comprendido la implementación de SCIM de Azure AD, puede empezar a desarrollar el punto de conexión de SCIM.Now that you have designed your schema and understood the Azure AD SCIM implementation, you can get started developing your SCIM endpoint. En lugar de comenzar desde cero y compilar la implementación totalmente por su cuenta, puede confiar en una serie de bibliotecas de SCIM de código abierto publicadas por la comunidad de SCIM.Rather than starting from scratch and building the implementation completely on your own, you can rely on a number of open source SCIM libraries published by the SCIM community.

Para obtener instrucciones sobre cómo crear un punto de conexión de SCIM, incluidos ejemplos, consulte Desarrollo de un punto de conexión SCIM de ejemplo.For guidance on how to build a SCIM endpoint including examples, see Develop a sample SCIM endpoint.

El código de referencia de ejemplo de .NET Core de código abierto publicado por el equipo de aprovisionamiento de Azure AD es uno de esos recursos que puede impulsar su desarrollo.The open source .NET Core reference code example published by the Azure AD provisioning team is one such resource that can jump start your development. Una vez que haya creado el punto de conexión de SCIM, querrá probarlo. Puede usar la colección de pruebas de Postman proporcionadas como parte del código de referencia o ejecutar las solicitudes o respuestas de ejemplo proporcionadas anteriormente.Once you have built your SCIM endpoint, you will want to test it out. You can use the collection of postman tests provided as part of the reference code or run through the sample requests / responses provided above.

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".The reference code is intended to help you get started building your SCIM endpoint and is provided "AS IS." Las contribuciones de la comunidad le ayudarán a crear y mantener el código.Contributions from the community are welcome to help build and maintain the code.

La solución se compone de dos proyectos: Microsoft.SCIM y Microsoft.SCIM.WebHostSample.The solution is composed of two projects, Microsoft.SCIM and 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.The Microsoft.SCIM project is the library that defines the components of the web service that conforms to the SCIM specification. Declara la interfaz Microsoft.SCIM.IProvider. Las solicitudes se traducen en llamadas a los métodos del proveedor, que se programan para funcionar en un almacén de identidades.It declares the interface Microsoft.SCIM.IProvider, requests are translated into calls to the provider’s methods, which would be programmed to operate on an identity store.

Desglose: Una solicitud traducida en llamadas a los métodos del proveedor

El proyecto Microsoft.SCIM.WebHostSample es una aplicación web ASP.NET Core de Visual Studio basada en la plantilla Empty.The Microsoft.SCIM.WebHostSample project is a Visual Studio ASP.NET Core Web Application, based on the Empty template. Esto permite implementar el código de ejemplo como independiente, hospedado en contenedores o en Internet Information Services.This allows the sample code to be deployed as standalone, hosted in containers or within Internet Information Services. También implementa la interfaz Microsoft.SCIM.IProvider, que mantiene las clases en memoria como almacén de identidades de ejemplo.It also implements the Microsoft.SCIM.IProvider interface keeping classes in memory as a sample identity store.

    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 personalizadoBuilding a custom SCIM endpoint

El servicio 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:The SCIM service must have an HTTP address and server authentication certificate of which the root certification authority is one of the following names:

  • CNNICCNNIC
  • ComodoComodo
  • CyberTrustCyberTrust
  • DigiCertDigiCert
  • GeoTrustGeoTrust
  • GlobalSignGlobalSign
  • Go DaddyGo Daddy
  • VeriSignVeriSign
  • WoSignWoSign
  • DST Root CA X3DST Root CA X3

El SDK de .NET Core incluye un certificado de desarrollo HTTPS que se puede usar durante el desarrollo. El certificado se instala como parte de la experiencia de primera ejecución.The .NET Core SDK includes an HTTPS development certificate that can be used during development, the certificate is installed as part of the first-run experience. En función de cómo ejecute la aplicación web ASP.NET Core, escuchará en un puerto diferente:Depending on how you run the ASP.NET Core Web Application it will listen to a different port:

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

Para obtener más información sobre HTTPS en ASP.NET Core, use el siguiente vínculo: Aplicar HTTPS en ASP.NET CoreFor more information on HTTPS in ASP.NET Core use the following link: Enforce HTTPS in ASP.NET Core

Control de la autenticación de puntos de conexiónHandling endpoint authentication

Las solicitudes de Azure Active Directory incluyen un token de portador de OAuth 2.0.Requests from Azure Active Directory include an OAuth 2.0 bearer token. Cualquier servicio que reciba la solicitud debe autenticar al emisor como Azure Active Directory para el inquilino de Azure Active Directory esperado.Any service receiving the request should authenticate the issuer as being Azure Active Directory for the expected Azure Active Directory tenant.

En el token, el emisor se identifica mediante una notificación de ISS; por ejemplo, "iss":"https://sts.windows.net/cbb1a5ac-f33b-45fa-9bf5-f37db0fed422/".In the token, the issuer is identified by an iss claim, like "iss":"https://sts.windows.net/cbb1a5ac-f33b-45fa-9bf5-f37db0fed422/". En este ejemplo, la dirección base del valor de notificación, https://sts.windows.net, identifica a Azure Active Directory como el emisor, mientras que el segmento de la dirección relativa, cbb1a5ac-f33b-45fa-9bf5-f37db0fed422, es un identificador único del inquilino de Azure Active Directory para el que se emitió el token.In this example, the base address of the claim value, https://sts.windows.net, identifies Azure Active Directory as the issuer, while the relative address segment, cbb1a5ac-f33b-45fa-9bf5-f37db0fed422, is a unique identifier of the Azure Active Directory tenant for which the token was issued.

La audiencia del token será el identificador de la plantilla de aplicación de la aplicación en la galería. Cada una de las aplicaciones registradas en un solo inquilino puede recibir la misma notificación iss con solicitudes SCIM.The audience for the token will be the application template ID for the application in the gallery, each of the applications registered in a single tenant may receive the same iss claim with SCIM requests. El identificador de la plantilla de aplicación para todas las aplicaciones personalizadas es 8adf8e6e-67b2-4cf2-a259-e3dc5476c621.The application template ID for all custom apps is 8adf8e6e-67b2-4cf2-a259-e3dc5476c621. El token generado por el servicio de aprovisionamiento de Azure AD solo se debe usar para realizar pruebas.The token generated by the Azure AD provisioning service should only be used for testing. No se debe usar en entornos de producción.It should not be used in production environments.

En el código de ejemplo, las solicitudes se autentican mediante el paquete Microsoft.AspNetCore.Authentication.JwtBearer.In the sample code, requests are authenticated using the Microsoft.AspNetCore.Authentication.JwtBearer package. 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 Azure Active Directory para un inquilino concreto:The following code enforces that requests to any of the service’s endpoints are authenticated using the bearer token issued by Azure Active Directory for a specified tenant:

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

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

También se requiere un token de portador para usar las pruebas de Postman proporcionadas y realizar la depuración local con localhost.A bearer token is also required to use of the provided postman tests and perform local debugging using localhost. El código de ejemplo usa entornos ASP.NET Core para cambiar las opciones de autenticación durante la fase de desarrollo y habilitar el uso de un token autofirmado.The sample code uses ASP.NET Core environments to change the authentication options during development stage and enable the use a self-signed token.

Para más información sobre varios entornos de ASP.NET Core, consulte Uso de varios entornos en ASP.NET Core.For more information on multiple environments in ASP.NET Core, see Use multiple environments in 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:The following code enforces that requests to any of the service’s endpoints are authenticated using a bearer token signed with a custom key:

public void ConfigureServices(IServiceCollection services)
{
    if (_env.IsDevelopment())
    {
        services.AddAuthentication(options =>
        {
            options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
            options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
            options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
        })
        .AddJwtBearer(options =>
        {
            options.TokenValidationParameters =
                new TokenValidationParameters
                {
                    ValidateIssuer = false,
                    ValidateAudience = false,
                    ValidateLifetime = false,
                    ValidateIssuerSigningKey = false,
                    ValidIssuer = "Microsoft.Security.Bearer",
                    ValidAudience = "Microsoft.Security.Bearer",
                    IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("A1B2C3D4E5F6A1B2C3D4E5F6"))
                };
        });
    }
...

Envíe una solicitud GET al controlador de tokens para obtener un token de portador válido. El método GenerateJSONWebToken es el responsable de crear un token que coincida con los parámetros configurados para el desarrollo:Send a GET request to the Token controller to get a valid bearer token, the method GenerateJSONWebToken is responsible to create a token matching the parameters configured for development:

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 usuariosHandling provisioning and deprovisioning of users

Ejemplo 1. Consulta del servicio para buscar un usuario coincidenteExample 1. Query the service for a matching user

Azure Active Directory (AAD) 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 AAD.Azure Active Directory (AAD) queries the service for a user with an externalId attribute value matching the mailNickname attribute value of a user in AAD. 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 Azure Active Directory.The query is expressed as a Hypertext Transfer Protocol (HTTP) request such as this example, wherein jyoung is a sample of a mailNickname of a user in Azure Active Directory.

Nota

Esto es solo un ejemplo.This is an example only. No todos los usuarios tendrán un atributo mailNickname, y el valor que tiene un usuario no puede ser único en el directorio.Not all users will have a mailNickname attribute, and the value a user has may not be unique in the directory. Además, el atributo utilizado para la coincidencia (que en este caso es externalId) es configurable en las asignaciones de atributos de AAD.Also, the attribute used for matching (which in this case is externalId) is configurable in the AAD attribute mappings.

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.In the sample code the request is translated into a call to the QueryAsync method of the service’s provider. Esta es la firma de ese método:Here is the signature of that method:

// 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:In the sample query, for a user with a given value for the externalId attribute, values of the arguments passed to the QueryAsync method are:

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

Ejemplo 2. Aprovisionamiento de un usuarioExample 2. Provision a user

Si la respuesta a una consulta al servicio web relativa 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, AAD solicita al servicio que aprovisione un usuario correspondiente al de AAD.If the response to a query to the web service for a user with an externalId attribute value that matches the mailNickname attribute value of a user doesn't return any users, then AAD requests that the service provision a user corresponding to the one in AAD. Este es un ejemplo de dicha solicitud:Here is an example of such a request:

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.In the sample code the request is translated into a call to the CreateAsync method of the service’s provider. Esta es la firma de ese método:Here is the signature of that method:

// 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 para aprovisionar un usuario, el valor del argumento del recurso es una instancia de la clase Microsoft.SCIM.Core2EnterpriseUser, que se define en la biblioteca Microsoft.SCIM.Schemas.In a request to provision a user, the value of the resource argument is an instance of the Microsoft.SCIM.Core2EnterpriseUser class, defined in the Microsoft.SCIM.Schemas library. 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, con el valor de la propiedad Identifier establecida en el identificador único del usuario recién aprovisionado.If the request to provision the user succeeds, then the implementation of the method is expected to return an instance of the Microsoft.SCIM.Core2EnterpriseUser class, with the value of the Identifier property set to the unique identifier of the newly provisioned user.

Ejemplo 3. Consulta del estado actual de un usuarioExample 3. Query the current state of a user

Para actualizar un usuario que se sabe que existe en un almacén de identidades dirigido por un SCIM, Azure Active Directory solicita el estado actual de dicho usuario desde el servicio con una solicitud como esta:To update a user known to exist in an identity store fronted by an SCIM, Azure Active Directory proceeds by requesting the current state of that user from the service with a request such as:

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

En el código de ejemplo, la solicitud se traduce en una llamada al método RetrieveAsync del proveedor del servicio.In the sample code the request is translated into a call to the RetrieveAsync method of the service’s provider. Esta es la firma de ese método:Here is the signature of that method:

// 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:In the example of a request to retrieve the current state of a user, the values of the properties of the object provided as the value of the parameters argument are as follows:

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

Ejemplo 4. Consulta del valor de un atributo de referencia que se va a actualizarExample 4. Query the value of a reference attribute to be updated

Si se va a actualizar un atributo de referencia, Azure Active Directory consulta el servicio para determinar si el valor actual del atributo de referencia en el almacén de identidades dirigido por el servicio, ya coincide con el valor de dicho atributo en Azure Active Directory.If a reference attribute is to be updated, then Azure Active Directory queries the service to determine whether the current value of the reference attribute in the identity store fronted by the service already matches the value of that attribute in Azure Active Directory. Para los usuarios, el único atributo del que se va a consultar el valor actual de esta manera es el atributo manager.For users, the only attribute of which the current value is queried in this way is the manager attribute. 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.Here is an example of a request to determine whether the manager attribute of a user object currently has a certain value: In the sample code the request is translated into a call to the QueryAsync method of the service’s provider. El valor de las propiedades del objeto proporcionado como el valor del argumento parameters es el siguiente:The value of the properties of the object provided as the value of the parameters argument are as follows:

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

En este caso, 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, en función del orden de las expresiones del parámetro de consulta filter.Here, the value of the index x can be 0 and the value of the index y can be 1, or the value of x can be 1 and the value of y can be 0, depending on the order of the expressions of the filter query parameter.

Ejemplo 5. Solicitud de Azure AD a un servicio SCIM para actualizar un usuarioExample 5. Request from Azure AD to an SCIM service to update a user

A continuación se proporciona un ejemplo de una solicitud de Azure Active Directory a un servicio SCIM para actualizar un usuario:Here is an example of a request from Azure Active Directory to an SCIM service to update a user:

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

En el código de ejemplo, la solicitud se traduce en una llamada al método UpdateAsync del proveedor del servicio.In the sample code the request is translated into a call to the UpdateAsync method of the service’s provider. Esta es la firma de ese método:Here is the signature of that method:

// 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:In the example of a request to update a user, the object provided as the value of the patch argument has these property values:

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

Ejemplo 6. Desaprovisionamiento de un usuarioExample 6. Deprovision a user

Para desaprovisionar un usuario de un almacén de identidades dirigido por un servicio SCIM, AAD envía una solicitud como esta:To deprovision a user from an identity store fronted by an SCIM service, AAD sends a request such as:

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

En el código de ejemplo, la solicitud se traduce en una llamada al método DeleteAsync del proveedor del servicio.In the sample code the request is translated into a call to the DeleteAsync method of the service’s provider. Esta es la firma de ese método:Here is the signature of that method:

// 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:The object provided as the value of the resourceIdentifier argument has these property values in the example of a request to deprovision a user:

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

Integración del punto de conexión de SCIM con el cliente de SCIM de AADIntegrate your SCIM endpoint with the AAD SCIM client

Azure AD se puede configurar para que aprovisione automáticamente usuarios y grupos asignados a aplicaciones que implementan un perfil específico del protocolo SCIM 2.0.Azure AD can be configured to automatically provision assigned users and groups to applications that implement a specific profile of the SCIM 2.0 protocol. Los detalles del perfil están documentados en Información sobre la implementación de SCIM de Azure AD.The specifics of the profile are documented in Understand the Azure AD SCIM implementation.

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.Check with your application provider, or your application provider's documentation for statements of compatibility with these requirements.

Importante

La implementación de SCIM de Azure AD se basa en el servicio de aprovisionamiento de usuarios de Azure AD, que está diseñado para mantener a los usuarios constantemente sincronizados entre Azure AD y la aplicación de destino, y que implementa un conjunto muy específico de operaciones estándar.The Azure AD SCIM implementation is built on top of the Azure AD user provisioning service, which is designed to constantly keep users in sync between Azure AD and the target application, and implements a very specific set of standard operations. Es importante comprender estos comportamientos para entender el comportamiento del cliente de SCIM de Azure AD.It's important to understand these behaviors to understand the behavior of the Azure AD SCIM client. Para obtener más información, consulte la sección Ciclos de aprovisionamiento: inicial e incremental en Funcionamiento del aprovisionamiento.For more information, see the section Provisioning cycles: Initial and incremental in How provisioning works.

IntroducciónGetting started

Las aplicaciones que admiten el perfil SCIM descrito en este artículo se pueden conectar a Azure Active Directory mediante la característica "de aplicación situada fuera de la galería" de la galería de aplicaciones de Azure AD.Applications that support the SCIM profile described in this article can be connected to Azure Active Directory using the "non-gallery application" feature in the Azure AD application gallery. Una vez conectadas, Azure AD ejecuta un proceso de sincronización cada 40 minutos en el que 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.Once connected, Azure AD runs a synchronization process every 40 minutes where it queries the application's SCIM endpoint for assigned users and groups, and creates or modifies them according to the assignment details.

Para conectar una aplicación que admite SCIM:To connect an application that supports SCIM:

  1. Inicie sesión en el portal de AAD.Sign in to the AAD portal. Tenga en cuenta que puede obtener acceso a una evaluación gratuita de Azure Active Directory con licencias P2 si se suscribe al programa para programadores.Note that you can get access a free trial for Azure Active Directory with P2 licenses by signing up for the developer program

  2. En el panel izquierdo, seleccione Aplicaciones empresariales.Select Enterprise applications from the left pane. Se muestra una lista de las aplicaciones configuradas, incluidas aquellas que se han agregado desde la galería.A list of all configured apps is shown, including apps that were added from the gallery.

  3. Seleccione + Nueva aplicación > + Cree su propia aplicación.Select + New application > + Create your own application.

  4. Escriba un nombre para la aplicación, elija la opción "Integrar cualquier otra aplicación que no se encuentre en la galería" y seleccione Agregar para crear un objeto de aplicación.Enter a name for your application, choose the option "integrate any other application you don't find in the gallery" and select Add to create an app object. 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.The new app is added to the list of enterprise applications and opens to its app management screen.

    Captura de pantalla que muestra la galería de aplicaciones de Azure AD Galería de aplicaciones de Azure ADScreenshot shows the Azure AD application gallery Azure AD application gallery

    Nota

    Si usa la antigua experiencia de la galería de aplicaciones, siga la guía de la pantalla que aparece a continuación.If you are using the old app gallery experience, follow the screen guide below.

    Captura de pantalla que muestra la experiencia de la galería de aplicaciones antigua de Azure AD Experiencia de la galería de aplicaciones antigua de Azure ADScreenshot shows the Azure AD old app gallery experience Azure AD old app gallery experience

  5. En la pantalla de administración de la aplicación, seleccione Aprovisionamiento en el panel izquierdo.In the app management screen, select Provisioning in the left panel.

  6. En el menú Modo de aprovisionamiento, seleccione Automático.In the Provisioning Mode menu, select Automatic.

    Ejemplo: Página Aprovisionamiento de una aplicación en Azure PortalExample: An app's Provisioning page in the Azure portal
    Configuración del aprovisionamiento en Azure PortalConfiguring provisioning in the Azure portal

  7. En el campo Dirección URL del inquilino, escriba la dirección URL del punto de conexión SCIM de la aplicación.In the Tenant URL field, enter the URL of the application's SCIM endpoint. Ejemplo: https://api.contoso.com/scim/Example: https://api.contoso.com/scim/

  8. Si el punto de conexión SCIM requiere un token de portador OAuth de un emisor que no sea Azure AD, copie el token de portador OAuth necesario en el campo Token secreto.If the SCIM endpoint requires an OAuth bearer token from an issuer other than Azure AD, then copy the required OAuth bearer token into the optional Secret Token field. Si este campo se deja en blanco, Azure AD incluye un token de portador OAuth emitido desde Azure AD con cada solicitud.If this field is left blank, Azure AD includes an OAuth bearer token issued from Azure AD with each request. Las aplicaciones que usan Azure AD como un proveedor de identidades pueden validar este token que emitió Azure AD.Apps that use Azure AD as an identity provider can validate this Azure AD-issued token.

    Nota

    No se recomienda dejar este campo en blanco y basarse en un token generado por Azure AD.It's not recommended to leave this field blank and rely on a token generated by Azure AD. Esta opción está disponible principalmente para fines de prueba.This option is primarily available for testing purposes.

  9. Seleccione Probar conexión para que Azure Active Directory intente conectarse al punto de conexión SCIM.Select Test Connection to have Azure Active Directory attempt to connect to the SCIM endpoint. Si se produce un error en el intento, se muestra la información de error.If the attempt fails, error information is displayed.

    Nota

    La prueba de conexión consulta el punto de conexión SCIM de un usuario que no existe mediante un GUID aleatorio, como la propiedad de coincidencia seleccionada en la configuración de Azure AD.Test Connection queries the SCIM endpoint for a user that doesn't exist, using a random GUID as the matching property selected in the Azure AD configuration. La respuesta correcta esperada es HTTP 200 OK con un mensaje ListResponse de SCIM vacío.The expected correct response is HTTP 200 OK with an empty SCIM ListResponse message.

  10. Si la conexión se realiza con éxito, a continuación, seleccione Guardar para guardar las credenciales de administrador.If the attempts to connect to the application succeed, then select Save to save the admin credentials.

  11. En la sección Asignaciones, hay dos conjuntos seleccionables de asignaciones de atributos: uno para los objetos de usuario y otro para los objetos de grupo.In the Mappings section, there are two selectable sets of attribute mappings: one for user objects and one for group objects. Seleccione cada uno de ellos para revisar los atributos que se sincronizan desde Azure Active Directory a la aplicación.Select each one to review the attributes that are synchronized from Azure Active Directory to your app. 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.The attributes selected as Matching properties are used to match the users and groups in your app for update operations. Para confirmar los cambios, seleccione Guardar.Select Save to commit any changes.

    Nota

    Opcionalmente, puede deshabilitar la sincronización de objetos de grupo deshabilitando la asignación de "grupos".You can optionally disable syncing of group objects by disabling the "groups" mapping.

  12. En Settings (Configuración), el campo Scope (Ámbito) define qué usuarios y grupos se sincronizan.Under Settings, the Scope field defines which users and groups are synchronized. Seleccione Sincronizar solo los usuarios y grupos asignados (recomendado) para que se sincronicen solamente los usuarios y los grupos asignados en la pestaña Usuarios y grupos.Select Sync only assigned users and groups (recommended) to only sync users and groups assigned in the Users and groups tab.

  13. Una vez completada la configuración, cambie el Estado de aprovisionamiento a Activado.Once your configuration is complete, set the Provisioning Status to On.

  14. Seleccione Guardar para iniciar el servicio de aprovisionamiento de Azure AD.Select Save to start the Azure AD provisioning service.

  15. Al sincronizar solo los usuarios y grupos asignados (recomendado), no olvide seleccionar la pestaña Usuarios y grupos y asignar los usuarios o grupos que quiere sincronizar.If syncing only assigned users and groups (recommended), be sure to select the Users and groups tab and assign the users or groups you want to sync.

Una vez que haya empezado el ciclo inicial, puede seleccionar Registros de aprovisionamiento en el panel izquierdo para supervisar el progreso; con esto se muestran todas las acciones realizadas por el servicio de aprovisionamiento en la aplicación.Once the initial cycle has started, you can select Provisioning logs in the left panel to monitor progress, which shows all actions done by the provisioning service on your app. Para más información sobre cómo leer los registros de aprovisionamiento de Azure AD, consulte el tutorial de Creación de informes sobre el aprovisionamiento automático de cuentas de usuario.For more information on how to read the Azure AD provisioning logs, see Reporting on automatic user account provisioning.

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.The initial cycle takes longer to perform than later syncs, which occur approximately every 40 minutes as long as the service is running.

Si va a crear una aplicación que usará más de un inquilino, puede hacer que esté disponible en la galería de aplicaciones de Azure AD.If you're building an application that will be used by more than one tenant, you can make it available in the Azure AD application gallery. De este modo, facilitará a las organizaciones la detección de la aplicación y la configuración del aprovisionamiento.This will make it easy for organizations to discover the application and configure provisioning. Publicar la aplicación en la galería de Azure AD y hacer que el aprovisionamiento esté disponible para otros usuarios es fácil.Publishing your app in the Azure AD gallery and making provisioning available to others is easy. Consulte los pasos aquí.Check out the steps here. Microsoft colaborará con usted a fin de integrar su aplicación en nuestra galería, probar su punto de conexión y publicar la documentación de incorporación de versiones para que los clientes la usen.Microsoft will work with you to integrate your application into our gallery, test your endpoint, and release onboarding documentation for customers to use.

Use la lista de comprobación para incorporar la aplicación rápidamente y que los clientes tengan una experiencia de implementación fluida.Use the checklist to onboard your application quickly and customers have a smooth deployment experience. La información se recopilará en el momento en que se incorpore a la galería.The information will be gathered from you when onboarding to the gallery.

  • Admitir un punto de conexión de grupo y usuario de SCIM 2.0 (solo se requiere uno, pero se recomiendan los dos)Support a SCIM 2.0 user and group endpoint (Only one is required but both are recommended)
  • Admitir al menos 25 solicitudes por segundo por inquilino para asegurarse de que los usuarios y grupos se aprovisionan y desaprovisionan sin retraso (obligatorio)Support at least 25 requests per second per tenant to ensure that users and groups are provisioned and deprovisioned without delay (Required)
  • Establecimiento de contactos de ingeniería y soporte técnico para guiar la incorporación de clientes a la galería (obligatorio)Establish engineering and support contacts to guide customers post gallery onboarding (Required)
  • Tres credenciales de prueba sin expiración para la aplicación (obligatorio)3 Non-expiring test credentials for your application (Required)
  • Compatibilidad con la concesión de código de autorización de OAuth o un token de larga duración, tal como se describe a continuación (obligatorio)Support the OAuth authorization code grant or a long lived token as described below (Required)
  • 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)Establish an engineering and support point of contact to support customers post gallery onboarding (Required)
  • Compatibilidad con la detección de esquemas (obligatorio)Support schema discovery (required)
  • Compatibilidad con la actualización de varias pertenencias a grupos con una única instrucción PATCHSupport updating multiple group memberships with a single PATCH
  • Documentación del punto de conexión de SCIM públicamenteDocument your SCIM endpoint publicly

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.The SCIM spec doesn't define a SCIM-specific scheme for authentication and authorization and relies on the use of existing industry standards.

Método de autorizaciónAuthorization method VentajasPros DesventajasCons Soporte técnicoSupport
Nombre de usuario y contraseña (no recomendado ni compatible con Azure AD)Username and password (not recommended or supported by Azure AD) Fácil de implementarEasy to implement No seguro: Tu contraseña no importaInsecure - Your Pa$$word doesn't matter Se admite según cada caso en las aplicaciones de la galería.Supported on a case-by-case basis for gallery apps. No se admite para las aplicaciones que no son de la galería.Not supported for non-gallery apps.
Token de portador de larga duraciónLong-lived bearer token Los tokens de larga duración no requieren que haya un usuario presente.Long-lived tokens do not require a user to be present. Son fáciles de usar para los administradores al configurar el aprovisionamiento.They are easy for admins to use when setting up provisioning. 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.Long-lived tokens can be hard to share with an admin without using insecure methods such as email. Compatibles con las aplicaciones de la galería y las que no forman parte de ella.Supported for gallery and non-gallery apps.
Concesión de código de autorización de OAuthOAuth authorization code grant 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.Access tokens are much shorter-lived than passwords, and have an automated refresh mechanism that long-lived bearer tokens do not have. Un usuario real debe estar presente durante la autorización inicial, lo que añade un nivel de responsabilidad.A real user must be present during initial authorization, adding a level of accountability. Requiere que haya un usuario presente.Requires a user to be present. Si el usuario deja la organización, el token no es válido y será necesario volver a realizar la autorización.If the user leaves the organization, the token is invalid and authorization will need to be completed again. Compatible con aplicaciones de la galería, pero no con aplicaciones que no son de la galería.Supported for gallery apps, but not non-gallery apps. 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.However, you can provide an access token in the UI as the secret token for short term testing purposes. 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.Support for OAuth code grant on non-gallery is in our backlog, in addition to support for configurable auth / token URLs on the gallery app.
Concesión de credenciales del cliente de OAuthOAuth client credentials grant 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.Access tokens are much shorter-lived than passwords, and have an automated refresh mechanism that long-lived bearer tokens do not have. 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.Both the authorization code grant and the client credentials grant create the same type of access token, so moving between these methods is transparent to the API. El aprovisionamiento se puede automatizar completamente y los nuevos tokens se pueden solicitar silenciosamente sin la interacción del usuario.Provisioning can be completely automated, and new tokens can be silently requested without user interaction. No compatible con las aplicaciones de la galería y las que no forman parte de ella.Not supported for gallery and non-gallery apps. La compatibilidad se encuentra en nuestro trabajo pendiente.Support is in our backlog.

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 AAD.It's not recommended to leave the token field blank in the AAD provisioning configuration custom app UI. El token generado está disponible principalmente para fines de prueba.The token generated is primarily available for testing purposes.

Flujo de concesión de código de OAuthOAuth code grant flow

El servicio de aprovisionamiento admite la concesión del código de autorización y, después de enviar la solicitud de publicación de la aplicación en la galería, nuestro equipo trabajará con usted para recopilar la información siguiente:The provisioning service supports the authorization code grant and after submitting your request for publishing your app in the gallery, our team will work with you to collect the following information:

  • 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.Authorization URL, a URL by the client to obtain authorization from the resource owner via user-agent redirection. Se redirige al usuario a esta dirección URL para autorizar el acceso.The user is redirected to this URL to authorize access.

  • Dirección URL de intercambio de token: una dirección URL del cliente para intercambiar una concesión de autorización por un token de acceso, normalmente con autenticación del cliente.Token exchange URL, a URL by the client to exchange an authorization grant for an access token, typically with client authentication.

  • Identificador de cliente: el servidor de autorización emite al cliente registrado un identificador de cliente, que es una cadena única que representa la información de registro que proporciona el cliente.Client ID, the authorization server issues the registered client a client identifier, which is a unique string representing the registration information provided by the client. El identificador de cliente no es un secreto; se expone al propietario del recurso y no debe usarse solo para la autenticación del cliente.The client identifier is not a secret; it is exposed to the resource owner and must not be used alone for client authentication.

  • Secreto de cliente: un secreto generado por el servidor de autorización que debe ser un valor único que solo conoce el servidor de autorización.Client secret, a secret generated by the authorization server that should be a unique value known only to the authorization server.

Nota

La dirección URL de autorización y la dirección URL de intercambio de tokens no se pueden configurar actualmente por inquilino.The Authorization URL and Token exchange URL are currently not configurable per tenant.

Nota

OAuth 1 no se admite debido a la exposición del secreto de cliente.OAuth v1 is not supported due to exposure of the client secret. Se admite OAuth v2.OAuth v2 is supported.

Procedimientos recomendados (pero no obligatorios):Best practices (recommended, but not required):

  • Se admiten varias direcciones URL de redireccionamiento.Support multiple redirect URLs. Los administradores pueden configurar el aprovisionamiento tanto desde "portal.azure.com" como desde "aad.portal.azure.com".Administrators can configure provisioning from both "portal.azure.com" and "aad.portal.azure.com". La compatibilidad con varias direcciones URL de redireccionamiento garantizará que los usuarios puedan autorizar el acceso desde cualquier portal.Supporting multiple redirect URLs will ensure that users can authorize access from either portal.
  • Admita varios secretos para una renovación sencilla, sin tiempo de inactividad.Support multiple secrets for easy renewal, without downtime.

Configuración del flujo de concesión de código de OAuthHow to setup OAuth code grant flow

  1. Inicie sesión en Azure Portal, vaya a Aplicaciones empresariales > Aplicación > Aprovisionamiento y seleccione Autorizar.Sign in to the Azure portal, go to Enterprise applications > Application > Provisioning and select Authorize.

    1. Azure Portal redirige al usuario a la dirección URL de autorización (página de inicio de sesión de la aplicación de terceros).Azure portal redirects user to the Authorization URL (sign in page for the third party app).

    2. El administrador proporciona las credenciales a la aplicación de terceros.Admin provides credentials to the third party application.

    3. La aplicación de terceros redirige al usuario de vuelta a Azure Portal y le proporciona el código de concesión.Third party app redirects user back to Azure portal and provides the grant code

    4. Los servicios de aprovisionamiento de Azure AD llama a la dirección URL del token y proporciona el código de concesión.Azure AD provisioning services calls the token URL and provides the grant code. La aplicación de terceros responde con el token de acceso, el token de actualización y la fecha de expiración.The third party application responds with the access token, refresh token, and expiry date

  2. 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.When the provisioning cycle begins, the service checks if the current access token is valid and exchanges it for a new token if needed. 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.The access token is provided in each request made to the app and the validity of the request is checked before each request.

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.While it's not possible to setup OAuth on the non-gallery applications, you can manually generate an access token from your authorization server and input it as the secret token to a non-gallery application. De esta forma, puede comprobar la compatibilidad del servidor de SCIM con el cliente de SCIM de AAD antes de incorporarla a la galería de aplicaciones, que admite la concesión de código de OAuth.This allows you to verify compatibility of your SCIM server with the AAD SCIM client before onboarding to the app gallery, which does support the OAuth code grant.

Tokens de portador OAuth de larga duración: si la aplicación no admite el flujo de concesión de código de autorización de OAuth, también puede generar un token de portador de OAuth de larga duración que un administrador puede usar para configurar la integración del aprovisionamiento.Long-lived OAuth bearer tokens: If your application doesn't support the OAuth authorization code grant flow, instead generate a long lived OAuth bearer token that an administrator can use to setup the provisioning integration. El token debe ser perpetuo o, de lo contrario, el trabajo de aprovisionamiento se pondrá en cuarentena cuando expire el token.The token should be perpetual, or else the provisioning job will be quarantined when the token expires.

Puede solicitar más métodos de autenticación y autorización en UserVoice.For additional authentication and authorization methods, let us know on UserVoice.

Para ayudar a impulsar el reconocimiento y la demanda de nuestra integración conjunta, se recomienda actualizar la documentación existente y ampliar la integración en los canales de marketing.To help drive awareness and demand of our joint integration, we recommend you update your existing documentation and amplify the integration in your marketing channels. A continuación, se muestra un conjunto de actividades de lista de comprobación que se recomienda completar para respaldar el lanzamientoThe below is a set of checklist activities we recommend you complete to support the launch

Pasos siguientesNext steps