Validando Tokens para Adicionar Autenticação e Autorização a Implantações de API

O que acontece durante a autenticação de token?

Quando um gateway de API recebe uma solicitação de um cliente de API e você especificou uma política de autenticação de token, o gateway de API localiza um token (por exemplo, em um cabeçalho de token) e usa esse token.

Você especifica como o gateway de API valida o token obtido definindo a política de validação da política de autenticação de token como um dos seguintes tipos:

• OAuth Ponto final de introspecção 2.0: Especifique esse tipo de política de validação se quiser que o gateway de API valide um token JWT ou não JWT com o ponto final de introspecção de um provedor de identidades. Você precisa especificar o URL de Descoberta do provedor de identidades do qual obter o ponto final de introspecção. Nesse caso, o gateway de API passa as credenciais do cliente (o id do cliente, juntamente com o segredo do cliente recuperado do serviço Vault) para o provedor de identidades para validar o token. O token é validado sem o uso de chaves públicas. Para tornar a validação futura mais rápida, você pode especificar que deseja que o gateway de API armazene em cache a resposta do ponto final de introspecção, por entre 1 hora (o padrão) e 24 horas. Se você estiver definindo a especificação de implantação de API em um arquivo JSON e quiser esse comportamento, inclua uma política de validação do tipo REMOTE_DISCOVERY.
• JWKS Remoto: Especifique esse tipo de política de validação se quiser que o gateway de API use chaves de verificação públicas recuperadas de um provedor de identidades no runtime para verificar um JWT. Nesse caso, o gateway de API entra em contato com o provedor de identidades para verificar o JWT. O provedor de identidades atua como o servidor de autorização. Se você estiver definindo a especificação de implantação de API em um arquivo JSON e quiser esse comportamento, inclua uma política de validação do tipo REMOTE_JWKS.
• Chaves estáticas: Especifique esse tipo de política de validação se quiser que o gateway de API use chaves de verificação públicas já emitidas por um provedor de identidades (conhecidas como 'chaves estáticas') para verificar um JWT. Nesse caso, o gateway de API pode verificar o JWT localmente no runtime sem precisar entrar em contato com o provedor de identidades. O resultado é uma validação de token mais rápida. Se você estiver definindo a especificação de implantação de API em um arquivo JSON e quiser esse comportamento, inclua uma política de validação do tipo STATIC_KEYS

Se a validação for bem-sucedida, o gateway de API roteará a solicitação para o ponto final de API apropriado.

Se a validação falhar devido a um token inválido ou ausente na solicitação original, você especificará o comportamento do gateway de API definindo a política de falha de validação da política de autenticação de token como um dos seguintes tipos:

• Padrão (HTTP 401 Não Autorizado): Especifique esse tipo de política de falha de validação se quiser que o gateway de API retorne uma resposta HTTP-401 ao cliente de API. Esta é a resposta padrão. Se você estiver definindo a especificação de implantação de API em um arquivo JSON e quiser esse comportamento, simplesmente não inclua uma política de falha de validação.
• Resposta personalizada: Especifique esse tipo de política de falha de validação se quiser que o gateway de API retorne uma resposta alternativa (uma resposta modificada) ao cliente de API, em vez de uma resposta HTTP-401. Se você estiver definindo a especificação de implantação de API em um arquivo JSON e quiser esse comportamento, inclua uma política de falha de validação do tipo MODIFY_RESPONSE.
• OAuth 2.0: Especifique esse tipo de política de falha de validação se quiser que o gateway de API obtenha um token JWT novo e válido do provedor de identidades para solicitações GET (tendo primeiro armazenado com segurança os parâmetros de consulta de solicitação originais). Para solicitações PUT e POST, você pode especificar um caminho relativo na implantação de API atual para o qual redirecionar clientes de API. Usando esse tipo de política de falha de validação, você também pode definir um back-end de log-out para remover quaisquer cookies de sessão associados, revogar tokens chamando o ponto final da sessão final do provedor de identidades e redirecionar para um URL pós-log-out permitido. Se você estiver definindo a especificação de implantação de API em um arquivo JSON e quiser esse comportamento, inclua uma política de falha de validação do tipo OAUTH2.

  Observe que as políticas de falha de validação do tipo OAuth 2.0 atualmente suportam apenas o fluxo de autorização do OpenID Connect e apenas a geração de token JWT (consulte Observações sobre OAuth 2.0 e OpenID Connect). No caso do fluxo de autorização do OpenID Connect, dois tokens denominados id_token (sempre codificados por JWT) e access_token (pode ser codificado por JWT) são retornados. O gateway de API salva os valores de token nas variáveis de contexto request.auth[id_token] e request.auth[access_token], juntamente com reivindicações personalizadas nas variáveis de contexto request.auth[id_token_claims][<claim-name>] e request.auth[access_token_claims][<claim-name>], respectivamente (consulte Adicionando Variáveis de Contexto a Políticas e Definições de Back-End HTTP). No recebimento do novo token JWT id_token, o gateway de API recupera os detalhes da solicitação e retoma o processamento da solicitação usando o token.

O local do qual o gateway de API obtém um token depende do tipo de política de validação (uma das pontos finais de introspecção OAuth 2.0, JWKS Remoto ou Chaves estáticas) e do tipo de política de falha de validação (uma das opções Padrão (HTTP 401 Não Autorizado), Resposta personalizada ou OAuth 2.0), da seguinte forma:

• Se você especificar uma política de validação do tipo OAuth 2.0 ponto final de introspecção e uma política de falha de validação do tipo OAuth 2.0, o gateway de API inicialmente tentará obter o token de um ou outro dos seguintes itens:
  • Se você selecionou a opção Usar cookies para sessão na política de falha de validação, em um cookie de sessão.
  • Caso contrário, a partir do cabeçalho X-APIGW-TOKEN na solicitação.

  Se o gateway de API não puder obter um token do local inicial, o gateway de API obterá o token do cabeçalho de solicitação ou do parâmetro de consulta especificado na política de autenticação de token.

  Se a validação do token for subsequentemente bem-sucedida e você tiver selecionado a opção Usar cookies para sessão, o gateway de API armazenará o token gerado como uma string não legível por humanos em um cookie de sessão. Se o cliente da API fizer uma solicitação subsequente, o token será obtido do cookie de sessão. Para evitar ataques de CSRF, quando o TOKEN gerado é armazenado em um cookie de sessão, o gateway de API também retorna um TOKEN CSRF em um cabeçalho de resposta de X-CSRF-TOKEN (consulte Observações sobre a Proteção de CSRF (Cross-Site Request Forgery)).

• Se você não especificar uma política de validação do tipo OAuth 2.0 ponto final de introspecção e uma política de falha de validação do tipo OAuth 2.0, o gateway de API obterá o token do cabeçalho da solicitação ou do parâmetro de consulta especificado na política de autenticação de token.

Observações sobre JWTs (JSON Web Tokens)

Os tokens que você usa para controlar o acesso a APIs geralmente são JWTs (JSON Web Tokens). Um JWT é um token de acesso baseado em JSON enviado em uma solicitação HTTP de um cliente de API para um recurso. Os JWTs são emitidos por provedores de identidade. O Gateway de API suporta o uso de qualquer provedor de identidades compatível com OAuth2, como OCI IAM com Domínios de Identidade, Oracle Identity Cloud Service (IDCS), Auth0 e Okta. Se um JWT for necessário para acessar um recurso, o recurso validará o JWT com um servidor de autorização usando uma chave de verificação pública correspondente, chamando um ponto final de validação no servidor de autorização ou usando uma chave de verificação local fornecida pelo servidor de autorização.

Um JWT compreende:

• Um cabeçalho, que identifica o tipo de token e o algoritmo criptográfico usado para gerar a assinatura.
• Um payload, contendo reivindicações sobre a identidade do usuário final, e as propriedades do próprio JWT. Uma reivindicação é um par de chave-valor, em que a chave corresponde ao nome da reivindicação. Recomenda-se um payload (embora não seja necessário) para conter determinadas reivindicações reservadas com nomes específicos, como tempo de expiração (exp), público-alvo (aud), emissor (iss) e não antes (nbf). Um payload também pode conter reivindicações personalizadas com nomes definidos pelo usuário.
• Uma assinatura, para validar a autenticidade do JWT (derivado pela codificação base64 do cabeçalho e do payload).

Ao usar JWTs para controlar o acesso a APIs, você pode especificar que as reivindicações reservadas no payload do JWT devem ter valores específicos antes que o gateway de API considere o JWT válido. Por padrão, os gateways de API validam JWTs usando as reivindicações de expiração (exp), público-alvo (aud) e emissor (iss), juntamente com a reivindicação não antes (nbf), se presente. Também é possível especificar valores aceitáveis para reivindicações personalizadas. Consulte Detalhes do Provedor de Identidades a Serem Usados para Reivindicações iss e aud e para o URI JWKS.

Quando um JWT foi validado, o gateway da API extrai reivindicações do payload do JWT como pares do valor da chave e as salva como registros na tabela do contexto request.auth para uso pela implantação de API. Por exemplo, como variáveis de contextos para uso em uma definição do backend HTTP (consulte Adicionando Variáveis do Contexto a Políticas e Definições do Backend HTTP). Se o payload do JWT contiver a reivindicação scope, você poderá usar os valores da reivindicação nas políticas de solicitação de autorização para rotas individuais para especificar as operações que um usuário final tem permissão para executar.

Observações sobre o OAuth 2.0 e o OpenID Connect

O protocolo OAuth 2.0 permite a recuperação segura de recursos seguros, protegendo as credenciais do cliente. OAuth 2.0 é um protocolo flexível e seguro que conta com SSL (Secure Sockets Layer) para garantir que os dados entre servidores Web e navegadores permaneçam privados. Embora o OAuth 2.0 seja diferente do JWT e usado para diferentes fins, o OAuth 2.0 e o JWT são compatíveis. Como o protocolo OAuth2 não especifica o formato de tokens, os JWTs podem ser incorporados ao uso de OAuth2. Para obter mais informações sobre o OAuth 2.0, consulte a documentação OAuth 2.0.

O OpenID Connect é uma camada de identidade simples sobre o protocolo OAuth 2.0. O uso do OpenID Connect permite que gateways de API verifiquem a identidade de um cliente de API com base na autenticação executada por um servidor de autorização. O OpenID Connect também permite que gateways de API obtenham informações básicas de perfil sobre o cliente de API. Para obter mais informações sobre o OpenID Connect, consulte a documentação do OpenID Connect.

Notas sobre a proteção contra falsificação de solicitações entre locais (CSRF)

Um invasor pode montar um ataque CSRF explorando a existência de um cookie de navegador para fazer com que um usuário envie um comando não intencional para um aplicativo web, como um gateway de API. Se o aplicativo determinar que o usuário já foi autenticado com sucesso por causa da existência do cookie do navegador, o aplicativo executará o comando com consequências potencialmente prejudiciais.

Ao definir uma política de validação do tipo OAuth 2.0 ponto final de introspecção e uma política de falha de validação do tipo OAuth 2.0, você especifica como um gateway de API armazena um novo token JWT obtido usando o fluxo de autorização do OpenID Connect:

• Selecione a opção Usar cookies para sessão se quiser armazenar o novo token JWT em um cookie de sessão. Para evitar possíveis ataques de CSRF, quando o gateway de API armazena o TOKEN em um cookie de sessão, ele também retorna um TOKEN CSRF em um cabeçalho de resposta X-CSRF-TOKEN. Solicitações de mutação subsequentes para o gateway de API (como solicitações POST, PUT e DELETE, mas não solicitações GET) devem incluir o TOKEN CSRF em um cabeçalho de solicitação X-CSRF-TOKEN, além do TOKEN JWT no cookie de sessão que é incluído automaticamente.

  Observe que o gateway de API também armazena o token CSRF na variável de contexto request.auth[apigw_csrf_token]. Se o cliente da API não conseguir ler o cabeçalho de resposta inicial do X-CSRF-TOKEN por algum motivo, você poderá incluir a variável de contexto request.auth[apigw_csrf_token] em uma política de resposta de transformação de cabeçalho para adicionar um cabeçalho de resposta contendo o token CSRF a cada resposta retornada ao cliente da API. Essa abordagem garante que o cliente da API possa extrair com sucesso o token CSRF do cabeçalho de resposta para inclusão nos cabeçalhos de solicitação de mutação X-CSRF-TOKEN subsequentes que ele envia para o gateway de API. Veja um exemplo de política de resposta de transformação de cabeçalho adequada:

  "responsePolicies": {
          "headerTransformations": {
            "setHeaders": {
              "items": [
                {
                  "name": "MY-CSRF-TOKEN",
                  "values": ["${request.auth[apigw_csrf_token]}"],
                  "ifExists": "OVERWRITE"              }
              ]
            }
          }
        }

  Para obter mais informações sobre políticas de resposta da transformação de cabeçalho, consulte Adicionando Políticas da Resposta da Transformação de Cabeçalho.

• Não selecione a opção Usar cookies para sessão se não quiser armazenar o novo token JWT em um cookie de sessão. Em vez disso, o gateway de API retorna um TOKEN não legível por humanos em um cabeçalho de resposta X-APIGW-TOKEN. As solicitações subsequentes ao gateway de API devem incluir o mesmo TOKEN em um cabeçalho de solicitação X-APIGW-TOKEN.

Para obter mais informações sobre CSRF, pesquise on-line.

Observações sobre o uso de políticas de solicitação JWT_AUTHENTICATION

Em releases anteriores, talvez você tenha criado políticas de solicitação de autenticação do tipo JWT_AUTHENTICATION para usar JWTs para autenticação.

Se você estiver criando novas políticas de solicitação de autenticação para usar JWTs, agora recomendamos que crie políticas de solicitação de autenticação do tipo TOKEN_AUTHENTICATION (consulte Usando a Console para Adicionar Políticas de Solicitação de Autorização e Autenticação de Token e Editando um Arquivo JSON para Adicionar Políticas de Solicitação de Autorização e Autenticação de Token). Também recomendamos migrar as políticas de solicitação JWT_AUTHENTICATION existentes para as políticas TOKEN_AUTHENTICATION.

Observe que as políticas de solicitação JWT_AUTHENTICATION existentes ainda são suportadas. Observe também que, embora você possa criar novas políticas de solicitação JWT_AUTHENTICATION (conforme descrito nas instruções originais na seção Usando uma Política de Solicitação de Autenticação JWT_AUTHENTICATION (não mais recomendada)), recomendamos que você crie políticas de solicitação de autenticação do tipo TOKEN_AUTHENTICATION.