Ámbitos y permisos en la plataforma de identidad de Microsoft

La plataforma de identidad de Microsoft implementa el protocolo de autorización OAuth 2.0. 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
• https://vault.azure.netAzure Key Vault:

Ocurre lo mismo con cualquier recurso de terceros integrado en la plataforma de identidad de Microsoft. Cualquiera de estos recursos puede definir también un conjunto de permisos que se puede utilizar para dividir la funcionalidad de ese recurso en fragmentos más pequeños. Por ejemplo, Microsoft Graph tiene permisos definidos para realizar, entre otras, las tareas siguientes:

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

En OAuth 2.0, estos tipos de conjuntos de permisos se denominan ámbitos. A menudo se hace referencia a ellos como permisos. 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.

En las solicitudes al servidor de autorización para la Plataforma de identidad de Microsoft, si el identificador de recurso se omite 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.

Permisos restringidos por el administrador

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

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. En su lugar, a la aplicación cliente se le conceden los permisos directamente. Estos tipos de permisos solo se deben usar 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.

Si solicita los ámbitos de OpenID Connect y un token, obtendrá un token para llamar al punto de conexión de UserInfo.

El ámbito openid

Si una aplicación inicia sesión mediante OpenID Connect, debe solicitar el ámbito openid. El ámbito openid aparece en la página de consentimiento de la cuenta profesional como el permiso Iniciar sesión en su nombre.

Con este permiso, una aplicación puede recibir un identificador único para el usuario en forma de la notificación sub. El permiso también ofrece acceso de la aplicación al punto de conexión de UserInfo. 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. 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 referencia id_tokens.

El ámbito offline_access

El ámbito offline_access 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 el permiso Mantener el acceso a los datos a los que le ha dado acceso.

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. Los tokens de actualización tienen una duración larga. La aplicación puede obtener nuevos tokens de acceso cuando expiren los antiguos.

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, solo se recibirá un token de acceso del punto de conexión /token.

El token de acceso suele ser 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 un día. 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:

• Requisitos de ámbito: asegúrese de que solicita los offline_access ámbitos junto con cualquier otro ámbito necesario.
• Tipo de concesión de autorización: el token de actualización se proporciona generalmente al usar el tipo de concesión de código de autorización. Si el flujo difiere, puede afectar a la respuesta.
• Configuración del cliente: compruebe la configuración de la aplicación en la plataforma de identidad. 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. 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.

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

El ámbito .default se puede usar en cualquier flujo de OAuth 2.0 y para iniciar el consentimiento del administrador. Su uso es necesario en el flujo con derechos delegados y en el flujo de credenciales de cliente.

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.

.default cuando el usuario ya ha dado el consentimiento

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 ha concedido ningún permiso para el recurso solicitado (o si se ha proporcionado 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 ha concedido al menos un permiso delegado para Microsoft Graph en nombre del usuario que ha iniciado sesión, el inicio de sesión continuará y todos los permisos delegados de Microsoft Graph que se hayan concedido para ese usuario se incluirán en el token de acceso. Si no se ha concedido ningún permiso para el recurso solicitado (Microsoft Graph, en este ejemplo), se mostrará 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 para los permisos User.Read y Contacts.Read. También se ha registrado para 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 mostrará un mensaje de error o el formulario de solicitud de consentimiento del administrador). Tanto Contacts.Read como Mail.Read estarán en la solicitud 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 .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 que tienen como destino la Plataforma de identidad de Microsoft no deben utilizar 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 del cliente y .default

.default también se utiliza para solicitar roles de aplicación (también conocidos como permisos de aplicación) 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.

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.

Las solicitudes de credenciales de cliente en el servicio cliente deben incluir 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. No se admite la emisión de una solicitud de credenciales de cliente con permisos de aplicación individuales (roles). 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 producir problemas con la validación de tokens. 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 identificador URI del recurso significa que la barra diagonal debe estar presente cuando se solicita el token. 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).

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.

Consulte también

• Solicitud de permisos a través del consentimiento en la plataforma de identidad
• Tokens de id. de la Plataforma de identidad de Microsoft
• Tokens de acceso de la Plataforma de identidad de Microsoft