Autenticación e inicio de sesión de OneDrive para la Empresa
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).
Usar Azure Active Directory para la autenticación
Para usar la API de OneDrive con OneDrive para la Empresa, necesita tener un token de acceso que autentique la aplicación en un conjunto determinado de permisos para un usuario.
Obtener una aplicación configurada para tener acceso a OneDrive para la Empresa es un desafío. Estamos trabajando en facilitar este proceso, así que tenga paciencia.
En esta sección, obtendrá información sobre cómo:
La API de OneDrive usa el esquema de autenticación OAuth 2.0 estándar para autenticar usuarios y generar tokens de acceso. Proporcione un token de acceso a cada llamada API mediante un encabezado HTTP:
Authorization: bearer {token}
Puede tener acceso a la API enviando solicitudes HTTP a una dirección URL de punto de conexión específica.
La dirección URL raíz se basa en el nombre de host del servidor que actúa como el punto de conexión REST.
Puede usar la API de detección para buscar puntos de conexión para los servicios de Office 365.
Para obtener más información, vea Common endpoint discovery tasks using the Discovery Service API (Tareas comunes de detección de puntos de conexión con la API de Servicio de detección).
La dirección URL raíz aparece en el ejemplo siguiente, donde {tenant} proviene de la URL de punto de conexión que se ha detectado:
https://{tenant}-my.sharepoint.com/_api/v2.0/
Registrar su aplicación con Azure Active Directory
Antes de que pueda iniciar sesión, necesita registrar la aplicación con Azure Active Directory y establecer los permisos que necesita la aplicación. Para obtener más información, vea Register your app for SharePoint Server 2016 or OneDrive for Business (Registrar la aplicación para SharePoint Server 2016 o OneDrive para la Empresa).
Iniciar sesión en OneDrive para la Empresa
Para iniciar sesión en OneDrive para la Empresa por primera vez, la aplicación necesita los valores siguientes:
- Id. de cliente y clave (secreto de cliente) como se han registrado con Azure Active Directory (AAD)
- El código de autorización que se ha recibido del flujo de código de autorización de OAuth 2
- Dirección URL de punto de conexión de la API de OneDrive para la Empresa
- Token de acceso para el recurso de OneDrive para la Empresa
- Token de actualización para generar tokens de acceso adicionales cuando expire el token actual.
Los pasos siguientes le guiarán a través de las solicitudes necesarias para obtener todos estos valores.
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. Vea Autenticación de aplicaciones con Microsoft Graph para obtener información de autenticación general de Office 365. En cambio, obtener todos los valores necesarios para usar la API de OneDrive para la Empresa requiere unos pasos adicionales.
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. En este proceso también se crea y se envía un token de actualización a la aplicación. Con el token de actualización, está disponible el uso a largo plazo de la API cuando el usuario no está usando la aplicación de manera activa.
Cada token de acceso que se ha generado mediante Azure Active Directory es específico para un único recurso. Para detectar el punto de conexión de la API de OneDrive para la Empresa y para realizar llamadas a ese punto de conexión necesitará dos tokens de acceso, uno para cada punto de conexión de la API (recurso).
Un único token de actualización puede usarse para generar tokens de acceso para cualquier punto de conexión al que su aplicación tenga autorización para tener acceso.
Paso 1. Iniciar sesión y obtener un código de autorización
Para comenzar, la aplicación carga el punto de conexión OAuth 2 de Azure Active Directory común en un explorador web que pide al usuario que inicie sesión con sus credenciales. Esta dirección URL usa el punto de conexión de inquilino común y es válido para cualquier aplicación.
GET https://login.microsoftonline.com/common/oauth2/authorize?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}
Parámetros necesarios de la cadena de consulta
| Nombre del parámetro | Valor | Descripción |
|---|---|---|
| client_id | cadena | El id. de cliente creado para su aplicación. |
| response_type | cadena | Specifies the requested response type. In an authorization code grant request, the value must be code. |
| redirect_uri | cadena | La URL de redireccionamiento a la que se envía al explorador una vez finalizada la autenticación. |
Nota El URI de redireccionamiento debe coincidir con uno de los URI de redireccionamiento que ha especificado en el Portal de administración de Azure.
Respuesta
Después de una autenticación correcta del usuario y la autorización de la aplicación, como se muestra en el ejemplo siguiente, el explorador web se redirige a la URL de redireccionamiento con los parámetros adicionales agregados a la URL.
https://myapp.contoso.com/myapp/callback?code=AwABAAAAvPM...
El valor de la cadena de consulta code es el código de autorización que necesitará en el paso siguiente.
Paso 2. Canjear el código de autorización por tokens
Después de que haya recibido el valor code, puede canjear este código por un conjunto de tokens que le permiten autenticarse con varias API de Office 365.
Para canjear el código, realice una solicitud al punto de conexión de token para Azure Active Directory, como se muestra en el ejemplo:
POST https://login.microsoftonline.com/common/oauth2/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&resource={resource_id}
El cuerpo de esta solicitud es una cadena codificada con la dirección URL, con los siguientes 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 | Uno de los valores de clave creados para la aplicación. |
| code | string | El código de autorización que ha recibido en la primera solicitud de autenticación. |
| resource | cadena | El recurso al que quiere tener acceso. |
En la mayoría de los casos, la dirección URL de punto de conexión de la API de OneDrive para la Empresa no se conocerá.
Para detectar la URL de punto de conexión, necesita realizar una llamada a la API de detección de Office 365.
Para autenticarse con la API de detección, necesita solicitar un token de acceso para el recurso https://api.office.com/discovery/.
Asegúrese de incluir el carácter / final, de otro modo, la aplicación denegará el acceso a la API de detección.
Respuesta
Si la llamada se realiza correctamente, el cuerpo de la respuesta es una cadena JSON que incluye propiedades access_token, expires_in y refresh_token.
{
"expires_in": 3600,
"access_token":"EwCo...AA==",
"refresh_token":"eyJh...9323"
}
Nota: Pueden existir propiedades adicionales en la respuesta. Estas propiedades no se necesitan para usar las API.
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, o repitiendo la solicitud de autenticación desde el principio.
Paso 3. Detectar el URI de recurso de OneDrive para la Empresa
Como los diferentes usuarios e inquilinos usan una dirección URL diferente para proporcionar acceso a la API a la aplicación, necesitará detectar la URL para OneDrive para la Empresa del usuario que ha iniciado sesión. Para hacer esto, la aplicación puede usar la API de detección de Office 365 para solicitar una lista de servicios y puntos de conexión de API disponibles en la aplicación y el usuario que ha iniciado sesión.
Con un token de acceso que haya recibido para un recurso https://api.office.com/discovery/, puede realizar una solicitud a la API de detección para obtener información sobre qué servicios están disponibles:
GET https://api.office.com/discovery/v2.0/me/services
Authorization: Bearer {access_token}
| Nombre del parámetro | Valor | Descripción |
|---|---|---|
| access_token | string | Un token de acceso válido para el recurso https://api.office.com/discovery/ |
Respuesta
Si la llamada se realiza correctamente, el cuerpo de la respuesta contiene datos JSON con información sobre los servicios disponibles para el usuario y la aplicación. Puede analizar esta respuesta para buscar la URL de punto de conexión para la API de OneDrive para la Empresa.
{
"@odata.context": "https:\/\/api.office.com\/discovery\/v1.0\/me\/$metadata#allServices",
"value": [
{
"@odata.type": "#Microsoft.DiscoveryServices.ServiceInfo",
"capability": "MyFiles",
"serviceApiVersion": "v2.0",
"serviceEndpointUri": "https:\/\/contoso-my.sharepoint.com\/_api\/v2.0",
"serviceResourceId": "https:\/\/contoso-my.sharepoint.com\/"
}
]
}
Nota: Pueden devolverse otras propiedades en el objeto ServiceInfo. Este ejemplo se trunca en las propiedades de clave.
Para localizar la URL de punto de conexión para OneDrive para la Empresa del usuario, querrá buscar el objeto ServiceInfo en la colección value que coincide con el siguiente predicado:
capability = "MyFiles" AND serviceApiVersion = "v2.0"
Cuando la aplicación encuentre un objeto ServiceInfo coincidente para OneDrive para la Empresa del usuario, necesita almacenar el valor de dos propiedades de ese objeto: serviceResourceId y serviceEndpointUri. Estos valores se usarán en el paso siguiente para proporcionar un nuevo token de acceso y realizar llamadas API de OneDrive.
Paso 4. Canjear el token de actualización para obtener un token de acceso para llamar a la API de OneDrive
Ahora que la aplicación conoce la URL de punto de conexión y recurso para OneDrive para la Empresa del usuario, puede canjear el token de actualización que ha recibido en el paso 2 para obtener un token de acceso que puede usarse con la API de OneDrive.
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/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&resource={resource_id}
El cuerpo de la solicitud es una cadena codificada con la dirección URL, con los siguientes parámetros:
| 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 | cadena | Uno de los valores de la sección Claves creados para la aplicación. |
| refresh_token | cadena | El token de actualización que recibió antes. |
| recurso | cadena | El recurso al que quiere tener acceso. Debe ser el valor serviceResourceId que se ha detectado anteriormente. |
Nota El URI de redireccionamiento debe coincidir con el URI de redireccionamiento especificado en el Portal de administración de Azure.
Respuesta
Si la llamada se realiza correctamente, el cuerpo de la respuesta es una cadena JSON que incluye propiedades access_token, expires_in y refresh_token.
{
"expires_in": 3600,
"access_token":"EwCo...AA==",
"refresh_token":"eyJh...9323"
}
Nota: Reemplace los valores del token de actualización que ha almacenado anteriormente por los que se han devuelto de las llamadas posteriores al servicio de token para garantizar que su aplicación tiene un token con la expiración más reciente.
El valor de la propiedad access_token ahora puede usarse para realizar solicitudes autenticadas a la API de OneDrive. Para obtener más información sobre los tokens de actualización, vea Autorización del acceso a aplicaciones web mediante OAuth 2.0 y Azure Active Directory.
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 (normalmente 1 hora). 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.
Si el token de acceso expira, las solicitudes a la API devolverán una respuesta 401 Unauthorized.
Si recibe esta respuesta en una solicitud autenticada debe generar un nuevo token de acceso con el token de actualización almacenado.
Paso 5. Realizar una solicitud a la API de OneDrive
Ahora que la aplicación tiene un token de acceso válido para el punto de conexión de API OneDrive para la Empresa del usuario, puede realizar una solicitud autenticada a la API de OneDrive.
Para realizar la solicitud necesitará el valor serviceEndpointUri que ha obtenido de la API de detección y el token de acceso que ha recibido del servicio de token.
Por ejemplo, para obtener los detalles de OneDrive para la Empresa del usuario, puede realizar una solicitud a la ruta de API /drive:
GET {serviceEndPointUri}/drive
Authorization: Bearer {access_token}
Errores
Si existen errores con la autenticación, el explorador web se redirige 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. Este tipo de información no se muestra siempre en el contenido de la página de error que se ha mostrado en el explorador.
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.
Para obtener más información sobre cómo controlar los errores, vea Autorización del acceso a aplicaciones web mediante OAuth 2.0 y Azure Active Directory.
Temas relacionados
En los temas siguientes se incluye información general de alto nivel de otros conceptos que se aplican a la API de OneDrive.
- Develop with the OneDrive API (Desarrollo con la API de OneDrive)
- Usar Azure Active Directory para la autenticación
- OneDrive authentication and sign-in using Microsoft accounts (Inicio de sesión y autenticación de OneDrive con cuentas Microsoft)
- Office 365 authentication concepts (Conceptos de la autenticación de Office 365)
- OAuth 2.0 in Azure AD (OAuth 2.0 en Azure AD)
- Authorization Code Grant Flow (Flujo de concesión del código de autorización)