Introdução ao OAuth 2.0

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Página inicial do OAuth: consulte a página inicial do OAuth para uma visualização de nível superior da orientação OAuth que fornecemos.

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

O que é OAuth 2.0?

Há muitos livros, blogs e sites dedicados ao OAuth 2.0. É altamente recomendável que você comece analisando a especificação IETF OAuth 2.0. Veja a definição de OAuth 2.0 a partir da própria especificação IETF OAuth 2.0:

"O framework da estrutura de autorização do OAuth 2.0 permite que um aplicativo de terceiros consiga acesso limitado a um serviço HTTP em nome do proprietário de um recurso, orquestrando uma interação de aprovação entre o proprietário do recurso e o serviço HTTP ou permitindo que o aplicativo de terceiros receba acesso em seu próprio nome."

A principal coisa que você precisa saber é que o OAuth 2.0 oferece uma maneira para que os aplicativos tenham acesso limitado aos recursos protegidos (como dados bancários ou outras informações confidenciais que o usuário quer acessar a partir de um app) sem a necessidade do usuário compartilhar as credenciais de login no app.

Dica: digamos que você tenha encontrado um app que permite acessar várias contas bancárias. Talvez o aplicativo seja usado com seus impostos ou para gerenciar seu orçamento. Você tem três contas bancárias que gostaria de gerenciar com o aplicativo e tem um nome de usuário e senha diferentes para cada uma delas. Agora, para que o aplicativo acesse suas contas bancárias, são necessárias essas credenciais confidenciais. Basicamente, você está fornecendo essas informações confidenciais ao aplicativo. Você confia no app para ter suas senhas e nomes de usuário? E se o app for invadido? Agora, você precisa se lembrar de alterar as credenciais bancárias para cada conta. Esse é o problema fundamental resolvido pelo OAuth 2.0. Continue lendo para saber mais.

O fluxo do OAuth 2.0

Este é o fluxo geral da framework do OAuth 2.0. Discutiremos esse fluxo em mais detalhes neste tópico, começando com um diagrama, que ilustra muito como o OAuth 2.0 funciona. Se você não estiver familiarizado com os termos usados neste diagrama, leia esta seção para uma introdução rápida.

Termos que você precisa conhecer

• Cliente: também chamado de app. Pode ser um app executado em um dispositivo móvel ou um app da Web tradicional. O aplicativo faz solicitações ao servidor de recursos para recursos protegidos em nome do proprietário do recurso. O proprietário do recurso precisa conceder ao aplicativo permissão para acessar os recursos protegidos.
• Proprietário de recursos: também chamado de usuário final. Geralmente, a pessoa (ou outra entidade) capaz de conceder acesso a um recurso protegido. Por exemplo, se um app precisar usar dados de um dos seus sites de mídia social, você será o proprietário do recurso, ou seja, a única pessoa que poderá conceder ao app acesso aos seus dados.
• Servidor de recursos: pense no servidor de recursos como um serviço como o Facebook, o Google, o Twitter, um serviço de RH na intranet ou um serviço de parceiro na sua extranet B2B. O Apigee é um servidor de recursos sempre que a validação do token OAuth for necessária para processar solicitações de API. O servidor de recursos precisa de algum tipo de autorização para exibir recursos protegidos ao aplicativo.
• Servidor de autorização: o servidor de autorização é implementado em conformidade com a especificação OAuth 2.0 e é responsável por validar concessões de autorização e emitir os tokens de acesso que concedem ao app acesso aos dados do usuário no servidor de recursos. É possível configurar os endpoints de token no Apigee. Nesse caso, o Apigee assume o papel de servidor de autorização.
• Conceder autorização: concede ao aplicativo permissão para recuperar um token de acesso em nome do usuário final. O OAuth 2.0 define quatro "tipos de concessão" específicos. Consulte Quais são os tipos de concessão do OAuth 2.0.
• Token de acesso: uma string longa de caracteres que serve como uma credencial usada para acessar recursos protegidos. Consulte O que é um token de acesso?.
• Recurso protegido: dados do proprietário do recurso. Por exemplo, a lista de contatos do usuário, informações da conta ou outros dados confidenciais.

Onde a Apigee se encaixa

É possível proteger qualquer API com proxy usando a Apigee com OAuth 2.0. A Apigee inclui uma implementação de servidor de autorização e, dessa forma, pode gerar e validar tokens de acesso. Os desenvolvedores começam registrando os aplicativos na Apigee. Os apps registrados podem solicitar tokens de acesso por meio de qualquer uma das quatro tipo de concessão de interações.

A Apigee fornece uma política de OAuthV2 de vários atributos que implementa os detalhes de cada tipo de concessão, facilitando a configuração do OAuth na Apigee. Por exemplo, você pode configurar uma política que recebe uma solicitação de um token de acesso, avalia todas as credenciais necessárias e retorna um token de acesso, se as credenciais forem válidas.

Observe que os servidores de recursos que seu proxy de API segura chama precisam estar protegidas por um firewall (ou seja, os recursos não podem ser acessados por nenhum meio além do proxy da API ou de outra API que seja segura).

O que são tipos de concessão do OAuth 2.0?

Pense nos tipos de concessão como caminhos ou interações diferentes que um app pode seguir para receber um token de acesso. Cada tipo de concessão atende a um ou mais casos de uso, e você precisa selecionar os tipos de concessão a serem usados com base nas suas próprias necessidades. Em geral, cada tipo de concessão tem vantagens e desvantagens, e você precisará ponderar as compensações com base nos seus casos de uso comercial. Uma consideração importante é a confiança dos aplicativos que acessarão seus dados. Geralmente, os aplicativos de terceiros são menos confiáveis do que os aplicativos desenvolvidos e usados em uma empresa.

A Apigee é compatível com 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 do servidor de autorização emitir um token de acesso, o app precisa receber primeiro um código de autorização do servidor de recursos. Você viu esse fluxo sempre que seu aplicativo abre um navegador para a página de login do servidor de recursos e convida você a fazer login na sua conta real (por exemplo, Facebook ou Twitter).

Se você fizer o login com sucesso, o aplicativo receberá um código de autorização que pode ser usado para negociar um token de acesso com o servidor de autorização. Normalmente, esse tipo de concessão é usado quando o aplicativo reside em um servidor, e não no cliente. Esse tipo de concessão é considerado altamente seguro porque o aplicativo cliente nunca processa ou vê o nome de usuário ou a senha do usuário para o servidor de recursos (ou seja, o aplicativo nunca vê ou manipula suas credenciais do Twitter). Esse fluxo de tipo de concessão também é chamado de OAuth de três pernas.

• implícito: uma versão simplificada do código de autorização é considerada. Normalmente, esse tipo de concessão é usado quando o aplicativo reside no cliente. Por exemplo, o código do aplicativo é implementado em um navegador usando JavaScript ou outra linguagem de script (em vez de residir e executar em um servidor da Web separado). Nesse fluxo de tipo de concessão, o servidor de autorização retorna um token de acesso diretamente quando o usuário é autenticado, em vez de emitir um código de autorização primeiro. As concessões implícitas podem melhorar a capacidade de resposta do app em alguns casos, mas essa vantagem precisa ser avaliada em relação a possíveis implicações de segurança, conforme descrito na especificação IETF.
• credenciais de senha do proprietário do recurso: nesse fluxo, o cliente recebe um token de acesso quando o nome de usuário/senha do usuário é validado pelo servidor de autorização. Esse fluxo é recomendado para aplicativos altamente confiáveis. Uma vantagem desse fluxo sobre, por exemplo, autenticação básica, é que o usuário apresenta apenas o nome de usuário/senha uma vez. Depois disso, o token de acesso será usado.
• Credenciais do cliente: em situações em que o app cliente está agindo em seu próprio nome. Ou seja, o cliente também é o proprietário do recurso. Esse tipo de concessão normalmente é usado quando o aplicativo precisa acessar um serviço de armazenamento de dados de back-end, por exemplo. O aplicativo precisa usar o serviço para fazer o trabalho, e o serviço é opaco para o usuário final. Com esse tipo de concessão, um aplicativo pode receber um token de acesso mostrando o ID do cliente e as chaves secretas do cliente ao servidor de autorização. Nenhuma outra etapa é necessária. oferece uma solução de credenciais de cliente pronta para uso e fácil de implementar para qualquer proxy de API.

O que é um token de acesso?

Um token de acesso é uma longa string de caracteres que serve como uma credencial usada para acessar recursos protegidos. Os tokens de recursos (também chamados de tokens do portador) são passados nos cabeçalhos de autorização, como este:

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

O servidor de recursos entende que o token de acesso está em para credenciais como nome de usuário e senha. Além disso, os tokens de acesso podem ser emitidos com restrições para que, por exemplo, o aplicativo possa ler, mas não gravar ou excluir dados no servidor de recursos. Um token de acesso pode ser revogado se, por exemplo, o app estiver comprometido. Nesse caso, você precisará conseguir um novo token de acesso para continuar usando o app. No entanto, não será necessário alterar seu nome de usuário ou sua senha no servidor de recursos protegidos (por exemplo, Facebook ou Twitter).

Os tokens de acesso geralmente têm expiração (por motivos de segurança). Alguns tipos de concessão permitem que o servidor de autorização emita um token de atualização, permitindo que o app busque um novo token de acesso quando o antigo expirar. Para mais detalhes sobre tokens de acesso e atualização, consulte a especificação do IETF 2.0 para IETF.

Acesso limitado por meio de escopos

Por meio do mecanismo de escopos, o OAuth 2.0 pode conceder ao aplicativo acesso limitado a recursos protegidos. Por exemplo, um app pode ter acesso apenas a recursos específicos, pode atualizar recursos ou ter acesso somente leitura. Em fluxos de três pernas do OAuth, o usuário geralmente especifica o nível de acesso por meio de uma página de consentimento (por exemplo, uma página da Web em que o usuário seleciona o escopo com uma caixa de seleção ou outro mecanismo).

Como registrar um aplicativo

Todos os clientes (aplicativos) precisam se registrar no servidor de autorização do OAuth 2.0 a partir do qual pretendem solicitar tokens de acesso. Ao registrar um aplicativo, você recebe um conjunto de chaves novamente. Uma delas é uma chave pública chamada identificador de cliente e a outra é uma chave secreta chamada chave secreta do cliente. Sem essas chaves, um app não pode emitir solicitações para códigos de autorização ou tokens de acesso ao servidor de autorização. Observe que, enquanto a especificação IETF OAuth chama essas chaves do ID do cliente e a chave secreta do cliente, a IU da Apigee as chama de ID de consumidor e chave secreta do consumidor. Elas são equivalentes.

Resumo dos casos de uso do OAuth 2.0

O fluxo de tipos de concessão do OAuth 2.0 que você escolheu implementar depende do seu caso de uso específico, já que alguns tipos de concessão são mais seguros do que outros. Sua escolha de tipos de concessão depende da confiabilidade do aplicativo cliente e requer considerações muito cuidadosas, conforme descrito na tabela a seguir:

Caso de uso	Confiabilidade	Tipos sugeridos de concessão de autorização OAuth 2.0	Descrição
B2B (extranet), intranet, outros	Aplicativos altamente confiáveis, criados por desenvolvedores internos ou desenvolvedores com um relacionamento comercial confiável com o provedor da API. Apps que precisam acessar recursos em seu próprio nome.	Credenciais do cliente	Normalmente, o app também é o proprietário do recurso. Requer ID do cliente e chaves secretas do cliente O app precisa ser registrado no provedor de serviços
Sites de intranet, portais	Apps confiáveis criados por desenvolvedores internos ou confiáveis de terceiros. Um bom exemplo é fazer login no site de RH da sua empresa para fazer seleções de seguros, enviar avaliações ou alterar informações pessoais.	Senha Implícito	Requer ID e chave secreta do cliente, além de nome de usuário e senha O app precisa ser registrado no provedor de serviços
Apps disponíveis publicamente	Os aplicativos não confiáveis são escritos por desenvolvedores terceirizados que não têm uma relação comercial confiável com o provedor de API. Por exemplo, os desenvolvedores que se registram em programas de API pública geralmente não são confiáveis.	Código de autorização	Exige que o usuário faça login no provedor de recursos de terceiros. Por exemplo, Twitter, Facebook) O aplicativo nunca vê o nome de usuário e a senha do usuário O app precisa ser registrado no provedor de serviços
B2C	Há um usuário final individual (usuário móvel) envolvido e as credenciais do usuário são armazenadas no dispositivo móvel.	Implícito	O app precisa ser registrado no provedor de serviços As credenciais de usuário são armazenadas no dispositivo que executa o app.

OAuth 2.0 x segurança da chave de API

A validação da chave de API exige que um app envie uma chave para a Apigee. A chave precisa ser uma chave do consumidor válida de um app de desenvolvedor da Apigee associado ao proxy da API. Se, por algum motivo, você precisar revogar a permissão de um app cliente para fazer chamadas para um proxy, será necessário revogar essa chave do consumidor. Os aplicativos clientes que usam essa chave também não poderão acessar o proxy da API. Por outro lado, um token OAuth pode ser revogado a qualquer momento sem revogar as chaves do aplicativo. O aplicativo pode simplesmente solicitar um novo token em nome do usuário e, se um token for concedido, o aplicativo pode continuar usando o proxy de API.

Outra diferença entre uma chave de API e um token é que o token pode incluir atributos de metadados que é possível recuperar e usar depois. Por exemplo, é possível armazenar o ID do usuário que está fazendo a chamada de API e usá-lo para personalizar chamadas ao serviço de destino de back-end.

Para detalhes sobre a validação de chaves de API, consulte Chaves de API. Para informações sobre o uso de atributos personalizados com tokens OAuth, consulte Como personalizar tokens e códigos de autorização.

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

Observação:esta seção se aplica apenas a clientes da Apigee híbrida.

Ao gerar um novo token OAuth com a política OAuthV2, é possível definir um prazo de validade para o token com o atributo ExpiresIn. Por padrão, os tokens são limpos do armazenamento três dias após o vencimento. Se você definir um tempo de expiração longo, como 48 horas, poderá notar um aumento inesperado no uso do espaço em disco para o Cassandra. Para evitar o uso excessivo de espaço em disco, defina um tempo de expiração mais curto (uma hora é recomendado) e/ou defina uma configuração que mude o atraso pós-expiração de três dias para um período mais curto.

Os clientes da Apigee híbrida podem mudar o tempo de limpeza padrão definindo a seguinte configuração no arquivo 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 vai esperar para limpar os tokens após a expiração. Inclua essa estrofe exatamente como está escrita, com as aspas.

Por exemplo, para definir o tempo de descarte como uma hora após a expiração:

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

Recursos recomendados

Leitura

Consulte Saiba mais sobre o OAuth 2.0.