Usando uma Política de Solicitação de Autenticação JWT_AUTHENTICATION (não mais recomendada)

Ao usar uma política de solicitação de autenticação do tipo JWT_AUTHENTICATION, para que um usuário final possa acessar uma implantação de API que use JWTs (JSON Web Tokens) para autenticação e autorização, ele deverá obter um JWT de um provedor.

Ao chamar uma API implantada em um gateway de API, o cliente de API fornece o JWT como um parâmetro de consulta ou no cabeçalho da solicitação. O gateway de API valida o JWT usando uma chave de verificação pública correspondente fornecida pelo provedor de identidades emissor. Usando a política da solicitação de autenticação JWT_AUTHENTICATION da implantação da API, você pode configurar como o gateway da API valida os JWTs:

• Você pode configurar o gateway de API para recuperar chaves de verificação públicas do provedor de identidades no runtime. Nesse caso, o provedor de identidades atua como o servidor de autorização.
• Você pode configurar o gateway  API com antecedência com chaves de verificação públicas já emitidas por um provedor de identidades (conhecido como "chaves estáticas"), permitindo que o gateway de API verifique JWTs localmente no runtime sem precisar entrar em contato com o provedor de identidades. O resultado é uma validação de token mais rápida.

Para adicionar uma nova política de solicitação de autenticação e autorização JWT_AUTHENTICATION a uma especificação de implantação de API em um arquivo JSON:

1. 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": "JWT_AUTHENTICATION",
            "isAnonymousAccessAllowed": <true|false>,
            "issuers": ["<issuer-url>", "<issuer-url>"],
            <"tokenHeader"|"tokenQueryParam">: <"<token-header-name>"|"<token-query-param-name>">,
            "tokenAuthScheme": "<authentication-scheme>",
            "audiences": ["<intended-audience>"],
            "publicKeys": {
              "type": <"REMOTE_JWKS"|"STATIC_KEYS">,
              <public-key-config>
            },
            "verifyClaims": [
              {"key": "<claim-name>",
               "values": ["<acceptable-value>", "<acceptable-value>"],
               "isRequired": <true|false>
              }
            ],
            "maxClockSkewInSeconds": <seconds-difference>
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            }
          }
        ]
      }

      em que:

      • "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.
      • <issuer-url> é o URL (ou uma string de texto) de um provedor de identidades que é permitido na reivindicação de emissor (iss) de um JWT a ser usado para acessar a implantação de 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/ . Você pode especificar um ou vários provedores de identidade (até cinco no máximo). Consulte Detalhes do Provedor de Identidades a Serem Usados para Reivindicações iss e aud e para o URI JWKS.
      • <"tokenHeader"|"tokenQueryParam">: <"<token-header-name>"|"<token-query-param-name>"> indica se é um cabeçalho de solicitação que contém o JWT (e em caso afirmativo, o nome do cabeçalho) ou um parâmetro da consulta que contém o JWT (e em caso afirmativo, o nome do parâmetro da consulta). Observe que você pode especificar "tokenHeader": "<token-header-name>" ou "tokenQueryParam": "<token-query-param-name>">, mas não ambos.
      • <tokenAuthScheme> é o nome do esquema de autenticação a ser usado se o JWT estiver contido em um cabeçalho de solicitação. Por exemplo, "Bearer".
      • <intended-audience> é um valor permitido na reivindicação de público-alvo (aud) de um JWT para identificar o destinatário pretendido do token. Por exemplo, o público-alvo pode ser, mas não precisa ser, o nome do host do gateway de API. Você pode especificar um ou vários públicos-alvo (até cinco no máximo). Consulte Detalhes do Provedor de Identidades a Serem Usados para Reivindicações iss e aud e para o URI JWKS.
      • "type": <"REMOTE_JWKS"|"STATIC_KEYS"> indica como você deseja que o gateway de API valide JWTs usando chaves de verificação públicas. Especifique REMOTE_JWKS para configurar o gateway de API para recuperar até dez chaves de verificação públicas do provedor em runtime. Especifique STATIC_KEYS para configurar o gateway da API com até dez chaves públicas de verificação já emitidas por um provedor de identidades (permitindo que o gateway da API verifique JWTs localmente sem precisar contatar o provedor de identidades).

      • <public-key-config> fornece os detalhes da validação de JWT, de acordo com se você especificou "REMOTE_JWKS" ou "STATIC_KEYS" como o valor de "type": da seguinte forma:

        • Se você especificou "type": "REMOTE_JWKS" para configurar o gateway de API para validar JWTs recuperando chaves de verificação públicas do provedor de identidades no runtime, forneça detalhes da seguinte forma:

                "publicKeys": {
                  "type": "REMOTE_JWKS",
                  "uri": "<uri-for-jwks>",
                  "maxCacheDurationInHours": <cache-time>,
                  "isSslVerifyDisabled": <true|false>
                }
          

          em que:

          • "uri": "<uri-for-jwks>" especifica o URI do qual será recuperado o JWKS (JSON Web Key Set) a ser usado para verificar a assinatura em JWTs. 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.
          • "maxCacheDurationInHours": <cache-time> especifica o número de horas (entre 1 e 24) em que o gateway de API deve colocar em cache o JWKS após recuperá-lo.
          • "isSslVerifyDisabled": <true|false> indica se a verificação SSL será desativada ao se comunicar com o provedor de identidades. A Oracle recomenda não definir esta opção como trueporque 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.

          Por exemplo:

                "publicKeys": {
                  "type": "REMOTE_JWKS",
                  "uri": "https://www.somejwksprovider.com/oauth2/v3/certs",
                  "maxCacheDurationInHours": 3,
                  "isSslVerifyDisabled": false
                }
          

        • Se você especificou "type": "STATIC_KEYS", os detalhes a serem fornecidos dependem do formato da chave já emitida pelo provedor de identidades (independentemente do formato, você pode especificar até dez chaves):

          • Se a chave estática for uma Chave Web JSON, especifique "format": "JSON_WEB_KEY", especifique o identificador da chave estática usada para assinar o JWT como o valor do parâmetro "kid" e forneça valores para outros parâmetros para verificar a assinatura do JWT.

            Por exemplo:

                            
                  "publicKeys": {
                    "type": "STATIC_KEYS",
                    "keys": [
                      {
                        "format": "JSON_WEB_KEY",
                        "kid": "master_key",
                        "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).

          • Se a chave estática for uma chave pública codificada por PEM, especifique "format": "PEM", especifique o identificador da chave estática usada para assinar o JWT como o valor de "kid" e forneça a chave como o valor de "key".

            Por exemplo:

                            
                  "publicKeys": {
                    "type": "STATIC_KEYS",
                    "keys": [
                      {
                        "format": "PEM",
                        "kid": "master_key"
                        "key": -----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.

      • verifyClaims opcionalmente especifica nomes e valores de reivindicações adicionais para uma ou mais reivindicações extras a serem validadas em um JWT (até dez no máximo).
        • "key": "<claim-name>" é o nome de uma reivindicação que pode ou deve ser incluída em um JWT. 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.
        • "values": ["<acceptable-value>", "<acceptable-value>"] (opcionalmente) indica um ou mais valores aceitáveis para a reivindicação.
        • "isRequired": <true|false> indica se a reivindicação deve ser incluída no 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

      • maxClockSkewInSeconds: <seconds-difference> opcionalmente especifica a diferença de tempo máxima entre os relógios do sistema do provedor de identidade que emitiu um JWT e o gateway de API. O valor especificado é levado em consideração quando o gateway de API valida o 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.

      Por exemplo, a seguinte política authentication configura o gateway de API com uma chave de verificação pública já emitida por um provedor de identidades para validar o JWT no cabeçalho da solicitação de Autorização:

      {
        "requestPolicies": {
          "authentication": {
            "type": "JWT_AUTHENTICATION",
            "isAnonymousAccessAllowed": false,
            "issuers": ["https://identity.oraclecloud.com/"],
            "tokenHeader": "Authorization",
            "tokenAuthScheme": "Bearer",
            "audiences": ["api.dev.io"],
            "publicKeys": {
              "type": "STATIC_KEYS",
              "keys": [
                {
                  "format": "JSON_WEB_KEY",
                  "kid": "master_key",
                  "kty": "RSA",
                  "n": "0vx7agoebGc...KnqDKgw",
                  "e": "AQAB",
                  "alg": "RS256",
                  "use": "sig"
                }
              ]
            },
            "verifyClaims": [
              {
                "key": "is_admin",
                "values": ["service:app", "read:hello"],
                "isRequired": true
              }
            ],
            "maxClockSkewInSeconds": 10
          }
        },
        "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 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": "JWT_AUTHENTICATION",
            "isAnonymousAccessAllowed": false,
            "issuers": ["https://identity.oraclecloud.com/"],
            "tokenHeader": "Authorization",
            "tokenAuthScheme": "Bearer",
            "audiences": ["api.dev.io"],
            "publicKeys": {
              "type": "STATIC_KEYS",
              "keys": [
                {
                  "format": "JSON_WEB_KEY",
                  "kid": "master_key",
                  "kty": "RSA",
                  "n": "0vx7agoebGc...KnqDKgw",
                  "e": "AQAB",
                  "alg": "RS256",
                  "use": "sig"
                }
              ]
            },
            "verifyClaims": [
              {
                "key": "is_admin",
                "values": ["service:app", "read:hello"],
                "isRequired": true
              }
            ],
            "maxClockSkewInSeconds": 10
          }
        },
        "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": "JWT_AUTHENTICATION",
            "isAnonymousAccessAllowed": false,
            "issuers": ["https://identity.oraclecloud.com/"],
            "tokenHeader": "Authorization",
            "tokenAuthScheme": "Bearer",
            "audiences": ["api.dev.io"],
            "publicKeys": {
              "type": "STATIC_KEYS",
              "keys": [
                {
                  "format": "JSON_WEB_KEY",
                  "kid": "master_key",
                  "kty": "RSA",
                  "n": "0vx7agoebGc...KnqDKgw",
                  "e": "AQAB",
                  "alg": "RS256",
                  "use": "sig"
                }
              ]
            },
            "verifyClaims": [
              {
                "key": "is_admin",
                "values": ["service:app", "read:hello"],
                "isRequired": true
              }
            ],
            "maxClockSkewInSeconds": 10
          }
        },
        "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 autenticados com sucesso, desde que a reivindicação scope do JWT inclua 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 incluídos na reivindicação scope do JWT. 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 algum dos escopos especificados estiver incluído na reivindicação scope do JWT.

      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": "JWT_AUTHENTICATION",
            "isAnonymousAccessAllowed": false,
            "issuers": ["https://identity.oraclecloud.com/"],
            "tokenHeader": "Authorization",
            "tokenAuthScheme": "Bearer",
            "audiences": ["api.dev.io"],
            "publicKeys": {
              "type": "STATIC_KEYS",
              "keys": [
                {
                  "format": "JSON_WEB_KEY",
                  "kid": "master_key",
                  "kty": "RSA",
                  "n": "0vx7agoebGc...KnqDKgw",
                  "e": "AQAB",
                  "alg": "RS256",
                  "use": "sig"
                }
              ]
            },
            "verifyClaims": [
              {
                "key": "is_admin",
                "values": ["service:app", "read:hello"],
                "isRequired": true
              }
            ],
            "maxClockSkewInSeconds": 10
          }
        },
        "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 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
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ê 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.

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

{
  "requestPolicies": {
    "authentication": {
      "type": "JWT_AUTHENTICATION",
      "isAnonymousAccessAllowed": false,
      "issuers": ["https://identity.oraclecloud.com/"],
      "tokenHeader": "Authorization",
      "tokenAuthScheme": "Bearer",
      "audiences": ["api.dev.io"],
      "publicKeys": {
        "type": "STATIC_KEYS",
        "keys": [
          {
            "format": "JSON_WEB_KEY",
            "kid": "master_key",
            "kty": "RSA",
            "n": "0vx7agoebGc...KnqDKgw",
            "e": "AQAB",
            "alg": "RS256",
            "use": "sig"
          }
        ]
      },
      "verifyClaims": [
        {
          "key": "is_admin",
          "values": ["service:app", "read:hello"],
          "isRequired": true
        }
      ],
      "maxClockSkewInSeconds": 10
    }
  },
  "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" ]
        }
      }
    }
  ]
}

{
  "requestPolicies": {
    "authentication": {
      "type": "TOKEN_AUTHENTICATION",
      "isAnonymousAccessAllowed": false,
      "tokenHeader": "Authorization",
      "tokenAuthScheme": "Bearer",
      "maxClockSkewInSeconds": 10,
      "validationPolicy": {
        "type": "STATIC_KEYS",
        "keys": [
          {
            "format": "JSON_WEB_KEY",
            "kid": "master_key",
            "kty": "RSA",
            "n": "0vx7agoebGc...KnqDKgw",
            "e": "AQAB",
            "alg": "RS256",
            "use": "sig"
          }
        ],
        "additionalValidationPolicy": {
          "audiences": [
            "api.dev.io"
          ],
          "verifyClaims": [
            {
              "key": "is_admin",
              "values": [
                "service:app",
                "read:hello"
              ],
              "isRequired": true
            }
          ],
          "issuers": [
            "https://identity.oraclecloud.com/"
          ]
        }
      }
    }
  },
  "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"
          ]
        }
      }
    }
  ]
}