OAuth 2.0 para apps para dispositivos móveis e de computador

Este documento explica como os aplicativos instalados em dispositivos como telefones, tablets e usam os endpoints OAuth 2.0 do Google para autorizar o acesso a a API de dados do YouTube.

O OAuth 2.0 permite que os usuários compartilhem dados específicos com um aplicativo, mantendo nomes de usuário, senhas e outras informações privadas. Por exemplo, um aplicativo pode usar OAuth 2.0 para obter permissões para recuperar os dados do YouTube de um canal.

Os apps instalados são distribuídos para dispositivos individuais, e presume-se que eles e não pode manter segredos. Eles podem acessar as APIs do Google enquanto o usuário está no aplicativo ou quando que o app esteja sendo executado em segundo plano.

Esse fluxo de autorização é semelhante ao usado para aplicativos de servidor da Web. A principal diferença é que os apps instalados precisam abrir o navegador do sistema e fornecer um URI de redirecionamento local para processar do servidor de autorização do Google.

Alternativas

Em apps para dispositivos móveis, use o Login do Google para Android ou No iOS. Login do Google as bibliotecas de cliente lidam com autenticação e autorização do usuário e podem ser mais simples que o protocolo de nível inferior descrito aqui.

Para apps executados em dispositivos que não são compatíveis com um navegador do sistema ou que têm entrada limitada recursos, como TVs, consoles de jogos, câmeras ou impressoras, consulte OAuth 2.0 para TVs e Dispositivos ou Login em TVs e dispositivos de entrada limitada.

Bibliotecas e amostras

Recomendamos as seguintes bibliotecas e exemplos para ajudar você a implementar o fluxo do OAuth 2.0 descritos neste documento:

• Biblioteca AppAuth para Android
• Biblioteca AppAuth para iOS
• OAuth para apps: Windows Amostras

Pré-requisitos

Ativar as APIs do projeto

Qualquer aplicativo que chame APIs do Google precisa ativar essas APIs no API Console:

Para ativar uma API para um projeto, faça o seguinte:

1. Open the API Library no Google API Console.
2. If prompted, select a project, or create a new one.
3. Use a página "Biblioteca" para encontrar e ativar a API YouTube Data. Encontre e ative outras APIs que seu aplicativo vai usar.

Criar credenciais de autorização

Qualquer aplicativo que use o OAuth 2.0 para acessar as APIs do Google deve ter credenciais de autorização que identificam o aplicativo para o servidor OAuth 2.0 do Google. As etapas a seguir explicam como criar credenciais para seu projeto. Seus aplicativos podem usar as credenciais para acessar as APIs que você ativou nesse projeto.

1. Go to the Credentials page.
2. Clique em Criar credenciais > ID do cliente OAuth.
3. As seções abaixo descrevem os tipos de clientes e os métodos de redirecionamento que o Google servidor de autorização compatível. Escolha o tipo de cliente recomendado para sua o aplicativo, nomeie seu cliente OAuth e defina os outros campos do formulário como apropriados.

Identificar escopos de acesso

Os escopos permitem que seu aplicativo solicite acesso apenas aos recursos necessários permitindo que os usuários controlem a quantidade de acesso que eles concedem ao aplicativo. Portanto, há pode ser uma relação inversa entre o número de escopos solicitados e a probabilidade de obter o consentimento do usuário.

Antes de começar a implementar a autorização do OAuth 2.0, recomendamos que você identifique os escopos que o app precisa de permissão para acessar.

A API YouTube Data v3 usa os seguintes escopos:

O documento Escopos da API OAuth 2.0 contém um lista de escopos que você pode usar para acessar as APIs do Google.

Como receber tokens de acesso do OAuth 2.0

As etapas a seguir mostram como seu aplicativo interage com o servidor OAuth 2.0 do Google para receber o consentimento de um usuário para executar uma solicitação de API em nome dele. Seu aplicativo precisa ter consentimento antes de executar uma solicitação de API do Google que exija a autorização do usuário.

Etapa 1: gerar um verificador de código e um desafio

O Google aceita a chave de prova para troca de código (PKCE) para tornar o fluxo de apps instalados mais seguro. Um verificador de código exclusivo é criado para cada solicitação de autorização, e seu valor transformado, chamado "code_challenge", é enviado à servidor de autorização para receber o código de autorização.

Criar o verificador de código

Um code_verifier é uma string criptográfica aleatória de alta entropia que usa a função caracteres [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", com tamanho mínimo de 43 caracteres e tamanho máximo de 128 caracteres.

O verificador de código deve ter entropia suficiente para que não seja possível adivinhar o valor.

Criar o desafio de código

Há dois métodos de criação do desafio de código.

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

code_challenge = code_verifier

Etapa 2: enviar uma solicitação ao servidor OAuth 2.0 do Google

Para obter autorização do usuário, envie uma solicitação ao servidor de autorização do Google em https://accounts.google.com/o/oauth2/v2/auth: Esse endpoint processa a pesquisa de sessão ativa, autentica o usuário e recebe o consentimento dele. O endpoint só pode ser acessado por SSL e recusa conexões HTTP (não SSL).

O servidor de autorização suporta os seguintes parâmetros de string de consulta para aplicativos:

Exemplos de URLs de autorização

As guias abaixo mostram exemplos de URLs de autorização para as diferentes opções de URI de redirecionamento.

Os URLs são idênticos, exceto pelo valor do parâmetro redirect_uri. Os URLs também contêm os parâmetros response_type e client_id obrigatórios como o parâmetro state opcional. Cada URL contém quebras de linha e espaços para facilitar a leitura.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=com.example.app%3A/oauth2redirect&
 client_id=client_id

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=http%3A//127.0.0.1%3A9004&
 client_id=client_id

Etapa 3: o Google solicita o consentimento do usuário

Nesta etapa, o usuário decide se concede o acesso solicitado ao seu aplicativo. Neste etapa, o Google exibe uma janela de consentimento com o nome do seu aplicativo e a API do Google serviços que está solicitando permissão de acesso com as credenciais de autorização do usuário. um resumo dos escopos de acesso a serem concedidos. O o usuário poderá então consentir em conceder acesso a um ou mais escopos solicitados por seu aplicativo ou recusar a solicitação.

O aplicativo não precisa fazer nada nessa etapa, já que aguarda a resposta Servidor OAuth 2.0 do Google indicando se algum acesso foi concedido. Essa resposta é explicada em próxima etapa.

Etapa 4: gerenciar a resposta do servidor OAuth 2.0

A maneira pela qual seu aplicativo recebe a resposta de autorização depende da esquema de URI de redirecionamento usado. Independentemente do esquema, o A resposta conterá um código de autorização (code) ou um erro (error). Por exemplo, error=access_denied indica que o usuário recusou a solicitação.

Se o usuário conceder acesso a seu aplicativo, você pode trocar o código de autorização por um de acesso e um token de atualização, conforme descrito na próxima etapa.

Etapa 5: trocar o código de autorização para atualização e acesso tokens

Para trocar um código de autorização por um token de acesso, chame o método https://oauth2.googleapis.com/token e defina os seguintes parâmetros:

O snippet a seguir mostra um exemplo de solicitação:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=http://127.0.0.1:9004&
grant_type=authorization_code

O Google responde a essa solicitação retornando um objeto JSON que contém um e um token de atualização.

A resposta contém os seguintes campos:

O snippet a seguir mostra um exemplo de resposta:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/youtube.force-ssl",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Como chamar APIs do Google

Depois que o aplicativo obtém um token de acesso, você pode usá-lo para fazer chamadas a um serviço em nome de um determinado conta de usuário se os escopos de acesso exigidos pela API tiverem sido concedidos. Para fazer isso, inclua o token de acesso em uma solicitação à API incluindo uma consulta access_token ou um valor Bearer do cabeçalho HTTP Authorization. Quando possível, o cabeçalho HTTP é preferível, porque as strings de consulta tendem a ser visíveis nos registros do servidor. Na maioria casos, você pode usar uma biblioteca de cliente para configurar suas chamadas para as APIs do Google (por exemplo, quando chamando a API de transmissão do YouTube ao vivo).

A API de transmissão do YouTube ao vivo não é compatível com o fluxo da conta de serviço. Como não há não há maneira de vincular uma conta de serviço a uma conta do YouTube, tenta autorizar solicitações com este vai gerar um erro NoLinkedYouTubeAccount.

Você pode experimentar todas as APIs do Google e visualizar seus escopos em OAuth 2.0 Playground.

Exemplos GET HTTP

Uma chamada ao liveBroadcasts.list endpoint (a API de transmissão do YouTube ao vivo) usando o protocolo HTTP Authorization: Bearer pode ser semelhante ao seguinte. É necessário especificar seu próprio token de acesso:

GET /youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Esta é uma chamada para a mesma API para o usuário autenticado com o access_token parâmetro da string de consulta:

GET https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

Exemplos de curl

É possível testar esses comandos com o aplicativo de linha de comando curl. Este é um exemplo que usa a opção de cabeçalho HTTP (preferencial):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true

Ou, alternativamente, a opção do parâmetro da string de consulta:

curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

Atualização do token de acesso

Os tokens de acesso expiram periodicamente e se tornam credenciais inválidas para uma solicitação de API relacionada. Você podem atualizar um token de acesso sem solicitar a permissão do usuário (inclusive quando o usuário é ausente) se você solicitou acesso off-line aos escopos associados ao token.

Para atualizar um token de acesso, o aplicativo envia um HTTPS POST solicitação ao servidor de autorização do Google (https://oauth2.googleapis.com/token) que inclui os seguintes parâmetros:

O snippet a seguir mostra um exemplo de solicitação:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

Contanto que o usuário não tenha revogado o acesso concedido ao aplicativo, o servidor de token retorna um objeto JSON que contém um novo token de acesso. O snippet a seguir mostra um exemplo resposta:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "token_type": "Bearer"
}

Há limites para o número de tokens de atualização que serão emitidos. um limite por combinação de cliente/usuário e outra por usuário em todos os clientes. Salvar tokens de atualização no armazenamento a longo prazo e continuarão a usá-los enquanto permanecerem válidos. Se o seu aplicativo solicitar muitos tokens de atualização, poderá atingir esses limites; nesse caso, tokens de atualização mais antigos vão parar de funcionar.

Revogação de um token

Em alguns casos, um usuário pode querer revogar o acesso concedido a um aplicativo. Um usuário pode revogar o acesso acessando Configurações da conta. Consulte a Remover seção de acesso a sites ou apps da guia Sites e apps com acesso à sua conta documento de suporte para mais informações.

Também é possível para um aplicativo revogar programaticamente o acesso concedido a ele. A revogação programática é importante nos casos em que um usuário cancela a inscrição, remove uma aplicativo ou os recursos de API exigidos por um aplicativo tiverem mudado significativamente. Em outras palavras, do processo de remoção pode incluir uma solicitação de API para garantir que as permissões anteriores concedidas ao aplicativo são removidas.

Para revogar programaticamente um token, o aplicativo faz uma solicitação para https://oauth2.googleapis.com/revoke e inclui o token como um parâmetro:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

O token pode ser um token de acesso ou de atualização. Se o token for de acesso e tiver um token de atualização correspondente, o token de atualização também será revogado.

Se a revogação for processada com sucesso, o código de status HTTP da resposta será 200: Para condições de erro, um código de status HTTP 400 é retornado junto com um código de erro.

Leitura adicional

A prática recomendada atual da IETF OAuth 2.0 para Apps nativos é muitas das práticas recomendadas documentadas aqui.