Autorização e inscrição do OneDrive no Microsoft Graph

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

1. Registrar seu aplicativo para receber uma ID de aplicativo.
2. Inscrever seu usuário 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 a estrutura de autorização padrão do OAuth 2.0 para autorizar aplicativos e gerar tokens de acesso. Você deve fornecer um token de acesso para cada chamada de API autenticada usando um cabeçalho HTTP:

Authorization: bearer {token}

Observação: a estrutura de autorização recomendada está usando o ponto de extremidade do Azure AD v2.0. No entanto, alguns cenários corporativos podem exigir o uso do ponto de extremidade do Azure AD original. Confira mais informações em Autenticação de aplicativo com o Microsoft Graph.

Registrar seu aplicativo

A primeira etapa é registrar um aplicativo na Microsoft e fornecer alguns detalhes sobre ele. Você pode registrar seu aplicativo e receber uma nova ID do aplicativo na página Azure App registros.

Confira as etapas detalhadas sobre como registrar seu aplicativo em Registrar seu aplicativo na API do OneDrive.

Conectar os usuários

Seu aplicativo deve iniciar o processo de inscrição entrando em contato com o ponto de extremidade de autorização do Azure Active Directory com um escopo especificado. O fluxo segue os fluxos de autorização padrão do OAuth 2.0 e requer chamadas de um navegador da Web ou controle de navegador da Web. O resultado do fluxo de autorização retornará um token de acesso e, opcionalmente, outros tokens que seu aplicativo pode usar para acessar a API.

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:

files.readwrite offline_access

Fluxos de autenticação com suporte

Enquanto o Azure Active Directory dá suporte a vários fluxos de autorização, os dois mais comuns estão descritos aqui:

• Fluxo de tokens
• Fluxo de códigos

Fluxo do tokens

O fluxo de autorização mais simples é o fluxo do tokens. Esse fluxo é útil para receber um token de acesso rapidamente para usar a API do OneDrive de forma interativa. Ele não oferece um token de atualização e, portanto, não é uma boa opção para acessar recursos no longo prazo.

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.microsoftonline.com/common/oauth2/v2.0/authorize?client_id={client_id}&scope={scope}
    &response_type=token&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 fornecida com mais parâmetros adicionados à 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

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 ao Microsoft Graph.

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.microsoftonline.com/common/oauth2/v2.0/authorize?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://myapp.com/auth-redirect?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.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 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 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 no Microsoft Graph.

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 seu aplicativo solicitou o escopo offline_access, esta etapa retorna 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.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 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 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, authentication_token e refresh_token, se você solicitou o escopo 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 no Microsoft Graph.

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.microsoftonline.com/common/oauth2/v2.0/logout?post_logout_redirect_uri={redirect-uri}

Essa chamada removerá os cookies que permitem que o logon único ocorra e garantirá que a próxima vez que o aplicativo iniciar o fluxo de autorização, o usuário precisará entrar novamente. Usar esse fluxo de logoff não revoga o conteúdo concedido anteriormente a um aplicativo.

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 da conta da Microsoft 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 um 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.

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
• Autenticação de aplicativo com o Microsoft Graph