Documentação do Oracle Cloud Infrastructure

Usando a Console para Adicionar Autenticação de Token e Políticas da Solicitação de Autorização

Adicione políticas de solicitação de autenticação e autorização a uma especificação da implantação da API usando a Console.

  1. Crie ou atualize uma implantação de API usando a Console, selecione a opção Criar implantação e informe detalhes na página Informações Básicas.

    Para obter mais informações, consulte Implantando uma API em um Gateway da API Criando uma Implantação de API e Updating an API Gateway.

  2. Selecione Próximo para exibir a página Autenticação.

  3. Selecione Autenticação Única para especificar que você deseja usar um único servidor de autenticação para todas as solicitações.

    Estas instruções pressupõem que você deseja usar um único servidor de autenticação. Como alternativa, se quiser usar vários servidores de autenticação, selecione Multi-Authentication e siga as instruções em Usando a Console para Adicionar Vários Servidores de Autenticação à mesma Implantação de API.

  4. Marque ou desmarque Ativar acesso anônimo para especificar se os usuários finais não autenticados (ou seja, anônimos) podem acessar rotas na implantação de API.

    Por padrão, essa opção não está selecionada. Se você nunca quiser que usuários anônimos possam acessar rotas, não selecione essa opção. Observe que, se você selecionar essa opção, também precisará especificar explicitamente cada rota para a qual o acesso anônimo é permitido, selecionando Anônimo como o Tipo de Autorização em cada política de autorização da rota.

  5. Selecione Autenticação de Token na lista de opções Tipo de autenticação e especifique:
    • Local do token: Se os tokens estão contidos em um cabeçalho de solicitação ou em um parâmetro de consulta.

    • Detalhes do token de autenticação: Dependendo se os tokens estão contidos em um cabeçalho de solicitação ou em um parâmetro de consulta, especifique:

      • Nome do cabeçalho do token: e Esquema de autenticação: Se os tokens estiverem contidos em um cabeçalho de solicitação, informe o nome do cabeçalho (por exemplo Authorization) e o esquema de autenticação de HTTP (somente Bearer é suportado no momento).
      • Nome do parâmetro token: Se os tokens estiverem contidos em um parâmetro da consulta, informe o nome do parâmetro da consulta.
  6. Especifique como deseja que o gateway de API valide tokens:

    1. Se você quiser que o gateway de API valide tokens JWT e tokens não JWT com um ponto final de introspecção do servidor de autorização do OAuth 2.0 usando credenciais do cliente (incluindo um segredo do cliente recuperado de um vault no serviço Vault), selecione Ponto final de introspecção do OAuth 2.0 na lista Tipo e especifique:

      • ID do Cliente: O ID do cliente a ser enviado para o ponto final de introspecção. Você obtém um ID de cliente criando e registrando um aplicativo cliente com o servidor de autorização. Por exemplo, 5hsti38yhy5j2a4tas455rsu6ru8yui3wrst4n1 . Consulte Pré-requisitos para Autenticação de Token.
      • Vault: O nome de um vault no serviço Vault que contém o segredo do cliente a ser enviado para o ponto final de introspecção, na lista de vaults no compartimento especificado. Você obtém um segredo do cliente criando e registrando um aplicativo cliente com o servidor de autorização. Consulte Pré-requisitos para Autenticação de Token.
      • Segredo do vault no <nome do compartimento>: O nome de um segredo do vault que contém o segredo do cliente a ser enviado para o ponto final de introspecção, na lista de segredos do vault no compartimento especificado.
      • Número da versão do segredo do vault: A versão do segredo do vault que contém o segredo do cliente a ser enviado para o ponto final de introspecção.
      • URL de Descoberta: O URL conhecido do servidor de autorização do qual o gateway de API deve obter pontos finais de metadados de autorização. Por exemplo, https://my-idp/oauth2/default/.well-known/openid-configuration.

        Observe que o URL deve ser roteável da sub-rede contendo o gateway da API no qual a API está implantada.

      • Duração máxima do cache em horas: O número de horas (entre 1 e 24) que o gateway de API deve armazenar em cache a resposta do ponto final da introspecção.
      • Diferença máxima do relógio em segundos: (Opcional) A diferença máxima de tempo entre os relógios do sistema do servidor de autorização que emitiu um token e o gateway de API. O valor informado aqui é levado em consideração quando o gateway da API valida um JWT para determinar se ele ainda é válido, usando a reivindicação não antes (nbf) (se presente) e a reivindicação de expiração (exp) no JWT. O mínimo (e padrão) é 0, o máximo é 120.
      • Desativar a verificação SSL: Se deve desativar a verificação SSL ao se comunicar com o servidor de autorização. Por padrão, essa opção não está selecionada. A Oracle recomenda não selecionar essa opção porque ela pode prejudicar a validação do token. O API Gateway confia em certificados de várias Autoridades de Certificado emitidas para o OCI IAM com Domínios de Identidade, Oracle Identity Cloud Service (IDCS), Auth0 e Okta.

    2. Se você quiser que o gateway de API valide JWTs recuperando chaves de verificação públicas do provedor da identidade no runtime, selecione JWKS Remoto na lista Tipo e especifique:

      • URI JWKS: O URI do qual recuperar o JWKS (JSON Web Key Set) a ser usado para verificar a assinatura em JWTs. Por exemplo, https://www.somejwksprovider.com/oauth2/v3/certs. Para obter mais informações sobre o URI a ser especificado, consulte Detalhes do Provedor de Identidades a Serem Usados para Reivindicações iss e aud e para o URI JWKS.

        Observe o seguinte:

        • O URI deve ser roteável da sub-rede que contém o gateway de API no qual a API está implantada.

        • Se o gateway de API falhar ao recuperar o JWKS, todas as solicitações para a implantação de API retornarão um código de resposta HTTP 500. Consulte o log de execução do gateway de API para obter mais informações sobre o erro (consulte Adicionando Registro em Log a Implantações de API).
        • Determinados parâmetros de chave devem estar presentes no JWKS para verificar a assinatura do JWT (consulte Parâmetros de Chave Necessários para Verificar Assinaturas de JWT).
        • O JWKS pode conter até dez chaves.
      • Duração máxima do cache em horas: O número de horas (entre 1 e 24) que o gateway de API deve armazenar o JWKS em cache após recuperá-lo.
      • Diferença máxima do relógio em segundos: (Opcional) A diferença máxima de tempo entre os relógios do sistema do servidor de autorização que emitiu um token e o gateway de API. O valor informado aqui é levado em consideração quando o gateway da API valida um JWT para determinar se ele ainda é válido, usando a reivindicação não antes (nbf) (se presente) e a reivindicação de expiração (exp) no JWT. O mínimo (e padrão) é 0, o máximo é 120.
      • Desativar a verificação SSL: se a verificação SSL deve ser desativada durante a comunicação com o provedor de identidades. Por padrão, essa opção não está selecionada. A Oracle recomenda não selecionar esta opção porque ela pode comprometer a validação do JWT. O API Gateway confia em certificados de várias Autoridades de Certificado emitidas para o OCI IAM com Domínios de Identidade, Oracle Identity Cloud Service (IDCS), Auth0 e Okta.

    3. Se quiser que o gateway da API valide JWTs com chaves públicas de verificação já emitidas por um provedor de identidades (ativando o gateway da API para verificar JWTs localmente sem precisar entrar em contato o provedor de identidades), selecione Chaves estáticas na lista Tipo e especifique até dez chaves estáticas:

      • ID da Chave: O identificador da chave estática usado para assinar o JWT. O valor deve corresponder à reivindicação kid no cabeçalho do JWT. Por exemplo, master_key.

      • Formato da chave: O formato da chave estática, como uma Chave Web JSON ou Chave Pública codificada em PEM.

        • Chave da Web JSON: se a chave estática for uma Chave da Web JSON, cole a chave neste campo.

          Por exemplo:

          {
  "kty": "RSA",
  "n": "0vx7agoebGc...KnqDKgw",
  "e": "AQAB",
  "alg": "RS256",
  "use": "sig"
}

          Observe que determinados parâmetros devem estar presentes na chave estática para verificar a assinatura do JWT (consulte Parâmetros Chave Necessários para Verificar Assinaturas de JWT). Observe também que RSA é atualmente o único tipo de chave suportado (kty).

        • Chave pública codificada por PEM: se a chave estática for uma chave pública codificada por PEM, cole-a neste campo. Por exemplo:

          -----BEGIN PUBLIC KEY-----
XsEiCeYgglwW/KAhSSNRVdD60QlXYMWHOhXzSFDZCLf1WXxKMZCiMvVrsBIzmFEXnFmcsO2mxwlL5/8qQudomoP+yycJ2gWPIgqsZcQRheJWxVC5ep0MeEHlvLnEvCi9utpAnjrsZCQ7plfZVPX7XORvezwqQhBfYzwA27M2FgOOs8DOIYfqQ1Ki3DMqEppFnjLcjgQtknbTlT7YgG6tzobwig8M2KIrPjJ0BmbJAFH
-----END PUBLIC KEY-----

          Observe que os marcadores -----BEGIN PUBLIC KEY----- e -----END PUBLIC KEY----- são obrigatórios.

      • Outra chave: Selecione para adicionar outras chaves (até um máximo de dez).
  7. (Opcional) Especifique detalhes adicionais para a validação do token JWT:

    1. Na seção Emissores, especifique valores permitidos na reivindicação (iss) do emissor de um JWT que está sendo usado para acessar a implantação de API:

      • Emissores permitidos: Especifique o URL (ou uma sequência de caracteres de texto) de um provedor de identidades permitido na reivindicação do emissor (iss) de um JWT a ser usado para acessar a implantação da API. Por exemplo, para permitir que um JWT emitido pelo OCI IAM com Domínios de Identidade seja usado para acessar a implantação de API, informe https://identity.oraclecloud.com/ . Consulte Detalhes do Provedor de Identidades a Serem Usados para Reivindicações iss e aud e para o URI JWKS.
      • Outro emissor: Selecione para adicionar outros provedores de identidade (até cinco no máximo).

    2. Na seção Públicos-alvo, especifique valores permitidos na reivindicação de público (aud) de um JWT que está sendo usado para acessar a implantação de API:

    3. Validação de reivindicações: (Opcional) Além dos valores das reivindicações de aud e iss do público-alvo que você já especificou, você pode especificar nomes e valores para uma ou mais reivindicações adicionais a serem validadas em JWT. Observe que todos os nomes e valores de chave informados são simplesmente tratados como strings e devem corresponder exatamente a nomes e valores no JWT. Correspondência de padrões e outros tipos de dados não são suportados.

      • Reivindicação é obrigatória: Especifique se a reivindicação no campo Chave da reivindicação deve ser incluída no JWT.
      • Chave de reivindicação: (Opcional) Especifique o nome de uma reivindicação que pode ser ou deve ser incluída em um JWT. Se a reivindicação precisar ser incluída no JWT, selecione Obrigatório. O nome da reivindicação especificado pode ser um nome de reivindicação reservado, como a reivindicação de assunto (sub) ou um nome de reivindicação personalizado emitido por um provedor de identidades específico.
      • Valores da reivindicação: (Opcional) Especifique um valor aceitável para a reivindicação no campo Chave da reivindicação. Selecione o sinal de mais (+) para informar outro valor aceitável. Se você especificar um ou mais valores aceitáveis para a reivindicação, o gateway de API validará se a reivindicação tem um dos valores especificados.

      Observe que é possível especificar uma reivindicação em um JWT sem especificar um valor para ele. Para isso, digite o nome da demanda no campo Chave da demanda, deixe o campo Valores da demanda em branco e defina A demanda é obrigatória, conforme apropriado.

  8. Especifique como deseja que o gateway de API trate uma resposta de autenticação com falha (retornada após uma tentativa malsucedida de validar um token ausente ou inválido) configurando uma política de falha de validação:
    1. Se você quiser que o gateway de API envie um código de status HTTP 401 e o cabeçalho WWW-Authenticate na resposta (a resposta padrão para um token ausente ou inválido), selecione Padrão (HTTP 401 Não Autorizado).

    2. Se quiser que o gateway de API use um fluxo de autorização do OpenID Connect para obter um novo token de acesso JWT, selecione OAuth 2.0. Observe que essa opção só estará disponível se você tiver selecionado Ponto final de introspecção do OAuth 2.0 na lista Tipo de Validação anteriormente. Especifique:

      • Escopos: Um ou mais escopos de acesso a serem incluídos em uma reivindicação scope enviada ao servidor de autorização. Para usar o fluxo de autorização do OpenID Connect, inclua openid como um dos escopos. Por exemplo, openid, email:read, profile.
      • Tipo de resposta: O tipo de resposta necessário do fluxo de autorização. Informe code como o tipo de resposta.
      • Caminho de redirecionamento de fallback: (opcional) Um caminho relativo na implantação de API atual para a qual redirecionar clientes de API se a solicitação original fosse uma solicitação PUT ou POST. Por exemplo, /home

        Se a solicitação original era uma solicitação GET, o processamento da solicitação é retomado com um novo token de acesso JWT, portanto, um caminho de fallback não é usado.

      • Caminho de log-out: (opcional) Um caminho relativo para um back-end de log-out na implantação de API atual. O caminho especificado deve corresponder ao caminho de rota definido para o back-end de log-out. Por exemplo, /revoke

        Um cliente de API pode chamar o back-end de log-out para revogar tokens. Uma chamada para o back-end de log-out pode incluir um URL pós-log-out como um parâmetro de consulta chamado postLogoutUrl. Consulte Adicionando Log-out como um Back-End do API Gateway.

      • Expiração da resposta em horas: (opcional) O período para armazenar em cache o token JWT gerado pelo fluxo de autorização. O default é 1 hora.
      • Usar credenciais do cliente de ponto final de introspecção do OAuth2: Especifique se deseja usar os mesmos detalhes do cliente especificados anteriormente para o ponto final de introspecção do OAuth 2.0 para obter um novo token de acesso JWT (que geralmente é o caso). Se você não quiser usar os detalhes especificados anteriormente, informe diferentes detalhes do cliente a serem usados para obter um novo token de acesso JWT do servidor de autorização, da seguinte forma:
        • ID do Cliente: O ID do cliente a ser enviado para o ponto final de introspecção. Por exemplo, 5hsti38yhy5j2a4tas455rsu6ru8yui3wrst4n1
        • Vault: O nome de um vault no serviço Vault que contém o segredo do cliente a ser enviado para o ponto final de introspecção, na lista de vaults no compartimento especificado.
        • Segredo do vault: O nome do segredo do vault que contém o segredo do cliente a ser enviado para o ponto final de introspecção, na lista de segredos do vault no compartimento especificado.
        • Número da versão do segredo do vault: A versão do segredo do vault que contém o segredo do cliente a ser enviado para o ponto final de introspecção.

      Opcionalmente, você pode optar por armazenar nos cookies os tokens e valores obtidos durante os fluxos de autorização do OpenID, selecionando Opções avançadas e selecionando:

      • Usar PKCE: (opcional) Especifique se deseja usar PKCE (Chave de Prova para Troca de Código) para segurança adicional. PKCE é uma extensão de segurança OAuth 2.0 para evitar CSRF (Cross-Site Request Forgery) e ataques de injeção de código de autorização. PKCE não substitui um segredo de cliente, e PKCE é recomendado mesmo se um segredo de cliente é usado. Para obter mais informações sobre PKCE, consulte a documentação do OAuth 2.0.
      • Usar cookies para sessão: (opcional) Especifique como armazenar tokens JWT recém-gerados como strings não legíveis por humanos no final de um fluxo de autorização do OpenID Connect:
        • Selecione esta opçã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. As solicitações subsequentes ao gateway de API (além das 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.
        • Não selecione esta opçã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.

        Consulte Observações sobre a Proteção contra CSRF (Cross-Site Request Forgery)

      • Use cookies para etapas intermediárias: (opcional) Especifique como armazenar valores de etapa intermediária do fluxo de autorização (por exemplo, parâmetros de solicitação). Selecione esta opção para armazenar os valores nos cookies do navegador. Desmarque esta opção para armazenar os valores com o gateway de API.
    3. Se você quiser personalizar a resposta para uma tentativa malsucedida de validar um token ausente ou inválido, selecione Resposta personalizada e especifique um código de status (e um corpo de mensagem opcional) para retornar ao cliente da API:
      • Código de status HTTP: Informe um código de status HTTP alternativo. Por exemplo, 500.
      • Corpo da mensagem: Informe um corpo da mensagem. Por exemplo, Unfortunately, authentication failed.O corpo da mensagem pode incluir qualquer variável de contexto (exceto request.body).
      • Opcionalmente, modifique os cabeçalhos da resposta que o gateway de API retorna ao cliente de API especificando uma política de resposta de transformação de cabeçalho. Para obter mais informações sobre políticas de transformação de cabeçalho, consulte Adicionando Políticas de Resposta de Transformação de Cabeçalho.

  9. Selecione Próximo para informar detalhes de rotas individuais na implantação de API na página Routes.

  10. Selecione Adicionar rota e especifique a primeira rota na implantação de API que mapeie um caminho e um ou mais métodos para um serviço de back-end:

    • Caminho: Um caminho para chamadas de API usando os métodos listados para o serviço de back-end. Observe que o caminho da rota que você especificar:

      • é relativo ao prefixo do caminho de implantação
      • deve ser precedido por uma barra ( / ) e pode ser apenas uma barra
      • pode conter várias barras (desde que elas não sejam adjacentes) e pode terminar com uma barra
      • pode incluir caracteres alfanuméricos maiúsculos e minúsculos
      • pode incluir os caracteres especiais $ - _ . + ! * ' ( ) , % ; : @ & =
      • pode incluir parâmetros e curingas (consulte Adicionando Parâmetros de Caminho e Curingas a Caminhos de Rota)
    • Métodos: Um ou mais métodos aceitos pelo serviço de back-end, separados por vírgulas. Por exemplo, GET, PUT.

    • Adicionar um único backend ou Adicionar vários backends: Se todas as solicitações devem ser roteadas para o mesmo back end ou para rotear solicitações para backends diferentes de acordo com a variável de contexto e as regras informadas.

      Estas instruções supõem que você deseja usar um único back-end; portanto, selecione Adicionar um único backend. Como alternativa, se você quiser usar back-ends diferentes, selecione Adicionar vários back-ends e siga as instruções em Usando a Console para Adicionar a Seleção de Back-End Dinâmico a uma Especificação de Implantação de API.

    • Tipo de backend: O tipo do serviço de back-end, como um dos seguintes:

  11. Para especificar uma política de autorização que se aplique a uma rota individual, selecione Mostrar políticas de solicitação de rota, selecione o botão Adicionar ao lado da Autorização e especifique:

    • Tipo de Autorização: Como conceder acesso à rota. Especifique:

      • Qualquer um:  Só concede acesso a usuários finais que foram autenticados com sucesso, desde que o JWT tenha uma reivindicação scope que inclua pelo menos um dos escopos de acesso especificados no campo Escopo Permitido. Nesse caso, a opção Ativar acesso anônimo da política da autenticação não tem efeito.
      • Anônimo: Concede acesso a todos os usuários finais, mesmo que eles não tenham sido autenticados com sucesso usando o JWT. Nesse caso, você deve ter selecionado a opção Ativar acesso anônimo da política.
      • Somente autenticação: Só concede acesso a usuários finais que foram autenticados com sucesso usando o JWT. Nesse caso, a opção Ativar acesso anônimo da política da autenticação não tem efeito.
    • Escopo Permitido: Se você tiver selecionado Qualquer um como o Tipo de Autorização, informe uma lista delimitada por vírgulas de uma ou mais strings que correspondem aos escopos de acesso no JWT. O acesso só será concedido a usuários finais autenticados com sucesso se o JWT tiver uma reivindicação scope que inclua um dos escopos de acesso especificados. Por exemplo, read:hello
    Observação

    Se você não incluir uma política de autorização para uma rota específica, o acesso será concedido como se tal política existisse e o Tipo de Autorização estivesse definido como Somente autenticação. Em outras palavras, independentemente da definição da opção Ativar acesso anônimo da diretiva de autenticação:

    • somente usuários finais autenticados podem acessar a rota
    • todos os usuários autenticados podem acessar a rota, independentemente dos escopos de acesso na reivindicação scope do JWT
    • usuários finais anônimos não podem acessar a rota
  12. Selecione Criar e Próximo para revisar os detalhes inseridos para a implantação de API.
  13. Selecione Criar ou Atualizar para criar ou atualizar a implantação de API.
  14. (Opcional) Confirme se a API foi implantada com êxito, chamando-a (consulte Chamando uma API Implantada em um Gateway de API).