Flujo de código de autorización de OAuth 2.0 en Azure Active Directory B2C

Artículo
11/06/2023

Puede usar la concesión de un código de autorización de OAuth 2.0 en las aplicaciones instaladas en un dispositivo para obtener acceso a recursos protegidos, como las API web. Mediante la implementación de OAuth 2.0 de Azure Active Directory B2C (Azure AD B2C) puede agregar tareas de registro, inicio de sesión y otras tareas de administración de identidades a las aplicaciones de página única, móviles y de escritorio. Este artículo es independiente del lenguaje y en él describimos cómo enviar y recibir mensajes HTTP sin usar ninguna biblioteca de código abierto. Cuando sea posible, se recomienda usar las bibliotecas de autenticación de Microsoft (MSAL) admitidas. Consulte las aplicaciones de ejemplo que usan MSAL.

El flujo de código de autorización de OAuth 2.0 se describe en la sección 4.1 de la especificación de OAuth 2.0. Puede usarlo para llevar a cabo la autenticación y la autorización en la mayoría de los tipos de aplicación, incluidas las aplicaciones web, las aplicaciones de página única y las aplicaciones instaladas de forma nativa. Puede usar el flujo de código de autorización de OAuth 2.0 para adquirir de forma segura tokens de acceso y tokens de actualización para las aplicaciones, que se pueden usar para acceder a recursos protegidos por un servidor de autorización. El token de actualización permite que el cliente adquiera nuevos tokens de acceso (y de actualización) cuando expira el token de acceso, normalmente al cabo de una hora.

Este artículo se centra en el flujo de código de autorización de OAuth 2.0 de clientes públicos. Un cliente público es cualquier aplicación cliente que no es de confianza para mantener la integridad de una contraseña secreta de forma segura. Esto incluye las aplicaciones de página única, las aplicaciones móviles, las aplicaciones de escritorio y prácticamente cualquier aplicación que no se ejecute en un servidor.

Nota:

Para agregar la administración de identidades a una aplicación web mediante Azure AD B2C, use OpenID Connect en lugar de OAuth 2.0.

Azure AD B2C extiende los flujos de OAuth 2.0 estándar para realizar algo más que una autorización y autenticación simples. Incorpora el flujo de usuario. Con los flujos de usuario, puede usar OAuth 2.0 para agregar experiencias de usuario a la aplicación, como el registro, el inicio de sesión y la administración de perfiles. Entre los proveedores de identidades que usan el protocolo OAuth 2.0 se incluyen: Amazon, Microsoft Entra ID, Facebook, GitHub, Google y LinkedIn.

Para probar las solicitudes HTTP en este artículo, haga lo siguiente:

Reemplace {tenant} por el nombre del inquilino de Azure AD B2C.
Reemplace 90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 por el id. de la aplicación que registró previamente en el inquilino de Azure AD B2C.
Reemplace {policy} por el nombre de una directiva que haya creado en el inquilino, por ejemplo b2c_1_sign_in.

Configuración del URI de redireccionamiento requerida para aplicaciones de página única

El flujo de código de autorización para aplicaciones de página única requiere configuración adicional. Siga las instrucciones para crear la aplicación de una sola página para marcar correctamente el URI de redireccionamiento como habilitado para CORS. Para actualizar un identificador URI de redirección existente para habilitar CORS, puede hacer clic en la solicitud de migración en la sección "Web" de la pestaña Autenticación del Registros de aplicaciones. Como alternativa, puede abrir el editor del manifiesto de registros de aplicaciones y establecer el campo type para el identificador URI de redirección en spa en la sección replyUrlsWithType.

El tipo de redireccionamiento spa es compatible con las versiones anteriores del flujo implícito. Las aplicaciones que usan actualmente el flujo implícito para obtener tokens pueden moverse al tipo de URI de redireccionamiento spa sin problemas y seguir usando el flujo implícito.

1. Obtener un código de autorización

El flujo del código de autorización comienza con el cliente dirigiendo al usuario al punto de conexión /authorize . Esta es la parte interactiva del flujo, en la que el usuario lleva a cabo la acción. En esta solicitud, el cliente indica en el parámetro scope los permisos que debe obtener por parte del usuario. En los ejemplos siguientes (con saltos de línea para mejorar la legibilidad) se muestra cómo adquirir un código de autorización. Si va a probar esta solicitud HTTP GET, use el explorador.

GET https://{tenant}.b2clogin.com/{tenant}.onmicrosoft.com/{policy}/oauth2/v2.0/authorize?
client_id=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6
&response_type=code
&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob
&response_mode=query
&scope=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6%20offline_access%20https://{tenant-name}/{app-id-uri}/{scope}
&state=arbitrary_data_you_can_receive_in_the_response
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256

Parámetro	¿Necesario?	Descripción
{tenant}	Obligatorio	Nombre de su inquilino de Azure AD B2C.
{policy}	Obligatorio	Flujo de usuario que se va a ejecutar. Especifique el nombre del flujo de usuario que creó en el inquilino de Azure AD B2C. Por ejemplo: `b2c_1_sign_in`, `b2c_1_sign_up` o `b2c_1_edit_profile`.
client_id	Obligatorio	Identificador de aplicación asignado a la aplicación en Azure Portal.
response_type	Obligatorio	El tipo de respuesta, que debe incluir `code` para el flujo de código de autorización. Puede recibir un token de identificador si lo incluye en el tipo de respuesta, como `code+id_token`, y en este caso, el ámbito debe incluir `openid`.
redirect_uri	Obligatorio	El URI de redirección de la aplicación, donde su aplicación envía y recibe las respuestas de autenticación. Debe coincidir exactamente con uno de los URI de redireccionamiento que ha registrado en el portal, con la excepción de que debe estar codificado como URL.
scope	Obligatorio	Una lista de ámbitos separada por espacios. El ámbito `openid` indica un permiso para iniciar sesión con el usuario y obtener los datos del usuario en forma de tokens de identificador. El ámbito `offline_access` es opcional para las aplicaciones web. Indica que la aplicación necesitará un token de actualización para el acceso extendido a los recursos. El id. de cliente indica que el token emitido está diseñado para que lo use un cliente registrado de Azure AD B2C. El `https://{tenant-name}/{app-id-uri}/{scope}` indica un permiso para los recursos protegidos, como una API web. Para más información, consulte Solicitud de un token de acceso.
response_mode	Recomendado	El método que se usa para devolver el código de autorización resultante a la aplicación. Puede ser `query`, `form_post` o `fragment`.
state	Recomendado	Un valor incluido en la solicitud que puede ser una cadena de cualquier contenido que desee usar. Se suele usar un valor único generado de manera aleatoria para evitar los ataques de falsificación de solicitudes entre sitios. El estado también se usa para codificar información sobre el estado del usuario en la aplicación antes de que se haya producido la solicitud de autenticación. Por ejemplo, la página en la que se encontraba el usuario o el flujo de usuario que se estaba ejecutando.
símbolo del sistema	Opcional	El tipo de interacción necesaria con el usuario. Actualmente, el único valor válido es `login`, que obliga al usuario a escribir sus credenciales en esa solicitud. El inicio de sesión único no surtirá efecto.
code_challenge	recomendado/requerido	Se usa para proteger concesiones de código de autorización a través de la clave de prueba para intercambio de códigos (PKCE). Se requiere si se incluye `code_challenge_method`. Debe agregar lógica a la aplicación para generar `code_verifier` y `code_challenge`. `code_challenge` es un hash SHA256 con codificación URL base64 de `code_verifier`. Almacene `code_verifier` en la aplicación para su uso posterior y envíe `code_challenge` junto con la solicitud de autorización. Para obtener más información, consulte PKCE RFC. Ahora se recomienda para todos los tipos de aplicación: aplicaciones nativas; aplicaciones de página única; y clientes confidenciales, como aplicaciones web.
`code_challenge_method`	recomendado/requerido	Método utilizado para codificar `code_verifier` para el parámetro `code_challenge`. Este DEBERÍA ser `S256`, pero la especificación permite utilizar `plain` si por alguna razón el cliente no admite SHA256. Si excluye `code_challenge_method`, pero sigue incluyendo `code_challenge`, se supone que `code_challenge` es texto no cifrado. La Plataforma de identidad de Microsoft admite tanto `plain` como `S256`. Para obtener más información, consulte PKCE RFC. Esto es necesario para las aplicaciones de página única que usan el flujo de código de autorización.
login_hint	No	Se puede usar para rellenar previamente el campo de nombre de inicio de sesión de la página de inicio de sesión. Para más información, consulte Rellenar previamente el nombre de inicio de sesión.
domain_hint	No	Proporciona una sugerencia a Azure AD B2C acerca del proveedor de identidades sociales que debe usarse para iniciar sesión. Si se incluye un valor válido, el usuario va directamente a la página de inicio de sesión del proveedor de identidades. Para más información, consulte Redirección del inicio de sesión a un proveedor social.
Parámetros personalizados	No	Parámetros personalizados que se pueden usar con directivas personalizadas. Por ejemplo, el URI de contenido de página personalizada dinámica o los solucionadores de notificaciones de clave-valor.

En este punto, se pedirá al usuario que complete el flujo de trabajo del flujo de usuario. Esto puede implicar que el usuario tenga que escribir su nombre de usuario y contraseña, iniciar sesión con una identidad social, registrarse en el directorio o realizar otros pasos. Las acciones del usuario dependerán de cómo se defina el flujo de usuario.

Cuando el usuario haya completado el flujo de usuario, Microsoft Entra ID devuelve una respuesta a la aplicación en el valor que ha usado para redirect_uri. Usa el método especificado en el parámetro response_mode. La respuesta es exactamente la misma para cada uno de los escenarios de acción del usuario, independientemente del flujo de usuario que se haya ejecutado.

Una respuesta correcta que usa response_mode=query tiene este aspecto:

GET urn:ietf:wg:oauth:2.0:oob?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...        // the authorization_code, truncated
&state=arbitrary_data_you_can_receive_in_the_response                // the value provided in the request

Parámetro	Descripción
código	El código de autorización que la aplicación solicitó. La aplicación puede usar el código de autorización para solicitar un token de acceso para un recurso de destino. Los códigos de autorización tienen una duración muy breve. Normalmente, caducan al cabo de unos 10 minutos.
state	Vea la descripción completa en la tabla de la sección anterior. Si un parámetro `state` está incluido en la solicitud, debería aparecer el mismo valor en la respuesta. La aplicación debe comprobar que los valores `state` de la solicitud y de la respuesta sean idénticos.

Las respuestas de error también se pueden enviar al URI de redireccionamiento para que la aplicación pueda controlarlas correctamente:

GET urn:ietf:wg:oauth:2.0:oob?
error=access_denied
&error_description=The+user+has+cancelled+entering+self-asserted+information
&state=arbitrary_data_you_can_receive_in_the_response

Parámetro	Descripción
error	Una cadena de código de error que se puede usar para clasificar los tipos de errores que se producen. También puede usar la cadena para reaccionar frente a errores.
error_description	Un mensaje de error específico que puede ayudarlo a identificar la causa raíz de un error de autenticación.
state	Vea la descripción completa en la tabla anterior. Si un parámetro `state` está incluido en la solicitud, debería aparecer el mismo valor en la respuesta. La aplicación debe comprobar que los valores `state` de la solicitud y de la respuesta sean idénticos.

2. Obtención de un token de acceso

Ahora que ha adquirido un código de autorización, puede canjear el elemento code por un token al recurso deseado mediante el envío de una solicitud POST al punto de conexión /token. En Azure AD B2C, puede solicitar tokens de acceso para otras API como de costumbre especificando sus ámbitos en la solicitud.

También puede solicitar un token de acceso para su propia API web de back-end de la aplicación mediante la convención del uso del identificador del cliente de la aplicación como el ámbito solicitado (lo que resultará en un token de acceso con ese identificador de cliente como el "público"):

POST https://{tenant}.b2clogin.com/{tenant}.onmicrosoft.com/{policy}/oauth2/v2.0/token HTTP/1.1

Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6
&scope=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 offline_access
&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&redirect_uri=urn:ietf:wg:oauth:2.0:oob
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong

Parámetro	¿Necesario?	Descripción
{tenant}	Obligatorio	Nombre de su inquilino de Azure AD B2C.
{policy}	Obligatorio	El flujo de usuario usado para adquirir el código de autorización. No puede usar un flujo de usuario diferente en esta solicitud.
client_id	Obligatorio	Identificador de aplicación asignado a la aplicación en Azure Portal.
client_secret	Sí, en Web Apps.	El secreto de la aplicación se generó en Azure Portal. Los secretos de cliente se usan en este flujo para escenarios de aplicaciones web, donde el cliente puede almacenar de forma segura un secreto de cliente. En escenarios de aplicación nativa (cliente público), los secretos de cliente no se pueden almacenar de forma segura y, por lo tanto, no se usan en esta llamada. Si usa un secreto de cliente, cámbielo periódicamente.
grant_type	Obligatorio	Tipo de concesión. Para el flujo de código de autorización, el tipo de concesión debe ser `authorization_code`.
scope	Recomendado	Una lista de ámbitos separada por espacios. Un valor de ámbito único indica a Microsoft Entra ID los dos permisos que se solicitan. El uso del identificador de cliente como ámbito indica que la aplicación necesita un token de acceso que se puede usar con su propio servicio o API web, representado por el mismo identificador de cliente. El ámbito `offline_access` indica que la aplicación necesita un token de actualización para un acceso de larga duración a los recursos. También puede usar el ámbito `openid` para solicitar un token de identificador desde Azure AD B2C.
código	Obligatorio	El código de autorización que adquirió del punto de conexión `/authorize`.
redirect_uri	Obligatorio	El URI de redirección de la aplicación en la que recibió el código de autorización.
code_verifier	recomendado	El mismo que `code_verifier` usó para obtener el código de autorización. Se requiere si PKCE se utilizó en la solicitud de concesión de código de autorización. Para obtener más información, consulte PKCE RFC.

Si va a probar esta solicitud HTTP POST, puede usar cualquier cliente HTTP, como Microsoft PowerShell o Postman.

Una respuesta correcta del token tiene el siguiente aspecto:

{
    "not_before": "1442340812",
    "token_type": "Bearer",
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "scope": "90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 offline_access",
    "expires_in": "3600",
    "refresh_token": "AAQfQmvuDy8WtUv-sd0TBwWVQs1rC-Lfxa_NDkLqpg50Cxp5Dxj0VPF1mx2Z...",
}

Parámetro	Descripción
not_before	Hora a la que el token se considera válido, en tiempo de época.
token_type	El valor del tipo de token. El único tipo que admite Microsoft Entra ID es Bearer.
access_token	El JSON Web Token (JWT) firmado que ha solicitado.
scope	Los ámbitos para los que el token es válido. También puede usar ámbitos para almacenar en caché los tokens para su posterior uso.
expires_in	El período de tiempo que el token es válido (en segundos).
refresh_token	Un token de actualización de OAuth 2.0. La aplicación puede usar este token para adquirir tokens adicionales una vez que expire el token actual. Los tokens de actualización tienen una duración larga. Puede usarlos para conservar el acceso a los recursos durante largos períodos de tiempo. Para obtener más información, consulte Azure AD B2C: referencia de tokens.

Las respuestas de error tienen un aspecto similar al siguiente:

{
    "error": "access_denied",
    "error_description": "The user revoked access to the app.",
}

Parámetro	Descripción
error	Una cadena de código de error que se puede usar para clasificar los tipos de errores que se producen. También puede usar la cadena para reaccionar frente a errores.
error_description	Un mensaje de error específico que puede ayudarlo a identificar la causa raíz de un error de autenticación.

3. Uso del token

Ahora que ha adquirido correctamente un token de acceso, puede usar el token en las solicitudes a las API web de back-end incluyéndolo en el encabezado Authorization:

GET /tasks
Host: mytaskwebapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...

4. Actualización del token

Los tokens de acceso y los tokens de identificación tienen una corta duración. Una vez expirados, debe actualizarlos para poder seguir obteniendo acceso a los recursos. Al actualizar el token de acceso, Azure AD B2C devuelve un nuevo token. En el token de acceso actualizado también se habrán actualizado los valores de notificación nbf (no antes), iat (emitido en) y exp (expiración). Todos los demás valores de notificación serán los mismos que los del token de acceso emitido originalmente.

Para actualizar el token, envíe otra solicitud POST al punto de conexión /token. Esta vez, proporcione el elemento refresh_token, en lugar de code:

POST https://{tenant}.b2clogin.com/{tenant}.onmicrosoft.com/{policy}/oauth2/v2.0/token HTTP/1.1

Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6
&scope=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 offline_access
&refresh_token=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&redirect_uri=urn:ietf:wg:oauth:2.0:oob

Parámetro	¿Necesario?	Descripción
{tenant}	Obligatorio	Nombre de su inquilino de Azure AD B2C.
{policy}	Obligatorio	El flujo de usuario usado para adquirir el token de actualización original. No puede usar un flujo de usuario diferente en esta solicitud.
client_id	Obligatorio	Identificador de aplicación asignado a la aplicación en Azure Portal.
client_secret	Sí, en Web Apps.	El secreto de la aplicación se generó en Azure Portal. Los secretos de cliente se usan en este flujo para escenarios de aplicaciones web, donde el cliente puede almacenar de forma segura un secreto de cliente. En escenarios de aplicación nativa (cliente público), los secretos de cliente no se pueden almacenar de forma segura y, por lo tanto, no se usan en esta llamada. Si usa un secreto de cliente, cámbielo periódicamente.
grant_type	Obligatorio	Tipo de concesión. Para este segmento del flujo de código de autorización, el tipo de concesión debe ser `refresh_token`.
scope	Recomendado	Una lista de ámbitos separada por espacios. Un valor de ámbito único indica a Microsoft Entra ID los dos permisos que se solicitan. El uso del identificador de cliente como ámbito indica que la aplicación necesita un token de acceso que se puede usar con su propio servicio o API web, representado por el mismo identificador de cliente. El ámbito `offline_access` indica que la aplicación necesitará un token de actualización para un acceso de larga duración a los recursos. También puede usar el ámbito `openid` para solicitar un token de identificador desde Azure AD B2C.
redirect_uri	Opcional	El URI de redirección de la aplicación en la que recibió el código de autorización.
refresh_token	Obligatorio	El token de actualización original que adquirió en el segundo segmento del flujo.