Adicionando Políticas de Solicitação de Autenticação e Autorização

Para adicionar políticas de solicitação de autenticação e autorização para tokens de acesso com vários argumentos a uma especificação de implantação de API usando a Console:

1. Crie ou atualize uma implantação de API usando a Console. Selecione a opção Totalmente Nova e insira os detalhes na página Informações Básicas.

   Para obter mais informações, consulte Implantando uma API em um Gateway de API por meio da Criação de uma Implantação de API e Atualizando um Gateway de API.

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 você quiser usar vários servidores de autenticação, selecione Multiautenticação 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 a caixa de seleção 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 Função do autorizador na lista de opções Tipo de autenticação.
6. Especifique a função de autorizador de multi-argumento a ser usada para autenticar o token de acesso de multi-argumento:
   • Aplicativo Oracle Functions no <compartment-name>: O nome do aplicativo no OCI Functions que contém a função de autorizador. Você pode selecionar um aplicativo de outro compartimento.
   • Nome da Função: O nome da função de autorizador no OCI Functions.
7. Selecione Função de autorizador de vários argumentos para especificar que você deseja passar um ou mais elementos de uma solicitação como token de acesso a uma função de autorizador que pode aceitar tokens de acesso de vários argumentos.
8. No painel Argumentos de função, especifique uma ou mais variáveis de contexto que forneçam valores para passar à função de autorizador como argumentos com nomes de argumento informados:
   1. Especifique uma variável de contexto fornecendo um valor a ser passado para a função de autorizador como um argumento:
      • Tabela de contexto: Selecione na lista a tabela de contexto que contém a variável de contexto:
        • Tabela de contexto request.query, contendo nomes e valores de parâmetros de consulta incluídos na solicitação
        • Tabela de contexto request.headers, contendo nomes e valores de cabeçalho incluídos na solicitação
        • Tabela de contexto request.cert, contendo uma versão codificada em Base64 do certificado apresentada por um cliente de API e validada com sucesso durante um handshake mTLS
        • Tabela de contexto request.host, contendo o nome do host para o qual a solicitação foi enviada (extraída do campo de cabeçalho Host na solicitação)
        • Tabela de contexto request.body, contendo o corpo da solicitação
      • Nome do cabeçalho ou Nome do parâmetro de consulta: Se você tiver selecionado a tabela de contexto request.headers ou request.params, informe o nome do cabeçalho ou do parâmetro de consulta que deseja transmitir à função de autorizador. Por exemplo, X-Api-Key, state.
      • Nome do argumento: Informe o nome do argumento ao qual atribuir o valor da variável de contexto. O argumento é passado para a função de autorizador. O nome do argumento informado deve corresponder ao nome do argumento que a função de autorizador espera receber.
   2. Especifique variáveis e argumentos de contexto adicionais conforme necessário (se necessário, selecione Outro argumento).

9. Opcionalmente, personalize como armazenar em cache a resposta de uma função de autorizador com vários argumentos:

   1. Selecione Mostrar opções avançadas.

      O painel Cache de resultados de função mostra quais argumentos estão presentes na chave de cache. A chave de cache identifica exclusivamente a resposta armazenada em cache retornada pela função de autorizador, usando argumentos e valores de argumento informados na solicitação de autenticação original. Por padrão, todos os argumentos e valores de argumentos (exceto um argumento com um valor da tabela de contexto request.body) que você especificou para passar à função de autorizador são usados para criar a chave de cache.

   2. Para adicionar ou remover argumentos da chave de cache, selecione Editar.
   3. Marque ou desmarque os argumentos passados para a função de autorizador para incluí-los ou excluí-los da chave de cache.

   Consulte Observações sobre o Armazenamento em Cache dos Resultados da Função do Autorizador de Vários Argumentos.

10. Opcionalmente, personalize como tratar uma resposta de autenticação com falha de uma função de autorizador com vários argumentos configurando uma política de falha de validação:

    1. Selecione Mostrar opções avançadas.

       O painel Resposta personalizada para autenticação com falha mostra o código de status HTTP e o corpo da mensagem a serem retornados ao cliente da API se a função de autorizador não puder autenticar a solicitação. Por padrão, o gateway de API envia um código de status HTTP 401 e o cabeçalho WWW-Authenticate na resposta. Consulte Observações sobre Políticas de Falha de Validação e o Tratamento de Respostas de Autenticação com Falha das Funções de Autorizador de Vários Argumentos.

    2. Especifique um código de status (e um corpo de mensagem opcional) para retornar ao cliente de API se a função de autorizador não puder autenticar a solicitação:
       • Código de status HTTP: Informe um código de status HTTP alternativo (por exemplo, 500). Como alternativa, você pode incluir uma variável de contexto para retornar o código retornado pela função de autorizador. Por exemplo, se a função de autorizador retornar um código de resposta no parâmetro responseCode, especifique request.auth[responseCode].
       • 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). Por exemplo, Unfortunately, authentication failed ${request.auth[my-auth-variable]}.

    3. Opcionalmente, modifique os cabeçalhos da resposta que o gateway de API retorna ao cliente de API selecionando Mostrar opções avançadas e especificando uma política de resposta de transformação de cabeçalho:

       • Para limitar os cabeçalhos incluídos em uma resposta, especifique:

         • Ação: Filtrar.
         • Tipo: Bloquear para remover da resposta os cabeçalhos listados explicitamente ou Permitir para permitir na resposta apenas os cabeçalhos listados explicitamente (quaisquer outros cabeçalhos são removidos da resposta).
         • Nomes de Cabeçalho: A lista de cabeçalhos a serem removidos da reposta ou permitidos na reposta (dependendo da definição de Tipo). Os nomes especificados não diferenciam maiúsculas de minúsculas e não devem ser incluídos em nenhuma outra política de resposta de transformação para a rota (com exceção dos itens filtrados conforme permitido). Por exemplo, User-Agent.

       • Para alterar o nome de um cabeçalho incluído em uma resposta (mantendo seu valor original), especifique:

         • Ação: Renomear.
         • Nome do cabeçalho: O nome original do cabeçalho que você está renomeando. O nome especificado não faz distinção entre maiúsculas e minúsculas e não deve ser incluído em nenhuma outra política de resposta de transformação para a rota. Por exemplo, X-Username.
         • Novo nome de cabeçalho: O novo nome do cabeçalho que você está renomeando. O nome especificado não faz distinção entre maiúsculas e minúsculas (a capitalização pode ser ignorada) e não deve ser incluído em nenhuma outra política de resposta de transformação para a rota (com exceção dos itens nas listas ALLOW). Por exemplo, X-User-ID.

       • Para adicionar um novo cabeçalho a uma resposta (ou para alterar ou manter os valores de um cabeçalho existente já incluído em uma resposta), especifique:

         • Ação: Definir.

         • Comportamento: Se o cabeçalho já existir, especifique o que fazer com o valor existente do cabeçalho:

           • Substituir, para substituir o valor existente do cabeçalho pelo valor especificado.
           • Anexar, para anexar o valor especificado ao valor existente do cabeçalho.
           • Ignorar, para manter o valor existente do cabeçalho.
         • Nome do cabeçalho: O nome do cabeçalho a ser adicionado à resposta (ou para alterar o valor de). O nome especificado não faz distinção entre maiúsculas e minúsculas e não deve ser incluído em nenhuma outra política de resposta de transformação para a rota (com exceção dos itens filtrados conforme permitido). Por exemplo, X-Api-Key.
         • Valores: O valor do novo cabeçalho (ou o valor a ser substituído ou acrescentado ao valor de um cabeçalho existente, dependendo da definição de Comportamento). Você pode especificar vários valores. O valor especificado pode ser uma string simples ou pode incluir variáveis de contexto (exceto request.body) entre delimitadores ${...}. Por exemplo, "value": "zyx987wvu654tsu321".

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

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

12. Na seção Rota 1, especifique a primeira rota na implantação de API que mapeia 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 diferentes back-ends de acordo com a variável de contexto e as regras informadas.

      Essas instruções pressupõ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 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 backend, como:
      • HTTP: Para um back-end de HTTP, você também precisa especificar um URL, detalhes de timeout e se deve desativar a verificação SSL (consulte Adicionando um URL HTTP ou HTTPS como um Back-End do Serviço API Gateway).
      • Oracle Functions: Para um back-end do OCI Functions, você também precisa especificar o aplicativo e a função (consulte Adicionando uma Função no OCI Functions como um Back-End do Serviço API Gateway).
      • Resposta Padrão: Para um back-end de resposta padrão, você também precisa especificar o código de status HTTP, o conteúdo no corpo da resposta e um ou mais campos de cabeçalho HTTP (consulte Adicionando Respostas Padrão como um Back-End do Serviço API Gateway).

13. 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 de 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 a função de autorizador também tenha retornado um dos escopos de acesso especificados no campo Escopo Permitido. Nesse caso, a opção Ativar Acesso Anônimo da política de 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 pela função de autorizador. Nesse caso, você deve ter selecionado a opção Ativar Acesso Anônimo da política de autenticação.
      • Somente autenticação: Só concede acesso a usuários finais que foram autenticados com sucesso pela função de autorizador. Nesse caso, a opção Ativar Acesso Anônimo da política de autenticação não tem efeito.
    • Escopo Permitido: Se você tiver selecionado Qualquer um como o Tipo de Autorização, insira uma lista delimitada por vírgulas de uma ou mais strings que correspondam aos escopos de acesso retornados pela função de autorizador. O acesso só será concedido aos usuários finais que foram autenticados com sucesso se a função de autorizador retornar 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 política de autenticação:

    • somente usuários finais autenticados podem acessar a rota
    • todos os usuários finais autenticados podem acessar a rota, independentemente dos escopos de acesso retornados pela função de autorizador
    • usuários finais anônimos não podem acessar a rota
14. Selecione Aplicar Alterações e, em seguida, selecione Próximo para revisar os detalhes informados para a implantação de API.
15. Selecione Criar ou Salvar Alterações para criar ou atualizar a implantação de API.
16. (Opcional) Confirme se a API foi implantada com êxito, chamando-a (consulte Chamando uma API Implantada em um Gateway de API).

Para adicionar políticas de solicitação de autenticação e autorização para tokens de acesso com vários argumentos a uma especificação de implantação de API em um arquivo JSON:

1. Usando seu editor de JSON preferido, edite a especificação de implantação de API existente à qual você deseja adicionar a funcionalidade de autenticação e autorização ou crie uma nova especificação de implantação de API (consulte Criando uma Especificação de Implantação de API).

   No mínimo, a especificação de implantação de API incluirá uma seção routes contendo:

   • Um caminho. Por exemplo, /hello
   • Um ou mais métodos. Por exemplo, GET
   • Uma definição de um back-end. Por exemplo, um URL ou o OCID de uma função no OCI Functions.

   Por exemplo, a seguinte especificação básica de implantação de API define uma função simples sem servidor Hello World no OCI Functions como um único back-end:

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         }
       }
     ]
   }

2. Adicione uma política de solicitação authentication que se aplique a todas as rotas na especificação de implantação de API:

   1. Insira uma seção requestPolicies antes da seção routes, se ainda não existir uma. Por exemplo:

      
      {
        "requestPolicies": {},
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
               "type": "ORACLE_FUNCTIONS_BACKEND",
               "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            }
          }
        ]
      }

   2. Adicione a seguinte política authentication à nova seção requestPolicies.

      {
        "requestPolicies": {
          "authentication": {
            "type": "<type-value>",
            "isAnonymousAccessAllowed": <true|false>,
            "functionId": "<function-ocid>",
            "parameters": {
              "<argument-n>": "<context-variable>",
              "<argument-n>": "<context-variable>",
              "<argument-n>": "<context-variable>"
            },
            "cacheKey": [
              "<cache-key-argument-n>", "<cache-key-argument-n>"
            ]
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            }
          }
        ]
      }

      em que:

      • <type-value> é o tipo de autenticação. Para usar uma função de autorizador para autenticação, especifique CUSTOM_AUTHENTICATION.
      • "isAnonymousAccessAllowed": <true|false> indica opcionalmente se usuários finais não autenticados (ou seja, anônimos) podem acessar rotas na especificação de implantação de API. Se você nunca quiser que usuários finais anônimos possam acessar rotas, defina essa propriedade como false. Se você não incluir essa propriedade na política authentication, o padrão false será usado. Observe que, se você não incluir essa propriedade e defini-la como true, também precisará especificar explicitamente cada rota para a qual o acesso anônimo é permitido, definindo a propriedade type como "ANONYMOUS" na política authorization de cada rota.
      • <function-ocid> é o OCID da função de autorizador implantada no OCI Functions.
      • <argument-n> é o nome do argumento ao qual atribuir o valor de uma e somente uma variável de contexto. O argumento é transmitido para a função de autorizador. O nome do argumento informado deve corresponder ao nome do argumento que a função de autorizador espera receber. É possível incluir vários pares de variáveis de contexto de argumento.
      • <context-variable> é uma variável de contexto cujo valor você deseja designar ao argumento correspondente. <context-variable> deve estar no formato <context-table-name> ou <context-table-name>[<key>], em que <context-table-name> é um dos seguintes:
        • request.query, uma tabela de contexto que contém nomes e valores de parâmetros de consulta incluídos na solicitação. Se quiser especificar um parâmetro de consulta, especifique a tabela de contexto request.query e o nome do parâmetro de consulta como chave no formato request.query[<query-parameter-name>]. Por exemplo, request.query[state]
        • request.headers, uma tabela de contexto que contém nomes e valores de cabeçalho incluídos na solicitação. Se quiser especificar um cabeçalho, especifique a tabela de contexto request.headers e o nome do cabeçalho como a chave no formato request.headers[<header-name>]. Por exemplo, request.headers[X-Api-Key]
        • Tabela de contexto request.cert, contendo uma versão codificada em Base64 do certificado apresentada por um cliente de API e validada com sucesso durante um handshake mTLS
        • request.host, uma tabela de contexto contendo o nome do host para o qual a solicitação foi enviada (extraída do campo de cabeçalho Host na solicitação)
        • request.body, uma tabela de contexto que contém o corpo da solicitação.
      • "cacheKey": ["<cache-key-argument-n>", "<cache-key-argument-n>"] opcionalmente restringe a chave de cache para usar apenas os argumentos especificados. A chave de cache identifica exclusivamente a resposta em cache retornada da função de autorizador, usando argumentos e valores de argumentos informados na solicitação de autenticação original. Por padrão, todos os argumentos e valores de argumentos (exceto para um argumento com um valor da tabela de contexto request.body) na lista parameters: {…} são usados para criar a chave de cache. Um argumento especificado para <cache-key-argument-n> deve ser um dos argumentos na lista parameters: {…}. Consulte Observações sobre o Armazenamento em Cache dos Resultados da Função do Autorizador de Vários Argumentos.
   3. Opcionalmente, adicione um validationFailurePolicy à seção de política authentication:

      {
        "requestPolicies": {
          "authentication": {
            "type": "<type-value>",
            "isAnonymousAccessAllowed": <true|false>,
            "functionId": "<function-ocid>",
            "parameters": {
              "<argument-n>": "<context-variable>",
              "<argument-n>": "<context-variable>",
              "<argument-n>": "<context-variable>"
            },
            "cacheKey": [
              "<cache-key-argument-n>", "<cache-key-argument-n>"
            ],
            "validationFailurePolicy": {
              "type": "MODIFY_RESPONSE",
              "responseCode": "<alternative-response-code>",
              "responseMessage": "<custom-message-body>",
              "responseTransformations": {
                "headerTransformations": {
                  <valid-header-transformation-response-policy>
                }
              }
            }
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            }
          }
        ]
      }

      em que:

      • "validationFailurePolicy": {…} opcionalmente permite que você altere o código de status HTTP, o corpo da mensagem e os cabeçalhos na resposta ao cliente da API se a função de autorizador não puder autenticar uma solicitação. Por padrão, o gateway de API envia um código de status HTTP 401 e o cabeçalho WWW-Authenticate na resposta. Consulte Observações sobre Políticas de Falha de Validação e o Tratamento de Respostas de Autenticação com Falha das Funções de Autorizador com Vários Argumentos.
      • <policy-type> é o tipo de política de falha de validação. Para modificar a resposta, especifique MODIFY_RESPONSE.
      • "responseCode": "<alternative-response-code>" especifica um código de status HTTP alternativo. Por exemplo, "responseCode": "500". Como alternativa, você pode incluir uma variável de contexto para retornar o código retornado pela função de autorizador. Por exemplo, se a função de autorizador retornar um código de resposta no parâmetro responseCode, especifique "request.auth[responseCode]".
      • "responseMessage": "<custom-message-body>" especifica o conteúdo a ser incluído no corpo da mensagem. Por exemplo, "responseMessage": "Unfortunately, authentication failed.". O corpo da mensagem pode incluir qualquer variável de contexto (exceto request.body). Por exemplo, "responseMessage": "Unfortunately, authentication failed ${request.auth[my-auth-variable]}".
      • "headerTransformations": {<valid-header-transformation-response-policy>} é uma política de resposta de transformação de cabeçalho válida. Consulte Editando um arquivo JSON para adicionar políticas de resposta de transformação de cabeçalho.

3. Adicione uma política de solicitação authorization para cada rota na especificação de implantação de API:

   1. Insira uma seção requestPolicies após a primeira seção backend da rota, se ainda não existir. Por exemplo:

      
      {
        "requestPolicies": {
          "authentication": {
            "type": "CUSTOM_AUTHENTICATION",
            .
            .
            .
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
               "type": "ORACLE_FUNCTIONS_BACKEND",
               "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            },
            "requestPolicies": {}
          }
        ]
      }

   2. Adicione a seguinte política authorization à seção requestPolicies:

      {
        "requestPolicies": {
          "authentication": {
            "type": "CUSTOM_AUTHENTICATION",
            .
            .
            .
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            },
            "requestPolicies": {
              "authorization": {
                "type": <"AUTHENTICATION_ONLY"|"ANY_OF"|"ANONYMOUS">, 
                "allowedScope": [ "<scope>" ]
              }
            }
          }
        ]
      }

      em que:

      • "type": <"AUTHENTICATION_ONLY"|"ANY_OF"|"ANONYMOUS"> indica como conceder acesso à rota:

        • "AUTHENTICATION_ONLY": Só concede acesso a usuários finais que foram autenticados com sucesso. Nesse caso, a propriedade "isAnonymousAccessAllowed" na política authentication da especificação de implantação de API não tem efeito.
        • "ANY_OF": Só concede acesso a usuários finais que foram autenticados com sucesso, desde que a função de autorizador também tenha retornado um dos escopos de acesso especificados na propriedade allowedScope. Nesse caso, a propriedade "isAnonymousAccessAllowed" na política authentication da especificação de implantação de API não tem efeito.
        • "ANONYMOUS":  Concede acesso a todos os usuários finais, mesmo que eles não tenham sido autenticados com sucesso. Nesse caso, você deve definir explicitamente a propriedade "isAnonymousAccessAllowed" como true na política authentication da especificação de implantação de API.
      • "allowedScope": [ "<scope>" ] é uma lista delimitada por vírgulas de uma ou mais strings que correspondem aos escopos de acesso retornados pela função de autorizador. Nesse caso, você deve definir a propriedade type como "ANY_OF" (a propriedade "allowedScope" será ignorada se a propriedade type estiver definida como "AUTHENTICATION_ONLY" ou "ANONYMOUS"). Observe também que, se você especificar mais de um escopo, o acesso à rota será concedido se qualquer um dos escopos especificados for retornado pela função de autorizador.

      Por exemplo, a política de solicitação a seguir define uma rota /hello que só permite que usuários finais autenticados com o escopo read:hello a acessem:

      {
        "requestPolicies": {
          "authentication": {
            "type": "CUSTOM_AUTHENTICATION",
            .
            .
            .
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            },
            "requestPolicies": {
              "authorization": {
                "type": "ANY_OF",
                "allowedScope": [ "read:hello" ]
              }
            }
          }
        ]
      }

   3. Adicione uma política de solicitação authorization para todas as rotas restantes na especificação de implantação de API.
   Observação
   
   

   Se você não incluir uma política authorization para uma rota específica, o acesso será concedido como se tal política não existisse e a propriedade type estivesse definida como "AUTHENTICATION_ONLY". Em outras palavras, independentemente da definição da propriedade isAnonymousAccessAllowed na política authentication da especificação de implantação de API:

   • somente usuários finais autenticados podem acessar a rota
   • todos os usuários finais autenticados podem acessar a rota, independentemente dos escopos de acesso retornados pela função de autorizador
   • usuários finais anônimos não podem acessar a rota
4. Salve o arquivo JSON que contém a especificação de implantação de API.

5. Use a especificação de implantação de API ao criar ou atualizar uma implantação de API das seguintes formas:

   • especificando o arquivo JSON na Console quando você selecionar a opção Carregar uma API existente
   • especificando o arquivo JSON em uma solicitação à API REST do serviço API Gateway

   Para obter mais informações, consulte Implantando uma API em um Gateway de API por meio da Criação de uma Implantação de API e Atualizando um Gateway de API.

6. (Opcional) Confirme se a API foi implantada com êxito, chamando-a (consulte Chamando uma API Implantada em um Gateway de API).

A seguinte especificação de implantação de API define:

• Uma política de solicitação de autenticação que chama uma função de autorizador de vários argumentos para executar a autenticação.
• Uma política de solicitação de autorização que especifica o que os usuários finais autenticados podem fazer.

{
  "requestPolicies": {
    "authentication": {
      "type": "CUSTOM_AUTHENTICATION",
      "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaac2______kg6fq",
      "isAnonymousAccessAllowed": true,
      "parameters": {
        "xapikey": "request.headers[X-Api-Key]",
        "referer": "request.headers[Referer]",
        "state": "request.query[state]",
        "city": "request.query[city]",
        "cert": "request.cert",
        "body": "request.body",
        "host": "request.host"
        },
      "cacheKey": [
        "xapikey", "referer"
        ],
      "validationFailurePolicy": {
        "type": "MODIFY_RESPONSE",
        "responseCode": "request.auth[responseCode]",
        "responseMessage": "Unfortunately, authentication failed.",
        "responseTransformations": {
        "headerTransformations": {
          "setHeaders": {
            "items": [
              {
                "name": "Location",
                "values": [
                  "${request.auth[location]}"
                  ]
                }
              ]
            },
          "filterHeaders": {
            "type": "BLOCK",
            "items": [
              {
                "name": "topSecret"
                }
              ]
            }
          }
        }
      }
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "authorization": {
          "type": "ANY_OF",
          "allowedScope": [ "read:hello" ]
        }
      }
    }
  ]
}

A política de solicitação de autenticação nesta especificação de implantação de API:

• Especifica a função de autorizador de vários argumentos a ser chamada para executar a autenticação e define os argumentos xapikey, referer, state, city, cert, body e host a serem passados para a função de autorizador. Os valores desses argumentos são obtidos de variáveis de contexto que têm valores da solicitação original.
• Define uma chave de cache personalizada para identificar exclusivamente a resposta em cache retornada da função de autorizador. Em vez de usar a chave de cache padrão (que inclui todos os argumentos enviados à função de autorizador e é recomendado), essa política de solicitação de autenticação especifica que a chave de cache deve incluir apenas os valores dos argumentos xapikey e referrer passados para a função de autorizador.
• Inclui uma política de falha de validação que modifica a resposta de falha de validação padrão para substituir o código de status HTTP 401 padrão pelo valor da variável de contexto request.auth[responseCode]. A variável de contexto request.auth[responseCode] tem o valor de um parâmetro de autenticação (nesse caso, chamado responseCode) retornado pela função de autorizador. Da mesma forma, a mensagem de falha de validação padrão é substituída por uma string de mensagem personalizada ("Unfortunately, authentication failed.").
• Inclui uma política de solicitação de transformação de cabeçalho na política de falha de validação que adiciona o cabeçalho location à resposta de falha de validação. O cabeçalho location recebe o valor da variável de contexto request.auth[location], que tem o valor de um parâmetro de autenticação (neste caso, chamado location) retornado pela função de autorizador. A política de solicitação de transformação de cabeçalho também remove cabeçalhos chamados topSecret da resposta.

A política de solicitação de autorização nesta especificação de implantação de API só permite que usuários finais autenticados pela função de autorizador e com o escopo read:hello acessem a rota /hello.

Para adicionar políticas de solicitação de autenticação e autorização para tokens de acesso de argumento único a uma especificação de implantação de API usando a Console:

1. Crie ou atualize uma implantação de API usando a Console. Selecione a opção Totalmente Nova e insira os detalhes na página Informações Básicas.

   Para obter mais informações, consulte Implantando uma API em um Gateway de API por meio da Criação de uma Implantação de API e Atualizando um Gateway de API.

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 você quiser usar vários servidores de autenticação, selecione Multiautenticação 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 a caixa de seleção 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 Função do autorizador na lista de opções Tipo de autenticação.
6. Especifique a função de autorizador de argumento único a ser usada para autenticar o token de acesso de argumento único:
   • Aplicativo Oracle Functions no <compartment-name>: O nome do aplicativo no OCI Functions que contém a função de autorizador. Você pode selecionar um aplicativo de outro compartimento.
   • Nome da Função: O nome da função de autorizador no OCI Functions.
7. Selecione Função de autorizador de argumento único para especificar que você deseja passar um token de acesso de argumento único em um cabeçalho ou parâmetro de consulta para uma função de autorizador de argumento único.
8. No painel Token de acesso, identifique o token de acesso a ser usado para autenticação:
   • Local do token: Selecione Cabeçalho ou Parâmetro de Consulta para especificar o local do token de acesso na solicitação.
   • Nome do cabeçalho do token ou Nome do Parâmetro do Token: Dependendo do local do token de acesso, informe o nome do cabeçalho ou do parâmetro de consulta que contém o token de acesso.

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

10. Na seção Rota 1, especifique a primeira rota na implantação de API que mapeia 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 diferentes back-ends de acordo com a variável de contexto e as regras informadas.

      Essas instruções pressupõ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 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 backend, como:
      • HTTP: Para um back-end de HTTP, você também precisa especificar um URL, detalhes de timeout e se deve desativar a verificação SSL (consulte Adicionando um URL HTTP ou HTTPS como um Back-End do Serviço API Gateway).
      • Oracle Functions: Para um back-end do OCI Functions, você também precisa especificar o aplicativo e a função (consulte Adicionando uma Função no OCI Functions como um Back-End do Serviço API Gateway).
      • Resposta Padrão: Para um back-end de resposta padrão, você também precisa especificar o código de status HTTP, o conteúdo no corpo da resposta e um ou mais campos de cabeçalho HTTP (consulte Adicionando Respostas Padrão como um Back-End do Serviço API Gateway).

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 de 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 a função de autorizador também tenha retornado um dos escopos de acesso especificados no campo Escopo Permitido. Nesse caso, a opção Ativar Acesso Anônimo da política de 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 pela função de autorizador. Nesse caso, você deve ter selecionado a opção Ativar Acesso Anônimo da política de autenticação.
      • Somente autenticação: Só concede acesso a usuários finais que foram autenticados com sucesso pela função de autorizador. Nesse caso, a opção Ativar Acesso Anônimo da política de autenticação não tem efeito.
    • Escopo Permitido: Se você tiver selecionado Qualquer um como o Tipo de Autorização, insira uma lista delimitada por vírgulas de uma ou mais strings que correspondam aos escopos de acesso retornados pela função de autorizador. O acesso só será concedido aos usuários finais que foram autenticados com sucesso se a função de autorizador retornar 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 política de autenticação:

    • somente usuários finais autenticados podem acessar a rota
    • todos os usuários finais autenticados podem acessar a rota, independentemente dos escopos de acesso retornados pela função de autorizador
    • usuários finais anônimos não podem acessar a rota
12. Selecione Próximo para revisar os detalhes informados para a implantação de API.
13. Selecione Criar ou Salvar Alterações 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).

Para adicionar políticas de solicitação de autenticação e autorização para tokens de acesso de argumento único a uma especificação de implantação de API em um arquivo JSON:

1. Usando seu editor de JSON preferido, edite a especificação de implantação de API existente à qual você deseja adicionar a funcionalidade de autenticação e autorização ou crie uma nova especificação de implantação de API (consulte Criando uma Especificação de Implantação de API).

   No mínimo, a especificação de implantação de API incluirá uma seção routes contendo:

   • Um caminho. Por exemplo, /hello
   • Um ou mais métodos. Por exemplo, GET
   • Uma definição de um back-end. Por exemplo, um URL ou o OCID de uma função no OCI Functions.

   Por exemplo, a seguinte especificação básica de implantação de API define uma função simples sem servidor Hello World no OCI Functions como um único back-end:

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         }
       }
     ]
   }

2. Adicione uma política de solicitação authentication que se aplique a todas as rotas na especificação de implantação de API:

   1. Insira uma seção requestPolicies antes da seção routes, se ainda não existir uma. Por exemplo:

      
      {
        "requestPolicies": {},
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
               "type": "ORACLE_FUNCTIONS_BACKEND",
               "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            }
          }
        ]
      }

   2. Adicione a seguinte política authentication à nova seção requestPolicies.

      {
        "requestPolicies": {
          "authentication": {
            "type": "<type-value>",
            "isAnonymousAccessAllowed": <true|false>,
            "functionId": "<function-ocid>",
            <"tokenHeader"|"tokenQueryParam">: <"<token-header-name>"|"<token-query-param-name>">
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            }
          }
        ]
      }

      em que:

      • <type-value> é o tipo de autenticação. Para usar uma função de autorizador para autenticação, especifique CUSTOM_AUTHENTICATION.
      • "isAnonymousAccessAllowed": <true|false> indica opcionalmente se usuários finais não autenticados (ou seja, anônimos) podem acessar rotas na especificação de implantação de API. Se você nunca quiser que usuários finais anônimos possam acessar rotas, defina essa propriedade como false. Se você não incluir essa propriedade na política authentication, o padrão false será usado. Observe que, se você não incluir essa propriedade e defini-la como true, também precisará especificar explicitamente cada rota para a qual o acesso anônimo é permitido, definindo a propriedade type como "ANONYMOUS" na política authorization de cada rota.
      • <function-ocid> é o OCID da função de autorizador implantada no OCI Functions.
      • <"tokenHeader"|"tokenQueryParam">: <"<token-header-name>"|"<token-query-param-name>"> indica se é um cabeçalho de solicitação que contém o token de acesso (e, em caso afirmativo, o nome do cabeçalho) ou um parâmetro de consulta que contém o token de acesso (e, em caso afirmativo, o nome do parâmetro de consulta). Observe que você pode especificar "tokenHeader": "<token-header-name>" ou "tokenQueryParam": "<token-query-param-name>">, mas não ambos.

      Por exemplo, a seguinte política authentication especifica uma função do OCI que validará o token de acesso no cabeçalho de solicitação de Autorização:

      {
        "requestPolicies": {
          "authentication": {
            "type": "CUSTOM_AUTHENTICATION",
            "isAnonymousAccessAllowed": false,
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaac2______kg6fq",
            "tokenHeader": "Authorization"
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            }
          }
        ]
      }

3. Adicione uma política de solicitação authorization para cada rota na especificação de implantação de API:

   1. Insira uma seção requestPolicies após a primeira seção backend da rota, se ainda não existir. Por exemplo:

      
      {
        "requestPolicies": {
          "authentication": {
            "type": "CUSTOM_AUTHENTICATION",
            "isAnonymousAccessAllowed": false,
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaac2______kg6fq",
            "tokenHeader": "Authorization"
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
               "type": "ORACLE_FUNCTIONS_BACKEND",
               "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            },
            "requestPolicies": {}
          }
        ]
      }

   2. Adicione a seguinte política authorization à seção requestPolicies:

      {
        "requestPolicies": {
          "authentication": {
            "type": "CUSTOM_AUTHENTICATION",
            "isAnonymousAccessAllowed": false,
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaac2______kg6fq",
            "tokenHeader": "Authorization"
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            },
            "requestPolicies": {
              "authorization": {
                "type": <"AUTHENTICATION_ONLY"|"ANY_OF"|"ANONYMOUS">, 
                "allowedScope": [ "<scope>" ]
              }
            }
          }
        ]
      }

      em que:

      • "type": <"AUTHENTICATION_ONLY"|"ANY_OF"|"ANONYMOUS"> indica como conceder acesso à rota:

        • "AUTHENTICATION_ONLY": Só concede acesso a usuários finais que foram autenticados com sucesso. Nesse caso, a propriedade "isAnonymousAccessAllowed" na política authentication da especificação de implantação de API não tem efeito.
        • "ANY_OF": Só concede acesso a usuários finais que foram autenticados com sucesso, desde que a função de autorizador também tenha retornado um dos escopos de acesso especificados na propriedade allowedScope. Nesse caso, a propriedade "isAnonymousAccessAllowed" na política authentication da especificação de implantação de API não tem efeito.
        • "ANONYMOUS":  Concede acesso a todos os usuários finais, mesmo que eles não tenham sido autenticados com sucesso. Nesse caso, você deve definir explicitamente a propriedade "isAnonymousAccessAllowed" como true na política authentication da especificação de implantação de API.
      • "allowedScope": [ "<scope>" ] é uma lista delimitada por vírgulas de uma ou mais strings que correspondem aos escopos de acesso retornados pela função de autorizador. Nesse caso, você deve definir a propriedade type como "ANY_OF" (a propriedade "allowedScope" será ignorada se a propriedade type estiver definida como "AUTHENTICATION_ONLY" ou "ANONYMOUS"). Observe também que, se você especificar mais de um escopo, o acesso à rota será concedido se qualquer um dos escopos especificados for retornado pela função de autorizador.

      Por exemplo, a política de solicitação a seguir define uma rota /hello que só permite que usuários finais autenticados com o escopo read:hello a acessem:

      {
        "requestPolicies": {
          "authentication": {
            "type": "CUSTOM_AUTHENTICATION",
            "isAnonymousAccessAllowed": false,
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaac2______kg6fq",
            "tokenHeader": "Authorization"
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            },
            "requestPolicies": {
              "authorization": {
                "type": "ANY_OF",
                "allowedScope": [ "read:hello" ]
              }
            }
          }
        ]
      }

   3. Adicione uma política de solicitação authorization para todas as rotas restantes na especificação de implantação de API.
   Observação
   
   

   Se você não incluir uma política authorization para uma rota específica, o acesso será concedido como se tal política não existisse e a propriedade type estivesse definida como "AUTHENTICATION_ONLY". Em outras palavras, independentemente da definição da propriedade isAnonymousAccessAllowed na política authentication da especificação de implantação de API:

   • somente usuários finais autenticados podem acessar a rota
   • todos os usuários finais autenticados podem acessar a rota, independentemente dos escopos de acesso retornados pela função de autorizador
   • usuários finais anônimos não podem acessar a rota
4. Salve o arquivo JSON que contém a especificação de implantação de API.

5. Use a especificação de implantação de API ao criar ou atualizar uma implantação de API das seguintes formas:

   • especificando o arquivo JSON na Console quando você selecionar a opção Carregar uma API existente
   • especificando o arquivo JSON em uma solicitação à API REST do serviço API Gateway

   Para obter mais informações, consulte Implantando uma API em um Gateway de API por meio da Criação de uma Implantação de API e Atualizando um Gateway de API.

6. (Opcional) Confirme se a API foi implantada com êxito, chamando-a (consulte Chamando uma API Implantada em um Gateway de API).