Como usar o OAuth com as APIs de dados do Google

Introdução

É um momento incrível para os desenvolvedores. Estamos começando a ver vários padrões abertos sendo adotados na Web. Como você sabe, o Google sempre foi um grande fã de padrões e de incentivar a comunidade de código aberto.

Recentemente, todas as APIs de dados do Google passaram a oferecer suporte ao OAuth, um protocolo aberto que visa padronizar a forma como os aplicativos para computador e Web acessam os dados particulares de um usuário. O OAuth oferece uma maneira de realizar a autenticação de API de forma 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 que escrevem e facilita 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 das APIs de dados do Google, mas não necessariamente os conceitos por trás do OAuth. Se você está começando ou apenas quer saber mais sobre o OAuth, não precisa procurar mais. Este artigo vai apresentar os conceitos básicos. Também vou discutir os detalhes da implementação do OAuth do Google.

Este documento também é destinado a desenvolvedores que já usam o AuthSub, principalmente no modo registrado com segurança avançada. Ao longo do texto, vou destacar as semelhanças e diferenças entre os dois protocolos. Se você tiver aplicativos que usam o AuthSub, use essas informações para migrar para o OAuth, um protocolo mais aberto e moderno.

Um pouco de terminologia

Para entender o OAuth, é preciso conhecer a terminologia dele. A especificação do OAuth e a documentação do Google sobre autenticação OAuth para aplicativos da Web (links em inglês) dependem muito de certas definições. Por isso, vamos esclarecer o que cada uma significa no contexto da implementação do OAuth do Google.

1. "OAuth dance"

   Meu termo não oficial para descrever o processo completo 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 do OAuth é o usuário conceder acesso manualmente aos dados dele. Se esta etapa for concluída, o token de solicitação será autorizado.

3. Token de acesso (OAuth)

   A última etapa é trocar o token de solicitação autorizada por um token de acesso. Depois que o aplicativo tiver esse token, o usuário não precisará passar pelo processo do OAuth novamente, a menos que o token seja revogado.

   Semelhança com o AuthSub:
   Um token de acesso do OAuth é a mesma coisa que um token de sessão seguro do AuthSub.

4. Endpoints (OAuth)

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

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

   Semelhança com o AuthSub:
   A troca de um token de solicitação autorizado por um token de acesso é análoga à atualização de um token do AuthSub 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 o AuthSub 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, o 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 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 grande variedade de tipos de clientes diferentes (Web, instalados, desktop, dispositivos móveis).

Observação: embora o protocolo OAuth seja compatível com o caso de uso de aplicativos instalados/para computador, o Google só oferece suporte ao OAuth para aplicativos da Web.

Primeiros passos

Registro

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

Como assinar as solicitações

Depois que o domínio for registrado, você poderá começar a assinar solicitações. Um dos conceitos mais difíceis do OAuth é como construir corretamente o oauth_signature e a noção da string de base da assinatura. A string de base são os dados que você assina 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

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 com o restante dos parâmetros oauth_* na ordem lexicográfica de valor de byte.
• Essa string também não contém um caractere "?".
• A parte base-http-request-url contém apenas o URL base codificado em URL: http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull.
• O oauth_token é codificado por URL 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 Assinatura de solicitações OAuth.

Diferença do AuthSub:
Como comparação, aqui está o mesmo exemplo usando o AuthSub seguro:

GET http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull%3Forderby%3Dstarttime 137131200 4572616e48616d6d

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 AuthSub, consulte Assinar solicitações do AuthSub.

Ferramenta OAuth Playground

Teste agora!

Finalidade

Alguns usuários sugeriram que o OAuth tem uma curva de aprendizado alta. Em comparação com outras APIs de autenticação do Google, concordo. A vantagem do OAuth fica evidente quando você expande seu app para usar outros serviços (que não são do Google). Escrever um único trecho de código de autenticação que funcione em diferentes provedores de serviços e APIs parece muito bom para mim. Você vai agradecer por aprender o protocolo agora.

O OAuth Playground é uma ferramenta que criei para ajudar os desenvolvedores a resolver problemas com o OAuth. Use o Playground para ajudar a depurar problemas, verificar sua própria implementação ou testar as APIs de dados do Google.

O que faz?

1. Ilustra o fluxo de autenticação OAuth: busca de um token de solicitação, autorização do token e upgrade para um token de acesso.
2. Mostra a string de base de assinatura correta para cada solicitação.
3. Mostra 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. Acesse um feed autenticado diretamente no navegador.
6. Permite testar seu próprio oauth_consumer_key (seu domínio registrado) e chave privada.
7. Descubra quais serviços de feed de dados do Google estão disponíveis para seu oauth_token.

Execução de demonstração

Etapa 1: escolher os escopos Primeiro, decida quais APIs você quer usar escolhendo um ou mais escopos. Nesta demonstração, estou solicitando um token que vai funcionar com o Blogger e os Contatos do Google. Semelhança com o AuthSub: O AuthSub também exige o parâmetro scope para controlar o intervalo de dados que um token pode acessar. O Google implementou esse parâmetro conforme sugerido na especificação do OAuth.
Etapa 2: modificar parâmetros e configurações do OAuth Por enquanto, não modifique nenhuma configuração na caixa "Modificar os parâmetros do OAuth". Depois, você pode testar com sua própria chave privada. Para isso, mude o 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 TESTE. Observação: oauth_signature_method e oauth_consumer_key são os únicos campos editáveis aqui. Os campos oauth_timestamp, oauth_nonce e oauth_token serão gerados automaticamente para você. Além de RSA-SHA1, você pode usar HMAC-SHA1 para o oauth_signature_method. Nesse caso, o Playground vai mostrar outras caixas em que você precisará inserir seu próprio oauth_consumer_key e o Secret do consumidor. Esses valores podem ser encontrados na página https://www.google.com/accounts/ManageDomains do seu domínio registrado. Diferença do AuthSub: No AuthSub 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. Existe um parâmetro assim no OAuth: oauth_consumer_key. Defina como seu domínio registrado.
Etapas 3 a 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 do OAuth. Primeiro, clique no botão "Solicitar token" na caixa "Receber o token". Alguns campos serão preenchidos com dados. A "String de base da assinatura" mostra a forma adequada da string de base usada para criar o parâmetro oauth_signature. O "cabeçalho de autorização" mostra o cabeçalho Authorization correspondente à solicitação. A caixa "Modificar os parâmetros do 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 mostra 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 o token". Nessa 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 com o AuthSub: Essa página de autorização é a mesma para o AuthSub. Diferença do AuthSub: O parâmetro de URL next do AuthSub é 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 "Conceder acesso", o token de solicitação é autorizado, e a atualização do token para https://www.google.com/accounts/OAuthGetAccessToken pode ser realizada de forma assíncrona. Dica: especificar um URL oauth_callback é preferível se você estiver escrevendo um aplicativo da Web, porque isso oferece uma experiência melhor ao usuário.
Por fim, clique no botão "Token de acesso" na caixa "Receber o token". Essa ação atualiza o rótulo do token de solicitação autorizado (indicado pelo "token de acesso" vermelho). Se quiser buscar um novo token, clique em "Começar de novo" para reiniciar a dança do OAuth. Agora podemos fazer algo interessante!

Como usar o token de acesso

Agora você pode consultar feeds, inserir, atualizar ou excluir dados. Tenha cuidado ao executar esses três últimos métodos HTTP, já que você está trabalhando com seus dados reais.

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

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

Este exemplo não retorna mais de três postagens em um blog específico. Você também pode clicar no link "Ver no navegador" abaixo da área com destaque de sintaxe para conferir o feed/entrada retornado diretamente no navegador.

Exemplo: como atualizar uma postagem

1. Localize o elemento <link> com um rel="edit" na postagem que você quer atualizar. que deve ser semelhante a este:

   <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 atual clicando em "Mostrar texto simples" na parte de cima do painel com destaque de sintaxe. Copie apenas o corpo da resposta, não os cabeçalhos.
3. Mude o menu suspenso do método HTTP para PUT.
4. Clique em "Inserir dados de postagem" abaixo do menu suspenso e cole o XML <entry> no pop-up.
5. Clique no botão "Executar".

O servidor vai responder com um 200 OK.

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

Conclusão

Tecnologias como o protocolo de publicação AtomPub/Atom (protocolo subjacente das APIs de dados do Google) e o OAuth ajudam a impulsionar a Web. À medida que mais e mais sites começam a adotar esses padrões, nós, desenvolvedores, somos os vencedores. Criar um app incrível de repente se torna menos assustador.

Se tiver dúvidas ou comentários sobre o OAuth Playground ou o uso do OAuth com as APIs do Google, acesse o fórum de suporte das APIs do G Suite e do Marketplace.

Recursos

• Autenticação OAuth para aplicativos da Web
• Lista de APIs de dados do Google
• Fórum de discussão sobre as APIs Google Accounts
• Especificação principal do OAuth 1.0