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) y nunca a la aplicación que opera en nombre del usuario. 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 contra el protocolo en su aplicación. Cuando sea posible, se recomienda usar las bibliotecas de autenticación de Microsoft (MSAL) admitidas en su lugar para adquirir tokens y llamar a API web protegidas. Consulte también las aplicaciones de ejemplo que usan MSAL para obtener ejemplos.

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 su lugar, 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 adquiridos a través del flujo de concesión implícito se canjean mediante un cliente confidencial, incluso si el cliente iniciado tiene 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 bajada no validará la firma del token de acceso que se le pasa. Esto produce un error porque los tokens firmados con una clave controlada por el cliente no se pueden aceptar de forma segura.

Diagrama de protocolo

Supongamos que el usuario ha autenticado una aplicación mediante el flujo de concesión de código de autorización de OAuth 2.0 u otro flujo de inicio de sesión. En este momento, la aplicación tiene un token de acceso para la API A (token A) con las notificaciones del usuario y el 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 esto en 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:

Observe que los parámetros son casi iguales que en el caso de la solicitud por secreto compartido, excepto que el client_secret parámetro se reemplaza por dos parámetros: a 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 exitosa

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 de formato v2.0, tokens de formato v1.0 o incluso formatos de token propietarios o cifrados. Los puntos de conexión v1.0 y v2.0 pueden emitir cualquier formato de token. De este modo, el recurso siempre puede obtener el formato correcto del token, independientemente de cómo o dónde lo solicite el cliente.

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 la API de bajada 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 exponer este error al 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 para acceder 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 nivel inferior estableciendo el token en el Authorization encabezado.

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 para el flujo on-Behalf-Of de OAuth 2.0 que permite que una aplicación basada en OAuth2 acceda a los 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 en UTF8 y Base 64url.

• SubjectConfirmationData para una aserción de SAML originada desde una llamada de OBO: si la aplicación de destino requiere un Recipient valor en SubjectConfirmationData, el valor debe configurarse como la primera dirección URL de respuesta nowildcard en la configuración de la aplicación de recursos. Dado que la dirección URL de respuesta predeterminada no se usa para determinar el Recipient valor, es posible que tenga que reordenar las direcciones URL de respuesta en la configuración de la aplicación para asegurarse de que se usa la primera dirección URL de respuesta nowildcard. Para obtener más información, consulte Url de respuesta.
• Nodo SubjectConfirmationData: el nodo no puede contener un InResponseTo atributo, 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 /.default ámbito de la aplicación SAML.
• Consentimiento: se debe conceder el consentimiento para recibir un token SAML que contenga datos de usuario en un flujo de OAuth. Para obtener información, consulte Obtención de consentimiento para la aplicación de nivel intermedio.

Respuesta con una aserción de SAML

• token_type: Portador
• expira_en: 3296
• ext_expires_in: 0
• expires_on: 1529627844
• recurso: https://api.contoso.com
• access_token: <aserción de SAML>
• tipo_de_token_emitido: urn:ietf:params:oauth:token-type:saml2
• refresh_token: <Token de actualización>

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 tener en cuenta lo siguiente para asegurarse de que el flujo de OBO es correcto:

Consentimiento .default y combinado

La aplicación de nivel intermedio agrega el cliente a la lista de aplicaciones cliente conocidas (knownClientApplications) en su manifiesto. Si el cliente desencadena un mensaje 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 realiza mediante el .default ámbito . 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.

Al desencadenar una pantalla de consentimiento mediante aplicaciones cliente conocidas y .default, la pantalla de consentimiento muestra los permisos para el cliente a la API de nivel intermedio y también solicita los permisos necesarios para 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 identificada en la solicitud de autorización, el mensaje de consentimiento se combina con todos los permisos necesarios configurados para la aplicación cliente. También se incluyen todos los permisos necesarios configurados para cada API de nivel intermedio que se enumeran en la lista de permisos necesarios del cliente, que identificó al cliente como una aplicación cliente conocida.

Aplicaciones previamente autenticadas

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 autenticadas (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 del 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, consulte la documentación de permisos y consentimiento.

Uso de una sola aplicación

En algunos escenarios, solo podría tener un único emparejamiento de cliente de nivel intermedio y front-end. En este escenario, podría resultar más fácil hacer que esta sea una sola aplicación, negando por completo la necesidad de 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.

• Concesión de credenciales de cliente de OAuth 2.0 en la plataforma de identidad de Microsoft
• Flujo de código de OAuth 2.0 en la plataforma de identidad de Microsoft
• Uso del /.default ámbito