Documentação do Oracle Cloud Infrastructure

Adicionando Log-out como Back-end do Serviço API Gateway

Descubra como definir um back-end de log-out com o Gateway de API.

Um requisito comum é que as APIs forneçam o recurso para que os clientes de API façam logout corretamente revogando tokens de acesso e, potencialmente, chamem outros URLs para executar tarefas adicionais pós-logout. O API Gateway permite que você defina back-ends de log-out para fornecer essa funcionalidade ao usar uma política de autenticação de token OAuth 2.0 para uma implantação de API. As solicitações para o back-end de log-out podem opcionalmente incluir um URL de pós-log-out como o valor de um parâmetro de consulta chamado postLogoutUrl.

Ao definir uma política de autenticação de token OAuth 2.0, você pode, opcionalmente, especificar um caminho para o back-end de log-out (o caminho de log-out) para revogar tokens de acesso no caso de uma falha de autenticação. Consulte Validando tokens para adicionar autenticação e autorização a implantações de API.

A definição de back-end de log-out inclui opcionalmente:

  • Uma lista de URLs pós-log-out permitidos para os quais uma solicitação pode ser redirecionada para revogar tokens de acesso. Se o parâmetro de consulta postLogoutUrl for incluído na solicitação, seu valor deverá ser um desses URLs. Os URLs na lista podem ser caminhos absolutos ou relativos, e os URLs podem incluir variáveis de contexto. Observe que, se você especificar um caminho relativo (ou seja, para outra rota na implantação de API), a implantação de API e a rota deverão permitir acesso anônimo. Observe também que, se você não incluir explicitamente um ou mais URLs na lista, qualquer URL pós-log-out será permitido.
  • Dados a serem transmitidos aos URLs de log-out quando a solicitação é redirecionada, como o valor do parâmetro de consulta state. Os dados só podem incluir variáveis de contexto (não valores estáticos).

Ao receber uma solicitação para o caminho de log-out de um cliente de API, o gateway de API verifica se o cliente de API está autenticado para chamar o back-end de log-out, verifica se qualquer URL pós-log-out incluído na solicitação é permitido e remove qualquer informação armazenada sobre a sessão do cliente de API (por exemplo, em cookies). Supondo que o URL pós-log-out seja permitido, o que acontece a seguir depende se o cliente da API está autenticado e se a resposta armazenada no cache anterior do URL de Descoberta especificado na política de autenticação de token OAuth 2.0 forneceu um ponto final de sessão final:

  • Se o cliente de API não for autenticado, o gateway de API redirecionará a solicitação de log-out para o URL pós-log-out.
  • Se o cliente de API for autenticado, mas a política de autenticação de token OAuth 2.0 não fornecer um ponto final de sessão final, o gateway de API redirecionará a solicitação de log-out para o URL pós-log-out e transmitirá qualquer informação de estado especificada na definição de back-end de log-out.
  • Se o cliente de API for autenticado e a política de autenticação de token OAuth 2.0 fornecer um ponto final de sessão final, o gateway de API redirecionará a solicitação de log-out para esse ponto final de sessão final e transmitirá o URL pós-log-out e qualquer informação de estado especificada na definição de back-end de log-out. Nesse caso, é responsabilidade do provedor de identidades redirecionar a solicitação para o URL pós-logout.

Você pode adicionar um back-end de log-out a uma especificação de implantação de API fazendo o seguinte:

  • usando a Console
  • editando um arquivo JSON

Usando a Console para Adicionar Back-Ends de Log-out a uma Especificação de Implantação de API

Para adicionar back-ends de log-out 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. Na página Autenticação, especifique opções de autenticação.

    Para obter mais informações sobre opções de autenticação, consulte Adicionando Autenticação e Autorização às Implantações de API.

  3. Na página Rotas, crie uma nova rota e especifique:

    • 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:

    • Métodos: Um ou mais métodos aceitos pelo serviço de back-end. No caso de back-ends de log-out, somente GET é aceito.
    • Tipo de Backend: O tipo do serviço de back-end como Logout.
    • URIs pós-logout permitidos: (opcional) Uma lista de um ou mais URLs permitidos para os quais uma solicitação de logout pode ser redirecionada para revogar tokens. Os URLs na lista podem ser caminhos absolutos ou relativos, e os URLs podem incluir variáveis de contexto. Por exemplo, ["https://${request.header[tenant-id].page.html}", "https://fixed-path.page.html", "/logout_html"].

      Observe o seguinte:

      • Um URL pós-logout pode ser incluído em uma solicitação ao back-end de logout como o valor de um parâmetro de consulta chamado postLogoutUrl.
      • Se você especificar um caminho relativo (ou seja, para outra rota na implantação de API), a implantação de API e a rota deverão permitir acesso anônimo.
      • Se você não incluir explicitamente um ou mais URLs na lista, qualquer URL pós-logout será permitido.
    • Estado pós-log-out: (opcional) Dados a serem informados quando uma solicitação de log-out é redirecionada para um ponto final da sessão final e/ou um URL pós-log-out. Os dados só podem incluir variáveis de contexto (não valores estáticos). Por exemplo, request.query[region]

      Os dados são informados como o valor do parâmetro de consulta state.

  4. (Opcional) Selecione Outra Rota para inserir detalhes de rotas adicionais.
  5. Selecione Próximo para revisar os detalhes informados para a implantação de API.
  6. Selecione Criar ou Salvar Alterações para criar ou atualizar a implantação de API.
  7. (Opcional) Confirme se a API foi implantada com êxito, chamando-a (consulte Chamando uma API Implantada em um Gateway de API).

Editando um Arquivo JSON para Adicionar BackEnds de Log-out a uma Especificação de Implantação de API

Para adicionar back-ends de log-out a uma especificação de implantação de API em um arquivo JSON: 

  1. Usando seu editor JSON preferido, edite a especificação de implantação de API existente à qual você deseja adicionar um back-end de log-out ou crie uma nova especificação de implantação de API (consulte Criando uma Especificação de Implantação de API).

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

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

  2. Na seção routes, inclua uma nova seção para um backend de log-out:

    {
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    },
    {
      "path": "<logout-route-path>",
      "methods": ["<method-list>"],
      "backend": {
        "type": "OAUTH2_LOGOUT",
        "allowedPostLogoutUris": ["<url>", "<url"],
        "postLogoutState": "<logout-data>"
      }
    }
  ]
}

    em que:

    • <logout-route-path> especifica um caminho para chamadas usando os métodos listados para o back-end de log-out. Observe que o caminho da rota que você especificar:

    • <method-list> especifica um ou mais métodos aceitos pelo back-end de log-out, separados por vírgulas. No caso de back-ends de log-out, somente GET é aceito.
    • "type": "OAUTH2_LOGOUT" especifica que o back-end é um back-end de log-out.

    • "allowedPostLogoutUris": ["<url>", "<url>"] especifica opcionalmente uma lista de um ou mais URLs permitidos para os quais uma solicitação de log-out pode ser redirecionada para revogar tokens. Os URLs na lista podem ser caminhos absolutos ou relativos, e os URLs podem incluir variáveis de contexto. Por exemplo, ["https://${request.header[tenant-id].page.html}", "https://fixed-path.page.html", "/logout_html"].

      Observe o seguinte:

      • Um URL pós-logout pode ser incluído em uma solicitação ao back-end de logout como o valor de um parâmetro de consulta chamado postLogoutUrl.
      • Se você especificar um caminho relativo (ou seja, para outra rota na implantação de API), a implantação de API e a rota deverão permitir acesso anônimo.
      • Se você não incluir explicitamente um ou mais URLs na lista, qualquer URL pós-logout será permitido.

    • "postLogoutState": "<logout-data>" especifica opcionalmente dados a serem transmitidos quando uma solicitação de log-out é redirecionada para um ponto final da sessão final e/ou um URL pós-log-out. Os dados só podem incluir variáveis de contexto (não valores estáticos). Por exemplo, request.query[region]

      Os dados são informados como o valor do parâmetro de consulta state.

    Neste exemplo, uma solicitação para o back-end /logout pode incluir um dos URLs especificados para allowedPostLogoutUris como o valor do parâmetro de consulta postLogoutUrl. Quando o URL pós-logout é chamado, o valor da variável de contexto request.query[region] é passado para o URL. Observe que, neste exemplo, um dos valores allowedPostLogoutUris ("/logout_html") é um caminho relativo para o back-end de resposta padrão /logout_html na mesma implantação de API. Como se trata de um caminho relativo para outra rota na mesma implantação de API, o back-end /logout_html deve incluir uma política de autorização do tipo ANONYMOUS, conforme mostrado aqui.

    {
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    },
    {
      "path": "/logout",
      "methods": ["GET"],
      "backend": {
        "type": "OAUTH2_LOGOUT",
        "allowedPostLogoutUris": ["https://${request.header[tenant-id].page.html}", "/logout_html"],
        "postLogoutState": "request.query[region]"
      }
    },
    {
      "path": "/logout_html",
      "methods": ["GET"],
      "backend": {
        "type": "STOCK_RESPONSE_BACKEND",
        "body": "Token could not be revoked."
      },
      "requestPolicies": {
        "authorization": {
          "type": "ANONYMOUS"
        }
      }
    }
  ]
}
  3. Salve o arquivo JSON que contém a especificação de implantação de API.

  4. 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.

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