Compartir a través de

Autenticación e inicio de sesión de OneDrive

Usar Microsoft Graph

En este tema se incluye información sobre cómo autorizar una aplicación con cuentas Microsoft para OneDrive Personal. En cambio, este enfoque ya no se recomienda. Las aplicaciones nuevas deben desarrollarse con Microsoft Graph y seguir el proceso de autorización de Authorization and sign-in for OneDrive in Microsoft Graph (Autorización e inicio de sesión de OneDrive en Microsoft Graph).

Introducción

Para usar la API de OneDrive, necesita tener un token de acceso que autentique la aplicación en un conjunto determinado de permisos para un usuario. En esta sección, obtendrá información sobre cómo realizar las siguientes acciones:

  1. Registrar la aplicación para obtener un id. de cliente y un secreto de cliente.
  2. Iniciar la sesión del usuario en OneDrive 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 esquema de autenticación OAuth 2.0 estándar para autenticar usuarios y generar tokens de acceso. Debe proporcionar un token de acceso para cada llamada API mediante una de las opciones siguientes.

  • Un encabezado HTTP: Authorization: bearer {token}

Registrar su aplicación

Para autenticar la aplicación, necesita registrarla con Microsoft y proporcionar algunos detalles sobre esta.

Para registrar su aplicación

Para obtener información sobre cómo registrar la aplicación, vea el tema 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 servicio web de autorización de la cuenta Microsoft con un ámbito especificado, y recibir un token de acceso. El flujo sigue los flujos de autenticación de OAuth 2.0 estándar y necesita llamadas desde un explorador web o un control de explorador web.

Á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 Necesario
offline_access Permite que la aplicación funcione sin conexión incluso cuando el usuario no está activo. Esto proporciona a la aplicación un refresh_token que puede usarse para generar tokens de acceso adicionales si fuera necesario. Este ámbito no está disponible para el flujo de tokens. No
onedrive.readonly Concede permisos de solo lectura a todos los archivos de OneDrive de un usuario, incluidos los archivos compartidos con este. Sí
onedrive.readwrite Concede permisos de lectura y escritura a todos los archivos de OneDrive de un usuario, incluidos los archivos compartidos con este. Para crear vínculos para compartir, se necesita este ámbito. Sí
onedrive.appfolder Concede permisos de lectura y escritura a una carpeta específica para su aplicación. Sí

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

onedrive.readwrite offline_access

Flujos de autenticación compatibles

Existen dos flujos de autenticación compatibles entre los que elegir:

Flujo de tokens

El flujo de autenticació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, por lo que no puede usarse para el acceso a largo plazo para la API de OneDrive.

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.live.com/oauth20_authorize.srf?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.

Use esta dirección URL de redireccionamiento para las aplicaciones móviles y de escritorio https://login.live.com/oauth20_desktop.srf.

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://login.live.com/oauth20_authorize.srf#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 la API de OneDrive.

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.live.com/oauth20_authorize.srf?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://login.live.com/oauth20_authorize.srf?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.live.com/oauth20_token.srf
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 redireccionamiento que especificó en el Centro para desarrolladores de cuentas 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 la API de OneDrive.

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 acceso a wl.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.live.com/oauth20_token.srf
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 sitio de administración de aplicaciones SDK de Live.

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 wl.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 la API de OneDrive.

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.live.com/oauth20_logout.srf?client_id={client_id}&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 la experiencia de inicio de sesión se le pedirá al usuario que especifique un nombre de usuario y una contraseña para continuar.

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. 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 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 su 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.

Errores

Si existen errores con la autenticación, el explorador web se redirigirá a una página de error. Aunque la página de error siempre muestra un mensaje descriptivo para el usuario, la dirección URL de la página de error incluye información adicional que puede ayudarle a resolver los problemas que han sucedido. Esta información no se muestra siempre en el contenido de la página de error que se ha mostrado en el explorador.

https://login.live.com/err.srf?lc=1033#error={error_code}&error_description={message}

La dirección URL incluye parámetros de consulta que puede usar para analizar el error y responder en consecuencia. Estos parámetros siempre se incluyen como un marcador (después del carácter #). El contenido de la página siempre mostrará un mensaje de error genérico para el usuario.

Si el usuario decide no proporcionar el consentimiento a la aplicación, el flujo se redirigirá a redirect_uri e incluirá los mismos parámetros de error.

Parámetros de error

Nombre del parámetro Valor Descripción
error string Código de error que identifica el error que se ha producido.
error_description string Una descripción del error.

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

  • Last updated on