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.
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 uma das suas redes sociais, você será o proprietário do recurso, ou seja, a única pessoa que pode 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 permissão de acesso" específicos. Consulte O que são os tipos de permissão de acesso 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 proxy de API por meio da Apigee com o 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 oferece uma política OAuthV2 multifacetada que implementa os detalhes de cada tipo de permissão de acesso, 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 permissão de acesso do OAuth 2.0?
Pense nos tipos de permissão de acesso como diferentes caminhos ou interações que um app pode seguir para receber um token de acesso. Cada tipo de permissão de acesso aborda um ou mais casos de uso, e você precisa selecionar quais tipos de permissão de acesso usar com base nas suas próprias necessidades. Em geral, cada tipo de permissão de acesso tem vantagens e desvantagens, e você precisa avaliar as compensações com base nos casos de uso comercial da sua empresa. 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 permissão de acesso do OAuth 2.0:
- código de autorização: considerado o tipo de permissão de acesso 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 permissão de acesso é usado quando o app reside em um servidor, e não no cliente. Esse tipo de permissão de acesso é considerado altamente seguro porque o app cliente nunca processa nem vê o nome de usuário ou a senha do usuário para o servidor de recursos (ou seja, por exemplo, o app nunca vê nem processa suas credenciais do Twitter). Esse fluxo de tipo de permissão de acesso também é chamado de OAuth de três etapas.
- implícito: uma versão simplificada do código de autorização é considerada. Normalmente, esse tipo de permissão de acesso é usado quando o app 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 permissão de acesso, 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 permissão de acesso é normalmente usado quando o app 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 permissão de acesso, um app pode receber um token de acesso apresentando o ID do cliente e as chaves chave secreta 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 permissão de acesso permitem que o servidor de autorização emita um token de atualização, o que permite 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 tipo de permissão de acesso do OAuth 2.0 que você escolhe implementar depende do seu caso de uso específico, já que alguns tipos de permissão de acesso são mais seguros do que outros. A escolha dos tipos de permissão de acesso depende da confiabilidade do app cliente e requer uma consideração muito cuidadosa, conforme descrito na tabela a seguir:
| Caso de uso | Confiabilidade | Tipos de permissão de acesso de autorização do OAuth 2.0 sugeridos | 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. |
|
|
| 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. |
|
|
| 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. |
|
|
| 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. |
|
|
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. O token precisa ser um token do cliente válido de um app de desenvolvedor da Apigee associado ao proxy de 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 apps clientes que usam essa chave também não poderão acessar o proxy de 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 e dos tempos de limpeza de tokens no armazenamento em disco
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 eliminados do
armazenamento três dias após a expiração. Se você definir um tempo de expiração longo, como 48 horas,
poderá notar um aumento inesperado no uso do espaço em disco do Cassandra. Para evitar o uso excessivo de espaço em disco, defina um prazo de validade mais curto (recomendamos uma hora) e/ou defina uma configuração
que mude o atraso pós-validade 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 a 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 limpeza 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.