Adicionando Políticas de Solicitação de Autenticação e Autorização para Tokens de Acesso de Argumento Único e Funções de Autorizador

Para adicionar políticas de solicitação de autenticação e autorização para tokens de acesso de argumento único 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 terá que 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 da autorização.

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: 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 do autorizador nas Funções do OCI.
7. Selecione Função de autorizador de argumento único para especificar que você deseja especificar 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 da localização 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 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 backend ou para rotear solicitações para diferentes backends 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:
      • 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 a aplicação e função (consulte Adicionando uma Função nas Funções do OCI como um Back-end do API Gateway).
      • Resposta de estoque: Para um back-end de resposta de estoque, você também precisa especificar o código de status HTTP, o conteúdo no corpo da resposta e um ou vários campos do cabeçalho HTTP (consulte Adicionando Respostas de Estoque como um Back-end do API Gateway).
      • Log-out: Para um back-end de log-out, você também precisa especificar uma lista de URLs permitidos para os quais uma solicitação pode ser redirecionada para revogar tokens e, opcionalmente, dados para passar para o URL de log-out (consulte Adicionando Log-out 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 da Autorização e especifique:

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

      • Qualquer: Só concede acesso a usuários finais que foram autenticados com sucesso, contanto que a função do autorizador também tenha retornado um dos escopos do acesso que você especificar no campo Adicionar 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 pela função de autorizador. 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 pela função de autorizador. Nesse caso, a opção Ativar acesso anônimo da política da autenticação não tem efeito.
    • Adicionar escopo permitido: Se você selecionou Qualquer como o tipo de Autorização, informe uma lista delimitada pela vírgula de um ou mais strings que correspondem aos escopos do acesso retornados pela função do 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 será definido comoSomente 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 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 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).

Para adicionar políticas de solicitação de autenticação e autorização para tokens de acesso de argumento único a uma especificação da implantação da 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, uma URL ou o OCID de uma função no OCI Functions.

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

   {
     "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 para o 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ê seleciona a opção Fazer Upload de uma API de implantação 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 da API Criando uma Implantação de API e Updating an API Gateway.

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