Nota
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
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.
Inicie sesión en Azure Portal.
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.
En Azure Portal, busque y seleccione Azure Active Directory.
En el menú izquierdo de Azure Active Directory , seleccione Registros de aplicaciones y, a continuación, seleccione Nuevo registro.
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
.
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.
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:
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 , fragment o 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_uri en 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 |
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 |
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.