Permisos y consentimiento en la plataforma de identidad de MicrosoftPermissions and consent in the Microsoft identity platform

Las aplicaciones que se integran con la Plataforma de identidad de Microsoft siguen un modelo de autorización que permite a los usuarios y los administradores controlar el modo en que se puede acceder a los datos.Applications that integrate with the Microsoft identity platform follow an authorization model that gives users and administrators control over how data can be accessed. La implementación del modelo de autorización se ha actualizado en la Plataforma de identidad de Microsoft.The implementation of the authorization model has been updated on the Microsoft identity platform. Cambia el modo en que una aplicación debe interactuar con la Plataforma de identidad de Microsoft.It changes how an app must interact with the Microsoft identity platform. En este artículo se tratan los conceptos básicos de este modelo de autorización, incluidos los ámbitos, los permisos y el consentimiento.This article covers the basic concepts of this authorization model, including scopes, permissions, and consent.

Permisos y ámbitosScopes and permissions

La plataforma de identidad de Microsoft implementa el protocolo de autorización OAuth 2.0.The Microsoft identity platform implements the OAuth 2.0 authorization protocol. OAuth 2.0 es un método a través del cual una aplicación de terceros puede acceder a recursos hospedados en Web en nombre de un usuario.OAuth 2.0 is a method through which a third-party app can access web-hosted resources on behalf of a user. Cualquier recurso hospedado en Web que se integre con la Plataforma de identidad de Microsoft tiene un identificador de recursos o un URI de identificador de aplicación.Any web-hosted resource that integrates with the Microsoft identity platform has a resource identifier, or application ID URI.

Estos son algunos ejemplos de recursos hospedados en Web de Microsoft:Here are some examples of Microsoft web-hosted resources:

  • Microsoft Graph: https://graph.microsoft.comMicrosoft Graph: https://graph.microsoft.com
  • Mail API de Microsoft 365: https://outlook.office.comMicrosoft 365 Mail API: https://outlook.office.com
  • https://vault.azure.netAzure Key Vault:Azure Key Vault: https://vault.azure.net

Ocurre lo mismo con cualquier recurso de terceros integrado en la plataforma de identidad de Microsoft.The same is true for any third-party resources that have integrated with the Microsoft identity platform. Cualquiera de estos recursos también puede definir un conjunto de permisos que se puede usar para dividir la funcionalidad de ese recurso en fragmentos menores.Any of these resources also can define a set of permissions that can be used to divide the functionality of that resource into smaller chunks. Por ejemplo, Microsoft Graph tiene permisos definidos para realizar, entre otras, las tareas siguientes:As an example, Microsoft Graph has defined permissions to do the following tasks, among others:

  • Leer el calendario de un usuarioRead a user's calendar
  • Escribir en el calendario de un usuarioWrite to a user's calendar
  • Enviar correo como un usuarioSend mail as a user

Debido a estas definiciones de tipos de permisos, el recurso tiene control específico sobre sus datos y el modo en que la funcionalidad de la API se expone.Because of these types of permission definitions, the resource has fine-grained control over its data and how API functionality is exposed. Una aplicación de terceros puede solicitar estos permisos a los usuarios y administradores, quienes deben aprobar la solicitud para que la aplicación pueda acceder a los datos o actuar en nombre de un usuario.A third-party app can request these permissions from users and administrators, who must approve the request before the app can access data or act on a user's behalf.

Al fragmentar la funcionalidad de un recurso en conjuntos de permisos pequeños, se pueden crear aplicaciones de terceros para solicitar solo los permisos que necesitan para realizar sus tareas.When a resource's functionality is chunked into small permission sets, third-party apps can be built to request only the permissions that they need to perform their function. Los usuarios y administradores pueden saber a qué datos puede acceder la aplicación.Users and administrators can know what data the app can access. Además, pueden estar más seguros de que la aplicación no se comporte con una intención malintencionada.And they can be more confident that the app isn't behaving with malicious intent. Los desarrolladores deben cumplir siempre con el principio del mínimo privilegio y pedir solo los permisos que necesitan para que sus aplicaciones funcionen.Developers should always abide by the principle of least privilege, asking for only the permissions they need for their applications to function.

En OAuth 2.0, estos tipos de conjuntos de permisos se denominan ámbitos.In OAuth 2.0, these types of permission sets are called scopes. A menudo se hace referencia a ellos como permisos.They're also often referred to as permissions. En la Plataforma de identidad de Microsoft, un permiso se representa como un valor de cadena.In the Microsoft identity platform, a permission is represented as a string value. En el ejemplo de Microsoft Graph, el valor de cadena para cada permiso es el siguiente:For the Microsoft Graph example, here's the string value for each permission:

  • Leer el calendario de un usuario mediante Calendars.ReadRead a user's calendar by using Calendars.Read
  • Escribir en el calendario de un usuario mediante Calendars.ReadWriteWrite to a user's calendar by using Calendars.ReadWrite
  • Enviar correo electrónico con un usuario mediante Mail.SendSend mail as a user using by Mail.Send

Una aplicación suele solicitar estos permisos, para lo que especifica los ámbitos en las solicitudes al punto de conexión de la autorización de la Plataforma de identidad de Microsoft.An app most commonly requests these permissions by specifying the scopes in requests to the Microsoft identity platform authorize endpoint. Sin embargo, algunos permisos con privilegios elevados solo se pueden conceder con el consentimiento del administrador.However, some high-privilege permissions can be granted only through administrator consent. Se pueden solicitar o conceder con el punto de conexión de consentimiento del administrador.They can be requested or granted by using the administrator consent endpoint. Siga leyendo para obtener más información.Keep reading to learn more.

Tipos de permisosPermission types

La Plataforma de identidad de Microsoft admite dos tipos de permisos: permisos delegados y permisos de aplicación.The Microsoft identity platform supports two types of permissions: delegated permissions and application permissions.

  • Permisos delegados: se utilizan en aplicaciones que tienen un usuario con la sesión iniciada.Delegated permissions are used by apps that have a signed-in user present. Para estas aplicaciones, el usuario o un administrador dan su consentimiento para los permisos que la aplicación requiere.For these apps, either the user or an administrator consents to the permissions that the app requests. A la aplicación se le delega el permiso para actuar como el usuario que inició sesión al realizar llamadas al recurso de destino.The app is delegated permission to act as the signed-in user when it makes calls to the target resource.

    Quienes no son administradores pueden dar su consentimiento para algunos permisos delegados.Some delegated permissions can be consented to by nonadministrators. Sin embargo, algunos permisos con privilegios elevados requieren el consentimiento de un administrador.But some high-privileged permissions require administrator consent. Para información sobre qué roles de administrador pueden dar su consentimiento para los permisos delegados, vea Permisos de roles de administrador en Azure Active Directory (Azure AD).To learn which administrator roles can consent to delegated permissions, see Administrator role permissions in Azure Active Directory (Azure AD).

  • Los permisos de aplicación los usan las aplicaciones que se ejecutan sin la presencia de un usuario con la sesión iniciada; por ejemplo, las aplicaciones que se ejecutan como demonios o servicios en segundo plano.Application permissions are used by apps that run without a signed-in user present, for example, apps that run as background services or daemons. Solo un administrador puede dar su consentimiento para los permisos de aplicación.Only an administrator can consent to application permissions.

Los permisos efectivos son los que la aplicación tiene al realizar solicitudes al recurso de destino.Effective permissions are the permissions that your app has when it makes requests to the target resource. Es importante comprender la diferencia entre, por un lado, los permisos delegados y los permisos de la aplicación que se conceden a una aplicación y, por otro, los permisos efectivos que se conceden a la aplicación cuando realiza llamadas al recurso de destino.It's important to understand the difference between the delegated permissions and application permissions that your app is granted, and the effective permissions your app is granted when it makes calls to the target resource.

  • En el caso de los permisos delegados, los permisos efectivos de la aplicación son la intersección con menos privilegios de los permisos delegados que se le han concedido a la aplicación (mediante consentimiento) y los privilegios del usuario que tiene iniciada la sesión actualmente.For delegated permissions, the effective permissions of your app are the least-privileged intersection of the delegated permissions the app has been granted (by consent) and the privileges of the currently signed-in user. La aplicación nunca puede tener más privilegios que el usuario que tiene la sesión iniciada.Your app can never have more privileges than the signed-in user.

    Dentro de las organizaciones, los privilegios del usuario que tiene la sesión iniciada pueden determinarse mediante directivas o pertenencia a uno o varios roles de administrador.Within organizations, the privileges of the signed-in user can be determined by policy or by membership in one or more administrator roles. Para información sobre qué roles de administrador pueden consentir los permisos delegados, consulte Permisos de roles de administrador en Azure AD.To learn which administrator roles can consent to delegated permissions, see Administrator role permissions in Azure AD.

    Por ejemplo, suponga que a su aplicación se le ha concedido el permiso delegado User.ReadWrite.All en Microsoft Graph.For example, assume your app has been granted the User.ReadWrite.All delegated permission. Este permiso concede a su aplicación de forma nominal un permiso para leer y actualizar el perfil de cada usuario de una organización.This permission nominally grants your app permission to read and update the profile of every user in an organization. Si el usuario que inició sesión es un administrador global, la aplicación puede actualizar el perfil de cada usuario de la organización.If the signed-in user is a global administrator, your app can update the profile of every user in the organization. Aun así, si el usuario con la sesión iniciada no tiene un rol de administrador, la aplicación puede actualizar solo el perfil del usuario que tiene la sesión iniciada.However, if the signed-in user doesn't have an administrator role, your app can update only the profile of the signed-in user. No puede actualizar los perfiles de otros usuarios de la organización, porque el usuario para el que tiene permiso para actuar en su nombre no tiene tales privilegios.It can't update the profiles of other users in the organization because the user that it has permission to act on behalf of doesn't have those privileges.

  • Para los permisos de aplicación, los permisos efectivos de la aplicación son el nivel completo de privilegios que concede el permiso.For application permissions, the effective permissions of your app are the full level of privileges implied by the permission. Por ejemplo, una aplicación que tiene el permiso de aplicación User.ReadWrite.All puede actualizar el perfil de cada usuario de la organización.For example, an app that has the User.ReadWrite.All application permission can update the profile of every user in the organization.

Ámbitos de OpenID ConnectOpenID Connect scopes

La implementación de la Plataforma de identidad de Microsoft de OpenID Connect tiene unos cuantos ámbitos bien definidos que también se hospedan en Microsoft Graph: openid, email, profile y offline_access.The Microsoft identity platform implementation of OpenID Connect has a few well-defined scopes that are also hosted on Microsoft Graph: openid, email, profile, and offline_access. Los ámbitos de OpenID Connect address y phone no son compatibles.The address and phone OpenID Connect scopes aren't supported.

Si solicita los ámbitos de OpenID Connect y un token, obtendrá un token para llamar al punto de conexión de UserInfo.If you request the OpenID Connect scopes and a token, you'll get a token to call the UserInfo endpoint.

openidopenid

Si una aplicación inicia sesión mediante OpenID Connect, debe solicitar el ámbito openid.If an app signs in by using OpenID Connect, it must request the openid scope. El ámbito openid aparece en la página de consentimiento de la cuenta profesional como el permiso Iniciar sesión en su nombre.The openid scope appears on the work account consent page as the Sign you in permission. En la página de consentimiento de la cuenta personal de Microsoft, aparece como el permiso Ver el perfil y conectarse a las aplicaciones y servicios con la cuenta de Microsoft.On the personal Microsoft account consent page, it appears as the View your profile and connect to apps and services using your Microsoft account permission.

Con este permiso, una aplicación puede recibir un identificador único para el usuario en forma de la notificación sub.By using this permission, an app can receive a unique identifier for the user in the form of the sub claim. El permiso también ofrece acceso de la aplicación al punto de conexión de UserInfo.The permission also gives the app access to the UserInfo endpoint. El ámbito openid puede usarse en el punto de conexión del token de la Plataforma de identidad de Microsoft para adquirir tokens de identificador.The openid scope can be used at the Microsoft identity platform token endpoint to acquire ID tokens. La aplicación puede usar estos tokens para la autenticación.The app can use these tokens for authentication.

emailemail

El ámbito email puede usarse con el ámbito openid y con cualquier otro.The email scope can be used with the openid scope and any other scopes. Proporciona acceso de la aplicación a la dirección de correo electrónico principal del usuario en forma de la notificación email.It gives the app access to the user's primary email address in the form of the email claim.

La notificación email solo se incluye en los tokens si hay una dirección de correo electrónico asociada a la cuenta de usuario, que no siempre es el caso.The email claim is included in a token only if an email address is associated with the user account, which isn't always the case. Si la aplicación usa el ámbito email, la aplicación debe ser capaz de controlar un caso en el que no existe ninguna notificación email en el token.If your app uses the email scope, the app needs to be able to handle a case in which no email claim exists in the token.

perfilprofile

El ámbito profile puede usarse con el ámbito openid y con cualquier otro.The profile scope can be used with the openid scope and any other scope. Proporciona acceso de la aplicación a una cantidad elevada de información sobre el usuario.It gives the app access to a large amount of information about the user. Por ejemplo, el nombre propio del usuario, el apellido, el nombre de usuario preferido o el id. de objeto, entre otros datos.The information it can access includes, but isn't limited to, the user's given name, surname, preferred username, and object ID.

Para ver una lista completa de las notificaciones profile disponibles en el parámetro id_tokens para un usuario específico, vea la referencia id_tokens.For a complete list of the profile claims available in the id_tokens parameter for a specific user, see the id_tokens reference.

offline_accessoffline_access

El ámbito offline_access proporciona acceso de la aplicación a recursos en nombre del usuario durante un periodo de tiempo prolongado.The offline_access scope gives your app access to resources on behalf of the user for an extended time. En la página de consentimiento, este ámbito aparece como el permiso Mantener el acceso a los datos a los que le ha dado acceso.On the consent page, this scope appears as the Maintain access to data you have given it access to permission.

Cuando un usuario aprueba el ámbito offline_access, la aplicación puede recibir tokens de actualización del punto de conexión del token de la Plataforma de identidad de Microsoft.When a user approves the offline_access scope, your app can receive refresh tokens from the Microsoft identity platform token endpoint. Los tokens de actualización tienen una duración larga.Refresh tokens are long-lived. La aplicación puede obtener nuevos tokens de acceso cuando expiren los antiguos.Your app can get new access tokens as older ones expire.

Nota

Este permiso aparece actualmente en todas las páginas de consentimiento, incluso en el caso de los flujos que no proporcionan un token de actualización (como el flujo implícito).This permission currently appears on all consent pages, even for flows that don't provide a refresh token (such as the implicit flow). Esta configuración abarca los escenarios en los que un cliente puede comenzar dentro del flujo implícito y después pasar al flujo de código, donde sí se espera un token de actualización.This setup addresses scenarios where a client can begin within the implicit flow and then move to the code flow where a refresh token is expected.

En la plataforma de identidad de Microsoft (solicitudes realizadas al punto de conexión v2.0), la aplicación debe solicitar explícitamente el ámbito de offline_access para recibir tokens de actualización.On the Microsoft identity platform (requests made to the v2.0 endpoint), your app must explicitly request the offline_access scope, to receive refresh tokens. Por tanto, cuando se canjea un código de autorización del flujo del código de autorización de OAuth 2.0, solo se recibirá un token de acceso del punto de conexión /token.So when you redeem an authorization code in the OAuth 2.0 authorization code flow, you'll receive only an access token from the /token endpoint.

El token de acceso es válido durante un breve período de tiempo.The access token is valid for a short time. Suele expirar al cabo de una hora.It usually expires in one hour. En ese momento, la aplicación tiene que redirigir al usuario de vuelta al punto de conexión /authorize para que obtenga un nuevo código de autorización.At that point, your app needs to redirect the user back to the /authorize endpoint to get a new authorization code. Durante esta redirección y, en función del tipo de aplicación, puede que el usuario tenga que volver a escribir sus credenciales o dar de nuevo el consentimiento a permisos.During this redirect, depending on the type of app, the user might need to enter their credentials again or consent again to permissions.

Para más información sobre cómo obtener y usar tokens de actualización, consulte la referencia del protocolo de la Plataforma de identidad de Microsoft.For more information about how to get and use refresh tokens, see the Microsoft identity platform protocol reference.

En una solicitud de autorización de OpenID Connect o OAuth 2.0, una aplicación puede solicitar los permisos que necesita mediante el parámetro de consulta scope.In an OpenID Connect or OAuth 2.0 authorization request, an app can request the permissions it needs by using the scope query parameter. Por ejemplo, cuando un usuario inicia sesión en una aplicación, la aplicación envía una solicitud como la del ejemplo siguiente.For example, when a user signs in to an app, the app sends a request like the following example. (Se han agregado saltos de línea para mejorar la legibilidad).(Line breaks are added for legibility.)

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=
https%3A%2F%2Fgraph.microsoft.com%2Fcalendars.read%20
https%3A%2F%2Fgraph.microsoft.com%2Fmail.send
&state=12345

El parámetro scope es una lista separada por espacios que incluye los permisos delegados que la aplicación solicita.The scope parameter is a space-separated list of delegated permissions that the app is requesting. Cada permiso se indica anexando el valor del permiso al identificador del recurso (URI del identificador de aplicación).Each permission is indicated by appending the permission value to the resource's identifier (the application ID URI). En la solicitud de ejemplo, la aplicación necesita permiso para leer el calendario del usuario y enviar correo electrónico en nombre del usuario.In the request example, the app needs permission to read the user's calendar and send mail as the user.

Después de que el usuario escriba sus credenciales, la Plataforma de identidad de Microsoft buscará un registro que coincida con el consentimiento del usuario.After the user enters their credentials, the Microsoft identity platform checks for a matching record of user consent. Si el usuario no dio su consentimiento a ninguno de los permisos solicitados en el pasado, y si el administrador no dio su consentimiento a estos permisos en nombre de toda la organización, la Plataforma de identidad de Microsoft solicita al usuario que conceda los permisos solicitados.If the user hasn't consented to any of the requested permissions in the past, and if the administrator hasn't consented to these permissions on behalf of the entire organization, the Microsoft identity platform asks the user to grant the requested permissions.

En este momento, los permisos offline_access ("Mantener el acceso a los datos a los que se le ha dado acceso") y user.read ("Iniciar sesión y leer su perfil") se incluyen automáticamente en el consentimiento inicial para una aplicación.At this time, the offline_access ("Maintain access to data you have given it access to") permission and user.read ("Sign you in and read your profile") permission are automatically included in the initial consent to an application. Estos permisos suelen ser necesarios para que la aplicación funcione correctamente.These permissions are generally required for proper app functionality. El permiso offline_access concede a la aplicación acceso a los tokens de actualización que son críticos para aplicaciones nativas y aplicaciones web.The offline_access permission gives the app access to refresh tokens that are critical for native apps and web apps. El permiso user.read concede acceso a la notificación sub.The user.read permission gives access to the sub claim. Permite al cliente o a la aplicación identificar correctamente al usuario con el tiempo y acceder a información de usuario rudimentaria.It allows the client or app to correctly identify the user over time and access rudimentary user information.

Captura de pantalla de ejemplo que muestra el consentimiento de la cuenta profesional

Cuando el usuario aprueba la solicitud del permiso, el consentimiento se registra.When the user approves the permission request, consent is recorded. No es necesario que el usuario dé su consentimiento de nuevo cuando inicie sesión posteriormente en la aplicación.The user doesn't have to consent again when they later sign in to the application.

Cuando una organización adquiere una licencia o una suscripción de una aplicación, la organización suele desear configurar de forma proactiva la aplicación para que la usen todos sus miembros.When an organization purchases a license or subscription for an application, the organization often wants to proactively set up the application for use by all members of the organization. Como parte de este proceso, el administrador puede conceder consentimiento a la aplicación para que actúe en nombre de cualquier usuario del inquilino.As part of this process, an administrator can grant consent for the application to act on behalf of any user in the tenant. Si el administrador concede el consentimiento del inquilino entero, los usuarios de la organización no verán una página de consentimiento para la aplicación.If the admin grants consent for the entire tenant, the organization's users don't see a consent page for the application.

Para solicitar el consentimiento de los permisos delegados para todos los usuarios de un inquilino, la aplicación puede usar el punto de conexión de consentimiento del administrador.To request consent for delegated permissions for all users in a tenant, your app can use the admin consent endpoint.

Además, las aplicaciones deben usar el punto de conexión de consentimiento del administrador para solicitar los permisos de la aplicación.Additionally, applications must use the admin consent endpoint to request application permissions.

Permisos restringidos por el administradorAdmin-restricted permissions

Algunos permisos de privilegios elevados de los recursos de Microsoft se pueden establecer en restringido para los administradores.Some high-privilege permissions in Microsoft resources can be set to admin-restricted. Estos son algunos ejemplos de estos tipos de permisos:Here are some examples of these kinds of permissions:

  • Leer los perfiles completos de todos los usuarios con User.Read.AllRead all user's full profiles by using User.Read.All
  • Escribir datos en el directorio de una organización mediante Directory.ReadWrite.AllWrite data to an organization's directory by using Directory.ReadWrite.All
  • Leer todos los grupos de seguridad del directorio de una organización con: Groups.Read.AllRead all groups in an organization's directory by using Groups.Read.All

Aunque un usuario consumidor podría conceder acceso de la aplicación a este tipo de datos, los usuarios de la organización no pueden conceder acceso al mismo conjunto de datos confidenciales de la empresa.Although a consumer user might grant an application access to this kind of data, organizational users can't grant access to the same set of sensitive company data. Si la aplicación solicita acceso a uno de estos permisos desde un usuario de la organización, el usuario recibe un mensaje de error que indica que no está autorizado para dar el consentimiento a los permisos de la aplicación.If your application requests access to one of these permissions from an organizational user, the user receives an error message that says they're not authorized to consent to your app's permissions.

Si la aplicación requiere ámbitos para permisos restringidos por el administrador, el administrador de una organización debe dar su consentimiento a esos ámbitos en nombre de los usuarios de la organización.If your app requires scopes for admin-restricted permissions, an organization's administrator must consent to those scopes on behalf of the organization's users. Para evitar que se muestren a los usuarios solicitudes de consentimiento de los permisos que no pueden conceder, la aplicación puede usar el punto de conexión de consentimiento del administrador.To avoid displaying prompts to users that request consent for permissions they can't grant, your app can use the admin consent endpoint. El punto de conexión de consentimiento del administrador se aborda en la sección siguiente.The admin consent endpoint is covered in the next section.

Si la aplicación solicita permisos delegados con privilegios elevados y un administrador los concede a través del punto de conexión de consentimiento del administrador, el consentimiento se concede a todos los usuarios del inquilino.If the application requests high-privilege delegated permissions and an administrator grants these permissions through the admin consent endpoint, consent is granted for all users in the tenant.

Si la aplicación solicita permisos de aplicación y un administrador los concede a través del punto de conexión de consentimiento del administrador, esta concesión no se realiza en nombre de un usuario específico.If the application requests application permissions and an administrator grants these permissions through the admin consent endpoint, this grant isn't done on behalf of any specific user. En su lugar, a la aplicación cliente se le conceden los permisos directamente.Instead, the client application is granted permissions directly. Estos tipos de permisos solo se usan en servicios de demonio y otras aplicaciones no interactivas que se ejecutan en segundo plano.These types of permissions are used only by daemon services and other noninteractive applications that run in the background.

Después de usar el punto de conexión de consentimiento del administrador para conceder el consentimiento del administrador, ya ha terminado.After you use the admin consent endpoint to grant admin consent, you're finished. No es necesarios que los usuarios realicen ninguna acción adicional.Users don't need to take any further action. Una vez concedido el consentimiento del administrador, los usuarios pueden obtener un token de acceso mediante un flujo de autenticación típico.After admin consent is granted, users can get an access token through a typical auth flow. El token de acceso resultante tiene los permisos consentidos.The resulting access token has the consented permissions.

Cuando un administrador global usa la aplicación y se dirige al punto de conexión de autorización, la Plataforma de identidad de Microsoft detecta el rol de usuario.When a Global Administrator uses your application and is directed to the authorize endpoint, the Microsoft identity platform detects the user's role. Pregunta si el administrador global desea dar su consentimiento en nombre de todo el inquilino para los permisos solicitados.It asks if the Global Administrator wants to consent on behalf of the entire tenant for the permissions you requested. En su lugar, podría usar un punto de conexión de consentimiento del administrador dedicado para solicitar proactivamente a un administrador que conceda permiso en nombre de todo el inquilino.You could instead use a dedicated admin consent endpoint to proactively request an administrator to grant permission on behalf of the entire tenant. Este punto de conexión también es necesario para solicitar permisos de aplicación.This endpoint is also necessary for requesting application permissions. No se pueden solicitar permisos de aplicación mediante el punto de conexión de autorización.Application permissions can't be requested by using the authorize endpoint.

Si sigue estos pasos, la aplicación puede recopilar los permisos para todos los usuarios de un inquilino, incluso en los ámbitos restringidos para los administradores.If you follow these steps, your app can request permissions for all users in a tenant, including admin-restricted scopes. Esta operación tiene privilegios elevados.This operation is high privilege. Use la operación solo si es necesario para su escenario.Use the operation only if necessary for your scenario.

Para ver un ejemplo de código que implementa lo pasos, consulte el ejemplo de ámbitos restringidos para los administradores en GitHub.To see a code sample that implements the steps, see the admin-restricted scopes sample in GitHub.

Solicitud de los permisos en el portal de registro de aplicacionesRequest the permissions in the app registration portal

En el portal de registro de aplicaciones, las aplicaciones pueden enumerar los permisos que necesitan, incluidos los permisos delegados y los permisos de aplicación.In the app registration portal, applications can list the permissions they require, including both delegated permissions and application permissions. Esta configuración permite el uso del ámbito /.default y la opción Conceder consentimiento de administrador de Azure Portal.This setup allows the use of the /.default scope and the Azure portal's Grant admin consent option.

En general, los permisos se deben definir estáticamente para una aplicación determinada.In general, the permissions should be statically defined for a given application. Deben formar un superconjunto de los permisos que la aplicación solicitará de manera dinámica o incremental.They should be a superset of the permissions that the app will request dynamically or incrementally.

Nota

Los permisos de aplicación solo se pueden solicitar con /.default.Application permissions can be requested only through the use of /.default. Por tanto, si la aplicación necesita permisos de aplicación, asegúrese de que se muestran en el portal de registro de aplicaciones.So if your app needs application permissions, make sure they're listed in the app registration portal.

Para configurar la lista de permisos solicitados estáticamente para una aplicación:To configure the list of statically requested permissions for an application:

  1. Vaya a su aplicación en la experiencia de inicio rápido Azure Portal: Registros de aplicaciones.Go to your application in the Azure portal - App registrations quickstart experience.
  2. Seleccione o cree una aplicación si aún no lo ha hecho.Select an application, or create an app if you haven't already.
  3. En la página Información general de la aplicación, en Administrar, seleccione Permisos de API > Agregar un permiso.On the application's Overview page, under Manage, select API Permissions > Add a permission.
  4. Seleccione Microsoft Graph en la lista de API disponibles.Select Microsoft Graph from the list of available APIs. A continuación, agregue los permisos que requiere la aplicación.Then add the permissions that your app requires.
  5. Seleccione Agregar permisos.Select Add Permissions.

Normalmente, cuando se compila una aplicación que usa el punto de conexión de consentimiento del administrador, la aplicación necesita una página o una vista en la que el administrador pueda aprobar los permisos de la aplicación.Typically, when you build an application that uses the admin consent endpoint, the app needs a page or view in which the admin can approve the app's permissions. Esta página puede ser:This page can be:

  • parte del flujo de registro de la aplicación,Part of the app's sign-up flow.
  • parte de la configuración de la aplicación oPart of the app's settings.
  • un flujo de "conexión" dedicado.A dedicated "connect" flow.

En muchos casos, tiene sentido que la aplicación muestre esta vista de "conexión" solo después de que un usuario haya iniciado sesión con una cuenta de Microsoft profesional o educativa.In many cases, it makes sense for the app to show this "connect" view only after a user has signed in with a work Microsoft account or school Microsoft account.

Cuando inicia la sesión del usuario en la aplicación, puede identificar a la organización a la que pertenece el administrador antes de pedirle que apruebe los permisos necesarios.When you sign the user in to your app, you can identify the organization to which the admin belongs before you ask them to approve the necessary permissions. Aunque este paso no es estrictamente necesario, puede ayudarle a crear una experiencia más intuitiva para los usuarios de la organización.Although this step isn't strictly necessary, it can help you create a more intuitive experience for your organizational users.

Para iniciar la sesión del usuario, siga los tutoriales del protocolo de la Plataforma de identidad de Microsoft.To sign the user in, follow the Microsoft identity platform protocol tutorials.

Solicitud de los permisos de un administrador de directoriosRequest the permissions from a directory admin

Cuando esté listo para solicitar permisos al administrador de la organización, puede redirigir al usuario al punto de conexión de consentimiento del administrador de la Plataforma de identidad de Microsoft.When you're ready to request permissions from your organization's admin, you can redirect the user to the Microsoft identity platform admin consent endpoint.

// Line breaks are for legibility only.
GET https://login.microsoftonline.com/{tenant}/v2.0/adminconsent?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&state=12345
&redirect_uri=http://localhost/myapp/permissions
&scope=
https://graph.microsoft.com/calendars.read
https://graph.microsoft.com/mail.send
ParámetroParameter CondiciónCondition DescripciónDescription
tenant ObligatorioRequired El inquilino de directorio al que quiere solicitar permiso.The directory tenant that you want to request permission from. Se puede proporcionar en un formato de nombre descriptivo o GUID.It can be provided in a GUID or friendly name format. También se puede hacer referencia a él de forma genérica con las organizaciones, como se observa en el ejemplo.Or it can be generically referenced with organizations, as seen in the example. No use "común", porque las cuentas personales no pueden proporcionar consentimiento del administrador, salvo en el contexto de un inquilino.Don't use "common," because personal accounts can't provide admin consent except in the context of a tenant. Para garantizar la mejor compatibilidad con las cuentas personales que administran los inquilinos, use el identificador de inquilino cuando sea posible.To ensure the best compatibility with personal accounts that manage tenants, use the tenant ID when possible.
client_id ObligatorioRequired El identificador de aplicación (cliente) que la experiencia Azure Portal: Registros de aplicaciones asignó a la aplicación.The application (client) ID that the Azure portal – App registrations experience assigned to your app.
redirect_uri ObligatorioRequired El URI de redireccionamiento adonde desea que se envíe la respuesta para que la controle la aplicación.The redirect URI where you want the response to be sent for your app to handle. Debe coincidir exactamente con uno de los identificadores URI de redirección que registró el Portal de registro de aplicaciones.It must exactly match one of the redirect URIs that you registered in the app registration portal.
state RecomendadoRecommended Un valor incluido en la solicitud que se devolverá también en la respuesta del token.A value included in the request that will also be returned in the token response. Puede ser una cadena de cualquier contenido que desee.It can be a string of any content you want. Use el estado para codificar información sobre el estado del usuario en la aplicación antes de que se produzca la solicitud de autenticación, por ejemplo, la página o vista en la que estaba.Use the state to encode information about the user's state in the app before the authentication request occurred, such as the page or view they were on.
scope ObligatorioRequired Define el conjunto de permisos que la aplicación solicita.Defines the set of permissions being requested by the application. Los ámbitos pueden ser estáticos (mediante /.default) o dinámicos.Scopes can be either static (using /.default) or dynamic. Este conjunto puede incluir los ámbitos de OpenID Connect (openid, profile o email).This set can include the OpenID Connect scopes (openid, profile, email). Si necesita permisos de aplicación, debe usar /.default para solicitar la lista de permisos configurada de forma estática.If you need application permissions, you must use /.default to request the statically configured list of permissions.

En este momento, Azure AD requiere que un administrador de inquilinos inicie sesión para completar la solicitud.At this point, Azure AD requires a tenant administrator to sign in to complete the request. Se solicita al administrador que apruebe todos los permisos solicitados en el parámetro scope.The administrator is asked to approve all the permissions that you requested in the scope parameter. Si ha usado un valor estático (/.default), funcionará como el punto de conexión de consentimiento del administración de la versión v1.0 y el consentimiento de solicitud para todos los ámbitos que se encuentran en los permisos necesarios para la aplicación.If you used a static (/.default) value, it will function like the v1.0 admin consent endpoint and request consent for all scopes found in the required permissions for the app.

Respuesta correctaSuccessful response

Si el administrador aprueba los permisos para la aplicación, la respuesta correcta tendrá un aspecto similar al siguiente:If the admin approves the permissions for your app, the successful response looks like this:

GET http://localhost/myapp/permissions?tenant=a8990e1f-ff32-408a-9f8e-78d3b9139b95&state=state=12345&admin_consent=True
ParámetroParameter DescripciónDescription
tenant El inquilino del directorio que concedió los permisos solicitados, en formato GUID.The directory tenant that granted your application the permissions it requested, in GUID format.
state Un valor incluido en la solicitud que también se devolverá en la respuesta del token.A value included in the request that also will be returned in the token response. Puede ser una cadena de cualquier contenido que desee.It can be a string of any content you want. El estado se usa para codificar información sobre el estado del usuario en la aplicación antes de que se haya producido la solicitud de autenticación, por ejemplo, la página o vista en la que estaban.The state is used to encode information about the user's state in the app before the authentication request occurred, such as the page or view they were on.
admin_consent Se establecerá en True.Will be set to True.

Respuesta de errorError response

Si el administrador no aprueba los permisos de la aplicación, la respuesta de error tendrá el aspecto siguiente:If the admin doesn't approve the permissions for your app, the failed response looks like this:

GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request
ParámetroParameter DescripciónDescription
error Una cadena de código de error que puede usarse para clasificar los tipos de errores que se producen.An error code string that can be used to classify types of errors that occur. También se puede usar para reaccionar ante errores.It can also be used to react to errors.
error_description Un mensaje de error específico que puede ayudar a un desarrollador a identificar la causa de un error.A specific error message that can help a developer identify the root cause of an error.

Cuando haya recibido una respuesta correcta del punto de conexión de consentimiento del administrador, la aplicación habrá obtenido los permisos solicitados.After you've received a successful response from the admin consent endpoint, your app has gained the permissions it requested. Ahora puede solicitar un token para el recurso que desee.Next, you can request a token for the resource you want.

Uso de permisosUsing permissions

Después de que el usuario da su consentimiento para los permisos de la aplicación, esta puede obtener tokens de acceso que representan los permisos de la aplicación para acceder a un recurso de alguna manera.After the user consents to permissions for your app, your app can acquire access tokens that represent the app's permission to access a resource in some capacity. Un token de acceso solo se puede usar para un único recurso.An access token can be used only for a single resource. Sin embargo, dentro del token de acceso están todos los permisos codificados que se han concedido a la aplicación para ese recurso.But encoded inside the access token is every permission that your app has been granted for that resource. Para adquirir un token de acceso, la aplicación puede realizar una solicitud al punto de conexión del token de la Plataforma de identidad de Microsoft, como esta:To acquire an access token, your app can make a request to the Microsoft identity platform token endpoint, like this:

POST common/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/json

{
    "grant_type": "authorization_code",
    "client_id": "6731de76-14a6-49ae-97bc-6eba6914391e",
    "scope": "https://outlook.office.com/mail.read https://outlook.office.com/mail.send",
    "code": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq..."
    "redirect_uri": "https://localhost/myapp",
    "client_secret": "zc53fwe80980293klaj9823"  // NOTE: Only required for web apps
}

Puede usar el token de acceso resultante en las solicitudes HTTP al recurso.You can use the resulting access token in HTTP requests to the resource. Dicho token indica al recurso de forma confiable que la aplicación tiene el permiso apropiado para realizar una tarea específica.It reliably indicates to the resource that your app has the proper permission to do a specific task.

Para más información sobre el protocolo OAuth 2.0 y cómo obtener tokens de acceso, consulte la referencia del protocolo del punto de conexión de la Plataforma de identidad de Microsoft.For more information about the OAuth 2.0 protocol and how to get access tokens, see the Microsoft identity platform endpoint protocol reference.

Ámbito /.defaultThe /.default scope

Puede usar el ámbito /.default para ayudar a migrar las aplicaciones del punto de conexión v1.0 al punto de conexión de la Plataforma de identidad de Microsoft.You can use the /.default scope to help migrate your apps from the v1.0 endpoint to the Microsoft identity platform endpoint. El ámbito /.default está integrado en cada aplicación que hace referencia a la lista estática de los permisos configurados en el registro de la aplicación.The /.default scope is built in for every application that refers to the static list of permissions configured on the application registration.

Un valor scope de https://graph.microsoft.com/.default tiene la misma funcionalidad que resource=https://graph.microsoft.com en el punto de conexión v1.0.A scope value of https://graph.microsoft.com/.default is functionally the same as resource=https://graph.microsoft.com on the v1.0 endpoint. Al especificar el ámbito https://graph.microsoft.com/.default en su solicitud, la aplicación solicita un token de acceso que incluye los ámbitos para cada permiso de Microsoft Graph que ha seleccionado para la aplicación en el portal de registro de aplicaciones.By specifying the https://graph.microsoft.com/.default scope in its request, your application is requesting an access token that includes scopes for every Microsoft Graph permission you've selected for the app in the app registration portal. El ámbito se construye mediante el URI del recurso y /.default.The scope is constructed by using the resource URI and /.default. Por tanto, si el URI del recurso es https://contosoApp.com, el ámbito solicitado es https://contosoApp.com/.default.So if the resource URI is https://contosoApp.com, the scope requested is https://contosoApp.com/.default. En los casos en los que debe incluir una segunda barra diagonal para solicitar correctamente el token, vea la sección sobre barras diagonales finales.For cases where you must include a second slash to correctly request the token, see the section about trailing slashes.

El ámbito /.default se puede usar en cualquier flujo de OAuth 2.0.The /.default scope can be used in any OAuth 2.0 flow. Pero es necesario en el flujo con derechos delegados y en el flujo de credenciales de cliente.But it's necessary in the On-Behalf-Of flow and client credentials flow. También es necesario cuando se usa el punto de conexión de consentimiento del administrador v2 para solicitar los permisos de la aplicación.You also need it when you use the v2 admin consent endpoint to request application permissions.

Los clientes no pueden combinar el consentimiento estático (/.default) y dinámico en una única solicitud.Clients can't combine static (/.default) consent and dynamic consent in a single request. Por lo tanto, scope=https://graph.microsoft.com/.default+mail.read genera un error porque combina tipos de ámbitos.So scope=https://graph.microsoft.com/.default+mail.read results in an error because it combines scope types.

El ámbito /.default también desencadena el comportamiento del punto de conexión v1.0 para prompt=consent.The /.default scope triggers the v1.0 endpoint behavior for prompt=consent as well. Solicita el consentimiento para todos los permisos que la aplicación registró, con independencia del recurso.It requests consent for all permissions that the application registered, regardless of the resource. Si se incluye como parte de la solicitud, el ámbito /.default devuelve un token que contiene los ámbitos para el recurso solicitado.If it's included as part of the request, the /.default scope returns a token that contains the scopes for the resource requested.

La funcionalidad del ámbito /.default es idéntica al comportamiento del punto de conexión v1.0 basado en resource.The /.default scope is functionally identical to the behavior of the resource-centric v1.0 endpoint. También aporta el comportamiento de consentimiento del punto de conexión v1.0.It carries the consent behavior of the v1.0 endpoint as well. Esto quiere decir que /.default solo desencadena una petición de consentimiento si el usuario no ha concedido ningún permiso entre el cliente y el recurso.That is, /.default triggers a consent prompt only if the user has granted no permission between the client and the resource.

Si existe este consentimiento, el token devuelto contiene todos los ámbitos que el usuario ha concedido para ese recurso.If any such consent exists, the returned token contains all scopes the user granted for that resource. Sin embargo, si no se ha concedido ningún permiso o si se ha proporcionado el parámetro prompt=consent, se muestra una petición de consentimiento para todos los ámbitos que la aplicación cliente registró.However, if no permission has been granted or if the prompt=consent parameter has been provided, a consent prompt is shown for all scopes that the client application registered.

Ejemplo 1: El usuario o administrador de inquilinos han concedido permisosExample 1: The user, or tenant admin, has granted permissions

En este ejemplo, el usuario o un administrador de inquilino ha concedido al cliente los permisos de Microsoft Graph mail.read y user.read.In this example, the user or a tenant administrator has granted the mail.read and user.read Microsoft Graph permissions to the client.

Si el cliente realiza una solicitud a scope=https://graph.microsoft.com/.default, no se muestra ninguna petición de consentimiento, independientemente del contenido de los permisos registrados por las aplicaciones cliente para Microsoft Graph.If the client requests scope=https://graph.microsoft.com/.default, no consent prompt is shown, regardless of the contents of the client application's registered permissions for Microsoft Graph. El token devuelto contiene los ámbitos mail.read y user.read.The returned token contains the scopes mail.read and user.read.

Ejemplo 2: El usuario no ha concedido permisos entre el cliente y el recursoExample 2: The user hasn't granted permissions between the client and the resource

En este ejemplo, el usuario no ha dado su consentimiento entre el cliente y Microsoft Graph.In this example, the user hasn't granted consent between the client and Microsoft Graph. El cliente se ha registrado para los permisos user.read y contacts.read.The client has registered for the permissions user.read and contacts.read. También se ha registrado para el ámbito https://vault.azure.net/user_impersonation de Azure Key Vault.It has also registered for the Azure Key Vault scope https://vault.azure.net/user_impersonation.

Cuando el cliente solicita un token para scope=https://graph.microsoft.com/.default, el usuario ve una página de consentimiento para los ámbitos user.read y contacts.read, y los ámbitos user_impersonation de Key Vault.When the client requests a token for scope=https://graph.microsoft.com/.default, the user sees a consent page for the user.read scope, the contacts.read scope, and the Key Vault user_impersonation scopes. El token devuelto solo contiene los ámbitos user.read y contacts.read.The returned token contains only the user.read and contacts.read scopes. Solo se puede usar en Microsoft Graph.It can be used only against Microsoft Graph.

Ejemplo 3: El usuario ha dado su consentimiento y el cliente solicita más ámbitosExample 3: The user has consented, and the client requests more scopes

En este ejemplo, el usuario ya ha dado su consentimiento para mail.read al cliente.In this example, the user has already consented to mail.read for the client. El cliente se ha registrado para el ámbito contacts.read.The client has registered for the contacts.read scope.

Cuando el cliente solicita un token con scope=https://graph.microsoft.com/.default y solicita el consentimiento mediante prompt=consent, el usuario ve una página de consentimiento únicamente con todos los permisos registrados por la aplicación.When the client requests a token by using scope=https://graph.microsoft.com/.default and requests consent through prompt=consent, the user sees a consent page for all (and only) the permissions that the application registered. El ámbito contacts.read está en la página de consentimiento, pero mail.read no.The contacts.read scope is on the consent page but mail.read isn't. El token devuelto es para Microsoft Graph.The token returned is for Microsoft Graph. Contiene mail.read y contacts.read.It contains mail.read and contacts.read.

Uso del ámbito /.default con el clienteUsing the /.default scope with the client

En algunos casos, un cliente puede solicitar su propio ámbito /.default.In some cases, a client can request its own /.default scope. En el siguiente ejemplo se muestra este escenario.The following example demonstrates this scenario.

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
response_type=token            //Code or a hybrid flow is also possible here
&client_id=9ada6f8a-6d83-41bc-b169-a306c21527a5
&scope=9ada6f8a-6d83-41bc-b169-a306c21527a5/.default
&redirect_uri=https%3A%2F%2Flocalhost
&state=1234

Este ejemplo de código genera una página de consentimiento para todos los permisos registrados si las descripciones anteriores de consentimiento y /.default se aplican al escenario.This code example produces a consent page for all registered permissions if the preceding descriptions of consent and /.default apply to the scenario. A continuación, el código devuelve un id_token, en lugar de un token de acceso.Then the code returns an id_token, rather than an access token.

Este comportamiento se ajusta a algunos clientes heredados que se mueven de la Biblioteca de autenticación de Azure AD (ADAL) a la biblioteca de autenticación de Microsoft (MSAL).This behavior accommodates some legacy clients that are moving from Azure AD Authentication Library (ADAL) to the Microsoft Authentication Library (MSAL). Los nuevos clientes que tienen como destino la Plataforma de identidad de Microsoft no deben utilizar esta configuración.This setup shouldn't be used by new clients that target the Microsoft identity platform.

Flujo de concesión de credenciales de cliente y ./defaultClient credentials grant flow and /.default

/.default también se utiliza para solicitar permisos de aplicación o roles en una aplicación no interactiva, como una aplicación de demonio que usa el flujo de concesión de credenciales de cliente para llamar a una API web.Another use of /.default is to request application permissions (or roles) in a noninteractive application like a daemon app that uses the client credentials grant flow to call a web API.

Para crear permisos de aplicación (roles) para una API web, vea Incorporación de roles de aplicación a una aplicación y su recepción en el token.To create application permissions (roles) for a web API, see Add app roles in your application.

Las solicitudes de credenciales de cliente en la aplicación cliente deben incluir scope={resource}/.default.Client credentials requests in your client app must include scope={resource}/.default. Aquí, {resource} es la API web a la que la aplicación tiene previsto llamar.Here, {resource} is the web API that your app intends to call. No se admite la emisión de una solicitud de credenciales de cliente con permisos de aplicación individuales (roles).Issuing a client credentials request by using individual application permissions (roles) is not supported. En el token de acceso devuelto se incluyen todos los permisos de aplicación (roles) que se han concedido para esa API web.All the application permissions (roles) that have been granted for that web API are included in the returned access token.

Para conceder acceso a los permisos de aplicación que defina, incluida la concesión de consentimiento de administrador para la aplicación, vea Configuración de una aplicación cliente para acceder a las API web.To grant access to the application permissions you define, including granting admin consent for the application, see Configure a client application to access a web API.

Barra diagonal final y /.defaultTrailing slash and /.default

Algunos identificadores URI de recursos tienen una barra diagonal final, por ejemplo, https://contoso.com/ en lugar de https://contoso.com.Some resource URIs have a trailing forward slash, for example, https://contoso.com/ as opposed to https://contoso.com. La barra diagonal final puede producir problemas con la validación de tokens.The trailing slash can cause problems with token validation. Los problemas se producen principalmente cuando se solicita un token para Azure Resource Manager (https://management.azure.com/).Problems occur primarily when a token is requested for Azure Resource Manager (https://management.azure.com/). En este caso, una barra diagonal final en el identificador URI del recurso significa que la barra diagonal debe estar presente cuando se solicita el token.In this case, a trailing slash on the resource URI means the slash must be present when the token is requested. Por lo tanto, cuando se solicita un token para https://management.azure.com/ y se usa /.default, debe solicitar https://management.azure.com//.default (tenga en cuenta la barra diagonal doble).So when you request a token for https://management.azure.com/ and use /.default, you must request https://management.azure.com//.default (notice the double slash!). En general, si verifica que se está emitiendo el token y la API que debe aceptarlo lo está rechazando, considere la posibilidad de agregar una segunda barra diagonal y vuelva a intentarlo.In general, if you verify that the token is being issued, and if the token is being rejected by the API that should accept it, consider adding a second forward slash and trying again.

Para aplicar los pasos de solución de problemas, vea Error inesperado al otorgar consentimiento a una aplicación.For troubleshooting steps, see Unexpected error when performing consent to an application.

Pasos siguientesNext steps