Flujo con derechos delegados de OAuth 2.0 y Plataforma de identidad de Microsoft

El flujo en nombre de (OBO) describe el escenario de una API web mediante una identidad distinta a la suya para llamar a otra API web. Denominado "delegación en OAuth", la intención es pasar la identidad y los permisos de un usuario a través de la cadena de solicitudes.

Para que el servicio de nivel intermedio realice solicitudes autenticadas al servicio de nivel inferior, debe proteger un token de acceso de la plataforma de identidad de Microsoft. Solo usa ámbitos delegados y no roles de aplicación. Los roles permanecen asociados a la entidad de seguridad (el usuario), nunca a la aplicación que opera en nombre de los usuarios. Esto se produce para evitar que el usuario obtenga permiso para los recursos a los que no debe tener acceso.

En este artículo se describe cómo programar directamente con el protocolo de la aplicación. Cuando sea posible, se recomienda usar las bibliotecas de autenticación de Microsoft (MSAL) admitidas, en lugar de adquirir tokens y API web protegidas por llamadas. Para obtener ejemplos, consulte también las aplicaciones de ejemplo que usan MSAL.

Limitaciones del cliente

Si una entidad de servicio solicita un token de solo aplicación y lo envía a una API, esta intercambiará un token que no represente la entidad de servicio original. Esto se debe a que el flujo OBO solo funciona para las entidades de seguridad de usuario. En lugar de ello, debe usar el flujo de credenciales de cliente para obtener un token de solo aplicación. En el caso de las aplicaciones de una sola página (SPA), deben pasar un token de acceso a un cliente confidencial de nivel intermedio para ejecutar flujos OBO en su lugar.

Si un cliente usa el flujo implícito para obtener un id_token y también incluye caracteres comodín en una dirección URL de respuesta, el id_token no se puede usar con un flujo OBO. Un carácter comodín es una dirección URL que termina con un carácter *. Por ejemplo, si https://myapp.com/* era la dirección URL de respuesta, el id_token no se puede usar, ya que no es lo suficientemente específico como para identificar al cliente. Esto impedirá que se emita el token. Sin embargo, los tokens de acceso que se hayan adquirido mediante el flujo de concesión implícita pueden ser canjeados por un cliente confidencial, aunque el cliente iniciador tenga registrada una dirección URL de respuesta con caracteres comodín. Esto se debe a que el cliente confidencial puede identificar al cliente que adquirió el token de acceso. A continuación, el cliente confidencial puede usar el token de acceso para adquirir uno nuevo para la API de nivel inferior.

Además, las aplicaciones con claves de firma personalizadas no se pueden usar como API de nivel intermedio en el flujo OBO. Esto incluye las aplicaciones empresariales que están configuradas para el inicio de sesión único. Si la API de nivel intermedio usa una clave de firma personalizada, la API de nivel inferior no podrá validar la firma del token de acceso que se le pasa. Esto produce un error, ya que los tokens que están firmados con una clave que controla el cliente no se pueden aceptar de manera segura.

Diagrama del protocolo

Suponga que el usuario se ha autenticado en una aplicación mediante el flujo de concesión del código de autorización de OAuth 2.0 u otro flujo de inicio de sesión. En este punto, la aplicación tiene un token de acceso para la API A (token A) con las notificaciones del usuario y su consentimiento para acceder a la API web de nivel intermedio (API A). Ahora, la API A debe realizar una solicitud autenticada a la API web de bajada (API B).

Los pasos siguientes constituyen el flujo con derechos delegados y se explican con la ayuda del diagrama siguiente.

1. La aplicación cliente realiza una solicitud a la API A con el token A (con una notificación aud de la API A).
2. La API A se autentica en el punto de conexión de emisión de tokens de la Plataforma de identidad de Microsoft y solicita un token para obtener acceso a la API B.
3. El punto de conexión de emisión de tokens de la Plataforma de identidad de Microsoft valida las credenciales de la API A con el token A y emite el token de acceso para la API B (token B).
4. El token B lo establece la API A en el encabezado de autorización de la solicitud a la API B.
5. La API B devuelve los datos del recurso protegido a la API A y después los devuelve al cliente.

En este caso, el servicio de nivel intermedio no tiene interacción con el usuario para obtener el consentimiento del usuario para el acceso a la API de bajada. Por tanto, la opción para conceder acceso a la API de nivel inferior se presenta inicialmente como parte del paso de consentimiento durante la autenticación. Para obtener información sobre cómo implementar esta opción para la aplicación, consulte Obtención de consentimiento para la aplicación de nivel intermedio.

Solicitud de token de acceso de nivel intermedio

Para solicitar un token de acceso, realice una solicitud HTTP POST al punto de conexión de la Plataforma de identidad de Microsoft específico del inquilino con los parámetros siguientes.

https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token

Se pueden dar dos casos en función de si la aplicación cliente elige un secreto compartido o un certificado para su protección.

Primer caso: solicitud de token de acceso con un secreto compartido

Cuando se utiliza un secreto compartido, una solicitud de token de acceso entre servicios contiene los parámetros siguientes:

Ejemplo

El siguiente HTTP POST solicita un token de acceso y un token de actualización con el ámbito user.read para la API web https://graph.microsoft.com. La solicitud se firma con el secreto de cliente y la realiza un cliente confidencial.

//line breaks for legibility only
    
POST /oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com/<tenant>
Content-Type: application/x-www-form-urlencoded
    
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&client_secret=sampleCredentia1s
&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCJ9.eyJhdWQiOiIyO{a lot of characters here}
&scope=https://graph.microsoft.com/user.read+offline_access
&requested_token_use=on_behalf_of

Segundo caso: solicitud de token de acceso con un certificado

Una solicitud de token de acceso de servicio a servicio con un certificado contiene los parámetros siguientes, además de los parámetros del ejemplo anterior:

Tenga en cuenta que los parámetros son casi iguales que en el caso de solicitud con un secreto compartido, salvo que el parámetro client_secret se sustituye por dos parámetros: client_assertion_type y client_assertion. El parámetro client_assertion_type se establece en urn:ietf:params:oauth:client-assertion-type:jwt-bearer y el parámetro client_assertion se establece en el token JWT que se firma con la clave privada del certificado.

Ejemplo

El siguiente elemento HTTP POST solicita un token de acceso con el ámbito user.read para la API web https://graph.microsoft.com con un certificado. La solicitud se firma con el secreto de cliente y la realiza un cliente confidencial.

// line breaks for legibility only
    
POST /oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com/<tenant>
Content-Type: application/x-www-form-urlencoded
    
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&client_id=11112222-bbbb-3333-cccc-4444dddd5555
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}
&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCIsImtpZCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCJ9.eyJhdWQiO{a lot of characters here}
&requested_token_use=on_behalf_of
&scope=https://graph.microsoft.com/user.read+offline_access

Respuesta de token de acceso de nivel intermedio

Una respuesta correcta es una respuesta de OAuth 2.0 de JSON con los parámetros siguientes.

Ejemplo de respuesta correcta

En el ejemplo siguiente se muestra una respuesta correcta a una solicitud de un token de acceso para la API web https://graph.microsoft.com. La respuesta contiene un token de acceso y un token de actualización y se firma con la clave privada del certificado.

{
    "token_type": "Bearer",
    "scope": "https://graph.microsoft.com/user.read",
    "expires_in": 3269,
    "ext_expires_in": 0,
    "access_token": "eyJ0eXAiOiJKV1QiLCJub25jZSI6IkFRQUJBQUFBQUFCbmZpRy1tQTZOVGFlN0NkV1c3UWZkQ0NDYy0tY0hGa18wZE50MVEtc2loVzRMd2RwQVZISGpnTVdQZ0tQeVJIaGlDbUN2NkdyMEpmYmRfY1RmMUFxU21TcFJkVXVydVJqX3Nqd0JoN211eHlBQSIsImFsZyI6IlJTMjU2IiwieDV0IjoiejAzOXpkc0Z1aXpwQmZCVksxVG4yNVFIWU8wIiwia2lkIjoiejAzOXpkc0Z1aXpwQmZCVksxVG4yNVFIWU8wIn0.eyJhdWQiOiJodHRwczovL2dyYXBoLm1pY3Jvc29mdC5jb20iLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMWRiNDcvIiwiaWF0IjoxNDkzOTMwMzA1LCJuYmYiOjE0OTM5MzAzMDUsImV4cCI6MTQ5MzkzMzg3NSwiYWNyIjoiMCIsImFpbyI6IkFTUUEyLzhEQUFBQU9KYnFFWlRNTnEyZFcxYXpKN1RZMDlYeDdOT29EMkJEUlRWMXJ3b2ZRc1k9IiwiYW1yIjpbInB3ZCJdLCJhcHBfZGlzcGxheW5hbWUiOiJUb2RvRG90bmV0T2JvIiwiYXBwaWQiOiIyODQ2ZjcxYi1hN2E0LTQ5ODctYmFiMy03NjAwMzViMmYzODkiLCJhcHBpZGFjciI6IjEiLCJmYW1pbHlfbmFtZSI6IkNhbnVtYWxsYSIsImdpdmVuX25hbWUiOiJOYXZ5YSIsImlwYWRkciI6IjE2Ny4yMjAuMC4xOTkiLCJuYW1lIjoiTmF2eWEgQ2FudW1hbGxhIiwib2lkIjoiZDVlOTc5YzctM2QyZC00MmFmLThmMzAtNzI3ZGQ0YzJkMzgzIiwib25wcmVtX3NpZCI6IlMtMS01LTIxLTIxMjc1MjExODQtMTYwNDAxMjkyMC0xODg3OTI3NTI3LTI2MTE4NDg0IiwicGxhdGYiOiIxNCIsInB1aWQiOiIxMDAzM0ZGRkEwNkQxN0M5Iiwic2NwIjoiVXNlci5SZWFkIiwic3ViIjoibWtMMHBiLXlpMXQ1ckRGd2JTZ1JvTWxrZE52b3UzSjNWNm84UFE3alVCRSIsInRpZCI6IjcyZjk4OGJmLTg2ZjEtNDFhZi05MWFiLTJkN2NkMDExZGI0NyIsInVuaXF1ZV9uYW1lIjoibmFjYW51bWFAbWljcm9zb2Z0LmNvbSIsInVwbiI6Im5hY2FudW1hQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJWR1ItdmtEZlBFQ2M1dWFDaENRSkFBIiwidmVyIjoiMS4wIn0.cubh1L2VtruiiwF8ut1m9uNBmnUJeYx4x0G30F7CqSpzHj1Sv5DCgNZXyUz3pEiz77G8IfOF0_U5A_02k-xzwdYvtJUYGH3bFISzdqymiEGmdfCIRKl9KMeoo2llGv0ScCniIhr2U1yxTIkIpp092xcdaDt-2_2q_ql1Ha_HtjvTV1f9XR3t7_Id9bR5BqwVX5zPO7JMYDVhUZRx08eqZcC-F3wi0xd_5ND_mavMuxe2wrpF-EZviO3yg0QVRr59tE3AoWl8lSGpVc97vvRCnp4WVRk26jJhYXFPsdk4yWqOKZqzr3IFGyD08WizD_vPSrXcCPbZP3XWaoTUKZSNJg",
    "refresh_token": "OAQABAAAAAABnfiG-mA6NTae7CdWW7QfdAALzDWjw6qSn4GUDfxWzJDZ6lk9qRw4An{a lot of characters here}"
}

Este token de acceso tiene un formato v1.0 para Microsoft Graph. Esto se debe a que el formato del token se basa en el recurso al que se accede y no está relacionado con los puntos de conexión usados para solicitarlo. Microsoft Graph se configura para aceptar tokens v1.0, por lo que la plataforma de identidad de Microsoft genera tokens de acceso v1.0 cuando un cliente solicita tokens para Microsoft Graph. Otras aplicaciones podrían indicar que quieren tokens con formato v2.0, tokens con formato v1.0 o incluso formatos de tokens de propiedad o cifrados. Los puntos de conexión v1.0 y v2.0 pueden emitir cualquier formato de token. De esta manera, el recurso siempre puede obtener el formato correcto de token, independientemente de cómo o dónde el cliente haya solicitado el token.

Ejemplo de respuesta de error

El punto de conexión del token devuelve una respuesta de error al intentar adquirir un token de acceso para la API de bajada si dicha API tiene establecida una directiva de acceso condicional, como la autenticación multifactor. El servicio de nivel intermedio debe exponer el error a la aplicación cliente para que esta pueda proporcionar la interacción del usuario necesaria para cumplir la directiva de acceso condicional.

Para volver a mostrar este error en el cliente, el servicio de nivel intermedio responde con HTTP 401 No autorizado y con un encabezado HTTP WWW-Authenticate que contiene el error y el desafío de notificación. El cliente debe analizar este encabezado y adquirir un nuevo token del emisor de tokens mediante la presentación del desafío de notificaciones si existe uno. Los clientes no deben reintentar el acceso al servicio de nivel intermedio mediante un token de acceso almacenado en caché.

{
    "error":"interaction_required",
    "error_description":"AADSTS50079: Due to a configuration change made by your administrator, or because you moved to a new location, you must enroll in multifactor authentication to access 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2017-05-01 22:43:20Z",
    "error_codes":[50079],
    "timestamp":"2017-05-01 22:43:20Z",
    "trace_id":"0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlation_id":"aaaa0000-bb11-2222-33cc-444444dddddd",
    "claims":"{\"access_token\":{\"polids\":{\"essential\":true,\"values\":[\"00aa00aa-bb11-cc22-dd33-44ee44ee44ee\"]}}}"
}

Usar el token de acceso para obtener acceso al recurso protegido

Ahora, el servicio de nivel intermedio puede usar el token adquirido anteriormente para realizar solicitudes autenticadas a la API web de bajada mediante el establecimiento del token en el encabezado Authorization.

Ejemplo

    GET /v1.0/me HTTP/1.1
    Host: graph.microsoft.com
    Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw

Aserciones de SAML obtenidas con un flujo de OBO de OAuth2.0

Algunos servicios web basados en OAuth necesitan tener acceso a otras API de servicio web que aceptan aserciones de SAML en flujos no interactivos. Microsoft Entra ID puede proporcionar una aserción de SAML en respuesta a un flujo de On-Behalf-Of que usa un servicio web basado en SAML como un recurso de destino.

Se trata de una extensión no estándar del flujo con derechos delegados de OAuth 2.0 que permite a una aplicación basada en OAuth2 acceder a puntos de conexión de API de servicio web que consumen tokens SAML.

Obtener un token SAML mediante una solicitud OBO con un secreto compartido

Una solicitud de servicio a servicio para una aserción SAML contiene los siguientes parámetros:

La respuesta contiene un token SAML codificado con UTF8 y Base64url.

• SubjectConfirmationData para una aserción de SAML procedente de una llamada OBO: si la aplicación de destino requiere un valor de Recipient en SubjectConfirmationData, el valor se debe configurar como la primera dirección URL de respuesta que no sea de caracteres comodín en la configuración de la aplicación de recursos. Dado que no se usa la dirección URL de respuesta predeterminada para determinar el valor de Recipient, es posible que tenga que reordenar las direcciones URL de respuesta en la configuración de la aplicación para garantizar que se use la primera URL de respuesta que no tenga caracteres comodín. Para obtener más información, consulte Direcciones URL de respuesta.
• El nodo SubjectConfirmationData: este no puede contener un atributo InResponseTo, ya que no forma parte de una respuesta SAML. La aplicación que recibe el token SAML debe tener la capacidad de aceptar la aserción SAML sin el atributo InResponseTo.
• Permisos de API: tiene que agregar los permisos de API necesarios en la aplicación de nivel intermedio para permitir el acceso a la aplicación SAML, de modo que pueda solicitar un token para el ámbito /.default de la aplicación SAML.
• Consentimiento: debe otorgarse un consentimiento con el fin de recibir un token SAML que contenga datos de usuario en un flujo de OAuth. Para más información, consulte Obtención de consentimiento para la aplicación de nivel intermedio.

Respuesta con aserción SAML

• token_type: Portador
• expires_in: 3296
• ext_expires_in: 0
• expires_on: 1529627844
• resource: https://api.contoso.com
• access_token: <SAML assertion>
• issued_token_type: urn:ietf:params:oauth:token-type:saml2
• refresh_token: <Refresh token>

Obtener consentimiento para la aplicación de nivel intermedio

El objetivo del flujo OBO es garantizar que el consentimiento adecuado para que la aplicación cliente pueda llamar a la aplicación de nivel intermedio y que la aplicación de nivel intermedio tenga permiso para llamar al recurso de back-end. En función de la arquitectura o el uso de la aplicación, debe considerar lo siguiente para garantizar que el flujo OBO sea correcto.

Consentimiento .default y combinado

La aplicación de nivel intermedio agrega el cliente a la lista de aplicaciones cliente conocidas (knownClientApplications) de su manifiesto. Si el cliente desencadena una petición de consentimiento, el flujo de consentimiento es para sí mismo y para la aplicación de nivel intermedio. En la Plataforma de identidad de Microsoft, esto se hace con el ámbitoámbito .default. El ámbito .default es un ámbito especial que se usa para solicitar consentimiento a fin de acceder a todos los ámbitos para los que la aplicación tiene permisos. Esto resulta útil cuando la aplicación necesita acceder a varios recursos, pero el usuario solo debe solicitar el consentimiento una vez.

Cuando se desencadena una pantalla de consentimiento con aplicaciones cliente conocidas y .default, la pantalla de consentimiento muestra los permisos tanto al cliente como a la API de nivel intermedio, y también solicita los permisos que requiera la API de nivel intermedio. El usuario da su consentimiento para ambas aplicaciones y, a continuación, el flujo OBO funcionará.

El servicio de recursos (API) identificado en la solicitud debe ser la API para la que la aplicación cliente solicita un token de acceso como resultado del inicio de sesión del usuario. Por ejemplo, scope=openid https://middle-tier-api.example.com/.default (para solicitar un token de acceso para la API de nivel intermedio) o scope=openid offline_access .default (cuando no se identifica un recurso, el valor predeterminado es Microsoft Graph).

Independientemente de la API que se identifique en la solicitud de autorización, la solicitud de consentimiento se combina con todos los permisos necesarios que están configurados para la aplicación cliente. También se incluyen todos los permisos necesarios que están configurados para cada API de nivel intermedio que se enumeran en la lista de permisos necesarios del cliente, que han identificado al cliente como una aplicación cliente conocida.

Aplicaciones previamente autorizadas

Los recursos pueden indicar que una determinada aplicación siempre tiene permiso para recibir determinados ámbitos. Esto resulta útil para hacer que las conexiones entre un cliente de front-end y un recurso de back-end sean más fluidas. Un recurso puede declarar varias aplicaciones previamente autorizadas (preAuthorizedApplications) en su manifiesto. Cualquier aplicación de este tipo puede solicitar estos permisos en un flujo OBO y recibirlos sin que el usuario dé el consentimiento.

Consentimiento de administrador

Un administrador de inquilinos puede garantizar que las aplicaciones tienen permiso para llamar a las API necesarias al proporcionar el consentimiento del administrador para la aplicación de nivel intermedio. Para ello, el administrador puede encontrar la aplicación de nivel intermedio en su inquilino, abrir la página de los permisos necesarios y elegir la opción para dar permiso a la aplicación. Para más información sobre el consentimiento del administrador, vea la documentación sobre consentimientos y permisos.

Uso de una sola aplicación

En algunos escenarios, solo puede haber un único emparejamiento entre el nivel intermedio y el cliente front-end. En este escenario, le resultará más fácil hacer esto en una sola aplicación, sin la necesidad de que exista una aplicación de nivel intermedio. Para realizar la autenticación entre el cliente front-end y la API web, puede usar cookies, un token de identificador o un token de acceso solicitado para la propia aplicación. A continuación, solicite el consentimiento a esta aplicación única para el recurso back-end.

Consulte también

Obtenga más información sobre el protocolo OAuth 2.0 y conozca otra manera de realizar la autenticación entre servicios con las credenciales del cliente.

• La Plataforma de identidad de Microsoft y el flujo de credenciales de cliente de OAuth 2.0
• OAuth 2.0 code flow in Microsoft identity platform (Flujo de código de OAuth 2.0 en la Plataforma de identidad de Microsoft)
• Uso del ámbito /.default