Como usar o OAuth com as APIs de dados do Google

Eric Bidelman, equipe das APIs de dados do Google
setembro de 2008

Introdução

Este é um grande momento para os desenvolvedores. Começamos a ver vários padrões abertos sendo adotados em toda a Web. Como você sabe, o Google sempre foi um grande fã dos padrões e incentivando a comunidade de código aberto.

Recentemente, todas as APIs de dados do Google adotaram o suporte ao OAuth, um protocolo aberto que tem como objetivo padronizar a forma como os aplicativos da área de trabalho e da Web acessam os dados particulares de um usuário. Com o OAuth, é possível fazer a autenticação da API de maneira padrão e segura. Como programadores, aprendemos a reutilizar o código sempre que possível. O OAuth ajuda os desenvolvedores a reduzir a quantidade de código duplicado e facilitar a criação de ferramentas que funcionam com vários serviços de diferentes provedores.

Público-alvo

Este artigo pressupõe que você conhece uma ou mais APIs de dados do Google, mas não necessariamente os conceitos por trás do OAuth. Se você está começando ou só tem curiosidade sobre o OAuth, não precisa mais procurar. Este artigo fornece uma base básica dos conceitos. Também veremos os detalhes da implementação do OAuth do Google.

Ele também é destinado a desenvolvedores familiarizados com o uso do XPN, especialmente no modo registrado com segurança aprimorada. À medida que avançarmos, tentaremos destacar as semelhanças e as diferenças entre os dois protocolos. Se você tiver aplicativos que usam XPN, poderá usar essas informações para migrar para o OAuth, que é um protocolo moderno e mais aberto.

Um pouco de terminologia

O objetivo do OAuth é entender a terminologia dele. A especificação do OAuth e a documentação de autenticação OAuth para aplicativos da Web do Google dependem muito de certas definições. Portanto, vamos esclarecer o que cada um significa no contexto da implementação do OAuth do Google.

  1. "Dança OAuth"

    Meu termo não oficial para descrever todo o processo de autenticação/autorização do OAuth.

  2. Token de solicitação (OAuth)

    Um token inicial que informa ao Google que seu aplicativo está solicitando acesso a uma das APIs de dados do Google. A segunda etapa da dança OAuth é o usuário conceder manualmente acesso aos dados. Se a etapa for bem-sucedida, o token de solicitação vai ser autorizado.

  3. Token de acesso (OAuth)

    A última etapa da dança é trocar o token de solicitação autorizado por um token de acesso. Assim que o aplicativo tiver esse token, o usuário não precisará passar pela dança do OAuth novamente, a menos que o token seja revogado.

    Semelhança a ISBN:
    Um token de acesso OAuth é o mesmo que um token de sessão tmp seguro.

  4. Endpoints (OAuth)

    Esses são os URIs necessários para autenticar um aplicativo e receber um token de acesso. Há três no total, um para cada etapa do processo do OAuth. Os endpoints OAuth do Google são:

    Consiga um token de solicitação:https://www.google.com/accounts/OAuthGetRequestToken
    Autorize o token de solicitação:https://www.google.com/accounts/OAuthAuthorizeToken
    Faça upgrade para um token de acesso:https://www.google.com/accounts/OAuthGetAccessToken

    Semelhança a tmp:
    A troca de um token de solicitação autorizado para um de acesso é análoga à atualização de um token tmp de uso único para um token de sessão de longa duração em https://www.google.com/accounts/AuthSubRequestToken e https://www.google.com/accounts/AuthSubSessionToken, respectivamente. A diferença é que, por padrão, o XPN não tem o conceito de um token de solicitação inicial. Em vez disso, o usuário inicia o processo de token na página de autorização AuthSubRequestToken.

  5. Provedor de serviços (OAuth)

    No caso das APIs de dados do Google, esse provedor é o Google. Em geral, o provedor de serviços é usado para descrever o site ou serviço da Web que fornece os endpoints OAuth. Outro exemplo de provedor de serviços de OAuth é o MySpace.

  6. Consumidor (OAuth)

    O programa que solicita permissão para acessar os dados de um usuário (ou seja, seu aplicativo). O protocolo OAuth é flexível porque permite uma ampla variedade de tipos de clientes (Web, instalado, computador, celular).

Observação: o protocolo OAuth é compatível com o caso de uso de computador/aplicativo instalado, mas o Google só oferece suporte a aplicativos OAuth.

Como começar

Registro

Há uma pequena configuração antes de começar a usar o OAuth com as APIs de dados do Google. Como todas as solicitações de OAuth precisam ser assinadas digitalmente, primeiro é preciso registrar seu domínio e fazer upload de um certificado público para o Google. Para mais informações sobre como fazer isso, consulte Registro para aplicativos baseados na Web e Como gerar chaves e certificados para uso com o modo registrado.

Como assinar as solicitações

Depois que seu domínio for registrado, você poderá começar a assinar solicitações. Um dos conceitos mais difíceis do OAuth é construir corretamente o oauth_signature e a noção da string de base da assinatura. A string base é os dados assinados com sua chave privada (usando RSA_SHA1). O resultado é o valor definido para o oauth_signature.

Exemplo de solicitação

GET uma lista das agendas do Google de um usuário em http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime

Formato de string base base_string = http-method&base-http-request-url&normalized-string-of-oauth_parameters
Exemplo de string de base GET&http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull&oauth_consumer_key%3Dexample.com%26oauth_nonce%3D4572616e48616d6d%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D137131200%26oauth_token%3D1%252Fab3cd9j4ks73hf7g%26oauth_version%3D1.0%26orderby%3Dstarttime
Exemplo de solicitação HTTP 
GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime HTTP/1.1
Host:  http://www.google.com
Content-Type: application/atom+xml
Authorization: OAuth oauth_token="1%2Fab3cd9j4ks73hf7g", oauth_signature_method="RSA-SHA1", oauth_signature="wOJIO9AvZbTSMK%2FPY%3D...", oauth_consumer_key="example.com", oauth_timestamp="137131200", oauth_nonce="4572616e48616d6d", oauth_version="1.0"

Observação: isso é apenas uma representação. Seu oauth_signature será muito mais longo.

Observações sobre a string de base:

  • O parâmetro de consulta orderby=starttime é classificado junto com o restante dos parâmetros oauth_* na ordem de valor dos bytes lexicográficos.
  • Essa string também não contém um caractere "?".
  • A parte base-http-request-url contém apenas o URL base codificado para URL: http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull.
  • O oauth_token tem um URL codificado duas vezes.

Observações sobre o cabeçalho Authorization:

  • A ordem dos parâmetros oauth_* não importa no cabeçalho Authorization.
  • O cabeçalho não inclui o orderby=starttime como a string de base. Esse parâmetro de consulta é mantido como parte do URL da solicitação.

Para mais informações sobre como assinar solicitações usando o OAuth, consulte Assinar solicitações de OAuth.

Diferença de ISBN:
Para fins de comparação, este é o mesmo exemplo de uso do tmp seguro:

Formato de string base base_string = http-method http-request-URL timestamp nonce
Exemplo de string de base 
GET http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull%3Forderby%3Dstarttime 137131200 4572616e48616d6d
Exemplo de solicitação HTTP 
GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime HTTP/1.1
Host:  http://www.google.com
Content-Type: application/atom+xml
Authorization: AuthSub token="GD32CMCL25aZ-v____8B" data="GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime 137131200 4572616e48616d6d" sig="MCwCFrV93K4agg==..." sigalg="rsa-sha1"

Para mais informações sobre como assinar solicitações usando o tmp, consulte Assinar solicitações de tmp (link em inglês).

Ferramenta OAuth Playground

Finalidade

Alguns usuários sugeriram que o OAuth tem uma alta curva de aprendizado. Concordo com outras APIs de autenticação do Google. A vantagem do OAuth é aparente quando você expande seu app para usar outros serviços (que não são do Google). Escrever um único código de autenticação que funcione em diferentes provedores de serviços e as respectivas APIs parece muito bom. Mais tarde, vamos aprender mais sobre o protocolo.

O OAuth Playground é uma ferramenta que criamos para ajudar os desenvolvedores a resolver problemas do OAuth. Você pode usar o Playground para depurar problemas, verificar sua própria implementação ou fazer experimentos com as APIs de dados do Google.

Qual é a função dela?

  1. Ilustra o fluxo de autenticação OAuth: buscar um token de solicitação, autorizá-lo e fazer upgrade dele para um token de acesso.
  2. Exibe a string de base da assinatura correta para cada solicitação.
  3. Exibe o cabeçalho Authorization correto para cada solicitação.
  4. Demonstra como usar um oauth_token para interagir com um feed de dados do Google autenticado. Você pode GET/POST/PUT/DELETE dados.
  5. Veja um feed autenticado diretamente no navegador.
  6. Permite que você teste seu próprio oauth_consumer_key (domínio registrado) e chave privada.
  7. Descubra quais serviços do feed de dados do Google estão disponíveis para seu oauth_token.

Execução da demonstração

Etapa 1: escolher os escopos

Primeiro, decida quais APIs você quer usar escolhendo um ou mais escopos. Nesta demonstração, solicitamos um token que funcionará com o Blogger e com os Contatos do Google.

Semelhança a tmp:
O tmp também requer o parâmetro scope para controlar o intervalo de dados que um token pode acessar. O Google implementou esse parâmetro conforme sugerido nas especificações do OAuth.

Etapa 2: modificar os parâmetros e as configurações do OAuth

Por enquanto, não modifique as configurações na caixa "Modificar os parâmetros OAuth". Posteriormente, você poderá testar com sua própria chave privada. Para isso, altere oauth_consumer_key para seu domínio registrado e insira sua chave privada clicando em "Usar sua própria chave privada". Use apenas uma chave privada TEST.

Observação: oauth_signature_method e oauth_consumer_key são os únicos campos editáveis aqui. Os elementos oauth_timestamp, oauth_nonce e oauth_token serão gerados automaticamente.

Além de RSA-SHA1, você pode optar por usar HMAC-SHA1 para a oauth_signature_method. Nesse caso, o Playground mostrará caixas adicionais em que será necessário inserir seu próprio oauth_consumer_key e o segredo do consumidor. Esses valores estão disponíveis na página https://www.google.com/accounts/ManageDomains para seu domínio registrado.

Diferença de tmp:
No ConfigMap seguro, não há um parâmetro para definir explicitamente um nome de domínio. O domínio está incluído como parte do parâmetro de URL next. Há um parâmetro no OAuth: oauth_consumer_key. Defina-o como seu domínio registrado.

Etapa 3-5: adquirir o token de acesso

Há três etapas para conseguir um token de acesso OAuth. A primeira etapa é recuperar um token de solicitação. Isso informa ao Google que seu aplicativo está iniciando a dança OAuth.

Primeiro, clique no botão "Solicitar token" na caixa "Receber o token".

Certos campos serão preenchidos com dados.

  • A "string base de assinatura" mostra a forma correta da string base usada para criar o parâmetro oauth_signature.
  • O cabeçalho de autorização exibe o cabeçalho Authorization correspondente à solicitação.
  • A caixa "Modificar os parâmetros OAuth" preenchida com os valores oauth_nonce e oauth_timestamp enviados na solicitação.
  • A entrada oauth_token foi preenchida com o valor correspondente retornado no corpo da resposta. O Playground também exibe o tipo de oauth_token que temos no momento. No momento, é um token de solicitação.

Em seguida, clique no botão "Autorizar" na caixa "Receber token".

Nesta página de autorização, clique no botão "Conceder acesso" para autorizar o token de solicitação e ser redirecionado de volta ao OAuth Playground.

Semelhança a tmp:
Essa página de autorização é a mesma para tmp.

Diferença de tmp:
O parâmetro de URL next de XPN é análogo ao parâmetro oauth_callback. A diferença é que, no OAuth, o oauth_callback é opcional. Depois que o usuário clica no botão "Permitir acesso", o token de solicitação se torna autorizado e o upgrade do token para https://www.google.com/accounts/OAuthGetAccessToken pode ser realizado de forma assíncrona.

Dica: é melhor especificar um URL de oauth_callback se você estiver criando um aplicativo da Web, porque ele proporciona uma experiência melhor ao usuário.

Por fim, clique no botão "Token de acesso" na caixa "Receber o token".

Esta ação faz upgrade do token de solicitação autorizado (conforme indicado pelo rótulo vermelho "token de acesso").

Se você quiser buscar um novo token, clique em "Recomeçar" para reiniciar a dança do OAuth.

Agora podemos fazer algo interessante.

Como usar o token de acesso

Agora está tudo pronto para você consultar feeds, inserir, atualizar ou excluir dados. Tenha cuidado ao executar esses últimos três métodos HTTP ao trabalhar com seus dados reais.

Dica: para descobrir os feeds disponíveis para seu token de acesso, clique no botão "Feeds disponíveis".

Veja um exemplo de consulta: GET http://www.blogger.com/feeds/1982051675575479214/posts/default?max-results=3

Este exemplo retorna no máximo três postagens em um determinado blog. Também é possível ver o feed/entrada retornado diretamente no seu navegador clicando no link "Ver no navegador", abaixo da área destacada na sintaxe.

Exemplo: como atualizar uma postagem

  1. Localize o elemento <link> com um rel="edit" na postagem que você quer atualizar. O código será semelhante a este exemplo: 
    <link rel="edit" href="http://www.blogger.com/feeds/1982051675575479214/posts/default/8138973184593279875"/>

    Cole o URL href na entrada "Insira um feed de dados do Google".

  2. Copie o XML da entrada existente clicando em "view plain" na parte superior do painel destacado para sintaxe. Copie apenas o corpo da resposta, não os cabeçalhos.
  3. Mude o menu suspenso "Método HTTP" para PUT.
  4. Clique em "insira os dados da postagem" abaixo do menu suspenso e cole o XML <entry> no pop-up.
  5. Clique no botão "Executar".

O servidor vai responder com uma 200 OK.

Dica: em vez de copiar manualmente o link edit, desmarque a caixa de seleção "Destacar sintaxe?". Após uma consulta, você poderá clicar nos links dentro dos corpos de resposta XML.

Conclusão

Tecnologias como o AtomPub/Atom Publishing Protocol (protocolo subjacente das APIs de dados do Google) e o OAuth ajudam a promover a Web. À medida que cada vez mais sites começam a abraçar esses padrões, os desenvolvedores são os vencedores. De repente, criar um app incrível é menos assustador.

Se você tiver dúvidas ou comentários sobre o OAuth Playground ou usar o OAuth com as APIs do Google, acesse o Fórum de Suporte das APIs do G Suite e das APIs do Marketplace.

Recursos