Obtener acceso en nombre de un usuario

  • Artículo

Para llamar a Microsoft Graph, una aplicación debe obtener un token de acceso de la Plataforma de identidad de Microsoft. Este token de acceso incluye información sobre si la aplicación está autorizada para acceder a Microsoft Graph en nombre de un usuario que ha iniciado sesión o con su propia identidad. En este artículo se proporcionan instrucciones sobre cómo una aplicación puede acceder a Microsoft Graph en nombre de un usuario, también denominado acceso delegado.

En este artículo se detallan las solicitudes HTTP sin procesar implicadas para que una aplicación obtenga acceso en nombre de un usuario mediante un flujo popular denominado flujo de concesión de código de autorización de OAuth 2.0. Como alternativa, puede evitar escribir solicitudes HTTP sin procesar y usar una biblioteca de autenticación compatible o compilada por Microsoft que administre muchos de estos detalles automáticamente y le ayude a obtener tokens de acceso y a llamar a Microsoft Graph. Para obtener más información, consulte Uso de la biblioteca de autenticación de Microsoft (MSAL).

Requisitos previos

Antes de continuar con los pasos de este artículo:

  1. Comprenda los conceptos de autenticación y autorización en el Plataforma de identidad de Microsoft. Para obtener más información, consulte Conceptos básicos de autenticación y autorización.
  2. Registre la aplicación con Microsoft Entra ID. Para obtener más información, consulte Registro de una aplicación con el Plataforma de identidad de Microsoft.

Pasos de autenticación y autorización

Para que una aplicación obtenga autorización y acceso a Microsoft Graph mediante el flujo de código de autorización, debe seguir estos cinco pasos:

  1. Registre la aplicación con Microsoft Entra ID.
  2. Solicitar autorización.
  3. Solicitar un token de acceso.
  4. Usar el token de acceso para llamar a Microsoft Graph.
  5. [Opcional] Use el token de actualización para renovar un token de acceso expirado.

1. Registro de la aplicación

Para que la aplicación pueda llamar a los puntos de conexión de Plataforma de identidad de Microsoft o Microsoft Graph, debe registrarse correctamente. Siga los pasos para registrar la aplicación en el Centro de administración Microsoft Entra.

En el registro de la aplicación, guarde los valores siguientes:

  • Identificador de aplicación (denominado id. de objeto en el Centro de administración Microsoft Entra) asignado por el portal de registro de aplicaciones.
  • Uri de redireccionamiento (o dirección URL de respuesta) para que la aplicación reciba respuestas de Microsoft Entra ID.
  • Un secreto de cliente (contraseña de aplicación), un certificado o una credencial de identidad federada. Esta propiedad no es necesaria para clientes públicos como aplicaciones nativas, móviles y de página única.

2. Solicitar autorización

El primer paso del flujo de código de autorización es que el usuario autorice a la aplicación a actuar en su nombre.

En el flujo, la aplicación redirige al usuario al punto de conexión de Plataforma de identidad de Microsoft/authorize. A través de este punto de conexión, Microsoft Entra ID inicia sesión al usuario y solicita su consentimiento para los permisos que solicita la aplicación. Una vez obtenido el consentimiento, Microsoft Entra ID devolverá un código de autorización a la aplicación. A continuación, la aplicación puede canjear este código en el punto de conexión de Plataforma de identidad de Microsoft /token por un token de acceso.

Solicitud de autorización

En el ejemplo siguiente se muestra una solicitud al punto de /authorize conexión.

En la dirección URL de la solicitud, llame al /authorize punto de conexión y especifique las propiedades necesarias y recomendadas como parámetros de consulta.

En el ejemplo siguiente, la aplicación solicita los permisos User.Read y Mail.Read de Microsoft Graph, que permiten a la aplicación leer el perfil y el correo del usuario que ha iniciado sesión, respectivamente. El permiso offline_access es un ámbito OIDC estándar que se solicita para que la aplicación pueda obtener un token de actualización. La aplicación puede usar el token de actualización para obtener un nuevo token de acceso cuando expire el actual.

// Line breaks for legibility only

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=11111111-1111-1111-1111-111111111111
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=offline_access%20user.read%20mail.read
&state=12345  HTTP/1.1
Parámetros
Parámetro Obligatorio Descripción
tenant 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:
  • common es válido tanto para cuentas Microsoft, como para cuentas profesionales o educativas
  • organizations solo para cuentas profesionales o educativas
  • consumers solo para cuentas de Microsoft
  • identificadores de inquilino, como el ID de inquilino o el nombre de dominio.
    Para obtener más información, consulte conceptos básicos del protocolo.
    		•
    client_id Obligatorio Identificador de aplicación (cliente) que el portal de registro asignó a la aplicación. También se conoce como appId en la aplicación de Microsoft Graph y el objeto de entidad de servicio.
    response_type Obligatorio Debe incluirse code para el flujo de código de autorización de OAuth 2.0.
    redirect_uri Recomendado Uri de redireccionamiento de la aplicación, donde la aplicación envía y recibe respuestas de autenticación. Debe coincidir exactamente con uno de los URI de redireccionamiento que registró en el portal de registro de aplicaciones, excepto que debe estar codificado como dirección URL. Para aplicaciones nativas y móviles, debe usar el valor predeterminado de https://login.microsoftonline.com/common/oauth2/nativeclient.
    ámbito Obligatorio Lista separada por espacios de los permisos de Microsoft Graph para los que quiere que el usuario dé su consentimiento. Estos permisos pueden incluir permisos de recursos, como User.Read y Mail.Read, y ámbitos OIDC, como offline_access, que indica que la aplicación necesita un token de actualización para el acceso de larga duración a los recursos.
    response_mode Recomendado Especifica el método que se debe usar para devolver el token resultante a la aplicación. Puede ser query o form_post.
    estado Recomendado Valor incluido en la solicitud que también se devuelve en la respuesta del token. Puede ser una cadena de cualquier contenido que desee. Normalmente, se usa un valor único generado aleatoriamente para evitar ataques de falsificación de solicitudes entre sitios. Esta propiedad también se usa para codificar información sobre el estado del usuario en la aplicación antes de que se produjera la solicitud de autenticación, como la página o vista en la que se encontraba.

    Una vez que la aplicación envía la solicitud de autorización, se pide al usuario que escriba sus credenciales para autenticarse con Microsoft. El punto de conexión Plataforma de identidad de Microsoft v2.0 garantiza que el usuario ha dado su consentimiento a los permisos indicados en el parámetro de scope consulta. Si hay algún permiso al que el usuario o administrador no haya dado su consentimiento, se le pedirá que dé su consentimiento a los permisos necesarios. Para obtener más información sobre la experiencia de consentimiento de Microsoft Entra, consulte Experiencia de consentimiento de la aplicación e Introducción a los permisos y el consentimiento.

    El siguiente recorte de pantalla muestra un ejemplo del cuadro de diálogo de consentimiento que se muestra a un usuario de una cuenta de Microsoft.

    Cuadro de diálogo de consentimiento para una cuenta de Microsoft

    Respuesta de autorización

    Si el usuario da su consentimiento a los permisos que solicitó la aplicación, la respuesta contiene el código de autorización en el code parámetro . Este es un ejemplo de una respuesta correcta a la solicitud anterior. Dado que el response_mode parámetro de la solicitud se estableció queryen , la respuesta se devuelve en la cadena de consulta de la dirección URL de redireccionamiento.

    HTTP/1.1 200 OK

https://localhost/myapp/?code=M0ab92efe-b6fd-df08-87dc-2c6500a7f84d&state=12345&session_state=fe1540c3-a69a-469a-9fa3-8a2470936421#
    Parámetros de consulta
    Parámetro Descripción
    código El código de autorización que solicitó la aplicación. La aplicación usa 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, normalmente expiran después de unos 10 minutos.
    state Si se incluye un parámetro de estado en la solicitud, debe aparecer el mismo valor en la respuesta. La aplicación debe comprobar que los valores de estado de la solicitud y la respuesta son idénticos. Esta comprobación ayuda a detectar ataques de falsificación de solicitudes entre sitios (CSRF) contra el cliente.
    session_state 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.

    3. Solicitud de un token de acceso

    La aplicación usa la autorización code recibida en el paso anterior para solicitar un token de acceso mediante el envío de una POST solicitud al /token punto de conexión.

    Solicitud de 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=11111111-1111-1111-1111-111111111111
&scope=user.read%20mail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&client_secret=HF8Q~Krjqh4r...    // NOTE: Only required for web apps
    Parámetros
    Parámetro Obligatorio Descripción
    tenant 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:
  • common es válido tanto para cuentas Microsoft, como para cuentas profesionales o educativas
  • organizations solo para cuentas profesionales o educativas
  • consumers solo para cuentas de Microsoft
  • identificadores de inquilino, como el ID de inquilino o el nombre de dominio.
    Para obtener más información, consulte conceptos básicos del protocolo.
    		•
    client_id Obligatorio Identificador de aplicación (cliente) que el portal de registro asignó a la aplicación. También se conoce como appId en la aplicación de Microsoft Graph y el objeto de entidad de servicio.
    grant_type Obligatorio Debe ser authorization_code para el flujo del código de autorización.
    scope Obligatorio Lista de ámbitos separados por espacios. Los ámbitos que solicita la aplicación en este tramo deben ser equivalentes a o un subconjunto de los ámbitos que solicitó en el tramo de autorización del paso 2. Si los ámbitos especificados en esta solicitud abarcan varios servidores de recursos, el punto de conexión v2.0 devuelve un token para el recurso especificado en el primer ámbito.
    código Obligatorio El código de autorización que adquirió en el tramo de autorización en el paso 2.
    redirect_uri Obligatorio El mismo valor de URI de redireccionamiento que se usó para adquirir el código de autorización en el paso 2.
    client_secret Necesario para aplicaciones web Secreto de cliente que creó en el portal de registro de aplicaciones de la aplicación. No se debe usar en una aplicación nativa, ya que los secretos de cliente no se pueden almacenar de forma confiable en los dispositivos. Es necesario para las aplicaciones web y las API web, que tienen la capacidad de almacenar el client_secret de forma segura en el lado servidor.

    Respuesta de token

    El token de acceso contiene una lista de los permisos para los que es válido el token de acceso en el scope parámetro . La respuesta es similar al ejemplo siguiente.

    HTTP/1.1 200 OK
Content-type: application/json

{
    "token_type": "Bearer",
    "scope": "Mail.Read User.Read",
    "expires_in": 3736,
    "ext_expires_in": 3736,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4..."
}
    Propiedades del cuerpo de la respuesta
    Parámetro Descripción
    token_type Indica el valor del tipo de token. El único tipo que Microsoft Entra ID admite es Bearer.
    ámbito Lista separada por espacios de los permisos de Microsoft Graph para los que el token de acceso es válido.
    expires_in Período de validez del token de acceso (en segundos).
    ext_expires_in Indica una duración extendida del token de acceso (en segundos) y se usa para admitir resistencia cuando el servicio de emisión de tokens no responde.
    access_token El token de acceso solicitado. La aplicación puede usar este token para llamar a Microsoft Graph.
    refresh_token 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. Solo se devolverá un scope token de actualización si offline_access se incluyó como parámetro. Para obtener más información, consulte la referencia del token v2.0.

    4. Usar el token de acceso para llamar a Microsoft Graph

    Después de tener un token de acceso, la aplicación lo usa para llamar a Microsoft Graph adjuntando el token de acceso como token de portador al encabezado Authorization en una solicitud HTTP. La siguiente solicitud obtiene el perfil del usuario que ha iniciado sesión.

    Solicitud

    GET https://graph.microsoft.com/v1.0/me  HTTP/1.1
Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw
Host: graph.microsoft.com

    Respuesta

    Una respuesta correcta es similar a la siguiente (se han quitado algunos encabezados de respuesta).

    HTTP/1.1 200 OK
Content-Type: application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8
request-id: f45d08c0-6901-473a-90f5-7867287de97f
client-request-id: f45d08c0-6901-473a-90f5-7867287de97f
OData-Version: 4.0
Duration: 727.0022
Date: Thu, 20 Apr 2017 05:21:18 GMT
Content-Length: 407

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
    "businessPhones": [
        "425-555-0100"
    ],
    "displayName": "MOD Administrator",
    "givenName": "MOD",
    "jobTitle": null,
    "mail": "admin@contoso.com",
    "mobilePhone": "425-555-0101",
    "officeLocation": null,
    "preferredLanguage": "en-US",
    "surname": "Administrator",
    "userPrincipalName": "admin@contoso.com",
    "id": "10a08e2e-3ea2-4ce0-80cb-d5fdd4b05ea6"
}

    5. Use el token de actualización para renovar un token de acceso expirado.

    Los tokens de acceso son de corta duración y la aplicación debe actualizarlos después de que expiren para seguir accediendo a los recursos. La aplicación lo hace enviando otra POST solicitud al /token punto de conexión, esta vez:

    • Proporcionar el refresh_token en lugar del código en el cuerpo de la solicitud
    • refresh_token Especificar como el grant_type, en lugar de authorization_code.

    Solicitud

    // 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=11111111-1111-1111-1111-111111111111
&scope=user.read%20mail.read
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=jXoM3iz...      // NOTE: Only required for web apps
    Parámetros
    Parámetro Obligatorio Descripción
    tenant 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:
  • common es válido tanto para cuentas Microsoft, como para cuentas profesionales o educativas
  • organizations solo para cuentas profesionales o educativas
  • consumers solo para cuentas de Microsoft
  • identificadores de inquilino, como el ID de inquilino o el nombre de dominio.
    Para obtener más información, consulte conceptos básicos del protocolo.
    		•
    client_id Obligatorio Identificador de aplicación (cliente) que el portal de registro asignó a la aplicación. También se conoce como appId en la aplicación de Microsoft Graph y el objeto de entidad de servicio.
    grant_type Obligatorio Debe ser refresh_token.
    scope Opcional Una lista separada por espacios de permisos (ámbitos). Los permisos que solicita la aplicación deben ser equivalentes a o un subconjunto de los permisos que solicitó en la solicitud de código de autorización original en el paso 2.
    refresh_token Obligatorio El refresh_token que la aplicación adquirió durante la solicitud de token en el paso 3.
    client_secret Necesario para aplicaciones web Secreto de cliente que creó en el portal de registro de aplicaciones de la aplicación. No use el secreto en una aplicación nativa, ya que client_secrets no se puede almacenar de forma confiable en los dispositivos. Es necesario para las aplicaciones web y las API web, que tienen la capacidad de almacenar el client_secret de forma segura en el lado servidor.

    Respuesta

    Una respuesta de token correcta es similar a la siguiente.

    HTTP/1.1 200 OK
Content-type: application/json

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "token_type": "Bearer",
    "expires_in": 3599,
    "scope": "Mail.Read User.Read",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
}
    Parámetros del cuerpo de la respuesta
    Parámetro Descripción
    access_token El token de acceso solicitado. La aplicación puede usar este token en llamadas a Microsoft Graph.
    token_type Indica el valor del tipo de token. El único tipo que Microsoft Entra ID admite es Bearer.
    expires_in Período de validez del token de acceso (en segundos).
    scope Permisos (ámbitos) para los que es válido el token de acceso.
    refresh_token Un nuevo token de actualización de OAuth 2.0. Reemplace el token de actualización antiguo por este token de actualización recién adquirido para asegurarse de que los tokens de actualización sigan siendo válidos durante el mayor tiempo posible.

    Uso de la biblioteca de autenticación de Microsoft (MSAL)

    En este artículo, ha recorrido los detalles del protocolo de bajo nivel que normalmente solo se requieren al crear y emitir manualmente solicitudes HTTP sin procesar para ejecutar el flujo de código de autorización. En las aplicaciones de producción, use una biblioteca de autenticación compatible o compilada por Microsoft, como la Biblioteca de autenticación de Microsoft (MSAL), para obtener tokens de seguridad y llamar a API web protegidas como Microsoft Graph.

    MSAL y otras bibliotecas de autenticación admitidas simplifican el proceso mediante el control de detalles como la validación, el control de cookies, el almacenamiento en caché de tokens y las conexiones seguras, lo que le permite centrarse en la funcionalidad de la aplicación.

    Microsoft ha creado y mantiene una amplia selección de ejemplos de código que muestran el uso de bibliotecas de autenticación admitidas con el Plataforma de identidad de Microsoft. Para acceder a estos ejemplos de código, consulte los ejemplos de código de Plataforma de identidad de Microsoft.

    Contenido relacionado

    • Puede llamar a Microsoft Graph en nombre de un usuario de diferentes tipos de aplicaciones, como aplicaciones de página única, aplicaciones web y aplicaciones móviles. Para obtener más información, consulte Escenarios y flujos de autenticación admitidos.
    • Elija entre ejemplos de código creados y mantenidos por Microsoft para ejecutar aplicaciones personalizadas que usen bibliotecas de autenticación admitidas, usuarios de inicio de sesión y llamadas a Microsoft Graph. Consulte tutoriales de Microsoft Graph.