Compartir a través de

Ámbitos y permisos en la plataforma de identidad de Microsoft

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. 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.

En este artículo, obtendrá información sobre ámbitos y permisos en la plataforma de identidad.

En la siguiente lista se muestran algunos ejemplos de recursos de Microsoft hospedados en la Web:

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

Lo mismo sucede con los recursos de terceros que se integran con la plataforma de identidad de Microsoft. Cualquiera de estos recursos puede definir también un conjunto de permisos para dividir la funcionalidad de ese recurso en fragmentos más pequeños. As an example, Microsoft Graph defines permissions to do the following tasks, among others:

  • Leer el calendario de un usuario
  • Escribir en el calendario de un usuario
  • Enviar correo como un usuario

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. 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.

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. Los usuarios y administradores pueden saber a qué datos puede acceder la aplicación. Además, pueden estar más seguros de que la aplicación no se comporte con una intención malintencionada. Los desarrolladores deben cumplir siempre con el principio del mínimo privilegio y pedir solo los permisos que necesitan para que sus aplicaciones funcionen.

In OAuth 2.0, these types of permission sets are called scopes. They're also often referred to as permissions. En la Plataforma de identidad de Microsoft, un permiso se representa como un valor de cadena. Una aplicación solicita los permisos que necesita al especificar el permiso en el parámetro de consulta scope. La plataforma de identidad admite varios ámbitos de OpenID Connect bien definidos, y permisos basados en recursos (cada permiso se indica al anexar el valor de permiso al identificador del recurso o al URI del identificador de aplicación). Por ejemplo, la cadena de permiso https://graph.microsoft.com/Calendars.Read se usa para solicitar permiso para leer los calendarios de los usuarios en Microsoft Graph.

Admin-restricted permissions

Los permisos de la Plataforma de identidad de Microsoft se pueden establecer en restringidos por el administrador. Por ejemplo, muchos permisos de Microsoft Graph con privilegios más elevados requieren aprobación de administrador. Si la aplicación requiere 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. En la sección siguiente se proporcionan ejemplos de estos tipos de permisos:

  • User.Read.All: leer todos los perfiles completos de usuario
  • Directory.ReadWrite.All: escribir datos en el directorio de la organización
  • Groups.Read.All: leer todos los grupos de seguridad del directorio de una organización

Note

En las solicitudes a los puntos de conexión de autorización, token o consentimiento para la plataforma de identidad de Microsoft, si se omite el identificador de recursos en el parámetro de ámbito, se supone que el recurso es Microsoft Graph. Por ejemplo, scope=User.Read es equivalente a https://graph.microsoft.com/User.Read.

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. 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.

Si la aplicación solicita permisos de aplicación y un administrador los concede, esta concesión no se realiza en nombre de un usuario específico. Instead, the client application is granted permissions directly. Estos tipos de permisos solo deben usarse en servicios de demonio y otras aplicaciones no interactivas que se ejecutan en segundo plano. Para obtener más información sobre el escenario de acceso directo, consulte Escenarios de acceso en la Plataforma de identidad de Microsoft.

Para obtener una guía paso a paso sobre cómo exponer ámbitos en una API web, consulte Configuración de una aplicación para exponer una API web.

Ámbitos de OpenID Connect

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. Los ámbitos de OpenID Connect address y phone no son compatibles. Estos ámbitos a veces son opcionales y se consideran para el enriquecimiento de tokens de identificador. Estos ámbitos no siempre aparecerán en líneas independientes en una solicitud de consentimiento a un usuario.

If you request the OpenID Connect scopes and a token, you get a token to call the UserInfo endpoint.

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 permiso Iniciar sesión.

Una aplicación utiliza este permiso para recibir un identificador único para el usuario en forma de la declaración sub. El permiso también ofrece acceso de la aplicación al punto de conexión de UserInfo. El ámbito de openid se puede usar en el punto de conexión del token de la plataforma de identidad de Microsoft para adquirir tokens de identificador. La aplicación puede usar estos tokens para la autenticación.

El ámbito email

El ámbito email puede usarse con el ámbito openid y con cualquier otro. Proporciona acceso de la aplicación a la dirección de correo electrónico principal del usuario en forma de la notificación email.

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. 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.

El ámbito profile

El ámbito profile puede usarse con el ámbito openid y con cualquier otro. Proporciona acceso de la aplicación a una cantidad elevada de información sobre el usuario. Por ejemplo, el nombre propio del usuario, el apellido, el nombre de usuario preferido o el id. de objeto, entre otros datos.

Para ver una lista completa de las notificaciones profile disponibles en el parámetro id_tokens para un usuario específico, vea la id_tokens referencia.

El ámbito offline_access

El offline_access ámbito proporciona acceso de la aplicación a recursos en nombre del usuario durante un periodo de tiempo prolongado. En la página de consentimiento, este ámbito aparece como la Mantener acceso a los datos que le ha concedido acceso a permiso.

Si se concede algún permiso delegado, offline_access se concede implícitamente. Puede suponer que la aplicación tiene offline_access si se conceden permisos delegados. Los tokens de actualización tienen una duración larga. La aplicación puede obtener nuevos tokens de acceso cuando expiren los antiguos.

Note

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.

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. Por tanto, cuando se canjea un código de autorización del flujo del código de autorización de OAuth 2.0, recibirá un token de acceso del punto de conexión /token.

El token de acceso es válido durante aproximadamente una hora. En ese momento, la aplicación tiene que redirigir al usuario de vuelta al punto de conexión /authorize para solicitar un nuevo código de autorización. Durante este redireccionamiento y en función del tipo de aplicación, es posible que el usuario tenga que volver a escribir sus credenciales o dar de nuevo el consentimiento a permisos.

El token de actualización tiene una expiración más larga que el token de acceso y normalmente es válido durante 90 días. 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.

La inclusión del token de actualización en la respuesta puede depender de varios factores, incluida la configuración específica de la aplicación y los ámbitos solicitados durante el proceso de autorización. Si espera recibir un token de actualización en la respuesta, pero no puede hacerlo, tenga en cuenta los siguientes factores:

  • Scope requirements: Ensure that you're requesting the offline_access scopes along with any other necessary scopes.
  • Tipo de concesión de autorización: El token de actualización se proporciona al usar el tipo de concesión de código de autorización. Si el flujo difiere, la respuesta puede verse afectada.
  • Client configuration: Check your application's settings in the identity platform. Algunas configuraciones pueden restringir la emisión de refresh_tokens.

El ámbito .default

El ámbito .default se usa para hacer referencia genéricamente a un servicio de recursos (API) en una solicitud, sin identificar permisos específicos. Si el consentimiento es necesario, el uso de señales .default que indican que se debe solicitar consentimiento para todos los permisos necesarios enumerados en el registro de la aplicación (para todas las API de la lista).

El valor del parámetro de ámbito se construye mediante el URI de identificador del recurso y .default, separados por una barra diagonal (/). Por ejemplo, si el URI de identificador del recurso es https://contoso.com, el ámbito de la solicitud es https://contoso.com/.default. Para los casos en los que debe incluir una segunda barra diagonal para solicitar correctamente el token, consulte la sección sobre las barras diagonales finales.

El uso de scope={resource-identifier}/.default es funcionalmente el mismo que el de resource={resource-identifier} en el punto de conexión v1.0 (donde {resource-identifier} es el URI de identificador de la API, por ejemplo, https://graph.microsoft.com para Microsoft Graph).

The .default scope can be used in any OAuth 2.0 flow and to initiate admin consent. Its use is required in the On-Behalf-Of flow and client credentials flow.

Los clientes no pueden combinar el consentimiento estático (.default) y dinámico en una única solicitud. Por lo tanto, scope=https://graph.microsoft.com/.default Mail.Read genera un error porque combina tipos de ámbitos.

El parámetro de ámbito .default desencadena un aviso de consentimiento solo si no se ha concedido consentimiento para ningún permiso delegado entre el cliente y el recurso, en nombre del usuario que ha iniciado sesión.

Si existe consentimiento, el token devuelto contiene todos los ámbitos concedidos para ese recurso para el usuario que ha iniciado sesión. Sin embargo, si no se concedió ningún permiso para el recurso solicitado (o si se proporciona el parámetro prompt=consent), se muestra un aviso de consentimiento para todos los permisos necesarios configurados en el registro de la aplicación cliente, para todas las API de la lista.

Por ejemplo, si se solicita el ámbito https://graph.microsoft.com/.default, la aplicación solicita un token de acceso para Microsoft Graph API. Si se concedió al menos un permiso delegado para Microsoft Graph en nombre del usuario que inició sesión, el inicio de sesión continúa. Todos los permisos delegados de Microsoft Graph concedidos para ese usuario se incluirán en el token de acceso. Si no se concedió ningún permiso para el recurso solicitado (Microsoft Graph, en este ejemplo), se muestra una solicitud de consentimiento para todos los permisos necesarios configurados en la aplicación para todas las API de la lista.

Ejemplo 1: El usuario o administrador de inquilinos han concedido permisos

En este ejemplo, el usuario o un administrador de inquilino ha concedido al cliente los permisos de Microsoft Graph Mail.Read y User.Read.

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. El token devuelto contiene los ámbitos Mail.Read y User.Read.

Ejemplo 2: El usuario no ha concedido permisos entre el cliente y el recurso

En este ejemplo, el usuario no ha concedido consentimiento entre el cliente y Microsoft Graph, y tampoco lo ha hecho un administrador. El cliente se ha registrado en los permisos User.Read y Contacts.Read, y se ha registrado el ámbito https://vault.azure.net/user_impersonation de Azure Key Vault.

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 de Microsoft Graph, y el ámbito user_impersonation de Azure Key Vault. El token devuelto contiene solo los ámbitos User.Read y Contacts.Read, y solo se puede usar en Microsoft Graph.

Ejemplo 3: El usuario ha dado su consentimiento y el cliente solicita más ámbitos

En este ejemplo, el usuario ya ha dado su consentimiento para Mail.Read al cliente. El cliente se ha registrado para el ámbito Contacts.Read.

El cliente realiza primero un inicio de sesión con scope=https://graph.microsoft.com/.default. Según el parámetro scopes de la respuesta, el código de la aplicación detecta que solo se ha concedido Mail.Read. A continuación, el cliente inicia un segundo inicio de sesión con scope=https://graph.microsoft.com/.default y, esta vez, fuerza el consentimiento mediante prompt=consent. Si el usuario puede dar su consentimiento para todos los permisos que registró la aplicación, se le mostrará la solicitud de consentimiento. (Si no es así, se muestra un mensaje de error o el formulario de solicitud de consentimiento del administrador ). Tanto Contacts.Read como Mail.Read están en el mensaje de consentimiento. Si se concede consentimiento y el inicio de sesión continúa, el token devuelto es para Microsoft Graph y contiene Mail.Read y Contacts.Read.

Uso del ámbito de .default con el cliente

En algunos casos, un cliente puede solicitar su propio ámbito .default. En el siguiente ejemplo se muestra este escenario.

// 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=00001111-aaaa-2222-bbbb-3333cccc4444
    &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. A continuación, el código devuelve un id_token, en lugar de un token de acceso.

Los nuevos clientes destinados a la plataforma de identidad de Microsoft no deben usar esta configuración. Asegúrese de Migrar a la Biblioteca de autenticación de Microsoft (MSAL) desde la Biblioteca de autenticación de Azure AD (ADAL).

Flujo de concesión de credenciales de cliente y .default

Another use of .default is to request app roles (also known as application permissions) in a non-interactive application like a daemon app that uses the client credentials grant flow to call a web API.

Para definir roles de aplicación (permisos de aplicación) para una API web, vea Incorporación de roles de aplicación a una aplicación y su recepción en el token.

Client credentials requests in your client service must include scope={resource}/.default. En este caso, {resource} es la API web a la que la aplicación pretende llamar y para la que quiere obtener un token de acceso. Issuing a client credentials request by using individual application permissions (roles) is not supported. Todos los roles de aplicación (permisos de aplicación) que se han concedido para esa API web se incluyen en el token de acceso devuelto.

Para conceder acceso a los roles 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.

Barra diagonal final y .default

Algunos identificadores URI de recursos tienen una barra diagonal final, por ejemplo, https://contoso.com/ en lugar de https://contoso.com. La barra diagonal final puede causar problemas con la validación del token. Los problemas se producen principalmente cuando se solicita un token para Azure Resource Manager (https://management.azure.com/).

En este caso, una barra diagonal final en el URI del recurso significa que la barra diagonal debe estar presente cuando se solicita el token. Por lo tanto, cuando solicite un token para https://management.azure.com/ y use .default, debe solicitar https://management.azure.com//.default (observe la barra diagonal doble).

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.

See also

  • Last updated on