Autenticação e entrada no OneDrive

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.

Introdução

Para usar a API do OneDrive, você precisa ter um token de acesso que autentique seu aplicativo para um conjunto específico de permissões de um usuário. Nesta seção, você aprenderá a:

1. Registrar seu aplicativo para fazer uma ID de cliente e um segredo de cliente.
2. Inscrever seu usuário no OneDrive com os escopos especificados usando o fluxo de tokens ou o fluxo de códigos.
3. Cancelar a inscrição do usuário (opcional).

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. Você precisa fornecer um token de acesso para cada chamada de API usando uma das seguintes opções:

• Um cabeçalho HTTP: Authorization: bearer {token}

Registrar seu aplicativo

Para autenticar seu aplicativo, você precisa registrar seu aplicativo com a Microsoft e fornecer alguns detalhes sobre o aplicativo.

Para registrar seu aplicativo

Confira mais detalhes no tópico sobre como registrar seu aplicativo na API do OneDrive.

Conectar os usuários

Seu aplicativo deve iniciar o processo de entrada contatando o serviço Web de autorização de conta da Microsoft com um escopo especificado e receber um token de acesso. 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.

Escopos de autenticação

Os escopos determinam que tipo de acesso o aplicativo recebe quando o usuário está conectado. Todos os escopos dão suporte a logon único na Web, ou seja, se o usuário já tiver entrado no OneDrive, ele poderá ignorar o fluxo de autenticação e ir diretamente para o fluxo de autorização.

Por exemplo, um aplicativo comum pode solicitar os seguintes escopos:

onedrive.readwrite offline_access

Fluxos de autenticação com suporte

Há dois fluxos de autenticação com suporte para sua escolha:

• Fluxo de tokens
• Fluxo de códigos

Fluxo do tokens

O fluxo de autenticação mais fácil é o fluxo token. Esse fluxo é útil para receber um token de acesso rapidamente para usar a API do OneDrive de forma interativa. Esse fluxo não fornece um token de atualização, portanto não pode ser usado para ter acesso de longo prazo à API do OneDrive.

Para iniciar o processo de inscrição com o fluxo de tokens, use um navegador da Web ou controle de navegador da Web para carregar uma solicitação de URL.

GET https://login.live.com/oauth20_authorize.srf?client_id={client_id}&scope={scope}
    &response_type=token&redirect_uri={redirect_uri}

Parâmetros de cadeia de caracteres de consulta necessários

Use esta URL de redirecionamento para aplicativos móveis e da área de trabalho https://login.live.com/oauth20_desktop.srf.

Resposta

Após a autenticação e a autorização do seu aplicativo, o navegador da Web é redirecionado para a URL de redirecionamento com mais parâmetros adicionados à 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

Os valores de access_token, authentication_token e user_id estão truncados no exemplo anterior. Os valores de access_token e authentication_token são muito longos.

Você pode usar o valor de access_token para fazer solicitações à API do OneDrive.

Fluxo do códigos

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. Isso também permite que seu aplicativo receba um token de atualização que permitirá o uso no longo prazo da API em alguns cenários, para permitir o acesso quando o usuário não estiver usando ativamente o aplicativo.

Etapa 1. Receber um código de autorização

Para iniciar o processo de inscrição com o fluxo de códigos, use um navegador da Web ou controle de navegador da Web para carregar esta solicitação de URL.

GET https://login.live.com/oauth20_authorize.srf?client_id={client_id}&scope={scope}
  &response_type=code&redirect_uri={redirect_uri}

Parâmetros de cadeia de caracteres de consulta necessários

Resposta

Após a autenticação e a autorização do seu aplicativo, o navegador da Web é redirecionado para a URL de redirecionamento com mais parâmetros adicionados à URL.

https://login.live.com/oauth20_authorize.srf?code=df6aa589-1080-b241-b410-c4dff65dbf7c

Etapa 2. Resgatar o código dos tokens de acesso

Após receber o valor de code, você poderá resgatar esse código para um conjunto de tokens que permitem autenticar com a API do OneDrive. Para recuperar o código, realize a seguinte solicitação:

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 obrigatórios do corpo da solicitação

O corpo da solicitação é uma cadeia de caracteres de URL codificada corretamente, com alguns parâmetros obrigatórios.

Nota Para aplicativos Web, a parte de domínio do URI de redirecionamento deve corresponder à parte de domínio do URI de redirecionamento especificado no Centro de Desenvolvedores da conta Microsoft.

Resposta

Se a chamada é bem-sucedida, a resposta para a solicitação POST contém uma cadeia de caracteres JSON que inclui várias propriedades, inclusive access_token, token_type e refresh_token, se você solicitou o escopo wl.offline_access.

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

Agora você pode armazenar e usar o access_token fornecido para fazer solicitações autenticadas para a API do OneDrive.

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. Você pode solicitar 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.

Etapa 3. Receber um token de acesso ou um token de atualização

Se o seu aplicativo tiver solicitado acesso a wl.offline_access, esta etapa retornará um refresh_token que pode ser usado para gerar tokens de acesso adicionais após o token inicial expirar.

Para resgatar o token de atualização para um novo token de acesso, faça a solicitação a seguir:

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 obrigatórios do corpo da solicitação

O corpo da solicitação é uma cadeia de caracteres de URL codificada corretamente, com alguns parâmetros obrigatórios.

Nota Para aplicativos Web, a parte de domínio do URI de redirecionamento deve corresponder à parte de domínio do URI de redirecionamento especificado no Live SDK site de gerenciamento de aplicativos.

Resposta

Se a chamada for bem-sucedida, a resposta para a solicitação POST conterá uma cadeia de caracteres JSON que inclui várias propriedades, inclusive access_token, authentication_token e refresh_token, se você solicitou o escopo 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"
}

Agora você pode armazenar e usar o access_token para fazer solicitações autenticadas para a API do OneDrive.

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 (se estiver disponível) ou repetindo a solicitação de autenticação desde o início.

Cancelar a inscrição do usuário

Para cancelar a inscrição do usuário, execute as seguintes etapas:

1. Exclua qualquer valor de cache, access_token ou refresh_token, que você recebeu do fluxo de OAuth anteriormente.
2. Execute qualquer ação de cancelamento de inscrição no seu aplicativo (por exemplo, limpeza de estado local, remoção de itens armazenados em cache etc.).
3. Faça uma chamada ao serviço Web de autorização usando esta URL:

GET https://login.live.com/oauth20_logout.srf?client_id={client_id}&redirect_uri={redirect_uri}

Essa chamada removerá os cookies que permitem o logon único e garantirá que a próxima vez que o aplicativo iniciar a experiência de entrada, o usuário receberá uma solicitação para entrar um nome de usuário e senha a fim de continuar.

Parâmetros de cadeia de caracteres de consulta necessários

Após remover o cookie, o navegador será redirecionado para a URL de redirecionamento que você forneceu. Quando o navegador carrega sua página de redirecionamento, nenhum parâmetro de cadeia de caracteres de consulta de autenticação é definido, e você pode deduzir que o usuário fez logoff.

Revogar o acesso

Os usuários podem revogar o acesso do aplicativo às contas deles visitando a página de consentimento de gerenciamento de conta da Microsoft.

Quando o consentimento para seu aplicativo é revogado, qualquer token de atualização fornecido anteriormente ao seu aplicativo deixa de ser válido. Você precisará repetir o fluxo de autenticação para solicitar um novo acesso e atualizar o token do zero.

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. Nem sempre essas informações são exibidas no conteúdo da página de erro exibida no navegador.

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

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.

Parâmetros de erro

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.

• Desenvolver com a API do OneDrive