Flujo de código de autorización de OAuth 2.0 en Azure Active Directory B2C
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-b8bbc0b29dc6por 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 ejemplob2c_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. |
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 JWT firmado que ha solicitado. |
| scope | Los ámbitos para los que el token es válido. También puede usar los á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 son de larga duración y pueden usarse para conservar el acceso a los recursos durante largos periodos. 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. |
Usar su propio directorio de Azure AD B2C
Para probar estas solicitudes, lleve a cabo los siguientes pasos. Reemplace los valores de ejemplo que hemos usado en este artículo por los suyos propios.
- Cree un directorio de Azure AD B2C. Use el nombre del directorio en las solicitudes.
- Cree una aplicación para obtener un identificador de aplicación y un URI de redirección. Incluya un cliente nativo en la aplicación.
- Cree los flujos de usuario para obtener sus nombres de flujo de usuario.