Autenticação e entrada no OneDrive for Business
Usar o Microsoft Graph
Este tópico contém informações sobre como autorizar um aplicativo usando contas da Microsoft para OneDrive pessoal. No entanto, essa abordagem não é mais recomendada. Os novos aplicativos devem ser desenvolvidos usando o Microsoft Graph e seguir o processo de autorização na Autorização e entrada para OneDrive no Microsoft Graph.
Como usar o Azure Active Directory para autenticação.
Para usar a API do OneDrive com o OneDrive for Business, você precisa ter um token de acesso que autentique seu aplicativo para um conjunto específico de permissões de um usuário.
Configurar um aplicativo para acessar o OneDrive for Business é um desafio. Estamos trabalhando para facilitar esse processo, portanto, seja paciente conosco.
Nesta seção, você aprenderá a:
A API do OneDrive usa o esquema de autenticação padrão do OAuth 2.0 para autenticar os usuários e gerar tokens de acesso. Forneça um token de acesso para cada chamada de API por meio de um cabeçalho HTTP:
Authorization: bearer {token}
Acesse a API enviando solicitações HTTP para uma URL de ponto de extremidade específica.
A URL raiz tem base no nome do host do servidor que serve como o ponto de extremidade REST.
Use a API de descoberta para localizar pontos de extremidade de serviços do Office 365.
Para saber mais, veja Tarefas comuns de descoberta do ponto de extremidade usando a API do Serviço de Descoberta.
Sua URL raiz aparece no próximo exemplo, em que {tenant} provêm de sua URL de ponto de extremidade descoberta:
https://{tenant}-my.sharepoint.com/_api/v2.0/
Registrar o aplicativo com o Azure Active Directory
Antes de poder entrar, você precisa registrar seu aplicativo com o Azure Active Directory e definir as permissões que o aplicativo precisa. Para saber mais, veja Registrar seu aplicativo para SharePoint Server 2016 ou OneDrive for Business.
Entrar no OneDrive for Business
Para entrar no OneDrive for Business pela primeira vez, seu aplicativo precisa dos seguintes valores:
- ID e Chave do Cliente (segredo do cliente) conforme registrado no Azure Active Directory (AAD)
- Código de autorização recebido do fluxo de código de autorização do OAuth 2
- URL do ponto de extremidade da API do OneDrive for Business
- Token de acesso para o recurso do OneDrive for Business
- Token de atualização para gerar tokens de acesso adicionais quando o atual expirar.
As etapas a seguir apresentarão as solicitações necessárias para obter todos esses valores.
O fluxo segue fluxos de autenticação padrão OAuth 2.0 e exige chamadas a partir de um navegador da Web ou controle de navegador Web. Veja Noções básicas de conceitos de autenticação do aplicativo Office 365 para informações de autenticação gerais do Office 365. No entanto, fazer com que todos os valores exigidos usem a API do OneDrive for Business exige algumas etapas adicionais.
O fluxo de códigos para autenticação é um processo de três etapas com chamadas separadas para autenticar e autorizar o aplicativo e gerar um token de acesso para uso da API do OneDrive. Esse processo também cria e envia um token de atualização para seu aplicativo. Com o token de atualização, o uso de longo prazo da API estará disponível quando o usuário não estiver usando ativamente o aplicativo.
Cada token de acesso gerado pelo Azure Active Directory é específico a um único recurso. Para descobrir o ponto de extremidade da API do OneDrive for Business e fazer chamadas para esse ponto de extremidade, você precisará de dois tokens de acesso, um para cada ponto de extremidade de API (recursos).
Um único token de atualização pode ser usado para gerar tokens de acesso para qualquer ponto de extremidade para o qual seu aplicativo tem autorização de acesso.
Etapa 1. Fazer logon e obter um código de autorização
Para começar, seu aplicativo carrega o ponto de extremidade comum de OAuth 2 do Azure Active Directory em um navegador da Web que solicita ao usuário o logon com suas credenciais. Esta URL usa o ponto de extremidade de locatário comum e é válida para qualquer aplicativo.
GET https://login.microsoftonline.com/common/oauth2/authorize?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}
Parâmetros de cadeia de caracteres de consulta necessários
| Nome do parâmetro | Valor | Descrição |
|---|---|---|
| client_id | string | A ID do cliente criada para o seu aplicativo. |
| response_type | string | Specifies the requested response type. In an authorization code grant request, the value must be code. |
| redirect_uri | string | A URL de redirecionamento para a qual o navegador é enviado quando a autenticação é concluída. |
Observação O URI de redirecionamento deve coincidir com um dos URIs de redirecionamento que você especificou no Portal de Gerenciamento do Azure.
Resposta
Após a autenticação bem-sucedida do usuário e a autorização de seu aplicativo, conforme exibido no exemplo a seguir, o navegador da Web é redirecionado para sua URL de redirecionamento com parâmetros adicionais adicionados à URL.
https://myapp.contoso.com/myapp/callback?code=AwABAAAAvPM...
O valor de cadeia de caracteres da consulta de código é o código de autorização que você precisará para a próxima etapa.
Etapa 2. Resgatar o código de autorização para tokens
Após você receber o valor de code, você poderá recuperar esse código para um conjunto de tokens que permite a autenticação com diversas APIs do Office 365.
Para resgatar o código, faça uma solicitação para o ponto de extremidade do token para o Azure Active Directory, como no exemplo:
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}
O corpo desta solicitação é uma cadeia de caracteres codificada de URL, com os seguintes parâmetros obrigatórios:
| Nome do parâmetro | Valor | Descrição |
|---|---|---|
| client_id | string | O valor da ID do cliente criada para o aplicativo. |
| redirect_uri | string | A URL de redirecionamento para a qual o navegador é enviado quando a autenticação é concluída. Isso deve corresponder ao valor de redirect_uri na primeira solicitação. |
| client_secret | string | Um dos valores de Chave criados para o aplicativo. |
| code | string | O código de autorização recebido na primeira solicitação de autenticação. |
| recurso | string | O recurso que você deseja acessar. |
Na maioria dos casos, a URL do ponto de extremidade da API do OneDrive for Business será não conhecida.
Para descobrir a URL do ponto de extremidade, você precisa fazer uma chamada para a API de Descoberta do Office 365.
Para autenticar com a API de descoberta, você precisa solicitar um token de acesso para o recurso https://api.office.com/discovery/.
Inclua o caractere / à direita, caso contrário, o acesso de seu aplicativo será negado para a API de descoberta.
Resposta
Se a chamada for bem-sucedida, o corpo da resposta será uma cadeia de caracteres JSON que inclui as propriedades access_token, expires_in e refresh_token.
{
"expires_in": 3600,
"access_token":"EwCo...AA==",
"refresh_token":"eyJh...9323"
}
Observação: talvez haja propriedades adicionais na resposta. Essas propriedades não são necessárias para usar as APIs.
Importante: Trate os valores de access_token e refresh_token nesta resposta com a mesma segurança de uma senha de usuário.
O token de acesso é válido somente para o número de segundos especificado na propriedade expires_in. Solicite um novo token de acesso usando o token de atualização, ou repetindo a solicitação de autenticação desde o início.
Etapa 3. Descobrir o URI de recurso do OneDrive for Business
Como usuários e locatários diferentes usam uma URL diferente para fornecer à API acesso ao seu aplicativo, você precisará descobrir a URL para o OneDrive for Business do usuário conectado. Para fazer isso, seu aplicativo pode usar a API de Descoberta do Office 365 para solicitar uma lista de serviços e pontos de extremidade de API disponíveis para seu aplicativo e o usuário conectado.
Usando um token de acesso recebido para o recurso https://api.office.com/discovery/, você pode fazer uma solicitação para a API de descoberta a fim saber quais serviços estão disponíveis:
GET https://api.office.com/discovery/v2.0/me/services
Authorization: Bearer {access_token}
| Nome do parâmetro | Valor | Descrição |
|---|---|---|
| access_token | string | Um token de acesso válido para o recurso https://api.office.com/discovery/ |
Resposta
Se a chamada for bem-sucedida, o corpo da resposta conterá dados JSON com informações sobre os serviços disponíveis para o usuário e seu aplicativo. Você pode analisar esta resposta para encontrar a URL do ponto de extremidade para a API do OneDrive for Business.
{
"@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\/"
}
]
}
Observação: Outras propriedades retornarão no objeto ServiceInfo. Este exemplo é truncado para as propriedades principal.
Para localizar a URL do ponto de extremidade para o OneDrive for Business do usuário, convém encontrar o objeto ServiceInfo no conjunto value que coincida com o predicado a seguir:
capability = "MyFiles" AND serviceApiVersion = "v2.0"
Quando seu aplicativo localizar um objeto ServiceInfo correspondente para o OneDrive for Business do usuário, você precisará armazenar o valor de duas propriedades desse objeto: serviceResourceId e serviceEndpointUri. Esses valores serão usados na próxima etapa para obtenção de um novo token de acesso e para fazer chamadas da API do OneDrive.
Etapa 4. Resgatar token de atualização para um token de acesso chamar a API do OneDrive
Agora que seu aplicativo conhece o recurso e a URL do ponto de extremidade para o OneDrive for Business do usuário, ele pode resgatar o token de atualização recebido na etapa 2 para um token de acesso que pode ser usada com a API do OneDrive.
Para resgatar o token de atualização para um novo token de acesso, faça a solicitação a seguir:
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}
O corpo da solicitação é uma cadeia de caracteres codificada por URL com os seguintes parâmetros:
| Nome do parâmetro | Valor | Descrição |
|---|---|---|
| client_id | string | A ID do cliente criada para o aplicativo. |
| redirect_uri | string | A URL de redirecionamento para a qual o navegador é enviado quando a autenticação é concluída. Isso deve corresponder ao valor redirect_uri usado na primeira solicitação. |
| client_secret | string | Um dos valores de Chaves criados para o aplicativo. |
| refresh_token | string | O token de atualização recebido anteriormente. |
| recurso | string | O recurso que você deseja acessar. Esse deve ser o valor de serviceResourceId descoberto anteriormente. |
Nota O URI de redirecionamento deve corresponder ao URI de redirecionamento especificado no Portal de Gerenciamento do Azure.
Resposta
Se a chamada for bem-sucedida, o corpo da resposta será uma cadeia de caracteres JSON que inclui access_token, expires_in e refresh_token.
{
"expires_in": 3600,
"access_token":"EwCo...AA==",
"refresh_token":"eyJh...9323"
}
Observação: Substitua os valores do token de atualização armazenados anteriormente por aqueles retornados nas chamadas subsequentes para o serviço de token, a fim de garantir que seu aplicativo tenha um token com a data de validade mais recente.
Agora, o valor da propriedade access_token pode ser usado para fazer solicitações autenticadas para a API do OneDrive. Para saber mais sobre tokens de atualização, veja Tokens de atualização para vários recursos.
Importante: Trate os valores de access_token e refresh_token nesta resposta com a mesma segurança de uma senha de usuário.
O token de acesso é válido somente para o número de segundos especificado na propriedade expires_in (normalmente uma hora). Solicite um novo token de acesso usando o token de atualização (se estiver disponível) ou repetindo a solicitação de autenticação desde o início.
Se o token de acesso expirar, as solicitações para a API retornarão uma resposta 401 Unauthorized.
Se você receber essa resposta para uma solicitação autenticada, gere um novo token de acesso usando seu token de atualização armazenado.
Etapa 5. Fazer uma solicitação para a API do OneDrive
Agora que seu aplicativo tem um token de acesso válido para o ponto de extremidade da API OneDrive for Business do usuário, ele pode fazer uma solicitação autenticada para a API do OneDrive.
Para fazer a solicitação, você precisará do valor de serviceEndpointUri recuperado da API de descoberta e do token de acesso recebido do serviço de token.
Por exemplo, para obter os detalhes do OneDrive for Business do usuário, você pode fazer uma solicitação para o caminho da API do /drive:
GET {serviceEndPointUri}/drive
Authorization: Bearer {access_token}
Erros
Se houver erros com a autenticação, o navegador da Web será redirecionado para uma página de erro. Embora a página de erro sempre apresente uma mensagem amigável para o usuário final, a URL para a página de erro inclui informações adicionais que podem ajudar você a depurar o que aconteceu. Esse tipo de informação nem sempre é mostrado no conteúdo da página de erro exibida no navegador.
A URL inclui parâmetros de consulta que você pode usar para analisar o erro e responder adequadamente.
Esses parâmetros sempre são incluídos como um indicador (depois do caractere #).
O conteúdo da página sempre exibirá uma mensagem de erro genérica para o usuário.
Se o usuário escolher não dar permissão ao seu aplicativo, o fluxo será redirecionado para seu redirect_uri e incluirá os mesmos parâmetros de erro.
Para saber mais sobre como tratar erros, veja Tratamento de erros no OAuth 2.0.
Tópicos relacionados
Os tópicos a seguir contêm visões gerais de alto nível de outros conceitos que se aplicam à API do OneDrive.