Os tokens de API estáticos são usados há muito tempo para chamar APIs externas e acessar recursos de terceiros, como fornecedores de software. Com a evolução dos padrões de API, OAuth 2.0 surgiu como a opção que oferece segurança mais robusta, maior flexibilidade e uma melhor experiência para desenvolvedores. Vamos explorar as vantagens de abandonar os tokens estáticos em favor do OAuth 2.0.
Panorama dos tokens de API estáticos
Em um sistema de software seguro, todas as chamadas que permitem acesso de leitura ou modificação a recursos devem ser autorizadas. Ao chamar uma API protegida, a API precisa de alguma forma de validar a autorização. Os tokens de API estáticos são uma forma de fornecer informações de autorização à API usando um valor memorizado, sem levar em consideração o contexto do usuário. Como resultado, eles forneceram uma abordagem simples (mas limitada) para que os desenvolvedores concedessem acesso à API de outro aplicativo: gerar um token, armazená-lo uma única vez e prosseguir com a tarefa.
Se analisarmos um exemplo de chamada HTTP para o Okta, uma solicitação com um token de API estático pode ser algo como:
Quem chama a API (também conhecida como cliente) adiciona o valor do token à chamada. Dependendo do sistema do fornecedor chamado, a API pode adicionar o valor do token estático a um cabeçalho HTTP, como Authorization (usando um esquema de autorização padrão ou um proprietário, como o esquema SSWS da Okta), ou em um parâmetro de consulta.
Migre de tokens de API estáticos para OAuth 2.0 para maior segurança.
Tal como acontece com muitas tecnologias, esta facilidade de utilização acarreta um aumento correspondente na exposição ao risco. Ao contrário dos tokens OAuth 2.0 de curta duração, os tokens estáticos normalmente têm uma longa vida útil. Tokens de API definidos em parâmetros de consulta são particularmente perigosos. Os navegadores salvam URLs no histórico e os sistemas de registro podem gravar a URL inteira, expondo o token mais facilmente do que quando se utilizam cabeçalhos HTTP.
Para melhor compreender as preocupações de segurança associadas aos tokens de API estáticos, vamos analisar detalhadamente algumas de suas características e compará-las com o OAuth 2.0 como alternativa.
Riscos de acesso ao usar tokens de API estáticos
Tokens estáticos podem cair em mãos erradas, levando a acessos não autorizados. Por exemplo, tokens estáticos podem ser inadvertidamente incluídos em sistemas de controle de versão, expondo o token inadvertidamente aos visualizadores do repositório e ao histórico do controle de versão. Como os tokens estáticos têm longa duração, o risco de exposição desses tokens é particularmente preocupante, pois as consequências do roubo de um token são impactantes — um token estático roubado permanece ativo até ser desativado manualmente ou até expirar, permitindo acesso não autorizado.
Problemas de rotação de tokens
A rotação de tokens estáticos pode ser uma tarefa desafiadora. Como os valores dos tokens permanecem no ambiente ou nos sistemas de software do chamador, sincronizar a rotação para liberar rapidamente um token, gerar um novo e salvar o token, mantendo os ambientes de produção em funcionamento, pode apresentar desafios.
Limitar o escopo é difícil.
Atribuir escopos limitados a tokens estáticos não é uma tarefa simples. Os tokens estáticos geralmente concedem acesso à API chamada em sua totalidade — um nível de acesso "tudo ou nada". A definição de acesso com escopo limitado, como acesso somente leitura versus acesso de gravação, e outras medidas de controle de acesso mais refinadas podem não estar disponíveis ou serem difíceis de gerenciar por meio de tokens de API estáticos.
Permissões herdadas em tokens gerados pelo usuário
Os tokens de acesso gerados pelo usuário geralmente adotam as permissões da conta de usuário que os gerou. Se um administrador gerar o token, ele terá acesso total a todos os recursos e ações que o administrador puder executar. Para atenuar essa preocupação, por vezes as organizações criam contas de serviço com escopos limitados para gerar o token. No entanto, fazer isso acarreta custos adicionais de gerenciamento de usuários e pode resultar na ocupação de uma licença.
Desafios de auditoria
É complicado rastrear a utilização de tokens estáticos. Uma necessidade fundamental da auditoria é rastrear a interação de um usuário com uma API. No entanto, os tokens de API estáticos geralmente não contêm o contexto do usuário, e todas as chamadas à API usam o mesmo token estático, portanto, identificar a ação específica de um usuário com uma API pode ser impossível.
Tokens estáticos são frágeis
Os tokens vinculados às contas de usuário tornam-se inválidos quando o usuário sai da organização. Algumas organizações utilizam contas de serviço para neutralizar essa medida, o que acarreta riscos de acesso e sobrecarga de gerenciamento.
Existe uma maneira melhor e mais segura de acessar APIs que mitiga os riscos associados a tokens de API estáticos: usando fluxos OAuth 2.0 padrão do setor.
Adote o OAuth 2.0 para melhorar a segurança.
O OAuth 2.0 atende a praticamente qualquer cenário, substituindo tokens estáticos como os tokens SSWS da Okta. Mas, ao contrário dos tokens estáticos, as especificações do OAuth incluem definições e práticas seguras para necessidades como rotação de tokens, decisões básicas de autorização e muito mais para casos de uso cotidianos, como
- Interação automatizada entre serviços para lidar com chamadas de API em segundo plano, sem contexto do usuário.
- Automação baseada em tarefas por meio de suas operações de linha de comando.
- Limitar os dados e as ações do aplicativo aos níveis de acesso do usuário para manter a segurança da autorização.
O OAuth 2.0 suporta cada um dos casos de uso cotidianos listados acima por meio de propriedades de configuração enviadas em uma solicitação a um servidor de autorização centralizado. A interação geral é um processo de várias etapas como este:
1. O solicitante requisita um token de acesso do servidor de autorização, passando as propriedades de configuração necessárias para o caso de uso. O servidor de autorização retorna um token de acesso de curta duração. A duração do token depende do caso de uso. Alguns casos de uso são inerentemente mais seguros, portanto a duração da vida útil pode variar. A solicitação HTTP abaixo mostra um exemplo de solicitação para recuperar um token, mas não inclui as propriedades de configuração necessárias. Serão apresentadas as propriedades de configuração necessárias nos exemplos a seguir.
2. O solicitante utiliza o valor do token na requisição da API como um valor no cabeçalho de autorização da requisição HTTP usando o esquema Bearer. A solicitação HTTP pode ter a seguinte aparência:
O OAuth 2.0 é bastante complexo, então confira os recursos no final deste post para um estudo mais aprofundado. Neste post, não entraremos em todos os detalhes, mas adaptaremos as informações específicas aos casos de uso mencionados e forneceremos um resumo geral para cada um.
Vamos analisar cada caso de uso para ver como o OAuth 2.0 o suporta.
Interação de serviço para serviço
Você pode ter processos de backend que chamam outras APIs para obter dados ou executar ações. O OAuth 2.0 suporta solicitações de serviço para serviço ou de máquina para máquina sem um contexto de usuário associado à chamada, por meio de um fluxo de autorização chamado credenciais do cliente.
Vantagens de usar credenciais de cliente em vez de tokens de API
Utilizar o OAuth 2.0 para interação entre serviços oferece grandes vantagens em relação às chaves de API estáticas, especialmente no que diz respeito aos níveis de acesso chamados escopos. No OAuth 2.0, define-se os escopos que o token de acesso recebe como parte das propriedades de configuração em uma chamada para recuperar o token. É necessário garantir que a API chamada suporte o acesso baseado em escopo e que tenha sido concedido acesso aos escopos necessários. Por exemplo, as APIs do Okta definiram vários escopos para APIs de recursos, como okta.users.read e okta.users.write. É possível conceder acesso a um ou a ambos os escopos.
O fluxo de credenciais do cliente não é o mesmo que usar contas de serviço para autorização da API. O OAuth 2.0 oferece suporte à interação máquina a máquina em um formato padrão, sem ocupar uma conta de usuário para emular um usuário de automação. Note que, ao definir escopos, isso deverá ser feito na configuração do aplicativo de serviço e no servidor de autorização, e não no nível do usuário. A vantagem é que o senhor controla o acesso aos recursos para toda a aplicação de serviço, e não por meio de um usuário específico dentro da aplicação. O senhor não precisa mais se preocupar com o gerenciamento de contas de serviço e pode ter certeza de que o aplicativo não poderá acessar mais escopos do que os que o senhor permitiu.
Recupere um token de acesso usando as credenciais do cliente.
Para obter um token de acesso para este fluxo, enviar-se-ão propriedades especificando o tipo de fluxo de autorização, as credenciais e os escopos que o token de acesso possui. No OAuth 2.0, o termo usado para definir o fluxo de autorização é grant_type; para o fluxo de credenciais do cliente, deve-se passar o valor client_credentials.
As credenciais podem ser um JSON Web Token (JWT) criptograficamente seguro, assinado com a chave privada do cliente, ou um valor secreto gerado pelo seu servidor de autorização. Um JWT com chave privada é mais seguro, pois não se corre o risco de expor acidentalmente o valor secreto, o que poderia gerar preocupações de acesso semelhantes às de um token de API estático. Você irá gerar um par de chaves pública/privada e registrar a chave pública em um conjunto de chaves web JSON (JWKS) ou carregá-la no servidor de autorização para que este tenha a chave pública necessária para validar a assinatura JWT. Leia mais sobre este processo na documentação Implementar OAuth para Okta com um Aplicativo de Serviço.
Um exemplo de chamada HTTP para recuperar o token de acesso pode ser assim:
Após obter o token de acesso, o senhor o adicionará às chamadas da API como um cabeçalho: Authorization: Bearer access_token.
Leia mais sobre chamadas de API serviço a serviço usando .NET e criação de JWTs privados em Python em Proteja sua API Web .NET 6 e Configure o fluxo JWT de chave privada em três comandos Python.
Automação baseada em tarefas
Terminais de linha de comando, como Bash e PowerShell, são processos que não dependem de navegador para executar comandos ou scripts individuais dentro da janela do terminal. Diferentemente da interação anterior entre serviços, este fluxo envolve o contexto do usuário. O senhor deseja executar as operações de linha de comando com seu contexto de autorização, o que significa que terá acesso apenas aos recursos da API aos quais tem permissão. O OAuth 2.0 oferece suporte a esse caso de uso com um fluxo chamado fluxo de dispositivo.
A obtenção de tokens de acesso é um processo de várias etapas nesse fluxo. Antes de solicitar o token de acesso diretamente, como no caso de uso de serviço para serviço, primeiro obtém códigos de verificação exclusivos enviando o ID do cliente para um endpoint específico em seu servidor de autorização:
A resposta da chamada /device/authorize retorna dois códigos exclusivos — um código de dispositivo e um código de usuário — e um URI de verificação. Confirme a solicitação de autorização acessando o URI de verificação em seu navegador e inserindo o código do usuário.
Para recuperar o token de acesso, adicione a propriedade grant_type para especificar o fluxo OAuth 2.0 para o caso de uso e o código do dispositivo como propriedades de configuração na chamada:
Utilize o token de acesso da resposta no cabeçalho Authorization: Bearer access_token.
Você pode ler mais sobre o fluxo de código de dispositivo para linhas de comando em Autenticar a partir da linha de comando com Java.
Acesso do usuário por meio de um aplicativo web
O último caso de uso garante que a autorização do usuário se aplique ao acesso à API ao usar um aplicativo web. O OAuth 2.0 permite limitar as ações de um aplicativo a um subconjunto do que o usuário pode fazer e dos dados que ele visualiza. Nesse fluxo, tem-se o contexto do usuário para solicitar a autorização de recursos, e ter o contexto do usuário facilita a auditoria e o rastreamento de chamadas por usuários individuais. O fluxo OAuth 2.0 para este caso de uso combina um fluxo padrão, o fluxo de código de autorização e uma extensão para uma camada extra de segurança chamada chave de prova para troca de código (PKCE).
O fluxo de código de autorização com PKCE requer várias etapas para obter um token de acesso e envolve a interação do usuário por meio de consentimento e verificação, o que permite a autenticação multifatorial. Nesse fluxo, redirecionará o usuário para um servidor de autorização para obter o código de autorização antes de solicitar um token de acesso.
A URL de redirecionamento inclui propriedades específicas da solicitação para que o usuário possa concluir o login, incluindo a especificação do tipo de solicitação usando a propriedade `response_type` e o ID do cliente, entre outras propriedades.
Quando o usuário conclui o login com sucesso, o provedor de identidade o redireciona de volta para o aplicativo com um código de autorização na resposta de autorização. Para obter o token de acesso, deve-se fornecer o tipo de concessão para este fluxo, o código de autorização e outros metadados específicos da solicitação.
Com o token de acesso em mãos, o aplicativo web adiciona o token de acesso às chamadas de API de saída no cabeçalho Authorization: Bearer access_token.
Leia mais sobre o fluxo de código de autorização em Como a autenticação e a autorização funcionam para SPAs e Use PKCE com OAuth 2.0 e Spring Boot para maior segurança.
Elimine gradualmente os tokens de API estáticos e utilize o OAuth 2.0.
Migrações de software exigem tempo e planejamento, e ter um bom plano de ação ajuda bastante. Considere a transição para o OAuth 2.0 em pequenas etapas incrementais.
O primeiro passo para migrar de tokens de API estáticos é garantir que as APIs que o senhor utiliza sejam compatíveis com OAuth 2.0. Solicitamos que consulte o seu fornecedor caso esteja utilizando APIs de terceiros. Se a sua API for interna, será necessário adicionar suporte a OAuth. Após verificar se as APIs que os senhores estão chamando suportam OAuth, será necessário o ID do cliente para o aplicativo OAuth e habilitar medidas de acesso, como escopos.
Ao fazer login no seu Console de Administração do Okta como administrador, é possível determinar se utiliza tokens de API estáticos em um ambiente Okta. Na barra lateral, navegue até Segurança > API e selecione a guia Tokens para ver todos os tokens criados para a organização Okta. Esta visualização fornece informações sobre o uso do token da API, casos de uso e nível de acesso (por exemplo, um token criado por um Super Administrador tem acesso total). Será necessário avaliar cada um deles e convertê-los para usar o OAuth.
Vamos nos concentrar no caso de uso de uma chamada automatizada de serviço para serviço. Incorporar o OAuth 2.0 em suas APIs de uma só vez pode ser uma tarefa complexa, então vamos examinar como fazer isso gradualmente. Antes de fazer qualquer alteração no código, pode-se testar os passos localmente, manualmente, e usar o cliente HTTP favorito para solicitar um token e chamar uma API usando OAuth 2.0. Este caso utiliza o fluxo de credenciais do cliente com um JWT de chave privada. As etapas são:
- Gere o par de chaves pública/privada.
- Utilize o par de chaves pública/privada para gerar o JWT da chave privada.
- Solicitar o token de acesso
- Adicione o token de acesso à sua solicitação de API.
- Incorpore o OAuth ao seu sistema de aplicação.
1. Gere o par de chaves pública/privada.
Você pode gerar um par de chaves pública/privada seguindo estas instruções. O Admin Console do Okta pode gerar um par de chaves pública/privada para fins de teste, caso o senhor não deseje gerá-lo manualmente.
2. Gere a chave privada JWT.
Utilize o par de chaves pública/privada para criar o JWT da chave privada seguindo as instruções na documentação Implementar OAuth para Okta com um aplicativo de serviço. Nesta etapa, é mais importante entender como tudo funciona do que automatizar os passos. Por enquanto, o usuário pode armazenar o par de chaves pública/privada localmente, usar ferramentas instaladas em sua máquina e colar o JWKS contendo sua chave pública em um site gerador de JWT para testes.
3. Solicite o token de acesso.
Solicite o token de acesso usando sua chave privada JWT sem adicionar nenhum escopo, fazendo a solicitação HTTP em seu cliente HTTP preferido. O senhor deverá receber um erro ao usar o token de acesso sem o escopo adequado, mas testar erros e caminhos bem-sucedidos é uma boa prática. O token de acesso expira em algum momento, e o usuário verá a data de expiração na resposta do token de acesso. O token de acesso faz parte da resposta. O senhor usará a string inteira como token de acesso.
4. Adicione o token de acesso à sua solicitação de API.
Utilizando seu cliente HTTP, chame sua API usando o token de acesso. Você adicionará um cabeçalho de autorização e usará o esquema Bearer, portanto, sua chamada de API terá o seguinte cabeçalho, conforme mostrado abaixo:
Ao fazer a chamada à API, deverá receber como resposta um erro HTTP 403. Ótimo! Sucesso? Sim, um teste de caso de erro bem-sucedido. Agora o senhor sabe qual erro esperar caso ocorra um problema na configuração dos escopos. Vamos adicionar os escopos à solicitação do token de acesso e tentar novamente.
Desta vez, solicite seu token de acesso usando a chave privada JWT e adicione os escopos para a chamada da API. Utilize o token de acesso na chamada da API. O momento da verdade! O senhor deverá receber uma resposta positiva. O senhor saberá que há um erro de configuração se receber um erro 403 novamente. Caso isso aconteça, verifique novamente os escopos da solicitação e certifique-se de que o aplicativo OAuth 2.0 tenha os escopos que você está solicitando habilitados.
5. Adicione a autorização OAuth 2.0 ao seu sistema.
Agora que o senhor concluiu com sucesso a autorização OAuth 2.0 para uma chamada de servidor para serviço manualmente, pode incorporar aspectos dessas etapas ao seu sistema. Em um ambiente de desenvolvimento ou teste, por favor, tente usar o token de acesso. Será necessário alterar suas APIs para usar o cabeçalho de autorização com o formato do esquema Bearer e substituir o token de API estático existente pelo token de acesso gerado manualmente, para garantir que as chamadas de API funcionem sem automatizar as etapas para solicitar o token de acesso.
Quando o senhor tiver certeza de que seu sistema de API lida com o token de acesso corretamente, é hora de adicionar as etapas para solicitá-lo a partir do seu código. Sua infraestrutura tecnológica pode ter SDKs para auxiliar em pelo menos parte (ou em todas) as etapas da solicitação. Os SDKs de gerenciamento da Okta podem lidar com o handshake OAuth 2.0 em nome do cliente. Os usuários do Java Spring podem consultar a documentação do Spring Security, e os usuários do .NET Core podem consultar o Microsoft.AspNetCore.Authentication como exemplo. Lembre-se de testar seu trabalho ao longo do processo, tanto para o cenário ideal quanto para casos de erro e cenários como o tratamento correto da expiração do token de acesso.
Antes de implementar alterações em seu ambiente de produção, certifique-se de estar usando ferramentas de qualidade de produção para gerar o JWKS internamente e gerenciar sua chave privada com segurança.
Melhores práticas durante migrações de autorização de API
A transição imediata de tokens estáticos para não estáticos nem sempre é viável, especialmente em grandes organizações ou se você tiver muitas APIs para atualizar. Se o senhor ainda estiver usando tokens SSWS com o Okta, é recomendável mitigar os riscos até que possa migrar para o OAuth 2.0. As melhores práticas incluem:
- Implemente novas chamadas de API ou código usando OAuth 2.0.
- Siga o princípio do menor privilégio. Por exemplo:
- Não utilize contas pessoais para criar contas de serviço.
- Utilize uma função de administrador personalizada para contas de serviço, concedendo apenas as permissões essenciais.
- Utilize grupos e políticas de sessão globais para impedir logins interativos em contas de serviço.
Chamadas de API seguras com OAuth 2.0
A transição de tokens estáticos para o OAuth 2.0 não se trata apenas de adotar uma nova tecnologia, mas também de priorizar um ecossistema mais seguro, flexível e amigável para desenvolvedores. Embora os tokens estáticos tenham tido seu tempo e lugar, é evidente que o futuro reside em soluções OAuth 2.0 dinâmicas, centradas no usuário e seguras.
Lembre-se: com o avanço da tecnologia, manter-se atualizado e adaptar-se às melhores práticas não é apenas benéfico, é essencial. Migre para o OAuth 2.0 e embarque em uma jornada de desenvolvimento mais segura, simplificada e eficiente.
Próximos passos com OAuth 2.0
Caso o senhor ache este post interessante, talvez também goste destes outros.
- Selecionando a melhor autorização para suas integrações de API
- Adicione autenticação a qualquer aplicativo com o proxy OAuth2.
- OAuth para desenvolvedores Java
Consulte os guias para desenvolvedores de segurança de API da Okta para começar sua migração para o OAuth 2.0:
Configurar a demonstração de comprovação de posse
- Este guia explica como criar tokens de acesso com restrição de remetente, que são um mecanismo em nível de aplicação para evitar a repetição de tokens em diferentes pontos de extremidade.
- Este guia explica como interagir com as APIs do Okta usando tokens de acesso OAuth 2.0 com escopo. Configurar OAuth para Okta: aplicativo de serviço
- Este guia descreve a interação com as APIs do Okta usando tokens de acesso OAuth 2.0 com escopo para um aplicativo de serviço.
- Adicione autorização usando o Okta para proteger suas APIs. Ao concluir, terá um aplicativo de API REST seguro que valida as solicitações recebidas.
Integrar serviços de terceiros
- Este guia explica como configurar uma organização Okta para receber eventos de risco de um provedor terceirizado. Conexão segura de API entre organizações com OAuth 2.0
- Este guia descreve como configurar organizações Okta em modelo hub-and-spoke de forma segura para sincronizar usuários e grupos usando OAuth 2.0 em uma solução multi-tenant. Conecte o acesso à API da organização Okta a dados com escopo usando o fluxo de credenciais do cliente OAuth 2.0 para o aplicativo de integração Org2Org.
Configure a autenticação em vários níveis com valores ACR.
- Este guia explica como incluir o parâmetro acr_values em suas solicitações de autorização para aumentar a segurança do usuário final.
Para mais conteúdo interessante, siga @oktadev no X, encontre-nos no LinkedIn e inscreva-se no nosso canal do YouTube.
