Graph API de Azure Active DirectoryAzure Active Directory Graph API

Importante

A partir de febrero de 2019, comenzamos el proceso para dejar de utilizar algunas versiones anteriores de Azure Active Directory Graph API en favor de Microsoft Graph API.As of February 2019, we started the process to deprecate some earlier versions of Azure Active Directory Graph API in favor of the Microsoft Graph API.

Para más información, actualizaciones y plazos de tiempo, consulte Microsoft Graph o Azure AD Graph del centro de desarrollo de Office.For details, updates, and time frames, see Microsoft Graph or the Azure AD Graph in the Office Dev Center.

De ahora en adelante, las aplicaciones deben usar Microsoft Graph API.Moving forward, applications should use the Microsoft Graph API.

Este artículo se aplica a Azure AD Graph API.This article applies to Azure AD Graph API. Para obtener información similar relacionada con Microsoft Graph API, consulte Usar la API de Microsoft Graph.For similar info related to Microsoft Graph API, see Use the Microsoft Graph API.

Graph API de Azure Active Directory proporciona acceso mediante programación a Azure AD a través de los extremos de la API de REST.The Azure Active Directory Graph API provides programmatic access to Azure AD through REST API endpoints. Las aplicaciones pueden usar Graph API de Azure AD para ejecutar operaciones de creación, lectura, actualización y eliminación (CRUD) en objetos y datos de directorio.Applications can use Azure AD Graph API to perform create, read, update, and delete (CRUD) operations on directory data and objects. Por ejemplo, Graph API de Azure AD admite las siguientes operaciones comunes en un objeto de usuario:For example, Azure AD Graph API supports the following common operations for a user object:

  • Crear un usuario nuevo en un directorioCreate a new user in a directory
  • Obtener las propiedades detalladas de un usuario, como sus gruposGet a user’s detailed properties, such as their groups
  • Actualizar las propiedades de un usuario, como su ubicación y número de teléfono, o cambiar su contraseñaUpdate a user’s properties, such as their location and phone number, or change their password
  • Consultar la pertenencia a grupos de un usuario para el acceso basado en rolesCheck a user’s group membership for role-based access
  • Deshabilitar la cuenta de un usuario o eliminarla por completoDisable a user’s account or delete it entirely

Además, puede realizar las mismas operaciones en otros objetos, como grupos y aplicaciones.Additionally, you can perform similar operations on other objects such as groups and applications. Para llamar a Graph API de Azure AD en un directorio, la aplicación debe registrarse con Azure AD.To call Azure AD Graph API on a directory, your application must be registered with Azure AD. La aplicación también se debe conceder acceso a Graph API de Azure AD.Your application must also be granted access to Azure AD Graph API. Este acceso se logra normalmente mediante un flujo de consentimiento de usuario o administrador.This access is normally achieved through a user or admin consent flow.

Para empezar a usar Graph API de Azure Active Directory, consulte la Guía de inicio rápido de Graph API de Azure AD o la documentación interactiva de referencia sobre Graph API de Azure AD.To begin using the Azure Active Directory Graph API, see the Azure AD Graph API quickstart guide, or view the interactive Azure AD Graph API reference documentation.

CaracterísticasFeatures

Graph API de Azure AD ofrece las siguientes características:Azure AD Graph API provides the following features:

  • Puntos de conexión de API REST: Azure AD Graph API es un servicio RESTful que se compone de puntos de conexión a los que se accede con solicitudes HTTP estándar.REST API Endpoints: Azure AD Graph API is a RESTful service comprised of endpoints that are accessed using standard HTTP requests. Graph API de Azure AD admite tipos de contenido XML o notación de objetos JavaScript (JSON) en solicitudes y respuestas.Azure AD Graph API supports XML or Javascript Object Notation (JSON) content types for requests and responses. Para obtener más información, consulte Referencia de la API Graph de REST de Azure AD.For more information, see Azure AD Graph REST API reference.

  • Autenticación con Azure AD: Todas las solicitudes enviadas a Azure AD Graph API se tienen que autenticar anexando un token web JSON (JWT) al encabezado Authorization de la solicitud.Authentication with Azure AD: Every request to Azure AD Graph API must be authenticated by appending a JSON Web Token (JWT) in the Authorization header of the request. Para conseguir este token, es necesario enviar una solicitud al extremo del token de Azure AD y facilitar unas credenciales válidas.This token is acquired by making a request to Azure AD’s token endpoint and providing valid credentials. Puede usar el flujo de credenciales de cliente OAuth 2.0 o el flujo de concesión de código de autorización para conseguir un token con el que llamar a Graph.You can use the OAuth 2.0 client credentials flow or the authorization code grant flow to acquire a token to call the Graph. Para obtener más información, vea OAuth 2.0 en Azure AD.For more information, OAuth 2.0 in Azure AD.

  • Autorización basada en roles (RBAC) : En Azure AD Graph API se usan grupos de seguridad para llevar a cabo la RBAC.Role-Based Authorization (RBAC): Security groups are used to perform RBAC in Azure AD Graph API. Por ejemplo, si quiere saber si un usuario tiene acceso a un recurso determinado, la aplicación puede llamar a la operación Comprobar pertenencia a grupos (transitiva) , que devuelve true o false.For example, if you want to determine whether a user has access to a specific resource, the application can call the Check group membership (transitive) operation, which returns true or false.

  • Consulta diferencial: Una consulta diferencial le permite realizar el seguimiento de los cambios hechos en un directorio entre dos períodos de tiempo, sin tener que hacer consultas frecuentes a Azure AD Graph API.Differential Query: Differential query allows you to track changes in a directory between two time periods without having to make frequent queries to Azure AD Graph API. Este tipo de solicitud solo devolverá los cambios hechos entre la solicitud de consulta diferencial anterior y la solicitud actual.This type of request will return only the changes made between the previous differential query request and the current request. Para más información, vea Consulta diferencial de Graph API de Azure AD.For more information, see Azure AD Graph API differential query.

  • Extensiones de directorio: Puede agregar propiedades personalizadas a los objetos de directorio sin necesidad de un almacén de datos externo.Directory Extensions: You can add custom properties to directory objects without requiring an external data store. Por ejemplo, si su aplicación necesita una propiedad de usuario de Skype para cada usuario, puede registrar la nueva propiedad en el directorio para que esté disponible para su uso en todos los objetos de usuario.For example, if your application requires a Skype ID property for each user, you can register the new property in the directory and it will be available for use on every user object. Para obtener más información, consulte Extensiones de esquema de directorio de Graph API de Azure AD.For more information, see Azure AD Graph API directory schema extensions.

  • Protegido por ámbitos de permiso: Azure AD Graph API expone los ámbitos de permiso que permiten el acceso seguro a los datos de Azure AD mediante OAuth 2.0.Secured by permission scopes: Azure AD Graph API exposes permission scopes that enable secure access to Azure AD data using OAuth 2.0. Admite una variedad de tipos de aplicación cliente, entre ellos:It supports a variety of client app types, including:

    • Interfaces de usuario que reciben acceso delegado a los datos a través de una autorización del usuario con sesión iniciada (delegado).user interfaces that are given delegated access to data via authorization from the signed-in user (delegated)

    • Aplicaciones de servicio o demonio que funcionan en segundo plano sin un usuario que haya iniciado sesión presente y utilicen el control de acceso basado en rol definidos por la aplicación.service/daemon applications that operate in the background without a signed-in user being present and use application-defined role-based access control

      Tanto los permisos delegados y de aplicación representan un privilegio que se expone mediante Graph API de Azure AD, y las aplicaciones cliente pueden solicitarlos a través de las características de permisos de registro de aplicación en Azure Portal.Both delegated and application permissions represent a privilege exposed by the Azure AD Graph API and can be requested by client applications through application registration permissions features in the Azure portal. Los ámbitos de permiso de Graph API de Azure AD proporcionan información sobre lo que está disponible para su uso por la aplicación cliente.Azure AD Graph API permission scopes provides information on what's available for use by your client application.

EscenariosScenarios

Graph API de Azure AD admite muchos escenarios de aplicación.Azure AD Graph API enables many application scenarios. Los siguientes escenarios son los más comunes:The following scenarios are the most common:

  • Aplicación de línea de negocio (un solo inquilino) : En este escenario, un desarrollador empresarial trabaja para una organización que tiene una suscripción a Office 365.Line of Business (Single Tenant) Application: In this scenario, an enterprise developer works for an organization that has an Office 365 subscription. El desarrollador crea una aplicación web que interactúa con Azure AD para realizar tareas tales como la asignación de una licencia a un usuario.The developer is building a web application that interacts with Azure AD to perform tasks such as assigning a license to a user. Esta tarea requiere acceso a Graph API de Azure AD, por eso el desarrollador registra la aplicación de inquilino único en Azure AD y configura los permisos de lectura y escritura para Graph API de Azure AD.This task requires access to the Azure AD Graph API, so the developer registers the single tenant application in Azure AD and configures read and write permissions for Azure AD Graph API. A continuación, la aplicación se configura para que use sus propias credenciales o las del usuario que tenga iniciada la sesión para conseguir un token con el que llamar a Graph API de Azure AD.Then the application is configured to use either its own credentials or those of the currently sign-in user to acquire a token to call the Azure AD Graph API.
  • Aplicación de Software como servicio (multiinquilino) : En este escenario, un fabricante de software independiente (ISV) desarrolla una aplicación web multiinquilino hospedada que ofrece características de administración de usuarios para otras organizaciones que usan Azure AD.Software as a Service Application (Multi-Tenant): In this scenario, an independent software vendor (ISV) is developing a hosted multi-tenant web application that provides user management features for other organizations that use Azure AD. Estas características requieren acceso a objetos de directorio, por lo que la aplicación necesita llamar a Graph API de Azure AD.These features require access to directory objects, so the application needs to call the Azure AD Graph API. El desarrollador registra la aplicación en Azure AD, la configura para requerir permisos de lectura y escritura para Graph API de Azure AD, y habilita el acceso externo para que las demás organizaciones puedan permitir usar la aplicación en su directorio.The developer registers the application in Azure AD, configures it to require read and write permissions for Azure AD Graph API, and then enables external access so that other organizations can consent to use the application in their directory. Cuando se autentica un usuario de otra organización en la aplicación por primera vez, se le muestra un cuadro de diálogo de consentimiento con los permisos que solicita la aplicación.When a user in another organization authenticates to the application for the first time, they are shown a consent dialog with the permissions the application is requesting. La concesión de consentimiento proporciona a la aplicación los permisos solicitados para Graph API de Azure AD en el directorio del usuario.Granting consent will then give the application those requested permissions to Azure AD Graph API in the user’s directory. Para obtener más información acerca del marco de consentimiento, consulte Información general sobre el marco de consentimiento.For more information on the consent framework, see Overview of the consent framework.

Pasos siguientesNext steps

Para empezar a usar Azure Active Directory Graph API, consulte los temas siguientes:To begin using the Azure Active Directory Graph API, see the following topics: