Compartir a través de

Guía para desarrolladores para solicitar permisos y consentimiento en la Plataforma de identidad de Microsoft

Las aplicaciones de la plataforma de identidad de Microsoft dependen del consentimiento para obtener acceso a los recursos o API necesarios. Los distintos tipos de consentimiento son mejores para diferentes escenarios de aplicación. Elegir el mejor enfoque para dar su consentimiento a la aplicación le permite tener más éxito con los usuarios y las organizaciones.

En este artículo, obtendrá información sobre los distintos tipos de consentimiento y cómo solicitar permisos para la aplicación mediante consentimiento.

Nota:

En el caso de las aplicaciones de inquilinos externos, los clientes no pueden dar su consentimiento a los permisos por sí mismos. Un administrador deberá conceder consentimiento para que la aplicación acceda a los recursos en su nombre. Para obtener más información, consulte Concesión de consentimiento del administrador.

En el escenario estático de consentimiento del usuario, debe especificar todos los permisos que necesita en la configuración de la aplicación en el Centro de administración de Microsoft Entra. Si al usuario o al administrador, según corresponda, no se le concede permiso para esta aplicación, la plataforma de identidad de Microsoft pedirá al usuario que proporcione su consentimiento en este momento.

Los permisos estáticos también permiten a los administradores dar su consentimiento en nombre de todos los usuarios de la organización.

Aunque se basan en el consentimiento estático y en una lista de permisos única donde el código es sencillo y está bien organizado, la aplicación solicitará todos los permisos necesarios por adelantado. Este ajuste puede impedir que los usuarios y administradores aprueben la solicitud de acceso a la aplicación.

Con el punto de conexión de la plataforma de identidad de Microsoft, puede omitir los permisos estáticos definidos en la información de registro de la aplicación en el Centro de administración de Microsoft Entra. En su lugar, puede solicitar permisos dinámicamente desde el código de la aplicación. Puede empezar solicitando un conjunto mínimo de permisos inicialmente y pedir más a lo largo del tiempo a medida que el cliente usa más características de la aplicación. Para ello, puede especificar los ámbitos que la aplicación necesita en cualquier momento mediante la inclusión de los ámbitos en el scope parámetro al solicitar un token de acceso , sin necesidad de predefinirlos en la información de registro de la aplicación.

Si el usuario no ha consentido ninguno de los alcances de la solicitud, recibirá una solicitud de consentimiento para todos los permisos de esa solicitud. Estos se concederán además de cualquier otro permiso que ya se haya concedido para la aplicación, de manera incremental. Consentimiento incremental, solo se aplica a los permisos delegados y no a los permisos de aplicación.

Permitir que una aplicación solicite permisos dinámicamente a través del scope parámetro proporciona a los desarrolladores control total sobre la experiencia del usuario. Puede adelantar la experiencia de consentimiento y pedir todos los permisos en una solicitud de autorización inicial. Si su aplicación requiere un gran número de permisos, puede solicitar esos permisos de manera gradual conforme los usuarios intentan usar ciertas características de la aplicación a lo largo del tiempo.

Importante

El consentimiento dinámico puede ser cómodo, pero presenta un importante desafío para los permisos que requieren consentimiento del administrador. La experiencia de consentimiento del administrador de las hojas Registros de aplicaciones y Aplicaciones empresariales del portal no tiene conocimiento de esos permisos dinámicos en tiempo de consentimiento. Se recomienda que un desarrollador enumere todos los permisos con privilegios de administrador que la aplicación necesita en el portal.

Esto permite a los administradores de inquilinos dar su consentimiento en nombre de todos los usuarios del portal una vez. Los usuarios no tendrán que pasar por la experiencia de consentimiento para esos permisos al iniciar sesión. La alternativa es usar el consentimiento dinámico para esos permisos. Para conceder el consentimiento del administrador, un administrador individual inicia sesión en la aplicación, desencadena una solicitud de consentimiento para los permisos adecuados y selecciona el consentimiento de toda la organización en el diálogo de consentimiento.

En una solicitud de autorización de OpenID Connect o OAuth 2.0 , una aplicación puede solicitar los permisos que necesita mediante el scope parámetro de consulta. Por ejemplo, cuando un usuario inicia sesión en una aplicación, la aplicación envía una solicitud como en el ejemplo siguiente. (Se agregan saltos de línea para legibilidad).

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&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 scope parámetro es una lista separada por espacios de permisos delegados que solicita la aplicación. Cada permiso se indica anexando el valor del permiso al identificador del recurso (URI del identificador de aplicación). En el ejemplo de solicitud, la aplicación necesita permiso para leer el calendario del usuario y enviar correo como usuario.

Después del inicio de sesión, la plataforma de identidad de Microsoft comprueba si hay consentimiento del usuario existente. Si el usuario no aprueba los permisos solicitados y un administrador tampoco los aprueba, la plataforma pide al usuario que conceda consentimiento.

En el ejemplo siguiente, los permisos offline_access ("Mantener el acceso a los datos a los que da acceso") y User.Read ("Iniciar sesión y leer su perfil") se incluyen automáticamente en el consentimiento inicial para una aplicación. Estos permisos son necesarios para una funcionalidad de aplicación adecuada.

El offline_access permiso concede a la aplicación acceso a tokens de actualización críticos para aplicaciones nativas y aplicaciones web. El permiso User.Read concede acceso a la notificación sub. Permite que el cliente o la aplicación identifiquen correctamente al usuario a lo largo del tiempo y accedan a información de usuario rudimentaria.

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

Cuando el usuario aprueba la solicitud de permiso, se registra el consentimiento. El usuario no tiene que volver a dar su consentimiento cuando inicie sesión más adelante en la aplicación.

La solicitud de consentimiento para un inquilino completo requiere el consentimiento del administrador. El consentimiento del administrador realizado en nombre de una organización requiere los permisos estáticos registrados para la aplicación. Establezca esos permisos en el portal de registro de aplicaciones si necesita que un administrador dé su consentimiento en nombre de toda la organización.

Cuando la aplicación solicita permisos delegados que requieren consentimiento del administrador, los usuarios ven un error "no autorizado para dar su consentimiento" y necesitan pedir acceso a un administrador. Una vez que un administrador concede consentimiento para todo el inquilino, los usuarios no se le pedirán de nuevo a menos que se revoque el consentimiento o se agreguen nuevos permisos.

Los administradores que usan la misma aplicación verán el mensaje de consentimiento del administrador. El mensaje de consentimiento del administrador proporciona una casilla que les permite conceder a la aplicación acceso a los datos solicitados en nombre de los usuarios para todo el inquilino. Para obtener más información sobre la experiencia de consentimiento del usuario y del administrador, consulte Experiencia de consentimiento de la aplicación.

Algunos ejemplos de permisos delegados para Microsoft Graph que requieren consentimiento del administrador son:

  • La lectura de los perfiles completos de todos los usuarios con User.Read.All.
  • La escritura de datos en el directorio de una organización mediante Directory.ReadWrite.All.
  • La lectura de todos los grupos de seguridad del directorio de una organización mediante Groups.Read.All.

Para ver la lista completa de permisos de Microsoft Graph, consulte Referencia de permisos de Microsoft Graph.

También puede configurar permisos en sus propios recursos para requerir el consentimiento del administrador. Para obtener más información sobre cómo agregar ámbitos que requieren consentimiento del administrador, consulte Agregar un ámbito que requiera consentimiento del administrador.

Algunas organizaciones pueden cambiar la directiva de consentimiento del usuario predeterminada para el inquilino. Cuando la aplicación solicita acceso a los permisos, se evalúan con estas directivas. Es posible que el usuario tenga que solicitar el consentimiento del administrador incluso cuando no sea necesario de forma predeterminada. Para obtener información sobre cómo los administradores administran las directivas de consentimiento de las aplicaciones, consulte Administración de directivas de consentimiento de aplicaciones.

Nota:

En solicitudes de autorización, token o consentimiento de la plataforma de identidad de Microsoft, omita el identificador de recursos en el valor predeterminado del parámetro scope en Microsoft Graph. Por ejemplo, scope=User.Read se trata como https://graph.microsoft.com/User.Read.

Los permisos de aplicación siempre requieren el consentimiento del administrador. Los permisos de aplicación no tienen un contexto de usuario y la concesión de consentimiento no se realiza en nombre de ningún usuario específico. En su lugar, a la aplicación cliente se le conceden los permisos directamente. Estos tipos de permisos se usan solo en servicios de demonio y otras aplicaciones no interactivas que se ejecutan en segundo plano. Los administradores deben configurar los permisos por adelantado y conceder el consentimiento del administrador a través del Centro de administración de Microsoft Entra.

En caso de que la aplicación que solicita el permiso sea una aplicación multiinquilino, su registro de aplicación solo existe en el inquilino donde se creó, por lo que los permisos no se pueden configurar en el inquilino local. Si la aplicación solicita permisos que requieren consentimiento del administrador, el administrador debe dar su consentimiento en nombre de los usuarios. Para dar su consentimiento a estos permisos, los administradores deben registrarse en la propia aplicación, por lo que se desencadena la experiencia de inicio de sesión de consentimiento del administrador. Para obtener información sobre cómo configurar la experiencia de consentimiento del administrador para aplicaciones multiinquilino, consulte Habilitación de inicios de sesión multiinquilino.

Un administrador puede conceder consentimiento para una aplicación con las siguientes opciones.

Normalmente, cuando se compila una aplicación que requiere consentimiento del administrador, la aplicación necesita una página o vista en la que el administrador puede aprobar los permisos de la aplicación. Esta página puede ser:

  • Parte del flujo de registro de la aplicación.
  • Parte de la configuración de la aplicación.
  • un flujo de "conexión" dedicado.

En muchos casos, tiene sentido que la aplicación muestre la vista de "conexión" solo después de que un usuario haya iniciado sesión con una cuenta de Microsoft profesional o educativa.

Al iniciar sesión el usuario en la aplicación, puede identificar la organización a la que pertenece el administrador antes de pedirle que apruebe los permisos necesarios. Aunque este paso no es estrictamente necesario, puede ayudarle a crear una experiencia más intuitiva para los usuarios de la organización.

Para iniciar la sesión del usuario, siga los tutoriales del protocolo de la Plataforma de identidad de Microsoft.

Solicitud de los permisos en el portal de registro de aplicaciones

En el portal de registro de aplicaciones, las aplicaciones pueden enumerar los permisos que requieren, incluidos los permisos delegados y los permisos de aplicación. Esta configuración permite el uso del .default ámbito y la opción Conceder consentimiento del administrador del Centro de administración de Microsoft Entra.

En general, los permisos deben definirse estáticamente para una aplicación determinada. Deben formar un superconjunto de los permisos que la aplicación solicitará de manera dinámica o incremental.

Nota:

Los permisos de aplicación solo se pueden solicitar mediante .default. Por lo tanto, si la aplicación necesita permisos de aplicación, asegúrese de que se muestran en el portal de registro de aplicaciones.

Para configurar la lista de permisos solicitados estáticamente para una aplicación:

  1. Inicie sesión en el Centro de administración de Microsoft Entra siendo al menos un Administrador de aplicaciones en la nube.
  2. Vaya a Entra ID>Registros de aplicaciones>Todas las aplicaciones.
  3. Seleccione una aplicación o cree una aplicación si aún no lo ha hecho.
  4. En la página Información general de la aplicación, en Administrar, seleccione Permisos de> APIAgregar un permiso.
  5. Seleccione Microsoft Graph en la lista de API disponibles. A continuación, agregue los permisos que requiere la aplicación.
  6. Seleccione Agregar permisos.

Respuesta exitosa

Si el administrador aprueba los permisos de la aplicación, la respuesta correcta tiene este aspecto:

GET http://localhost/myapp/permissions?tenant=aaaabbbb-0000-cccc-1111-dddd2222eeee&state=state=12345&admin_consent=True
Parámetro Descripción
tenant El inquilino de directorio que concedió a la aplicación los permisos solicitados, en formato GUID.
state Un valor incluido en la solicitud devuelto en la respuesta del token. Puede ser una cadena de cualquier contenido que desee. El estado se usa para codificar información sobre el estado del usuario en la aplicación antes de que se produjera la solicitud de autenticación, como la página o la vista en la que estaban.
admin_consent Se establece en True.

Cuando reciba una respuesta correcta del punto de conexión de consentimiento del administrador, se concede a la aplicación los permisos solicitados. A continuación, puede solicitar un token para el recurso que desee.

Respuesta de error

Si el administrador no aprueba los permisos de la aplicación, la respuesta fallida es similar a la siguiente:

GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request
Parámetro Descripción
error Cadena de código de error que se puede usar para clasificar tipos de errores que se producen. También se puede usar para reaccionar a los errores.
error_description Un mensaje de error específico que puede ayudar a un desarrollador a identificar la causa principal de un error.

Una vez que el usuario da su consentimiento a los permisos de la aplicación, la aplicación puede adquirir tokens de acceso que representan el permiso de la aplicación para acceder a un recurso en cierta capacidad. Un token de acceso solo se puede usar para un único recurso. Sin embargo, dentro del token de acceso están todos los permisos codificados que se han concedido a la aplicación para ese recurso. 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, de la siguiente manera:

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

{
    "grant_type": "authorization_code",
    "client_id": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "scope": "https://microsoft.graph.com/Mail.Read https://microsoft.graph.com/mail.send",
    "code": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...",
    "redirect_uri": "https://localhost/myapp",
    "client_secret": "A1bC2dE3f..."  // NOTE: Only required for web apps
}

Puede usar el token de acceso resultante en solicitudes HTTP al recurso. Indica de forma confiable el recurso que la aplicación tiene el permiso adecuado para realizar una tarea específica.

Para obtener más información sobre el protocolo OAuth 2.0 y cómo obtener tokens de acceso, consulte la referencia del protocolo de punto de conexión de la plataforma de identidad de Microsoft.

Contenido relacionado

  • Last updated on