O OAuth é um protocolo utilizado para acessar APIs em nome de um usuário, mas o usuário não precisa estar presente quando a API é acessada.

Há ainda algumas formas que permitem que aplicativos acessem APIs usando tokens obtidos sem nenhuma intervenção do usuário, permitindo assim uma maior automatização dos seus aplicativos.

Leia este artigo para aprender sobre as várias maneiras de acessar uma API baseada em OAuth sem a presença do usuário.

Introdução

O OAuth tornou-se o padrão para acessar APIs baseadas na web e que exigem uma autorização antes que as funções da API possam ser chamadas.

Normalmente, é necessário que um usuário dê permissão para acessar a API em seu nome. No entanto, também é possível ter acesso a uma API sem a presença do usuário e, em alguns casos, sem exigir a autorização de um usuário real.

A classe PHP OAuth suporta várias formas de chamar uma API sem interação do usuário. Vamos dar uma olhada em cada um desses métodos de acesso e como você pode implementá-los usando a classe cliente OAuth.

1. O acesso regular API OAuth

Quando se acessa API OAuth, normalmente o usuário deve estar presente para conceder a autorização para que o aplicativo acesse a API. Uma vez que a autorização é concedida, o usuário não precisa estar presente para permitir que o aplicativo realize chamadas à API.

Assim, enquanto os tokens de autorização obtidos não expiraram, o aplicativo pode fazer as chamadas necessárias para a API.

Tenha em mente que, por padrão, a classe cliente OAuth usa sessões PHP para armazenar os tokens OAuth recuperados durante o processo de autorização. As sessões PHP são válidas apenas enquanto o usuário estiver acessando a página web a partir do mesmo local em que o token foi criado.

Assim, se o seu aplicativo precisa fazer chamadas de API quando o usuário não estiver presente, ele precisa armazenar os tokens em algum lugar, para que possam ser recuperados quando o aplicativo precisar deles.

A maneira usual para armazenar e recuperar os tokens é a utilização de um banco de dados. Você pode escrever seu próprio código para armazená-los no banco de dados do seu aplicativo. Normalmente você pode armazenar um registro da tabela do banco de dados para cada usuário que autorizou o acesso via API OAuth.

Nesse caso, é preciso saber quais variáveis da classe oauth_client_class são necessárias para salvar e restaurar mais tarde. Essas variáveis são: access_token, access_token_secret (OAuth apenas para 1 servidor), access_token_expiry (para os tokens que expiram), access_token_type, refresh_token (para tokens que podem ser renovados quando expiram).

De forma alternativa, você pode usar uma sub-classe da classe oauth_client_class que vem com esse pacote para armazenar tokens em seu banco de dados. Atualmente, o pacote vem com o script de sub-classe mysqli_oauth_client.php para armazenar valores de token em um banco de dados MySQL. Você pode criar outras sub-classes da sub-classe definida no arquivo database_oauth_client.php, caso prefira usar um banco de dados diferente.

2. Atualização automática de tokens expirados

Alguns servidores de API emitem tokens OAuth que expiram depois de um tempo. Esses tokens devem ser trocados por novos quando expirarem. Isso é feito enviando um novo pedido para o servidor da API usando um token de atualização obtido anteriormente, quando o último token de acesso foi obtido.

O novo token de acesso e um eventual novo token de atualização substituem os antigos tokens. Então você deve descartar os antigos tokens e utilizar os novos a partir daí.

A substituição do token acontecerá na próxima vez em que você fizer uma chamada de API e o antigo token estiver expirado. Por isso, é muito importante que o horário da máquina esteja absolutamente preciso ou, pelo menos, que não esteja atrasado.

Atualizar tokens expirados é um processo complicado, mas felizmente a classe oauth_client_class cuida disso para você de forma transparente. Caso esteja usando uma das classes de banco de dados mencionadas anteriormente, elas cuidarão do processo de substituição do token e do armazenamento dos novos tokens no banco de dados; caso contrário, verifique as variáveis mencionadas anteriormente e atualize os tokens armazenados, se necessário.

Algumas APIs, como as APIs do Google, apenas emitem tokens de atualização se você usar uma URL especial para recuperação do token. Felizmente, a classe oauth_client_class também pode assegurar que seja utilizada a URL do token correto. Basta definir a variável de classe offline para true, e utilizar uma URL especial para obter o token de atualização, para que ele possa renovar os tokens expirados automaticamente mais tarde.

O acesso à API offline utilizando um banco de dados para armazenar os tokens recuperados e atualizá-los para substituir os tokens expirados já foi explicado em um artigo detalhado sobre acesso offline para APIs baseadas em OAuth.

Outras APIs, como por exemplo a do Facebook, utilizam tokens de acesso que expiram após um tempo, mas não podem ser renovados automaticamente. Nesse caso, é preciso solicitar ao usuário que passe por todo o processo de autorização OAuth novamente.

De qualquer forma, quando isso acontecer, desde que você esteja pedindo outro token de acesso à API com as mesmas permissões, o usuário não verá a tela de autorização novamente.

3. Autorização com a senha do usuário

Alguns aplicativos não pretendem acessar APIs em nome de outros usuários, mas sim apenas por um único usuário que é o desenvolvedor do aplicativo. Nesse caso, existem APIs que podem retornar um token de acesso usando apenas o nome de usuário e a senha do desenvolvedor do aplicativo.

Isso é bom porque o usuário desenvolvedor não tem que estar presente quando o token de acesso é solicitado. Ele só precisa fornecer o nome de usuário e a senha para os seus próprios scripts que acessam a API. Isso é conhecido como fluxo de autorização usando senha do dono do aplicativo.

A classe oauth_client_class também implementa esse fluxo de autorização tendo a senha do dono do aplicativo como base. Tudo o que você precisa fazer é definir as variáveis oauth_username e oauth_password para usuário e senha do desenvolvedor, respectivamente.

O processo de chamar a API é o mesmo utilizado para o fluxo OAuth normal usando a função CallAPI.

Existem APIs, como a do Salesforce, que suportam esse tipo de fluxo de autorização baseado em senha.

4. Aplicativo com acesso somente via client_credentials

Outra forma de realizar chamadas de API sem interação do usuário é fazer com que o aplicativo realize chamadas de API apenas usando as credenciais do aplicativo cliente, ou seja, os valores das credenciais do aplicativo foram definidos nas variáveis client_id e client_secret.

Nesse caso, é necessário definir a variável de classe grant_type para client_credentials. Dessa forma que a classe obtém um token de acesso automaticamente, sem a necessidade de um usuário estar presente, assim como com o fluxo de autorização baseado em senha. A única diferença é que você não precisa fornecer qualquer nome de usuário ou senha para seus scripts.

APIs como a do Twitter suportam apenas esse tipo de autorização de aplicativo usando o protocolo OAuth 2. Tenha em mente que, para o acesso normal à API OAuth em nome de um usuário real, você precisa usar o protocolo OAuth 1.0a. A classe oauth_client_class suporta ambos os tipos de fluxo de autorização OAuth.

Conclusão

OAuth é um protocolo razoavelmente complexo, especialmente porque há duas versões do protocolo, e não há consenso sobre qual versão cada API utiliza.

Felizmente, a classe oauth_client_class tenta abstrair todas as versões de protocolo em uma única classe, para que você não precise aprender muito sobre o funcionamento interno do protocolo.

Além disso, a classe vem com um arquivo de configuração separado chamado oauth_configuration.json, que define valores para configurar a classe para diferentes tipos de servidores baseados em API OAuth bem conhecidos. Dessa forma, você praticamente só precisa definir a variável de classe server para o servidor de API que deseja acessar, de forma que não precisa perder muito tempo estudando o protocolo OAuth.

Ainda pode haver outros servidores para os quais ainda não há nenhuma configuração predefinida para você começar rapidamente. Caso queira usar um desses servidores, ou caso tenha qualquer outra pergunta, por favor, poste um comentário neste artigo, ou melhor poste um pedido de ajuda no fórum de suporte da classe PHP Oauth API.

***

Artigo traduzido pela Redação iMasters com autorização do autor. Publicado originalmente em http://www.phpclasses.org/blog/package/7700/post/5-4-Ways-to-Access-an-OAuth-API-Without-User-Interaction.html