Plataforma de identidad y flujo de código de autorización de OAuth 2.0

El tipo de concesión de código de autorización de OAuth 2.0 o flujo de código de autenticación permite a una aplicación cliente obtener acceso autorizado a recursos protegidos, como las API web. El flujo de código de autenticación requiere un agente de usuario que admita el redireccionamiento desde el servidor de autorización (la plataforma de identidad de Microsoft) a la aplicación. Por ejemplo, un explorador web, un escritorio o una aplicación móvil operados por un usuario para iniciar sesión en la aplicación y acceder a los datos.

En este artículo se describen los detalles del protocolo de bajo nivel necesarios solo al crear y emitir manualmente solicitudes HTTP sin procesar para ejecutar el flujo, lo que no se recomienda. En su lugar, use una biblioteca de autenticación integrada y compatible de Microsoft para obtener tokens de seguridad y llamar a las API web protegidas en las aplicaciones.

Aplicaciones que admiten el flujo de código de autenticación

Use el flujo de código de autenticación emparejado con clave de prueba para intercambio de códigos (PKCE) y OpenID Connect (OIDC) para obtener tokens de acceso y tokens de identificador en estos tipos de aplicaciones:

• Aplicación web de página única (SPA)
• Aplicación web estándar (basada en servidor)
• Aplicaciones de escritorio y móviles

Detalles del protocolo

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. Las aplicaciones que usan el flujo de código de autorización de OAuth 2.0 adquieren un access_token para incluir en las solicitudes a los recursos protegidos por la plataforma de identidad de Microsoft (normalmente API). Las aplicaciones también pueden solicitar nuevos identificadores y tokens de acceso para entidades autenticadas previamente mediante un mecanismo de actualización.

En este diagrama se muestra una vista de alto nivel del flujo de autenticación:

URI de redireccionamiento para aplicaciones de página única (SPA)

Los URI de redirección para SPA que usan el flujo de código de autenticación requieren una configuración especial.

• Agregue un URI de redireccionamiento que admita el flujo de código de autenticación con PKCE y el uso compartido de recursos entre orígenes (CORS): siga los pasos descritos en URI de redireccionamiento: MSAL.js 2.0 con flujo de código de autenticación.
• Actualizar un URI de redireccionamiento: Establezca el URI de redireccionamientotype a spa mediante el editor de manifiesto de la aplicación en el centro de administración de Microsoft Entra.

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. A pesar de esta compatibilidad con versiones anteriores, se recomienda usar el flujo de código de autenticación con PKCE para SPA.

Si intenta usar el flujo de código de autorización sin configurar CORS para el URI de redirección, verá este error en la consola:

access to XMLHttpRequest at 'https://login.microsoftonline.com/common/v2.0/oauth2/token' from origin 'yourApp.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

De ser así, visite el registro de aplicaciones y actualice el URI de redirección de la aplicación para usar el tipo spa.

Las aplicaciones no pueden usar un URI de redirección spa con flujos que no sean de SPA, por ejemplo, flujos de aplicaciones nativas o de credenciales de cliente. Para garantizar la seguridad y los procedimientos recomendados, la Plataforma de identidad de Microsoft devuelve un error si intenta usar un URI de redirección spa sin un encabezado Origin. De forma similar, la Plataforma de identidad de Microsoft también impide el uso de credenciales de cliente en todos los flujos en presencia de un encabezado Origin, para asegurarse de que los secretos no se usen desde dentro del explorador.

Solicitud de 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 . En esta solicitud de ejemplo, el cliente solicita los permisos openid, offline_access y https://graph.microsoft.com/mail.read del usuario.

Algunos permisos están restringidos a administradores; por ejemplo, la escritura de datos en el directorio de una organización mediante Directory.ReadWrite.All. Si la aplicación solicita acceso a uno de estos permisos desde un usuario de la organización, el usuario recibe un mensaje de error que indica que no está autorizado para dar el consentimiento a los permisos de la aplicación. Para solicitar acceso a los ámbitos restringidos para el administrador, debe solicitarlos directamente a un administrador global. Para obtener más información, consulte Permisos restringidos por el administrador.

A menos que se especifique lo contrario, no hay valores predeterminados para los parámetros opcionales. Sin embargo, hay un comportamiento predeterminado para una solicitud que omite los parámetros opcionales. El comportamiento predeterminado es iniciar sesión en el único usuario actual, mostrar el selector de cuenta si hay varios usuarios o mostrar la página de inicio de sesión si no hay ningún usuario que haya iniciado sesión.

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/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%2Fmail.read
&state=12345
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256

Parámetro	Obligatorio/opcional	Descripción
tenant	requerido	El valor {tenant} de la ruta de acceso de la solicitud se puede usar para controlar quién puede iniciar sesión en la aplicación. Los valores válidos son common, organizations, consumers y los identificadores de inquilinos. En el caso de los escenarios de invitado en los que se inicia la sesión de un usuario de un inquilino a otro inquilino, se debe proporcionar el identificador del inquilino para iniciar la sesión en el inquilino de recursos. Para más información, consulte Puntos de conexión.
client_id	requerido	El identificador de aplicación (cliente) que elcentro de administración de Microsoft Entra: experiencia de registro de aplicaciones asignó a la aplicación.
response_type	requerido	Debe incluir code para el flujo de código de autorización. También puede incluir id_token o token si usa el flujo híbrido.
redirect_uri	requerido	Parámetro redirect_uri de la aplicación, donde la aplicación puede enviar y recibir respuestas de autenticación. Debe coincidir exactamente con uno de los URI de redireccionamiento que registró en el Centro de administración de Microsoft Entra, excepto que debe estar codificado con dirección URL. En el caso de las aplicaciones nativas y móviles, use uno de los valores recomendados: https://login.microsoftonline.com/common/oauth2/nativeclient para aplicaciones que usan exploradores insertados, o http://localhost para aplicaciones que usan exploradores del sistema.
scope	requerido	Una lista separada por espacios de ámbitos que desea que el usuario consienta. Para el segmento /authorize de la solicitud, este parámetro puede abarcar varios recursos. Este valor permite que la aplicación obtenga consentimiento para varias API web a las que desea llamar.
response_mode	recomendado	Especifica la forma en la que la plataforma de identidad debe devolver el token solicitado a la aplicación. Valores admitidos: - query: valor predeterminado cuando se solicita un token de acceso. Proporciona el código como un parámetro de cadena de consulta en el URI de redireccionamiento. El parámetro query no se admite cuando se solicita un token de identificador mediante el flujo implícito. - fragment: valor predeterminado cuando se solicita un token de identificador mediante el flujo implícito. También se admite si solo se solicita un código. - form_post: ejecuta una prueba POST que contiene el código para el URI de redireccionamiento. Se admite cuando se solicita un código.
state	recomendado	Un valor incluido en la solicitud que también se devolverá en la respuesta del token. Puede ser una cadena de cualquier contenido que desee. Normalmente se usa un valor único generado de forma aleatoria para evitar los ataques de falsificación de solicitudes entre sitios. El valor también puede 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, podría codificar la página o la vista en la que se encontraba.
prompt	opcional	Indica el tipo de interacción necesaria con el usuario. Los valores válidos son login, none, consent y select_account. - prompt=login obliga al usuario a escribir sus credenciales en esa solicitud, negando el inicio de sesión único. - prompt=none es lo contrario. Garantiza que al usuario no se le presente ninguna solicitud interactiva. Si la solicitud no se puede completar sin notificaciones mediante el inicio de sesión único, la Plataforma de identidad de Microsoft devolverá un error interaction_required. - prompt=consent desencadena el cuadro de diálogo de consentimiento de OAuth después de que el usuario inicia sesión y solicita a este que conceda permisos a la aplicación. - prompt=select_account interrumpe el inicio de sesión único, lo que ofrece una experiencia de selección de cuentas en la que se enumeran todas las cuentas de la sesión o cualquier cuenta recordada, o bien una opción para usar una cuenta diferente.
login_hint	opcional	Puede usar este parámetro para rellenar previamente el campo de nombre de usuario y dirección de correo electrónico de la página de inicio de sesión del usuario. Las aplicaciones pueden usar este parámetro durante la reautenticación, una vez que se ha extraído la notificación opcional login_hint de un inicio de sesión anterior.
domain_hint	opcional	Si se incluye, la aplicación omite el proceso de detección basado en correo electrónico por el que pasa el usuario en la página de inicio de sesión, con lo que la experiencia de usuario será ligeramente más sencilla. Por ejemplo, enviarlos a su proveedor de identidades federado. Las aplicaciones pueden usar este parámetro durante la reautenticación, para lo que extraen tid de un inicio de sesión anterior.
code_challenge	recomendado/requerido	Se usa para proteger concesiones de código de autorización mediante la clave de prueba para intercambio de códigos (PKCE). Se requiere si se incluye code_challenge_method. Para obtener más información, consulte PKCE RFC. Este parámetro se recomienda ahora para todos los tipos de aplicaciones (tanto clientes públicos como confidenciales), y la Plataforma de identidades de Microsoft lo requiere para las aplicaciones de una página única mediante el flujo de código de autorización.
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 el cliente no admite SHA256. Si se excluye, se supone que code_challenge es texto no cifrado si se incluye code_challenge. La Plataforma de identidad de Microsoft admite tanto plain como S256. Para obtener más información, consulte PKCE RFC. Este parámetro es obligatorio para las aplicaciones de página única que usan el flujo de código de autorización.

En este punto, se le pide al usuario que escriba sus credenciales y que complete la autenticación. La Plataforma de identidad de Microsoft se asegura también de que el usuario ha dado su consentimiento a los permisos indicados en el parámetro de consulta scope. Si el usuario no ha dado su consentimiento a alguno de esos permisos, se le solicita al usuario su consentimiento para los permisos necesarios. Para obtener más información, consulte Permisos y consentimiento en la Plataforma de identidad de Microsoft.

Una vez que el usuario se autentica y otorga su consentimiento, la Plataforma de identidad de Microsoft devuelve una respuesta a la aplicación en el redirect_uri indicado mediante el método especificado en el parámetro response_mode.

Respuesta correcta

En este ejemplo se muestra una respuesta correcta mediante response_mode=query:

GET http://localhost?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345

Parámetro	Descripción
code	Parámetro authorization_code solicitado por la aplicación. La aplicación puede usar el código de autorización para solicitar un token de acceso para el recurso de destino. Los códigos de autorización tienen una duración breve. Normalmente, caducan al cabo de unos 10 minutos.
state	Si un parámetro state está incluido en la solicitud, debería aparecer el mismo valor en la respuesta. La aplicación debería comprobar que los valores de estado de la solicitud y la respuesta son idénticos.

También puede recibir un token de identificador si lo solicita y tiene habilitada la concesión implícita en el registro de aplicaciones. Este comportamiento se conoce a veces como flujo híbrido. Se usa en marcos como ASP.NET.

Respuesta de error

Las respuestas de error también pueden enviarse al redirect_uri para que la aplicación pueda controlarlas adecuadamente:

GET http://localhost?
error=access_denied
&error_description=the+user+canceled+the+authentication

Parámetro	Descripción
error	Una cadena de código de error que puede usarse para clasificar los tipos de errores y para reaccionar a los errores. Esta parte del error se incluye para que la aplicación pueda reaccionar correctamente al error, pero no explica en profundidad por qué se produjo un error.
error_description	Un mensaje de error específico que puede ayudar a un desarrollador a identificar la causa de un error de autenticación. Esta parte del error contiene la mayor parte de la información útil sobre por qué se produjo el error.

Códigos de error correspondientes a errores de puntos de conexión de autorización

En la tabla siguiente se describen los distintos códigos de error que pueden devolverse en el parámetro error de la respuesta de error.

Código de error	Descripción	Acción del cliente
invalid_request	Error de protocolo, como un parámetro obligatorio que falta.	Corrija el error y vuelva a enviar la solicitud. Se trata de un error de desarrollo que suele detectarse durante las pruebas iniciales.
unauthorized_client	La aplicación cliente no puede solicitar un código de autorización.	Este error puede producirse cuando la aplicación cliente no está registrada en Microsoft Entra ID o no está agregada al inquilino Microsoft Entra del usuario. La aplicación puede solicitar al usuario instrucciones para instalar la aplicación y agregarla a Microsoft Entra ID.
access_denied	El propietario del recurso ha denegado el consentimiento.	La aplicación cliente puede notificar al usuario que no puede continuar, salvo que este dé su consentimiento.
unsupported_response_type	El servidor de autorización no admite el tipo de respuesta de la solicitud.	Corrija el error y vuelva a enviar la solicitud. Se trata de un error de desarrollo que suele detectarse durante las pruebas iniciales. En el flujo híbrido, este error indica que debe habilitar la configuración de concesión implícita del token de identificador en el registro de la aplicación cliente.
server_error	El servidor ha detectado un error inesperado.	Vuelva a intentarlo. Estos errores pueden deberse a condiciones temporales. La aplicación cliente podría explicar al usuario que su respuesta se retrasó debido a un error temporal.
temporarily_unavailable	De manera temporal, el servidor está demasiado ocupado para atender la solicitud.	Vuelva a intentarlo. La aplicación podría explicar al usuario que su respuesta se retrasó debido a una condición temporal.
invalid_resource	El recurso de destino no es válido porque no existe, Microsoft Entra ID no lo encuentra o está configurado incorrectamente.	Este error indica que el recurso, en caso de existir, no se ha configurado en el inquilino. La aplicación puede solicitar al usuario instrucciones para instalar la aplicación y agregarla a Microsoft Entra ID.
login_required	Se encontraron demasiados usuarios o no se encontró ninguno.	El cliente solicitó la autenticación en modo silencioso (prompt=none), pero no se pudo encontrar un único usuario. Este error puede significar que hay varios usuarios activos en la sesión o que no hay ninguno. Este error tiene en cuenta el inquilino elegido. Por ejemplo, si hay dos cuentas de Microsoft Entra activas y una cuenta de Microsoft, y se elige consumers, la autenticación silenciosa funciona.
interaction_required	La solicitud requiere la interacción del usuario.	Es necesario realizar otro paso de autenticación o consentimiento. Vuelva a intentar realizar la solicitud sin prompt=none.

Solicitud de un token de identificador o flujo híbrido

Para saber quién es el usuario antes de canjear un código de autorización, es habitual que las aplicaciones también soliciten un token de identificador al solicitar el código de autorización. Este enfoque se conoce como flujo híbrido porque combina el OIDC con el flujo del código de autorización OAuth2.

El flujo híbrido se usa normalmente en aplicaciones web para representar una página para un usuario sin bloquear el canje del código, especialmente en ASP.NET. Las aplicaciones de una sola página y las aplicaciones web tradicionales se benefician de la menor latencia en este modelo.

El flujo híbrido es el mismo que el flujo de código de autorización descrito anteriormente, pero con tres adiciones. Todas estas adiciones son requerido para solicitar un token de identificador: nuevos ámbitos, un nuevo response_type y un nuevo parámetro nonce de consulta.

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code%20id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=fragment
&scope=openid%20offline_access%20https%3A%2F%2Fgraph.microsoft.com%2Fuser.read
&state=12345
&nonce=abcde
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256

Parámetros actualizado	Obligatorio/opcional	Descripción
response_type	requerido	La adición de id_token indica al servidor que la aplicación desea un token de identificador en la respuesta del punto de conexión /authorize.
scope	requerido	En el caso de los tokens de identificador, este parámetro debe actualizarse para incluir los ámbitos de token de identificador openid y, opcionalmente, profile y email.
nonce	requerido	Un valor incluido en la solicitud que ha generado la aplicación y que se incluye en el elemento id_token resultante como una notificación. La aplicación puede comprobar este valor para mitigar los ataques de reproducción de token. Normalmente, el valor es una cadena única aleatoria que se puede usar para identificar el origen de la solicitud.
response_mode	recomendado	Especifica el método que debe usarse para enviar el token resultante de nuevo a la aplicación. El valor predeterminado es query solo para un código de autorización, pero es fragment si la solicitud incluye un response_type id_token tal como se especifica en la especificación OpenID. Se recomienda que las aplicaciones usen form_post, especialmente al usar http://localhost como URI de redirección.

El uso de fragment como modo de respuesta provoca problemas para las aplicaciones web que leen el código del redireccionamiento. Los exploradores no pasan el fragmento al servidor web. En estas situaciones, las aplicaciones deben usar el modo de respuesta form_post para asegurarse de que todos los datos se envían al servidor.

Respuesta correcta

En este ejemplo se muestra una respuesta correcta mediante response_mode=fragment:

GET https://login.microsoftonline.com/common/oauth2/nativeclient#
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&id_token=eYj...
&state=12345

Parámetro	Descripción
code	El código de autorización que la aplicación solicitó. La aplicación puede utilizar el código de autorización para solicitar un token de acceso para el recurso de destino. Los códigos de autorización son de corta duración y normalmente expiran después de unos 10 minutos.
id_token	Un token de identificador para el usuario, emitido mediante la concesión implícita. Contiene una notificación c_hash especial, que es el hash del elemento code en la misma solicitud.
state	Si un parámetro state está incluido en la solicitud, debería aparecer el mismo valor en la respuesta. La aplicación debería comprobar que los valores de state de la solicitud y la respuesta sean idénticos.

Canje de un código por un token de acceso

Todos los clientes confidenciales tienen la opción de usar secretos de cliente o credenciales de certificado. La Plataforma de identidad de Microsoft genera los secretos compartidos simétricos. Las credenciales de certificado son claves asimétricas cargadas por el desarrollador. Para obtener más información, consulte Credenciales de certificado para la autenticación de aplicaciones en la Plataforma de identidad de Microsoft.

Para mayor seguridad, se recomienda usar las credenciales de certificados. Los clientes públicos, que incluyen aplicaciones nativas y aplicaciones de página única, no deben usar secretos ni certificados al canjear un código de autorización. Asegúrese siempre de que los URI de redirección incluyan el tipo de aplicación y sean únicos.

Solicitud de un token de acceso con un client_secret

Ahora que ha adquirido un authorization_code y que el usuario le ha concedido permiso, puede canjear el code por un access_token al recurso. Para canjear el code, envíe una solicitud POST al punto de conexión /token:

// Line breaks for legibility only

POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=11112222-bbbb-3333-cccc-4444dddd5555
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong 
&client_secret=sampleCredentia1s    // NOTE: Only required for web apps. This secret needs to be URL-Encoded.

Parámetro	Obligatorio/opcional	Descripción
tenant	requerido	El valor {tenant} de la ruta de acceso de la solicitud se puede usar para controlar quién puede iniciar sesión en la aplicación. Los valores válidos son common, organizations, consumers y los identificadores de inquilinos. Para más información, consulte Puntos de conexión.
client_id	requerido	El identificador de aplicación (cliente) que elcentro de administración de Microsoft Entra: registro de aplicaciones asignó a la aplicación.
scope	opcional	Lista de ámbitos separados por espacios. Todos los ámbitos deben provenir de un recurso único, junto con los ámbitos de OIDC (profile, openid, email). Para obtener más información, consulte Permisos y consentimiento en la Plataforma de identidad de Microsoft. Este parámetro es una extensión de Microsoft para el flujo de código de autorización, y se diseñó para permitir que las aplicaciones declaren el recurso para el que quieren el token durante el canje de tokens.
code	requerido	Parámetro authorization_code que has adquirido en el primer segmento del flujo.
redirect_uri	requerido	El mismo valor de redirect_uri usado para adquirir el parámetro authorization_code.
grant_type	requerido	Debe ser authorization_code para el flujo de código de autorización.
code_verifier	recomendado	Mismo parámetro code_verifier usado para obtener el parámetro authorization_code. 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.
client_secret	requerido para las aplicaciones web confidenciales	El secreto de la aplicación que creó en el portal de registro de aplicaciones para su aplicación. No use el secreto de aplicación en una aplicación nativa ni en una aplicación de página única, porque no es posible almacenar un client_secret de manera segura en los dispositivos ni páginas web. Es necesario para aplicaciones y API web, que pueden almacenar client_secret de forma segura en el servidor. Al igual que todos los parámetros de aquí, el secreto de cliente debe estar codificado como dirección URL antes de enviarse. El SDK se encarga de este paso. Para obtener más información sobre la codificación de URI, consulte la especificación sobre la sintaxis genérica de URI. También se admite el patrón de autenticación Básico de proporcionar credenciales en el encabezado de autorización, conforme a RFC 6749.

Solicitud de un token de acceso con una credencial de certificados

// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg

Parámetro	Obligatorio/opcional	Descripción
tenant	requerido	El valor {tenant} de la ruta de acceso de la solicitud se puede usar para controlar quién puede iniciar sesión en la aplicación. Los valores válidos son common, organizations, consumers y los identificadores de inquilinos. Para obtener más información, consulte Puntos de conexión.
client_id	requerido	El identificador de aplicación (cliente) que elcentro de administración de Microsoft Entra: registro de aplicaciones asignó a la aplicación.
scope	opcional	Lista de ámbitos separados por espacios. Todos los ámbitos deben provenir de un recurso único, junto con los ámbitos de OIDC (profile, openid, email). Para obtener más información, consulte permisos, consentimiento y ámbitos. Este parámetro es una extensión de Microsoft para el flujo de código de autorización. Esta extensión permite a las aplicaciones declarar el recurso para el que desean el token durante el canje de tokens.
code	requerido	Parámetro authorization_code que has adquirido en el primer segmento del flujo.
redirect_uri	requerido	El mismo valor de redirect_uri usado para adquirir el parámetro authorization_code.
grant_type	requerido	Debe ser authorization_code para el flujo de código de autorización.
code_verifier	recomendado	El mismo code_verifier que se usó para obtener el authorization_code. 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.
client_assertion_type	requerido para las aplicaciones web confidenciales	El valor debe establecerse en urn:ietf:params:oauth:client-assertion-type:jwt-bearer para usar una credencial de certificados.
client_assertion	requerido para las aplicaciones web confidenciales	Una aserción, que es un token web JSON (JWT), que debe crear y firmar con el certificado que ha registrado como credenciales de la aplicación. Lea el artículo sobre las credenciales de certificado para información sobre cómo registrar el certificado y el formato de la aserción.

Los parámetros son iguales que en el caso de la solicitud con un secreto compartido, salvo que el parámetro client_secret se sustituye por dos parámetros: client_assertion_type y client_assertion.

Respuesta correcta

En este ejemplo se muestra una respuesta de token correcta:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "token_type": "Bearer",
    "expires_in": 3599,
    "scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}

Parámetro	Descripción
access_token	El token de acceso solicitado. La aplicación puede usar este token para autenticarse en el recurso protegido, como una API web.
token_type	Indica el valor de tipo de token. El único tipo que Microsoft Entra ID admite es Bearer.
expires_in	Durante cuánto tiempo es válido el token de acceso, en segundos.
scope	Los ámbitos para los que el access_token es válido. Opcional. Este parámetro no es estándar y, si se omite, el token es para los ámbitos solicitados en el segmento inicial del flujo.
refresh_token	Un token de actualización de OAuth 2.0. La aplicación puede utilizar este token para obtener otros tokens de acceso una vez que expire el token de acceso actual. Los tokens de actualización tienen una duración larga. Pueden mantener el acceso a los recursos durante períodos prolongados. Para obtener más información sobre cómo actualizar un token de acceso, consulte Actualización del token de acceso más adelante en este artículo. Nota: Solo se proporciona si se solicitó el ámbito offline_access.
id_token	Un token web JSON. La aplicación puede descodificar los segmentos de este token para solicitar información sobre el usuario que ha iniciado sesión. La aplicación puede almacenar en caché los valores y mostrarlos, y los clientes confidenciales pueden usar este token para la autorización. Para más información sobre los parámetros id_tokens, consulte id_token reference. Nota: Solo se proporciona si se solicitó el ámbito openid.

Respuesta de error

Este ejemplo es una respuesta de error:

{
  "error": "invalid_scope",
  "error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/mail.read is not valid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "2016-01-09 02:02:12Z",
  "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
  "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}

Parámetro	Descripción
error	Una cadena de código de error que puede usarse para clasificar los tipos de errores y para reaccionar a los errores.
error_description	Un mensaje de error específico que puede ayudar a un desarrollador a identificar la causa de un error de autenticación.
error_codes	Una lista de los códigos de error específicos de STS que pueden ayudar en los diagnósticos.
timestamp	La hora a la que se produjo el error.
trace_id	Un identificador exclusivo para la solicitud que puede ayudar en los diagnósticos.
correlation_id	Un identificador exclusivo para la solicitud que puede ayudar en los diagnósticos entre componentes.

Códigos de error correspondientes a errores de puntos de conexión de token

Código de error	Descripción	Acción del cliente
invalid_request	Error de protocolo, como un parámetro obligatorio que falta.	Corrija la solicitud o el registro de la aplicación y vuelva a enviar la solicitud.
invalid_grant	El código de autorización o el comprobador de código PKCE no son válidos o han expirado.	Intente una nueva solicitud para el punto de conexión /authorize y compruebe que el parámetro code_verifier era correcto.
unauthorized_client	El cliente autenticado no está autorizado para usar este tipo de concesión de autorización.	Este error puede producirse cuando la aplicación cliente no está registrada en Microsoft Entra ID o no está agregada al inquilino Microsoft Entra del usuario. La aplicación puede solicitar al usuario instrucciones para instalar la aplicación y agregarla a Microsoft Entra ID.
invalid_client	Se produjo un error de autenticación de cliente.	Las credenciales del cliente no son válidas. Para corregirlo, el administrador de la aplicación actualiza las credenciales.
unsupported_grant_type	El servidor de autorización no admite el tipo de concesión de autorización.	Cambie el tipo de concesión de la solicitud. Este tipo de error solo debe producirse durante el desarrollo y detectarse en las pruebas iniciales.
invalid_resource	El recurso de destino no es válido porque no existe, Microsoft Entra ID no lo encuentra o está configurado incorrectamente.	Este código indica que el recurso, si existe, no se ha configurado en el inquilino. La aplicación puede solicitar al usuario instrucciones para instalar la aplicación y agregarla a Microsoft Entra ID.
interaction_required	No es estándar, ya que la especificación de OIDC exige este código solo en el punto de conexión /authorize. La solicitud requiere la interacción del usuario. Por ejemplo, se requiere otro paso de autenticación.	Vuelva a tratar de realizar la solicitud /authorize con los mismos ámbitos.
temporarily_unavailable	De manera temporal, el servidor está demasiado ocupado para atender la solicitud.	Vuelva a intentar la solicitud después de un pequeño retraso. La aplicación podría explicar al usuario que su respuesta se retrasó debido a una condición temporal.
consent_required	La solicitud requiere el consentimiento del usuario. Este error no es estándar. Normalmente solo se devuelve en el punto de conexión /authorize según las especificaciones de OIDC. Se devuelve cuando se usó un parámetro scope en el flujo de canje de código que la aplicación cliente no tiene permiso para solicitar.	El cliente debe devolver al usuario al punto de conexión /authorize con el ámbito correcto para desencadenar el consentimiento.
invalid_scope	El ámbito solicitado por la aplicación no es válido.	Actualice el valor del parámetro scope en la solicitud de autenticación por un valor válido.

Nota:

Es posible que las aplicaciones de página única reciban un error invalid_request que indica que solo se permite el canje de tokens entre orígenes para el tipo de cliente "Aplicación de página única". Esto indica que el URI de redirección usado para solicitar el token no se ha marcado como un URI de redirección spa. Revise los pasos de registro de aplicaciones sobre cómo habilitar este flujo.

Uso del token de acceso

Ahora que ha adquirido correctamente un access_token, puede usar el token en solicitudes a las API web mediante su inclusión en el encabezado Authorization:

GET /v1.0/me/messages
Host: https://graph.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...

Actualización del token de acceso

Los tokens de acceso tienen una corta duración. Para seguir accediendo a los recursos, actualícelos después de que expiren. Para ello, envíe otra solicitud POST al punto de conexión /token. Proporcione el elemento refresh_token, en lugar de code. Los tokens de actualización son válidos para todos los permisos para los que el cliente ya ha recibido consentimiento. Por ejemplo, para solicitar un nuevo token de acceso para scope=api://contoso.com/api/UseResource, se puede usar un token de actualización emitido en una solicitud para scope=mail.read.

Los tokens de actualización para aplicaciones web y aplicaciones nativas no tienen una duración especificada. Normalmente, las duraciones de este tipo de tokens son relativamente largas. Sin embargo, en algunos casos, los tokens de actualización expiran, se revocan o carecen de privilegios suficientes para realizar la acción. La aplicación debe esperar y controlar los errores que devuelve el punto de conexión de emisión de tokens. Las aplicaciones de página única obtienen un token con una vigencia de 24 horas, lo que requiere una nueva autenticación cada día. Esta acción se puede realizar de forma silenciosa en un iframe cuando las cookies de terceros están habilitadas. Debe realizarse en un marco de nivel superior, ya sea en la navegación de página completa o una ventana emergente, en exploradores sin cookies de terceros, como Safari.

Los tokens de actualización no se revocarán cuando se usen para adquirir nuevos tokens de acceso. Se espera que descarte el token de actualización anterior. La especificación de OAuth 2.0 indica: "El servidor de autorización PODRÍA emitir un token de actualización nuevo, en cuyo caso el cliente DEBE descartar el token de actualización anterior y reemplazarlo por el token de actualización nuevo. El servidor de autorización PODRÍA revocar el token de actualización anterior después de la emisión de un token de actualización nuevo al cliente".

Importante

En el caso de los tokens de actualización enviados a un URI de redirección registrado como spa, el token de actualización expira después de 24 horas. Los tokens de actualización adicionales adquiridos con el token de actualización inicial trasladan esa hora de expiración, por lo que las aplicaciones deben estar preparadas para volver a ejecutar el flujo de código de autorización con una autenticación interactiva para obtener un nuevo token de actualización cada 24 horas. Los usuarios no tienen que escribir sus credenciales y, normalmente, ni siquiera ven ninguna experiencia de usuario, solo una recarga de la aplicación. El explorador debe visitar la página de inicio de sesión en un marco de nivel superior para ver la sesión de inicio de sesión. Esto se debe a las características de privacidad en los exploradores, que bloquean las cookies de terceros.

// Line breaks for legibility only

POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=sampleCredentia1s    // NOTE: Only required for web apps. This secret needs to be URL-Encoded

Parámetro	Tipo	Descripción
tenant	requerido	El valor {tenant} de la ruta de acceso de la solicitud se puede usar para controlar quién puede iniciar sesión en la aplicación. Los valores válidos son common, organizations, consumers y los identificadores de inquilinos. Para más información, consulte Puntos de conexión.
client_id	requerido	El identificador de aplicación (cliente) que elcentro de administración de Microsoft Entra: experiencia de registro de aplicaciones asignó a la aplicación.
grant_type	requerido	Debe ser refresh_token para este segmento del flujo de código de autorización.
scope	opcional	Una lista de ámbitos separada por espacios. Los ámbitos solicitados en este segmento deben ser un subconjunto de los ámbitos solicitados en el segmento original de la solicitud authorization_code o uno equivalente a aquel. Si los ámbitos especificados en esta solicitud abarcan varios servidores de recursos, la Plataforma de identidad de Microsoft devuelve un token para el recurso especificado en el primer ámbito. Para obtener más información, consulte Permisos y consentimiento en la Plataforma de identidad de Microsoft.
refresh_token	requerido	El refresh_token que adquirió en el segundo segmento del flujo.
client_secret	necesario para las aplicaciones web	El secreto de la aplicación que creó en el portal de registro de aplicaciones para su aplicación. No debería utilizarse en una aplicación nativa, porque un client_secret no se puede almacenar de manera confiable en los dispositivos. Es necesario para aplicaciones y API web, que pueden almacenar client_secret de forma segura en el servidor. Este secreto debe estar codificado como dirección URL. Para obtener más información, consulte la especificación sobre la sintaxis genérica de URI.

Respuesta correcta

En este ejemplo se muestra una respuesta de token correcta:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "token_type": "Bearer",
    "expires_in": 3599,
    "scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}

Parámetro	Descripción
access_token	El token de acceso solicitado. La aplicación puede usar este token para autenticarse en el recurso protegido, como una API web.
token_type	Indica el valor de tipo de token. El único tipo que admite Microsoft Entra ID es Bearer.
expires_in	Durante cuánto tiempo es válido el token de acceso, en segundos.
scope	Los ámbitos para los que el access_token es válido.
refresh_token	Un nuevo token de actualización de OAuth 2.0. Reemplace el token de actualización antiguo con este token de actualización recientemente adquirido para asegurar que los tokens de actualización sigan siendo válidos durante el mayor tiempo posible. Nota: Solo se proporciona si se solicitó el ámbito offline_access.
id_token	Un token web JSON sin firmar. La aplicación puede descodificar los segmentos de este token para solicitar información sobre el usuario que ha iniciado sesión. La aplicación puede almacenar en caché los valores y mostrarlos, pero no debe depender de estos para ningún límite de seguridad o autorización. Para obtener más información sobre id_token, consulte los Tokens de identificador de la Plataforma de identidad de Microsoft. Nota: Solo se proporciona si se solicitó el ámbito openid.

Advertencia

No intente validar ni leer tokens para ninguna API de su propiedad, incluidos los tokens de este ejemplo, en el código. Los tokens de los servicios de Microsoft pueden usar un formato especial que no se validará como un JWT y también se pueden cifrar para los usuarios consumidores (cuenta Microsoft). Aunque la lectura de tokens es una herramienta útil de depuración y aprendizaje, no tome dependencias de esto en el código ni asuma detalles sobre los tokens que no son para una API que controle.

Respuesta de error

{
  "error": "invalid_scope",
  "error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/mail.read is not valid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "2016-01-09 02:02:12Z",
  "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
  "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}

Parámetro	Descripción
error	Una cadena de código de error que puede usarse para clasificar los tipos de errores y para reaccionar a los errores.
error_description	Un mensaje de error específico que puede ayudar a un desarrollador a identificar la causa de un error de autenticación.
error_codes	Una lista de los códigos de error específicos de STS que pueden ayudar en los diagnósticos.
timestamp	La hora a la que se produjo el error.
trace_id	Un identificador exclusivo para la solicitud que puede ayudar en los diagnósticos.
correlation_id	Un identificador exclusivo para la solicitud que puede ayudar en los diagnósticos entre componentes.

Para ver una descripción de los códigos de error y la acción recomendada que tiene que realizar el cliente, consulte la sección Códigos de error correspondientes a errores de puntos de conexión de token.

Pasos siguientes

• Repase los ejemplos de MSAL JS para comenzar a codificar.
• Obtenga información sobre los escenarios de intercambio de tokens.