Compartir a través de

Autorización e inicio de sesión de OneDrive en Microsoft Graph

  • Artículo

Para usar la API de OneDrive con Microsoft Graph, necesita tener un token de acceso que autorice la aplicación con un conjunto determinado de permisos para un usuario. En esta sección, obtendrá información sobre cómo:

  1. Registrar la aplicación para obtener un id. de aplicación.
  2. Iniciar la sesión del usuario con los ámbitos especificados mediante el flujo de tokens o el flujo de códigos.
  3. Cerrar la sesión del usuario (opcional).

La API de OneDrive usa el marco de autorización OAuth 2.0 estándar para autorizar aplicaciones y generar tokens de acceso. Debe proporcionar un token de acceso para cada llamada API autenticada mediante un encabezado HTTP:

Authorization: bearer {token}

Nota: El marco de autorización recomendado es usar el punto de conexión de Azure AD v2.0. En cambio, algunos escenarios de empresa pueden necesitar el uso del punto de conexión original de Azure AD. Para obtener más información, vea Autenticación de aplicaciones con Microsoft Graph.

Registrar su aplicación

El primer paso es registrar una aplicación con Microsoft y proporcionar algunos detalles sobre su aplicación. Puede registrar la aplicación y recibir un nuevo identificador de aplicación en la página registros de App de Azure.

Para obtener los pasos detallados sobre cómo registrar la aplicación, vea cómo registrar la aplicación para la API de OneDrive.

Inicio de sesión de los usuarios

Su aplicación debe iniciar el proceso de inicio de sesión poniéndose en contacto con el punto de conexión de autorización de Azure Active Directory con un ámbito especificado. El flujo sigue los flujos de autorización de OAuth 2.0 estándar y necesita llamadas desde un explorador web o un control de explorador web. El resultado del flujo de autorización devolverá un token de acceso y, opcionalmente, otros tokens que su aplicación puede usar para tener acceso a la API.

Ámbitos de autenticación

Los ámbitos determinan qué tipo de acceso se concede a la aplicación cuando el usuario ha iniciado sesión. Todos los ámbitos admiten el inicio de sesión único en la web, lo que significa que si un usuario ya ha iniciado sesión en OneDrive, entonces el usuario puede omitir el flujo de autenticación e ir directamente al flujo de autorización.

Nombre de ámbito Descripción
offline_access Permite que la aplicación funcione sin conexión incluso cuando el usuario no está activo. Necesita el uso de flujo de códigos.
files.read Concede permisos de solo lectura a todos los archivos de OneDrive de un usuario.
files.read.all Concede permisos de solo lectura a todos los archivos de OneDrive de un usuario, incluidos los archivos compartidos con este.
files.readwrite Concede permisos de lectura y escritura a todos los archivos de OneDrive de un usuario.
files.readwrite.all Concede permisos de lectura y escritura a todos los archivos de OneDrive de un usuario, incluidos los archivos compartidos con este.

Como ejemplo, una aplicación típica puede solicitar los ámbitos siguientes:

files.readwrite offline_access

Flujos de autenticación compatibles

Aunque Azure Active Directory admite varios flujos de autorización, los más comunes son los dos que se muestran aquí:

Flujo de tokens

El flujo de autorización más sencillo es el flujo de tokens. Este flujo es útil para obtener rápidamente un token de acceso para usar la API de OneDrive de una manera interactiva. Este flujo no proporciona un token de actualización y, por lo tanto, no es una buena opción para el acceso a largo plazo a los recursos.

Diagrama del flujo de tokens

Para iniciar el proceso de inicio de sesión con el flujo de tokens, use un explorador web o un control de explorador web para cargar una solicitud de dirección URL.

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id={client_id}&scope={scope}
    &response_type=token&redirect_uri={redirect_uri}

Parámetros necesarios de cadena de consulta

Nombre del parámetro Valor Descripción
client_id string El valor de id. de cliente que se ha creado para su aplicación.
redirect_uri cadena La dirección URL de redireccionamiento a la que se envía al explorador una vez finalizada la autenticación.
response_type string El tipo de respuesta que se espera del flujo de autorización. Para este flujo, el valor debe ser token.
scope string Una lista separada por espacios de ámbitos que necesita su aplicación.

Respuesta

Después de una autenticación y autorización correctas de la aplicación, el explorador web se redirige a la URL de redireccionamiento proporcionada con los parámetros adicionales agregados a la URL.

https://myapp.com/auth-redirect#access_token=EwC...EB
  &authentication_token=eyJ...3EM&token_type=bearer&expires_in=3600
  &scope=onedrive.readwrite&user_id=3626...1d

Los valores para access_token, authentication_token y user_id se truncan en el ejemplo anterior. Los valores para access_token y authentication_token son bastante largos.

Puede usar el valor de access_token para realizar solicitudes a Microsoft Graph.

Flujo de códigos

El flujo de códigos para la autenticación es un proceso de tres pasos con llamadas independientes para autenticar y autorizar la aplicación, y para generar un token de acceso para usar la API de OneDrive. Esto también permite que su aplicación reciba un token de actualización que permitirá el uso a largo plazo de la API en algunos escenarios, para permitir el acceso cuando el usuario no esté usando de manera activa la aplicación.

Diagrama del flujo de código de autorización

Paso 1. Obtener un código de autorización

Para iniciar el proceso de inicio de sesión con el flujo de códigos, use un explorador web o un control de explorador web para cargar esta solicitud de dirección URL.

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id={client_id}&scope={scope}
  &response_type=code&redirect_uri={redirect_uri}

Parámetros necesarios de cadena de consulta

Nombre del parámetro Valor Descripción
client_id cadena El id. de cliente creado para su aplicación.
scope string Una lista separada por espacios de ámbitos que necesita su aplicación.
redirect_uri cadena La dirección URL de redireccionamiento a la que se envía al explorador una vez finalizada la autenticación.
response_type string El tipo de respuesta que se espera del flujo de autorización. Para este flujo, el valor debe ser code.

Respuesta

Después de una autenticación y autorización correctas de la aplicación, el explorador web se redirigirá a la dirección URL de redireccionamiento con los parámetros adicionales agregados a la dirección URL.

https://myapp.com/auth-redirect?code=df6aa589-1080-b241-b410-c4dff65dbf7c

Paso 2. Canjear el código para obtener tokens de acceso

Después de que haya recibido el valor code, puede canjear este código por un conjunto de tokens que le permiten autenticarse con la API de OneDrive. Para canjear el código, realice la solicitud siguiente:

POST https://login.microsoftonline.com/common/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id={client_id}&redirect_uri={redirect_uri}&client_secret={client_secret}
&code={code}&grant_type=authorization_code

Parámetros de cuerpo de solicitud requeridos

El cuerpo de solicitud es una cadena codificada con la dirección URL correctamente, con algunos parámetros necesarios.

Nombre del parámetro Valor Descripción
client_id string El valor de id. de cliente que se ha creado para su aplicación.
redirect_uri cadena La dirección URL de redireccionamiento a la que se envía al explorador una vez finalizada la autenticación. Debe coincidir con el valor redirect_uri de la primera solicitud.
client_secret string El secreto de cliente que se crea para su aplicación.
code string El código de autorización que ha recibido en la primera solicitud de autenticación.

Nota En el caso de las aplicaciones web, la parte del dominio del URI de redirección debe coincidir con la parte del dominio del URI de redirección que especificó en el Centro para desarrolladores de Microsoft.

Respuesta

Si la llamada se realiza correctamente, la respuesta a la solicitud POST contiene una cadena JSON que incluye varias propiedades, incluidas access_token, token_type y refresh_token (si ha solicitado el ámbito wl.offline_access).

{
  "token_type":"bearer",
  "expires_in": 3600,
  "scope":"wl.basic onedrive.readwrite",
  "access_token":"EwCo...AA==",
  "refresh_token":"eyJh...9323"
}

Ahora puede almacenar y usar el access_token proporcionado para realizar solicitudes autenticadas en Microsoft Graph.

Importante: Trate los valores de access_token y refresh_token en esta respuesta de manera tan segura como lo haría con la contraseña de un usuario.

El token de acceso es válido solo durante el número de segundos que se especifique en la propiedad expires_in. Puede solicitar un nuevo token de acceso con el token de actualización (si está disponible), o repitiendo la solicitud de autenticación desde el principio.

Paso 3. Obtener un nuevo token de acceso o un token de actualización

Si la aplicación ha solicitado el ámbito offline_access, este paso devolverá un refresh_token que puede usarse para generar tokens de acceso adicionales después de que el token inicial haya expirado.

Para canjear el token de actualización para obtener un nuevo token de acceso, realice la solicitud siguiente:

POST https://login.microsoftonline.com/common/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id={client_id}&redirect_uri={redirect_uri}&client_secret={client_secret}
&refresh_token={refresh_token}&grant_type=refresh_token

Parámetros de cuerpo de solicitud requeridos

El cuerpo de solicitud es una cadena codificada con la dirección URL correctamente, con algunos parámetros necesarios.

Nombre del parámetro Valor Descripción
client_id cadena Identificador cliente que se crea para su aplicación.
redirect_uri cadena Dirección URL de redireccionamiento a la que se envía el explorador una vez finalizada la autenticación. Debe coincidir con el valor del parámetro redirect_uri que se usó en la primera solicitud.
client_secret string El secreto de cliente que se crea para su aplicación.
refresh_token cadena El token de actualización que recibió antes.

Nota En el caso de las aplicaciones web, la parte del dominio del URI de redirección debe coincidir con la parte del dominio del URI de redirección que especificó en el Centro para desarrolladores de Microsoft.

Respuesta

Si la llamada se realiza correctamente, la respuesta a la solicitud POST contiene una cadena JSON que incluye varias propiedades, incluidas access_token, authentication_token y refresh_token, si ha solicitado el ámbito offline_access.

{
  "token_type":"bearer",
  "expires_in": 3600,
  "scope": "wl.basic onedrive.readwrite wl.offline_access",
  "access_token":"EwCo...AA==",
  "refresh_token":"eyJh...9323"
}

Ahora puede almacenar y usar el access_token para realizar solicitudes autenticadas en Microsoft Graph.

Importante: Trate los valores de access_token y refresh_token en esta respuesta de manera tan segura como lo haría con la contraseña de un usuario.

El token de acceso es válido solo durante el número de segundos que se especifique en la propiedad expires_in. Puede solicitar un nuevo token de acceso con el token de actualización (si está disponible) o repitiendo la solicitud de autenticación desde el principio.

Cerrar la sesión del usuario

Para cerrar la sesión de un usuario, realice los siguientes pasos:

  1. Elimine cualquier valor access_token o refresh_token almacenado en caché que haya recibido anteriormente del flujo de OAuth.
  2. Realice cualquier acción de cierre de sesión en la aplicación (por ejemplo, limpiar el estado local, quitar cualquier elemento almacenado en caché, etc.).
  3. Realice una llamada al servicio web de autorización con esta dirección URL:
GET https://login.microsoftonline.com/common/oauth2/v2.0/logout?post_logout_redirect_uri={redirect-uri}

Esta llamada quitará cualquier cookie que permita que se produzca el inicio de sesión único y garantice que la próxima vez que la aplicación inicie el flujo de autorización, se necesitará que el usuario inicie sesión de nuevo. Con este flujo de cierre de sesión no se revoca ningún contenido concedido anteriormente a una aplicación.

Parámetros necesarios de la cadena de consulta

Nombre del parámetro Valor Descripción
redirect_uri cadena La dirección URL de redireccionamiento a la que se envía al explorador una vez finalizada la autenticación. Esta debe coincidir exactamente con el valor redirect_uri que se ha usado en la solicitud de obtención de tokens.

Después de quitar la cookie, el explorador se redirigirá a la dirección URL de redireccionamiento que ha proporcionado. Cuando el explorador carga su página de redireccionamiento, no se establecerá ningún parámetro de cadena de consulta de autenticación y puede deducir que el usuario ha cerrado la sesión.

Revocar el acceso

Los usuarios de la cuenta Microsoft pueden revocar un acceso de la aplicación a su cuenta visitando la página Administrar consentimiento de la cuenta Microsoft.

Cuando se revoca el consentimiento de una aplicación, cualquier token de actualización que se haya proporcionado anteriormente en su aplicación ya no será válido. Necesitará repetir el flujo de autenticación para solicitar un nuevo token de acceso y actualización desde el principio.

En los temas siguientes se incluye información general de alto nivel de otros conceptos que se aplican a la API de OneDrive.