Compartir a través de


Autorización del acceso a aplicaciones web de Azure Active Directory mediante el flujo de concesión de código de OAuth 2.0

Advertencia

Este contenido está destinado al punto de conexión antiguo de Azure AD v1.0. Use la plataforma de identidad de Microsoft para los nuevos proyectos.

Nota:

Si no indica al servidor qué recurso planea llamar, el servidor no desencadenará las directivas de acceso condicional para ese recurso. Por lo tanto, para activar el MFA, deberá incluir un recurso en la dirección URL.

Azure Active Directory (Azure AD) usa OAuth 2.0 para permitirle autorizar el acceso a aplicaciones web y API web en el inquilino de Azure AD. Esta guía es independiente del lenguaje y describe cómo enviar y recibir mensajes HTTP sin usar ninguna de nuestras bibliotecas de código abierto.

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. Se usa para realizar la autenticación y autorización en la mayoría de los tipos de aplicación, incluidas las aplicaciones web y las aplicaciones instaladas de forma nativa.

Registre su aplicación con el inquilino de Azure Active Directory (AD)

En primer lugar, registre la aplicación con el inquilino de Azure Active Directory (Azure AD). Esto le proporcionará un identificador de aplicación para la aplicación, así como habilitarlo para recibir tokens.

  1. Inicie sesión en Azure Portal.

  2. Elija el inquilino de Azure AD seleccionando su cuenta en la esquina superior derecha de la página, seguida de seleccionar la navegación Cambiar directorio y, a continuación, seleccionar el inquilino adecuado.

    • Omita este paso si solo tiene un inquilino de Azure AD en su cuenta o si ya ha seleccionado el inquilino de Azure AD adecuado.
  3. En Azure Portal, busque y seleccione Azure Active Directory.

  4. En el menú izquierdo de Azure Active Directory , seleccione Registros de aplicaciones y, a continuación, seleccione Nuevo registro.

  5. Siga las indicaciones y cree una nueva aplicación. No importa si es una aplicación web o una aplicación cliente pública (& escritorio móvil) para este tutorial, pero si desea ejemplos específicos para aplicaciones web o aplicaciones cliente públicas, consulte nuestras guías de inicio rápido .

    • Name es el nombre de la aplicación y describe la aplicación para los usuarios finales.
    • En Tipos de cuenta admitidos, seleccione Cuentas en cualquier directorio organizativo y cuentas personales de Microsoft.
    • Proporcione el URI de redirección. En el caso de las aplicaciones web, esta es la dirección URL base de la aplicación donde los usuarios pueden iniciar sesión. Por ejemplo: http://localhost:12345. Azure AD lo utiliza para devolver respuestas de token a los clientes públicos en móviles y escritorios. Escriba un valor específico de la aplicación. Por ejemplo: http://MyFirstAADApp.
  6. Una vez completado el registro, Azure AD asignará a la aplicación un identificador de cliente único (el identificador de aplicación ). Necesita este valor en las secciones siguientes, así que cópielo desde la página de la aplicación.

  7. Para buscar la aplicación en Azure Portal, seleccione Registros de aplicaciones y, a continuación, seleccione Ver todas las aplicaciones.

Flujo de autorización de OAuth 2.0

En un nivel alto, todo el flujo de autorización de una aplicación tiene un aspecto similar al siguiente:

Flujo de código de autenticación de OAuth

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, el cliente indica los permisos que necesita adquirir del usuario. Para obtener el punto de conexión de autorización de OAuth 2.0 para tu inquilino, selecciona Registros de aplicaciones > Puntos de conexión en el portal de Azure.

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%3A12345
&response_mode=query
&resource=https%3A%2F%2Fservice.contoso.com%2F
&state=12345
Parámetro Tipo Descripción
arrendatario Obligatorio Se puede usar el valor {tenant} de la ruta de acceso de la solicitud para controlar quién puede iniciar sesión en la aplicación. Los valores permitidos son identificadores de inquilino, por ejemplo, 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 o contoso.onmicrosoft.com o common para tokens independientes del inquilino.
ID de cliente Obligatorio El identificador de aplicación asignado a la aplicación cuando lo registró con Azure AD. Puede encontrarlo en Azure Portal. Haga clic en Azure Active Directory en la barra lateral de servicios, haga clic en Registros de aplicaciones y elija la aplicación.
tipo_de_respuesta Obligatorio Debe incluir code para el flujo de código de autorización.
URI de redirección recomendado La URI de redirección de tu aplicación, donde la aplicación puede enviar y recibir respuestas de autenticación. Debe coincidir exactamente con uno de los redirect_uris que registró en el portal, excepto que debe estar codificado en formato URL. En el caso de las aplicaciones nativas y móviles, debe usar el valor predeterminado de https://login.microsoftonline.com/common/oauth2/nativeclient.
modo_de_respuesta opcional Especifica el método que debe usarse para enviar el token resultante de nuevo a la aplicación. Puede ser query, fragment o form_post. query proporciona el código como parámetro de cadena de consulta en el URI de redirección. Si solicita un token de identificador mediante el flujo implícito, no puede usar query como se especifica en la especificación de OpenID. Si solo solicita el código, puede usar query, fragmento form_post. form_post ejecuta un POST que contiene el código a tu URI de redirección. El valor predeterminado es query para un flujo de código.
estado recomendado Un valor incluido en la solicitud que también se devolverá en la respuesta del token. Normalmente se usa un valor único generado aleatoriamente para evitar 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 o vista en la que estaban.
recurso recomendado URI del identificador de aplicación de la API web de destino (recurso protegido). Para buscar el URI del identificador de aplicación, en Azure Portal, haga clic en Azure Active Directory, en Registros de aplicaciones, abra la página Configuración de la aplicación y, a continuación, haga clic en Propiedades. También puede ser un recurso externo como https://graph.microsoft.com. Esto es necesario en una de las solicitudes de autorización o token. Para asegurarse de que hay menos mensajes de autenticación, colóquelo en la solicitud de autorización para asegurarse de que el consentimiento se recibe del usuario.
alcance Ignorado En el caso de las aplicaciones de Azure AD v1, los ámbitos deben configurarse estáticamente en Azure Portal en la configuración de aplicaciones, permisos necesarios.
inmediato opcional Indique el tipo de interacción del usuario necesaria.

Los valores válidos son:

login: se le pedirá al usuario que vuelva a autenticarse.

select_account: se pide al usuario que seleccione una cuenta, interrumpiendo el inicio de sesión único. El usuario puede seleccionar una cuenta de inicio de sesión existente, escribir sus credenciales para una cuenta recordada o elegir usar una cuenta diferente por completo.

consentimiento: se ha concedido el consentimiento del usuario, pero debe actualizarse. Se le pedirá al usuario que dé su consentimiento.

admin_consent: se debe pedir a un administrador que dé su consentimiento en nombre de todos los usuarios de su organización.

sugerencia_de_inicio_de_sesión opcional Se puede usar para rellenar previamente el campo nombre de usuario o dirección de correo electrónico de la página de inicio de sesión del usuario, si conoce su nombre de usuario con antelación. A menudo, las aplicaciones usan este parámetro durante la reautenticación, habiendo ya extraído el nombre de usuario de un inicio de sesión anterior mediante la notificación preferred_username.
indicador_de_dominio opcional Proporciona una sugerencia sobre el inquilino o dominio que el usuario debe usar para iniciar sesión. El valor del domain_hint es un dominio registrado para el inquilino. Si el inquilino está federado en un directorio local, AAD redirige al servidor de federación de inquilinos especificado.
método_de_desafío_de_código recomendado Método utilizado para codificar code_verifier para el parámetro code_challenge. Puede ser uno de plain o S256. Si se excluye, se supone que code_challenge es texto no cifrado si se incluye code_challenge. Azure AAD v1.0 admite tanto plain como S256. Para obtener más información, consulte PKCE RFC.
desafío_de_código recomendado Se usa para proteger las concesiones de códigos de autorización a través de la Clave de Prueba para Intercambio de Códigos (PKCE) desde un cliente nativo o público. Se requiere si se incluye code_challenge_method. Para obtener más información, consulte PKCE RFC.

Nota:

Si el usuario forma parte de una organización, un administrador de la organización puede dar su consentimiento o rechazarlo en nombre del usuario, o permitir que el usuario dé su consentimiento. El usuario tiene la opción de dar su consentimiento solo cuando el administrador lo permita.

En este momento, se pide al usuario que escriba sus credenciales y dé su consentimiento a los permisos solicitados por la aplicación en Azure Portal. Una vez que el usuario se autentica y otorga su consentimiento, Azure AD envía una respuesta a la aplicación en la dirección de la redirect_uri solicitud con el código.

Respuesta exitosa

Una respuesta correcta podría tener este aspecto:

GET  HTTP/1.1 302 Found
Location: http://localhost:12345/?code= AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrqqf_ZT_p5uEAEJJ_nZ3UmphWygRNy2C3jJ239gV_DBnZ2syeg95Ki-374WHUP-i3yIhv5i-7KU2CEoPXwURQp6IVYMw-DjAOzn7C3JCu5wpngXmbZKtJdWmiBzHpcO2aICJPu1KvJrDLDP20chJBXzVYJtkfjviLNNW7l7Y3ydcHDsBRKZc3GuMQanmcghXPyoDg41g8XbwPudVh7uCmUponBQpIhbuffFP_tbV8SNzsPoFz9CLpBCZagJVXeqWoYMPe2dSsPiLO9Alf_YIe5zpi-zY4C3aLw5g9at35eZTfNd0gBRpR5ojkMIcZZ6IgAA&session_state=7B29111D-C220-4263-99AB-6F6E135D75EF&state=D79E5777-702E-4260-9A62-37F75FF22CCE
Parámetro Descripción
consentimiento_del_administrador El valor es True si un administrador consintió en un aviso de solicitud de consentimiento.
código Código de autorización que solicitó 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.
estado_de_la_sesión Valor único que identifica la sesión de usuario actual. Este valor es un GUID, pero debe tratarse como un valor opaco que se pasa sin ser examinado.
estado Si se incluye un parámetro de estado en la solicitud, debe aparecer el mismo valor en la respuesta. Es recomendable que la aplicación compruebe que los valores de estado de la solicitud y la respuesta son idénticos antes de usar la respuesta. Esto ayuda a detectar ataques de falsificación de solicitud entre sitios (CSRF) contra el cliente.

Respuesta de error

También se pueden enviar respuestas de error a redirect_uri para que la aplicación pueda controlarlas correctamente.

GET http://localhost:12345/?
error=access_denied
&error_description=the+user+canceled+the+authentication
Parámetro Descripción
error Valor de código de error definido en la sección 5.2 del marco de autorización de OAuth 2.0. En la tabla siguiente se describen los códigos de error que devuelve Azure AD.
descripción_del_error Descripción más detallada del error. Este mensaje no está pensado para ser amigable para el usuario final.
estado El valor de estado es un valor no reutilizado generado aleatoriamente que se envía en la solicitud y se devuelve en la respuesta para evitar ataques de falsificación de solicitudes entre sitios (CSRF).

Códigos de error para errores del endpoint 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
solicitud no válida 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 y normalmente se detecta durante las pruebas iniciales.
cliente_no_autorizado No se permite que la aplicación cliente solicite un código de autorización. Esto suele ocurrir cuando la aplicación cliente no está registrada en Azure AD o no se agrega al inquilino de Azure AD del usuario. La aplicación puede solicitar al usuario instrucciones para instalar la aplicación y agregarla a Azure AD.
acceso denegado El propietario del recurso ha denegado el consentimiento. La aplicación cliente puede notificar al usuario que no puede continuar a menos que el usuario dé su consentimiento.
tipo_de_respuesta_no_soportado El servidor de autorización no admite el tipo de respuesta en la solicitud. Corrija el error y vuelva a enviar la solicitud. Se trata de un error de desarrollo y normalmente se detecta durante las pruebas iniciales.
error_del_servidor El servidor ha detectado un error inesperado. Vuelva a hacer la solicitud. Estos errores pueden deberse a condiciones temporales. La aplicación cliente puede explicar al usuario que su respuesta se retrasa debido a un error temporal.
no_disponible_temporalmente De manera temporal, el servidor está demasiado ocupado para atender la solicitud. Vuelva a hacer la solicitud. La aplicación cliente puede explicar al usuario que su respuesta se retrasa debido a una condición temporal.
recurso_inválido El recurso de destino no es válido porque no existe, Azure AD no puede encontrarlo o no está configurado correctamente. Esto indica que el recurso, si existe, no se ha configurado en el arrendatario. La aplicación puede solicitar al usuario instrucciones para instalar la aplicación y agregarla a Azure AD.

Uso del código de autorización para solicitar un token de acceso

Ahora que ha adquirido un código de autorización y el usuario le ha concedido permiso, puede canjear el código de un token de acceso al recurso deseado mediante el envío de una solicitud POST al /token punto de conexión:

// Line breaks for legibility only

POST /{tenant}/oauth2/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&client_id=2d4d11a2-f814-46a7-890a-274a72a7309e
&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrqqf_ZT_p5uEAEJJ_nZ3UmphWygRNy2C3jJ239gV_DBnZ2syeg95Ki-374WHUP-i3yIhv5i-7KU2CEoPXwURQp6IVYMw-DjAOzn7C3JCu5wpngXmbZKtJdWmiBzHpcO2aICJPu1KvJrDLDP20chJBXzVYJtkfjviLNNW7l7Y3ydcHDsBRKZc3GuMQanmcghXPyoDg41g8XbwPudVh7uCmUponBQpIhbuffFP_tbV8SNzsPoFz9CLpBCZagJVXeqWoYMPe2dSsPiLO9Alf_YIe5zpi-zY4C3aLw5g9at35eZTfNd0gBRpR5ojkMIcZZ6IgAA
&redirect_uri=https%3A%2F%2Flocalhost%3A12345
&resource=https%3A%2F%2Fservice.contoso.com%2F
&client_secret=p@ssw0rd

//NOTE: client_secret only required for web apps
Parámetro Tipo Descripción
arrendatario Obligatorio Se puede usar el valor {tenant} de la ruta de acceso de la solicitud para controlar quién puede iniciar sesión en la aplicación. Los valores permitidos son identificadores de inquilino, por ejemplo, 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 o contoso.onmicrosoft.com o common para tokens independientes del inquilino.
ID de cliente Obligatorio El identificador de aplicación asignado a la aplicación cuando lo registró con Azure AD. Puede encontrarlo en Azure Portal. El identificador de aplicación se muestra en la configuración del registro de la aplicación.
tipo_de_subvención Obligatorio Debe ser authorization_code para el flujo de código de autorización.
código Obligatorio El authorization_code que adquirió en la sección anterior
URI de redirección Obligatorio Se ha registrado algo redirect_urien la aplicación cliente.
secreto_del_cliente necesario para aplicaciones web, no permitidas para clientes públicos El secreto de la aplicación que creaste en el portal de Azure para tu aplicación en Claves. No se puede usar en una aplicación nativa (cliente público), ya que client_secrets no se pueden almacenar de forma confiable en los dispositivos. Es necesario para las aplicaciones web y las API web (todos los clientes confidenciales), que tienen la capacidad de almacenar client_secret de forma segura en el lado del servidor. La client_secret debe estar codificada con dirección URL antes de enviarse.
recurso recomendado URI del identificador de aplicación de la API web de destino (recurso protegido). Para buscar el URI del identificador de aplicación, en Azure Portal, haga clic en Azure Active Directory, en Registros de aplicaciones, abra la página Configuración de la aplicación y, a continuación, haga clic en Propiedades. También puede ser un recurso externo como https://graph.microsoft.com. Esto es necesario en una de las solicitudes de autorización o token. Para asegurarse de que hay menos mensajes de autenticación, colóquelo en la solicitud de autorización para asegurarse de que el consentimiento se recibe del usuario. Tanto en la solicitud de autorización como en la solicitud de token, los parámetros del recurso deben coincidir.
verificador_de_código opcional 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.

Para buscar el URI del identificador de aplicación, en Azure Portal, haga clic en Azure Active Directory, en Registros de aplicaciones, abra la página Configuración de la aplicación y, a continuación, haga clic en Propiedades.

Respuesta exitosa

Azure AD devuelve un token de acceso tras una respuesta correcta. Para minimizar las llamadas de red de la aplicación cliente y su latencia asociada, la aplicación cliente debe almacenar en caché los tokens de acceso para la duración del token especificada en la respuesta de OAuth 2.0. Para determinar la duración del token, use el valor de parámetro expires_in o expires_on.

Si un recurso de API web devuelve un invalid_token código de error, esto podría indicar que el recurso ha determinado que el token ha expirado. Si los tiempos del reloj del cliente y del recurso son diferentes (conocidos como "asimetría de hora"), el recurso podría considerar que el token expiraba antes de que el token se borre de la caché del cliente. Si esto ocurre, borre el token de la memoria caché, incluso si todavía está dentro de su duración calculada.

Una respuesta correcta podría tener este aspecto:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ",
  "token_type": "Bearer",
  "expires_in": "3600",
  "expires_on": "1388444763",
  "resource": "https://service.contoso.com/",
  "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4rTfgV29ghDOHRc2B-C_hHeJaJICqjZ3mY2b_YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfcUl4VBbiSHZyd1NVZG5QTIOcbObu3qnLutbpadZGAxqjIbMkQ2bQS09fTrjMBtDE3D6kSMIodpCecoANon9b0LATkpitimVCrl-NyfN3oyG4ZCWu18M9-vEou4Sq-1oMDzExgAf61noxzkNiaTecM-Ve5cq6wHqYQjfV9DOz4lbceuYCAA",
  "scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
  "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83ZmU4MTQ0Ny1kYTU3LTQzODUtYmVjYi02ZGU1N2YyMTQ3N2UvIiwiaWF0IjoxMzg4NDQwODYzLCJuYmYiOjEzODg0NDA4NjMsImV4cCI6MTM4ODQ0NDc2MywidmVyIjoiMS4wIiwidGlkIjoiN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlIiwib2lkIjoiNjgzODlhZTItNjJmYS00YjE4LTkxZmUtNTNkZDEwOWQ3NGY1IiwidXBuIjoiZnJhbmttQGNvbnRvc28uY29tIiwidW5pcXVlX25hbWUiOiJmcmFua21AY29udG9zby5jb20iLCJzdWIiOiJKV3ZZZENXUGhobHBTMVpzZjd5WVV4U2hVd3RVbTV5elBtd18talgzZkhZIiwiZmFtaWx5X25hbWUiOiJNaWxsZXIiLCJnaXZlbl9uYW1lIjoiRnJhbmsifQ."
}

Parámetro Descripción
token de acceso Token de acceso solicitado. Se trata de una cadena opaca: depende de lo que el recurso espera recibir y no está pensado para que el cliente examine. La aplicación puede usar este token para autenticarse en el recurso protegido, como una API web.
tipo_de_token Indica el valor de tipo de token. El único tipo que admite Azure AD es Bearer. Para obtener más información sobre los tokens de portador, consulte Marco de autorización de OAuth2.0: Uso de tokens de portador (RFC 6750)
expira_en Período de validez del token de acceso (en segundos).
vence_el Hora a la que expira el token de acceso. La fecha se representa como el número de segundos de 1970-01-01T0:0:0Z UTC hasta la hora de expiración. Este valor se utiliza para determinar la duración de los tokens almacenados en caché.
recurso El URI del identificador de aplicación de la API web (recurso protegido).
alcance Autorización de suplantación otorgada a la aplicación cliente. El permiso predeterminado es user_impersonation. El propietario del recurso protegido puede registrar valores adicionales en Azure AD.
token de actualización Un token de actualización de OAuth 2.0. La aplicación puede usar este token para adquirir tokens de acceso adicionales después de que expire el token de acceso actual. Los tokens de actualización son de larga duración y se pueden usar para mantener el acceso a los recursos durante períodos prolongados.
token de identificación JSON Web Token (JWT) sin firmar que representa un token de ID. La aplicación puede descodificar en base64Url los segmentos de este token para solicitar información sobre el usuario que inició sesión. La aplicación puede almacenar en caché los valores y mostrarlos, pero no debe confiar en ellos para los límites de autorización o seguridad.

Para obtener más información sobre los tokens web JSON, consulte la especificación de borrador de JWT IETF. Para más información sobre id_tokens, consulte el flujo de OpenID Connect v1.0.

Respuesta de error

Los errores del punto de conexión de emisión de tokens son códigos de error HTTP, ya que el cliente llama directamente al punto de conexión de emisión de tokens. Además del código de estado HTTP, el punto de conexión de emisión de tokens de Azure AD también devuelve un documento JSON con objetos que describen el error.

Una respuesta de error de ejemplo podría tener este aspecto:

{
  "error": "invalid_grant",
  "error_description": "AADSTS70002: Error validating credentials. AADSTS70008: The provided authorization code or refresh token is expired. Send a new interactive authorization request for this user and resource.\r\nTrace ID: 3939d04c-d7ba-42bf-9cb7-1e5854cdce9e\r\nCorrelation ID: a8125194-2dc8-4078-90ba-7b6592a7f231\r\nTimestamp: 2016-04-11 18:00:12Z",
  "error_codes": [
    70002,
    70008
  ],
  "timestamp": "2016-04-11 18:00:12Z",
  "trace_id": "3939d04c-d7ba-42bf-9cb7-1e5854cdce9e",
  "correlation_id": "a8125194-2dc8-4078-90ba-7b6592a7f231"
}
Parámetro Descripción
error Una cadena de código de error que puede utilizarse para clasificar los tipos de errores que se producen y para reaccionar ante ellos.
descripción_del_error Un mensaje de error específico que puede ayudar a un desarrollador a identificar la causa de un error de autenticación.
códigos_de_error Una lista de los códigos de error específicos de STS que pueden ayudar en los diagnósticos.
Marca de tiempo La hora a la que se produjo el error.
trace_id Un identificador exclusivo para la solicitud que puede ayudar en los diagnósticos.
identificador_de_correlación Un identificador exclusivo para la solicitud que puede ayudar en los diagnósticos entre componentes.

Códigos de estado HTTP

En la tabla siguiente se enumeran los códigos de estado HTTP que devuelve el punto de conexión de emisión de tokens. En algunos casos, el código de error es suficiente para describir la respuesta, pero si hay errores, debe analizar el documento JSON adjunto y examinar su código de error.

Código HTTP Descripción
400 Código HTTP predeterminado. Se usa en la mayoría de los casos y suele deberse a una solicitud con formato incorrecto. Corrija el error y vuelva a enviar la solicitud.
401 Error de autenticación. Por ejemplo, la solicitud falta el parámetro client_secret.
403 Error de autorización. Por ejemplo, el usuario no tiene permiso para acceder al recurso.
500 Se ha producido un error interno en el servicio. Vuelva a hacer la solicitud.

Códigos de error para errores del extremo del token

Código de error Descripción Acción del cliente
solicitud no válida Error de protocolo, como un parámetro obligatorio que falta. Corrección y reenvío de la solicitud
concesión no válida El código de autorización no es válido o ha expirado. Intente una nueva solicitud al endpoint /authorize.
cliente_no_autorizado El cliente autenticado no está autorizado para usar este tipo de concesión de autorización. Esto suele ocurrir cuando la aplicación cliente no está registrada en Azure AD o no se agrega al inquilino de Azure AD del usuario. La aplicación puede solicitar al usuario instrucciones para instalar la aplicación y agregarla a Azure AD.
cliente_no_válido Se produjo un error de autenticación de cliente. Las credenciales de cliente no son válidas. Para corregirlo, el administrador de la aplicación actualiza las credenciales.
tipo_de_subvención_no_soportado 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.
recurso_inválido El recurso de destino no es válido porque no existe, Azure AD no puede encontrarlo o no está configurado correctamente. Esto indica que el recurso, si existe, no se ha configurado en el arrendatario. La aplicación puede solicitar al usuario instrucciones para instalar la aplicación y agregarla a Azure AD.
se requiere interacción La solicitud requiere la interacción del usuario. Por ejemplo, se requiere un paso de autenticación adicional. En lugar de una solicitud no interactiva, vuelva a intentarlo con una solicitud de autorización interactiva para el mismo recurso.
no_disponible_temporalmente De manera temporal, el servidor está demasiado ocupado para atender la solicitud. Vuelva a hacer la solicitud. La aplicación cliente puede explicar al usuario que su respuesta se retrasa debido a una condición temporal.

Uso del token de acceso para acceder al recurso

Ahora que ha adquirido correctamente un access_token, puede usar el token en solicitudes a las API web, incluyéndolo en la cabecera Authorization. La especificación RFC 6750 explica cómo usar tokens de portador en solicitudes HTTP para acceder a los recursos protegidos.

Solicitud de ejemplo

GET /data HTTP/1.1
Host: service.contoso.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ

Respuesta de error

Los recursos protegidos que implementan RFC 6750 emiten códigos de estado HTTP. Si la solicitud no incluye credenciales de autenticación o falta el token, la respuesta incluye un WWW-Authenticate encabezado. Cuando se produce un error en una solicitud, el servidor de recursos responde con el código de estado HTTP y un código de error.

A continuación se muestra un ejemplo de una respuesta fallida cuando la solicitud del cliente no incluye el token de portador.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer authorization_uri="https://login.microsoftonline.com/contoso.com/oauth2/authorize",  error="invalid_token",  error_description="The access token is missing.",

Parámetros de error

Parámetro Descripción
uri_de_autorización URI (punto de conexión físico) del servidor de autorización. Este valor también se usa como clave de búsqueda para obtener más información sobre el servidor desde un punto de conexión de detección.

El cliente debe validar que el servidor de autorización es de confianza. Cuando Azure AD protege el recurso, es suficiente comprobar que la dirección URL comienza con https://login.microsoftonline.com u otro nombre de host que admite Azure AD. Un recurso específico del inquilino siempre debe devolver un URI de autorización específico del inquilino.

error Valor de código de error definido en la sección 5.2 del marco de autorización de OAuth 2.0.
descripción_del_error Descripción más detallada del error. Este mensaje no está pensado para ser amigable para el usuario final.
identificador_de_recurso Devuelve el identificador único del recurso. La aplicación cliente puede usar este identificador como valor del resource parámetro cuando solicita un token para el recurso.

Es importante que la aplicación cliente compruebe este valor; de lo contrario, un servicio malintencionado podría inducir un ataque de elevación de privilegios .

La estrategia recomendada para evitar un ataque es comprobar que resource_id coincide con la base de la dirección URL de la API web a la que se accede. Por ejemplo, si se accede a https://service.contoso.com/data, resource_id puede ser https://service.contoso.com/. La aplicación cliente debe rechazar un resource_id que no comience con la dirección URL base a menos que haya una manera alternativa confiable de comprobar el identificador.

Códigos de error del esquema Bearer

La especificación RFC 6750 define los siguientes errores para los recursos que usan el encabezado WWW-Authenticate y el Esquema Bearer en la respuesta.

Código de estado HTTP Código de error Descripción Acción del cliente
400 solicitud no válida La solicitud no tiene el formato correcto. Por ejemplo, podría faltar un parámetro o usar el mismo parámetro dos veces. Corrija el error y vuelva a intentar la solicitud. Este tipo de error solo debe producirse durante el desarrollo y detectarse en las pruebas iniciales.
401 token inválido Falta el token de acceso, no es válido o se revoca. El valor del parámetro error_description proporciona detalles adicionales. Solicite un nuevo token desde el servidor de autorización. Si se produce un error en el nuevo token, se ha producido un error inesperado. Envíe un mensaje de error al usuario y vuelva a intentarlo después de retrasos aleatorios.
403 alcance_insuficiente El token de acceso no contiene los permisos de suplantación necesarios para acceder al recurso. Envíe una nueva solicitud de autorización al punto de conexión de autorización. Si la respuesta contiene el parámetro scope, emplee el valor de ámbito en la solicitud al recurso.
403 acceso insuficiente El sujeto del token no tiene los permisos que se requieren para acceder al recurso. Pida al usuario que use una cuenta diferente o que solicite permisos al recurso especificado.

Actualización de los tokens de acceso

Los tokens de acceso son de corta duración y deben actualizarse después de que expiren para seguir accediendo a los recursos. Puede actualizar el access_token enviando otra POST solicitud al punto de conexión /token, pero esta vez proporcionando el refresh_token en lugar del code. Los tokens de actualización son válidos para todos los recursos a los que el cliente ya ha dado su consentimiento para acceder; por lo tanto, se puede usar un token de actualización emitido en una solicitud para resource=https://graph.microsoft.com solicitar un nuevo token de acceso para resource=https://contoso.com/api.

Los tokens de actualización no tienen vigencias especificadas. Normalmente, las duraciones de los tokens de actualización son relativamente largas. Sin embargo, en algunos casos, los tokens de actualización expiran, se revocan o carecen de privilegios suficientes para la acción deseada. La aplicación debe prever y manejar correctamente los errores que el endpoint de emisión de tokens pueda devolver.

Cuando reciba una respuesta con un error de token de actualización, descarte el token de actualización actual y solicite un nuevo código de autorización o token de acceso. En particular, cuando se usa un token de actualización en el flujo de concesión de código de autorización, si recibe una respuesta con los códigos de error interaction_required o invalid_grant, descarte el token de actualización y solicite un nuevo código de autorización.

Una solicitud de ejemplo al punto de conexión específico del arrendatario (también puede usar el punto de conexión común) para obtener un nuevo token de acceso mediante un token de actualización es el siguiente:

// Line breaks for legibility only

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

client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&resource=https%3A%2F%2Fservice.contoso.com%2F
&client_secret=JqQX2PNo9bpM0uEihUPzyrh    // NOTE: Only required for web apps

Respuesta exitosa

Una respuesta de token correcta será similar a la siguiente:

{
  "token_type": "Bearer",
  "expires_in": "3600",
  "expires_on": "1460404526",
  "resource": "https://service.contoso.com/",
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ",
  "refresh_token": "AwABAAAAv YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfcUl4VBbiSHZyd1NVZG5QTIOcbObu3qnLutbpadZGAxqjIbMkQ2bQS09fTrjMBtDE3D6kSMIodpCecoANon9b0LATkpitimVCrl PM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4rTfgV29ghDOHRc2B-C_hHeJaJICqjZ3mY2b_YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfmVCrl-NyfN3oyG4ZCWu18M9-vEou4Sq-1oMDzExgAf61noxzkNiaTecM-Ve5cq6wHqYQjfV9DOz4lbceuYCAA"
}
Parámetro Descripción
tipo_de_token Tipo de token. El único valor admitido es portador.
expira_en Duración restante del token en segundos. Un valor típico es 3600 (una hora).
vence_el Fecha y hora en que expira el token. La fecha se representa como el número de segundos de 1970-01-01T0:0:0Z UTC hasta la hora de expiración.
recurso Identifica el recurso protegido al que se puede usar el token de acceso para acceder.
alcance Se han concedido permisos de suplantación a la aplicación cliente nativa. El permiso predeterminado es user_impersonation. El propietario del recurso de destino puede registrar valores alternativos en Azure AD.
token de acceso Nuevo token de acceso solicitado.
token de actualización Una nueva "refresh_token" de OAuth 2.0 que se puede usar para solicitar nuevos tokens de acceso cuando el token de la presente respuesta expire.

Respuesta de error

Una respuesta de error de ejemplo podría tener este aspecto:

{
  "error": "invalid_resource",
  "error_description": "AADSTS50001: The application named https://foo.microsoft.com/mail.read was not found in the tenant named 295e01fc-0c56-4ac3-ac57-5d0ed568f872. This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant. You might have sent your authentication request to the wrong tenant.\r\nTrace ID: ef1f89f6-a14f-49de-9868-61bd4072f0a9\r\nCorrelation ID: b6908274-2c58-4e91-aea9-1f6b9c99347c\r\nTimestamp: 2016-04-11 18:59:01Z",
  "error_codes": [
    50001
  ],
  "timestamp": "2016-04-11 18:59:01Z",
  "trace_id": "ef1f89f6-a14f-49de-9868-61bd4072f0a9",
  "correlation_id": "b6908274-2c58-4e91-aea9-1f6b9c99347c"
}
Parámetro Descripción
error Una cadena de código de error que puede utilizarse para clasificar los tipos de errores que se producen y para reaccionar ante ellos.
descripción_del_error Un mensaje de error específico que puede ayudar a un desarrollador a identificar la causa de un error de autenticación.
códigos_de_error Una lista de los códigos de error específicos de STS que pueden ayudar en los diagnósticos.
Marca de tiempo La hora a la que se produjo el error.
trace_id Un identificador exclusivo para la solicitud que puede ayudar en los diagnósticos.
identificador_de_correlación Un identificador exclusivo para la solicitud que puede ayudar en los diagnósticos entre componentes.

Para obtener una descripción de los códigos de error y la acción de cliente recomendada, consulte Códigos de error para errores de punto de conexión de token.

Pasos siguientes

Para más información sobre el punto de conexión de Azure AD v1.0 y cómo agregar autenticación y autorización a las aplicaciones web y las API web, consulte aplicaciones de ejemplo.