Comentarios Editar

Obtener acceso en nombre de un usuario

  • Artículo
  • 14 minutos para leer

Para usar Microsoft Graph para leer y escribir recursos en nombre de un usuario, la aplicación debe obtener un token de acceso de la plataforma de identidad de Microsoft y adjuntarlo a las solicitudes que envía a Microsoft Graph. El flujo de autenticación exacto a usar para obtener tokens de acceso dependerá de la clase de aplicación que esté desarrollando y de si se quiere usar OpenID Connect para iniciar la sesión del usuario en la aplicación. Un flujo habitual que usan las aplicaciones nativas y móviles, y también algunas aplicaciones web es el flujo de concesión del código de autorización de OAuth 2.0. En este artículo veremos un ejemplo del uso de este flujo.

Pasos de autenticación y autorización

Los pasos básicos para usar el flujo de concesión del código de autorización de OAuth 2.0 para obtener un token de acceso del punto de conexión de la Plataforma de identidad de Microsoft son los siguientes:

  1. Registrar la aplicación con Azure AD.
  2. Obtener autorización.
  3. Obtener un token de acceso.
  4. Llamar a Microsoft Graph con el token de acceso.
  5. Usar un token de actualización para obtener un nuevo token de acceso.

1. Registrar la aplicación

Para usar el punto de conexión de la plataforma de identidad de Microsoft, debe registrar la aplicación con el Portal de registro de aplicaciones de Azure. Puede usar una cuenta de Microsoft o una cuenta profesional o educativa para registrar una aplicación.

Para configurar una aplicación para que use el flujo de concesión del código de autorización de OAuth 2.0, guarde los valores siguientes al registrar la aplicación:

  • El ID de aplicación (cliente) asignado por el portal de registro de aplicaciones.
  • Un secreto de cliente (aplicación), ya sea una contraseña o un par de claves pública y privada (certificado). El secreto de cliente no es necesario para las aplicaciones nativas.
  • Un URI de redireccionamiento (o URL de respuesta) para que la aplicación reciba respuestas de Azure AD.

Para conocer los pasos necesarios para configurar una aplicación en Microsoft Azure Portal, vea Registrar una aplicación.

2. Obtener la autorización

El primer paso para obtener un token de acceso para varios flujos de OpenID Connect (OIDC) y OAuth 2.0 consiste en redirigir al usuario al punto de conexión /authorize de la Plataforma de identidad de Microsoft. Azure AD iniciará la sesión del usuario y solicitará su consentimiento para los permisos que solicite la aplicación. En el flujo de concesión del código de autorización, después de obtener el consentimiento, Azure AD devolverá un código de autorización a la aplicación que puede canjear en el punto de conexión /token de la Plataforma de identidad de Microsoft por un token de acceso.

Solicitud de autorización

A continuación se muestra un ejemplo de solicitud al punto de conexión /authorize.

Con el punto de conexión de la Plataforma de identidad de Microsoft, los permisos se solicitan mediante el parámetro scope. En este ejemplo, los permisos solicitados de Microsoft Graph son User.Read y Mail.Read, que permitirán que la aplicación lea el perfil y el correo del usuario que ha iniciado sesión. El permiso offline_access es un ámbito estándar de OIDC 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 el actual expire.

// Line breaks for legibility only

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
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 para cuentas de Microsoft y cuentas profesionales o educativas, organizations solo para cuentas profesionales o educativas, consumers solo para cuentas de Microsoft, e identificadores de inquilino como el ID de inquilino o el nombre de dominio. Para obtener más información, consulte los conceptos básicos de protocolo.
client_id Obligatorio El ID de la aplicación que el portal de registro asignó a la aplicación.
response_type Obligatorio Debe incluir code para el flujo del código de autorización.
redirect_uri Recomendado URI de redireccionamiento de la aplicación, donde la aplicación puede enviar y recibir respuestas de autenticación. Debe coincidir exactamente con uno de los URI de redireccionamiento que ha registrado en el portal de registro de la aplicación, pero con codificación URL. En el caso de las 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 de OIDC, como offline_access, que indica que su 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.
state Recomendado Valor incluido en la solicitud que también se devolverá en la respuesta de token. Puede ser una cadena con cualquier contenido que quiera. Normalmente se usa un valor único generado de forma aleatoria para impedir los ataques de falsificación de solicitud entre sitios. El estado también se usa para codificar la información sobre el estado del usuario en la aplicación antes de que se produjese la solicitud de autenticación, como la página o la visualización en la que estaba.

Nota

Microsoft Graph expone dos tipos de permisos: de aplicación y delegados. En el caso de las aplicaciones que se ejecutan con un usuario que ha iniciado sesión, los permisos delegados se solicitan en el parámetro scope. Estos permisos delegan en su aplicación los privilegios del usuario que ha iniciado sesión, lo que permite que la aplicación actúe como dicho usuario al hacer llamadas a Microsoft Graph. Para obtener más información sobre los permisos disponibles mediante Microsoft Graph, vea la Referencia de permisos.

Microsoft Graph también expone los siguientes ámbitos de OIDC bien definidos: openid, email, profiley offline_access. Los ámbitos de OIDC address y phone no son admitidos. Para obtener más información sobre cada ámbito de OIDC, consulte Permisos y consentimiento.

Tras enviar una solicitud de autorización, se pedirá al usuario que escriba sus credenciales para autenticarse con Microsoft. El punto de conexión de la Plataforma de identidad de Microsoft v2.0 también se asegurará de que el usuario haya aceptado los permisos indicados en el parámetro de consulta scope. Si el usuario no ha aceptado alguno de estos permisos y si un administrador no ha dado su consentimiento en nombre de todos los usuarios de la organización, se pedirá al usuario que dé su consentimiento a los permisos necesarios.

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

Probar Si tiene una cuenta de Microsoft o una cuenta profesional o educativa de Azure AD, puede probarlo usted mismo si hace clic en el vínculo siguiente. Después de iniciar sesión, el explorador debería redirigirse a https://localhost/myapp/ con un code en la barra de direcciones.

https://login.microsoftonline.com/common/oauth2/v2.0/authorize...

Respuesta de autorización

Si el usuario acepta los permisos que ha solicitado la aplicación, la respuesta contendrá el código de autorización en el parámetro code. A continuación se muestra un ejemplo de una respuesta correcta a la solicitud anterior. Dado que el parámetro response_mode de la solicitud estaba establecido en query, la respuesta se devuelve en la cadena de consulta de la URL de redireccionamiento.

GET https://localhost/myapp/?
code=M0ab92efe-b6fd-df08-87dc-2c6500a7f84d
&state=12345
Parámetro Descripción
código Código de autorización solicitado por la aplicación. La aplicación puede usar el código de autorización para solicitar un token de acceso para el recurso de destino. Los códigos de autorización duran poco. Por lo general, expiran al cabo de 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 solicitud 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. Obtener un token

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 solicitud POST al punto de conexión /token.

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=jXoM3iz...    // NOTE: Only required for web apps
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 los conceptos básicos de protocolo.
    		•
    client_id Obligatorio El ID de la aplicación que el portal de registro asignó a la aplicación.
    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 solicitados por la aplicación en esta sección deben ser equivalentes a los ámbitos solicitados en la primera sección (autorización) o deben ser un subconjunto de estos. Si los ámbitos especificados en esta solicitud abarcan varios servidores de recursos, el punto de conexión de v2.0 devolverá un token para el recurso especificado en el primer ámbito.
    código Obligatorio Código de autorización adquirido en la primera sección del flujo.
    redirect_uri Obligatorio Mismo valor del URI de redireccionamiento que se usó para adquirir el código de autorización.
    client_secret Necesario para aplicaciones web El secreto del cliente que creó para su aplicación en el portal de registro 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 fiable en los dispositivos. Es necesario para aplicaciones web y API web, que pueden almacenar de forma segura el secreto de cliente en el lado servidor.

    Respuesta de token

    Aunque el token de acceso es opaco para la aplicación, la respuesta contiene una lista de los permisos para los que el token de acceso es válido en el parámetro scope.

    {
    "token_type": "Bearer",
    "scope": "user.read%20Fmail.read",
    "expires_in": 3600,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4..."
}
    Parámetro Descripción
    token_type Indica el valor de tipo del token. El único tipo que Azure AD admite es Bearer.
    ámbito Lista separada por espacios de los permisos de Microsoft Graph para los que es válido el token de acceso.
    expires_in Período de validez del token de acceso (en segundos).
    access_token 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. Cuando expire el token de acceso actual, la aplicación puede usar este token para obtener otros tokens de acceso. 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. Para obtener más información, vea la Referencia de tokens v2.0.

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

    Una vez que tenga un token de acceso, puede usarlo para llamar a Microsoft Graph. Para ello, inclúyalo en el encabezado Authorization de una solicitud. Mediante la solicitud siguiente se obtiene el perfil del usuario que ha iniciado sesión.

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

    Una respuesta correcta tendrá un aspecto similar al 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",
    "id":"12345678-73a6-4952-a53a-e9916737ff7f",
    "businessPhones":[
        "+1 555555555"
    ],
    "displayName":"Chris Green",
    "givenName":"Chris",
    "jobTitle":"Software Engineer",
    "mail":null,
    "mobilePhone":"+1 5555555555",
    "officeLocation":"Seattle Office",
    "preferredLanguage":null,
    "surname":"Green",
    "userPrincipalName":"ChrisG@contoso.onmicrosoft.com"
}

    5. Usar el token de actualización para obtener un nuevo token de acceso

    Los tokens de acceso tienen una duración breve y deberá actualizarlos una vez que hayan expirado para seguir teniendo acceso a los recursos. Puede hacerlo enviando otra solicitud POST al punto de conexión /token, proporcionando esta vez el refresh_token en lugar del code.

    Solicitud

    // Line breaks for legibility only

POST /common/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...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=refresh_token
&client_secret=jXoM3iz...      // NOTE: Only required for web apps
    Parámetro Obligatorio Descripción
    client_id Obligatorio El ID de la aplicación que el portal de registro asignó a la aplicación.
    grant_type Obligatorio Debe ser refresh_token.
    scope Obligatorio Lista de permisos (ámbitos) separados por espacios. Los solicitados por su aplicación deben ser equivalentes a los permisos solicitados en la solicitud del código de autorización original o deben ser un subconjunto de estos.
    refresh_token Obligatorio Token de actualización adquirido durante la solicitud de token.
    redirect_uri Obligatorio Mismo valor del URI de redireccionamiento que se usó para adquirir el código de autorización.
    client_secret Necesario para aplicaciones web Secreto del cliente creado en el portal de registro 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 fiable en los dispositivos. Es necesario para aplicaciones web y API web, que pueden almacenar de forma segura el secreto de cliente en el lado del servidor.

    Respuesta

    Una respuesta de token correcta tendrá un aspecto similar al siguiente.

    {
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "token_type": "Bearer",
    "expires_in": 3599,
    "scope": "user.read%20mail.read",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
}
    Parámetro Descripción
    access_token Token de acceso solicitado. La aplicación puede usar este token en las llamadas a Microsoft Graph.
    token_type Indica el valor de tipo del token. El único tipo que Azure AD 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 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 el máximo tiempo posible.

    Escenarios de aplicación admitidos y recursos adicionales

    Puede llamar a Microsoft Graph en nombre de un usuario desde los siguientes tipos de aplicaciones:

    Para obtener más información sobre los escenarios de aplicaciones compatibles con el punto de conexión de plataforma de identidad de Microsoft, vea Escenarios de aplicaciones y flujos de autenticación.

    Nota: Actualmente, el punto de conexión de la Plataforma de identidad de Microsoft no permite llamar a Microsoft Graph desde una API web independiente. En este caso, debe usar el punto de conexión de Azure AD.

    Para obtener más información sobre cómo obtener acceso a Microsoft Graph en nombre de un usuario desde el punto de conexión de la plataforma de identidad de Microsoft:

    Consideraciones sobre el punto de conexión

    Microsoft sigue siendo compatible con el punto de conexión de Azure AD. Hay varias diferencias entre usar el punto de conexión de la plataforma de identidad de Microsoft y el punto de conexión de Azure AD. Al usar el punto de conexión de Azure AD:

    • La aplicación necesitará un id. de aplicación distinto (id. de cliente) para cada plataforma.
    • Si la aplicación es multiinquilino, necesita configurarla de forma explícita para que sea multiinquilino en Azure Portal.
    • Todos los permisos que necesita la aplicación debe configurarlos el desarrollador. El punto de conexión de Azure AD no admite el consentimiento dinámico (incremental).
    • El punto de conexión de Azure AD usa un parámetro resource en las solicitudes de autorización y de token para especificar el recurso, como Microsoft Graph, para el que quiere los permisos. El punto de conexión no admite el parámetro scope.
    • El punto de conexión de Azure AD no expone un punto de conexión específico para el consentimiento del administrador. En su lugar, las aplicaciones usan el parámetro prompt=admin_consent en la solicitud de autorización para obtener el consentimiento del administrador para una organización. Para obtener más información, consulte Desencadenamiento del marco de consentimiento de Azure AD en tiempo de ejecución en Integración de aplicaciones con Azure Active Directory.

    Para obtener más información sobre cómo obtener acceso a Microsoft Graph en nombre de un usuario, consulte los siguientes recursos.

    Vea también