Introdução ao OAuth 2.0

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

Página inicial do OAuth: Consulte a página inicial do OAuth para ver uma vista de nível superior das orientações do OAuth que fornecemos.

Este tópico oferece uma vista geral básica do OAuth 2.0 no Apigee.

O que é o OAuth 2.0?

Existem muitos livros, blogues e sites dedicados ao OAuth 2.0. Recomendamos vivamente que comece por rever a especificação IETF OAuth 2.0. Aqui está a definição de OAuth 2.0 da especificação IETF do OAuth 2.0:

"A framework de autorização OAuth 2.0 permite que uma aplicação de terceiros obtenha acesso limitado a um serviço HTTP, quer em nome de um proprietário de recursos através da coordenação de uma interação de aprovação entre o proprietário de recursos e o serviço HTTP, quer permitindo que a aplicação de terceiros obtenha acesso em seu próprio nome."

O principal que precisa de saber é que o OAuth 2.0 oferece uma forma de as apps obterem acesso limitado aos recursos protegidos de um utilizador (pense numa conta bancária ou em quaisquer outras informações confidenciais a que um utilizador possa querer aceder a partir de uma app) sem que o utilizador tenha de divulgar as respetivas credenciais de início de sessão à app.

Sugestão: suponhamos que encontrou uma app que lhe permite aceder a várias contas bancárias. Talvez a app seja usada para ajudar com os seus impostos ou para gerir o seu orçamento. Tem três contas bancárias que quer gerir com a app e tem um nome de utilizador e uma palavra-passe diferentes para cada uma. Agora, para que a app aceda às suas contas bancárias, precisa dessas credenciais confidenciais. Basicamente, está a dar estas informações confidenciais à app. Confia na app para ter as suas palavras-passe e nomes de utilizador? O que acontece se a app for pirateada? Agora, tem de se lembrar de alterar as credenciais bancárias de cada conta. Este é o problema fundamental que o OAuth 2.0 resolve. Continue a ler para saber como.

O fluxo do OAuth 2.0

Segue-se o fluxo geral da framework de segurança OAuth 2.0. Vamos abordar este fluxo com mais detalhe neste tópico, começando com um diagrama que ilustra muito sobre como funciona o OAuth 2.0. Se não estiver familiarizado com os termos usados neste diagrama, leia esta secção para uma introdução rápida.

Termos que deve conhecer

• Cliente: também denominado a app. Pode ser uma app executada num dispositivo móvel ou uma app Web tradicional. A app faz pedidos ao servidor de recursos de recursos protegidos em nome do proprietário do recurso. O proprietário do recurso tem de conceder autorização à app para aceder aos recursos protegidos.
• Proprietário do recurso: também denominado utilizador final. Geralmente, trata-se da pessoa (ou outra entidade) que pode conceder acesso a um recurso protegido. Por exemplo, se uma app precisar de usar dados de um dos seus sites de redes sociais, é o proprietário do recurso, ou seja, a única pessoa que pode conceder à app acesso aos seus dados.
• Servidor de recursos: pense no servidor de recursos como um serviço como o Facebook, o Google ou o Twitter; ou um serviço de RH na sua intranet; ou um serviço de parceiros na sua extranet B2B. O Apigee é um servidor de recursos sempre que a validação de tokens OAuth é necessária para processar pedidos de API. O servidor de recursos precisa de algum tipo de autorização antes de fornecer recursos protegidos à app.
• Servidor de autorizações: o servidor de autorizações é implementado em conformidade com a especificação OAuth 2.0 e é responsável por validar concessões de autorizações e emitir os tokens de acesso que dão à app acesso aos dados do utilizador no servidor de recursos. Pode configurar pontos finais de tokens no Apigee, caso em que o Apigee assume a função de servidor de autorizações.
• Concessão de autorização: concede à app autorização para obter um token de acesso em nome do utilizador final. O OAuth 2.0 define quatro "tipos de autorização" específicos. Consulte o artigo Quais são os tipos de concessão do OAuth 2.0.
• Token de acesso: uma longa string de carateres que serve como credencial usada para aceder a recursos protegidos. Consulte o artigo O que é uma chave de acesso?.
• Recurso protegido: dados pertencentes ao proprietário do recurso. Por exemplo, a lista de contactos, as informações da conta ou outros dados confidenciais do utilizador.

Onde o Apigee se encaixa

Pode proteger qualquer API com proxy através do Apigee com o OAuth 2.0. O Apigee inclui uma implementação do servidor de autorizações e, como tal, pode gerar e validar tokens de acesso. Os programadores começam por registar as respetivas apps no Apigee. As apps registadas podem pedir tokens de acesso através de qualquer uma das quatro interações do tipo de autorização.

O Apigee fornece uma política OAuthV2 multifacetada que implementa os detalhes de cada tipo de concessão, o que facilita relativamente a configuração do OAuth no Apigee. Por exemplo, pode configurar uma política que recebe um pedido de um token de acesso, avalia todas as credenciais necessárias e devolve um token de acesso se as credenciais forem válidas.

Tenha em atenção que todos os servidores de recursos que o proxy de API seguro chama devem estar protegidos por uma firewall (ou seja, os recursos não devem estar acessíveis por nenhum meio, exceto o proxy de API ou outra API bem protegida).

Quais são os tipos de concessão do OAuth 2.0?

Pense nos tipos de autorização como caminhos ou interações diferentes que uma app pode seguir para obter um token de acesso. Cada tipo de concessão aborda um ou mais exemplos de utilização e tem de selecionar os tipos de concessão a usar com base nas suas próprias necessidades. Em geral, cada tipo de concessão tem vantagens e desvantagens, e tem de ponderar as concessões com base nos exemplos de utilização da sua empresa. Uma consideração importante é a fiabilidade das apps que vão aceder aos seus dados. Geralmente, as apps de terceiros são menos fidedignas do que as apps desenvolvidas e usadas numa empresa.

O Apigee suporta os quatro principais tipos de concessão do OAuth 2.0:

• código de autorização: considerado o tipo de concessão mais seguro. Antes de o servidor de autorização emitir um token de acesso, a app tem de receber primeiro um código de autorização do servidor de recursos. Já viu este fluxo sempre que a sua app abre um navegador para a página de início de sessão do servidor de recursos e lhe pede para iniciar sessão na sua conta real (por exemplo, Facebook ou Twitter).

Se iniciar sessão com êxito, a app recebe um código de autorização que pode usar para negociar um token de acesso com o servidor de autorização. Normalmente, este tipo de autorização é usado quando a app reside num servidor em vez de no cliente. Este tipo de concessão é considerado altamente seguro porque a app cliente nunca processa nem vê o nome de utilizador ou a palavra-passe do utilizador para o servidor de recursos (ou seja, por exemplo, a app nunca vê nem processa as suas credenciais do Twitter). Este fluxo de tipo de autorização também é denominado OAuth de três passos.

• implicit: considerada uma versão simplificada do código de autorização. Normalmente, este tipo de autorização é usado quando a app reside no cliente. Por exemplo, o código da app é implementado num navegador através de JavaScript ou outra linguagem de scripting (em vez de residir e ser executado num servidor Web separado). Neste fluxo do tipo de autorização, o servidor de autorização devolve uma chave de acesso diretamente quando o utilizador é autenticado, em vez de emitir primeiro um código de autorização. As autorizações implícitas podem melhorar a capacidade de resposta da app em alguns casos, mas esta vantagem tem de ser ponderada em função das possíveis implicações de segurança, conforme descrito na especificação da IETF.
• credenciais de palavra-passe do proprietário do recurso: neste fluxo, é emitido um token de acesso ao cliente quando o nome de utilizador/palavra-passe do utilizador é validado pelo servidor de autorizações. Este fluxo é recomendado para aplicações altamente fidedignas. Uma vantagem deste fluxo em relação, por exemplo, à autenticação básica, é que o utilizador só apresenta o nome de utilizador/palavra-passe uma vez. A partir desse momento, o token de acesso é usado.
• credenciais do cliente: considere usá-las em situações em que a app do cliente está a agir em nome próprio. Ou seja, o cliente também é o proprietário do recurso. Este tipo de autorização é normalmente usado quando a app precisa de aceder a um serviço de armazenamento de dados de back-end, por exemplo. A app precisa de usar o serviço para fazer o seu trabalho e, caso contrário, o serviço é opaco para o utilizador final. Com este tipo de concessão, uma app pode receber um token de acesso apresentando as chaves de ID de cliente e segredo do cliente ao servidor de autorizações. Não são necessários mais passos. oferece uma solução de credenciais de cliente pronta a usar que é fácil de implementar para qualquer proxy de API.

O que é um token de acesso?

Um token de acesso é uma longa string de carateres que funciona como uma credencial usada para aceder a recursos protegidos. Os tokens de recursos (também denominados tokens de portador) são transmitidos em cabeçalhos de autorização, da seguinte forma:

$ curl -H "Authorization: Bearer UAj2yiGAcMZGxfN2DhcUbl9v8WsR" \
  http://myorg-test.apigee.net/v0/weather/forecastrss?w=12797282

O servidor de recursos compreende que o token de acesso substitui credenciais como o nome de utilizador e a palavra-passe. Além disso, as chaves de acesso podem ser emitidas com restrições para que, por exemplo, a app possa ler, mas não escrever nem eliminar dados no servidor de recursos. Tenha em atenção que um token de acesso pode ser revogado se, por exemplo, a app for comprometida. Neste caso, tem de obter um novo token de acesso para continuar a usar a app. No entanto, não tem de alterar o nome de utilizador nem a palavra-passe no servidor de recursos protegidos (por exemplo, Facebook ou Twitter).

Geralmente, os tokens de acesso têm uma data de validade (por motivos de segurança). Alguns tipos de concessão permitem que o servidor de autorizações emita um token de atualização, o que permite à app obter um novo token de acesso quando o antigo expira. Para mais detalhes sobre tokens de acesso e atualização, consulte a especificação IETF OAuth 2.0.

Acesso limitado através de âmbitos

Através do mecanismo de âmbitos, o OAuth 2.0 pode conceder a uma app acesso limitado a recursos protegidos. Por exemplo, uma app pode ter acesso apenas a recursos específicos, pode conseguir atualizar recursos ou pode apenas ter acesso só de leitura. Nos chamados fluxos OAuth de três partes, o utilizador especifica normalmente o nível de acesso através de uma página de consentimento (por exemplo, uma página Web onde o utilizador seleciona o âmbito com uma caixa de verificação ou outro mecanismo).

Registar uma app

Todos os clientes (apps) têm de se registar no servidor de autorizações OAuth 2.0 a partir do qual pretendem pedir tokens de acesso. Quando regista uma app, recebe um conjunto de chaves. Uma é uma chave pública denominada identificador do cliente e a outra é uma chave secreta denominada segredo do cliente. Sem estas chaves, uma app não pode emitir pedidos de códigos de autorização nem chaves de acesso ao servidor de autorização. Tenha em atenção que, embora a especificação OAuth da IETF denomine estas chaves ID do cliente e segredo do cliente, a IU do Apigee denomina-as ID do consumidor e segredo do consumidor. São equivalentes.

Resumo dos exemplos de utilização do OAuth 2.0

O fluxo do tipo de concessão OAuth 2.0 que escolheu implementar depende do seu exemplo de utilização específico, uma vez que alguns tipos de concessão são mais seguros do que outros. A sua escolha de tipos de autorização depende da fiabilidade da app cliente e requer uma consideração muito cuidadosa, conforme descrito na tabela seguinte:

Exemplo de utilização	Fiabilidade	Tipos de concessão de autorização OAuth 2.0 sugeridos	Descrição
B2B (extranet), intranet, outro	Apps altamente fidedignas, escritas por programadores internos ou programadores com uma relação comercial fidedigna com o fornecedor da API. Apps que precisam de aceder a recursos em seu próprio nome.	Credenciais do cliente	Normalmente, a app também é o proprietário do recurso Requer chaves de ID de cliente e segredo do cliente Requer que a app esteja registada junto do fornecedor de serviços
Sites e portais de intranet	Apps fidedignas escritas por programadores internos ou de terceiros fidedignos. Um bom exemplo é iniciar sessão no site de recursos humanos da sua empresa para fazer seleções de seguros, enviar críticas ou alterar informações pessoais.	Palavra-passe Implícito	Requer o ID de cliente e o segredo, além do nome de utilizador e da palavra-passe Requer que a app esteja registada junto do fornecedor de serviços
Apps disponíveis publicamente	As apps não fidedignas são escritas por programadores externos que não têm uma relação comercial fidedigna com o fornecedor da API. Por exemplo, os programadores que se registam em programas de APIs públicas não devem ser considerados fidedignos.	Código de autorização	Requer que o utilizador inicie sessão no fornecedor de recursos de terceiros (por exemplo, Twitter, Facebook) A app nunca vê o nome de utilizador e a palavra-passe do utilizador Requer que a app esteja registada junto do fornecedor de serviços
B2C	Existe um utilizador final individual (utilizador de dispositivo móvel) envolvido e as credenciais do utilizador são armazenadas no dispositivo móvel.	Implícito	Requer que a app esteja registada junto do fornecedor de serviços. As credenciais do utilizador são armazenadas no dispositivo que executa a app.

Segurança do OAuth 2.0 vs. chave de API

A validação da chave da API requer que uma app envie uma chave para o Apigee. A chave tem de ser uma chave de consumidor válida de uma app de programador do Apigee associada ao proxy de API. Se, por algum motivo, precisar de revogar a autorização de uma app cliente para fazer chamadas a um proxy, tem de revogar essa chave de consumidor. As apps cliente que usam essa chave também não vão poder aceder ao proxy da API. Por outro lado, um token OAuth pode ser revogado em qualquer altura sem revogar as chaves da app. A app pode simplesmente pedir um novo token em nome do utilizador e, se for concedido um token, a app pode continuar a usar o proxy de API.

Outra diferença entre uma chave da API e um token é que um token pode incluir atributos de metadados que pode obter e usar mais tarde. Por exemplo, pode armazenar o ID do utilizador que está a fazer a chamada API e usá-lo para personalizar as chamadas ao serviço de destino de back-end.

Para ver detalhes sobre a validação de chaves da API, consulte o artigo Chaves da API. Para obter informações sobre a utilização de atributos personalizados com tokens OAuth, consulte o artigo Personalizar tokens e códigos de autorização.

Impacto da expiração dos tokens e dos tempos de limpeza no armazenamento em disco

Nota: esta secção aplica-se apenas a clientes híbridos do Apigee.

Quando gera um novo token OAuth com a política OAuthV2, pode definir um prazo de validade para o token com o atributo ExpiresIn. Por predefinição, os tokens são eliminados do armazenamento três dias após a respetiva expiração. Se definir um tempo de expiração elevado, como 48 horas, pode ver um aumento inesperado na utilização do espaço em disco para o Cassandra. Para evitar a utilização excessiva de espaço no disco, pode definir um prazo de validade mais curto (recomenda-se uma hora) e/ou definir uma configuração que altere o atraso de três dias após a validade para um período mais curto.

Os clientes do Apigee hybrid podem alterar o tempo de eliminação predefinido definindo a seguinte configuração no respetivo ficheiro de substituições:

runtime:
  cwcAppend:
    "conf_keymanagement_oauth.access.token.purge.after.seconds": "SECONDS"

Em que SECONDS é o número de segundos que o Apigee aguarda para remover completamente os tokens após a respetiva expiração. Certifique-se de que inclui esta estrofe exatamente como está escrita, com as aspas incluídas.

Por exemplo, para definir a hora da remoção completa para uma hora após a expiração:

runtime:
  cwcAppend:
    "conf_keymanagement_oauth.access.token.purge.after.seconds": "3600"

Recursos recomendados

Leitura

Consulte o artigo Saiba mais sobre o OAuth 2.0.