Documentación de Oracle Cloud Infrastructure

Uso de una política de solicitud de autenticación JWT_AUTHENTICATION (ya no se recomienda)

Antes de que un usuario final pueda acceder a un despliegue de API que utilice los tokens web JSON (JWT) para la autenticación y autorización, debe obtener un JWT de un proveedor de identidad.

Nota

En versiones anteriores, es posible que haya creado políticas de solicitud de autenticación de tipo JWT_AUTHENTICATION para utilizar los JWT para la autenticación.

Si está creando nuevas políticas de solicitud de autenticación para utilizar JWT, ahora le recomendamos que cree políticas de solicitud de autenticación del tipo TOKEN_AUTHENTICATION en su lugar (consulte Uso de la consola para agregar políticas de solicitud de autorización y autenticación de token y Edición de un archivo JSON para agregar políticas de solicitud de autorización y autenticación de token). También recomendamos migrar las políticas de solicitud de JWT_AUTHENTICATION existentes a las políticas de TOKEN_AUTHENTICATION.

Tenga en cuenta que las políticas de solicitud de JWT_AUTHENTICATION existentes aún se admiten. Tenga en cuenta también que, aunque puede crear nuevas políticas de solicitud JWT_AUTHENTICATION mediante la definición de la especificación de despliegue de API en un archivo JSON (como se describe en las instrucciones originales de esta sección), le recomendamos que en su lugar cree políticas de solicitud de autenticación de tipo TOKEN_AUTHENTICATION.

Al llamar a una API desplegada en un gateway de API, el cliente de API proporciona el JWT como parámetro de consulta o en la cabecera de la solicitud. El gateway de API valida el JWT mediante una clave de verificación pública correspondiente proporcionada por el proveedor de identidad emisor. Mediante la directiva de solicitud de autenticación JWT_AUTHENTICATION de la implementación de la API, puede configurar cómo valida el gateway de la API los JWT:

  • Puede configurar el gateway de API para recuperar claves de verificación públicas del proveedor de identidad en tiempo de ejecución. En este caso, el proveedor de identidad actúa como servidor de autorización.
  • Puede configurar el gateway de API con antelación con claves de verificación públicas ya emitidas por un proveedor de identidad (denominadas "claves estáticas"), lo que permite al gateway de API verificar los JWT localmente en tiempo de ejecución sin tener que ponerse en contacto con el proveedor de identidad. El resultado es una validación de token más rápida.

Para agregar una nueva política de autenticación y solicitud de autorización de JWT_AUTHENTICATION a una especificación de despliegue de API en un archivo JSON:

  1. Agregue una política de solicitud authentication que se aplique a todas las rutas de la especificación de despliegue de API:

    1. Inserte una sección requestPolicies antes de la sección routes si no existe ninguna. Por ejemplo:

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

    2. Agregue la siguiente política authentication a la nueva sección 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"
      }
    }
  ]
}

      donde:

      • "isAnonymousAccessAllowed": <true|false> opcionalmente indica si los usuarios finales no autenticados (es decir, anónimos) pueden acceder a rutas en la especificación de despliegue de API. Si desea que los usuarios finales anónimos no puedan acceder a rutas, defina esta propiedad en false. Si no incluye esta propiedad en la política authentication, se utilizará el valor por defecto false. Tenga en cuenta que si incluye esta propiedad y la define en true, también tendrá que especificar explícitamente cada ruta en la que se permite el acceso anónimo, definiendo la propiedad type en "ANONYMOUS" en la política authorization de cada ruta.
      • <issuer-url> es la URL (o una cadena de texto) de un proveedor de identidad que está permitido en la reclamación de emisor (iss) de un JWT que se utilizará para acceder al despliegue de API. Por ejemplo, para permitir que un JWT emitido por OCI IAM con dominios de identidad se utilice para acceder al despliegue de API, introduzca https://identity.oraclecloud.com/. Puede especificar uno o varios proveedores de identidad (hasta un máximo de cinco). Consulte Detalles del proveedor de identidad para usar en reclamaciones iss y aud y para el URI de JWKS.
      • <"tokenHeader"|"tokenQueryParam">: <"<token-header-name>"|"<token-query-param-name>"> indica si se trata en una cabecera de solicitud que contiene el JWT (y, si lo contienen, también Indica el nombre de la cabecera) o un parámetro que contiene el JWT (y, si lo contienen, también Indica el nombre del parámetro del consulta). Tenga en cuenta que puede especificar "tokenHeader": "<token-header-name>" o "tokenQueryParam": "<token-query-param-name>">, pero no los dos.
      • <tokenAuthScheme> es el nombre del esquema de autenticación que se va a utilizar si una cabecera de solicitud contiene el JWT. Por ejemplo, "Bearer".
      • <intended-audience> es un valor que se permite en la reclamación de público (aud) de un JWT para identificar el destinatario deseado del token. Por ejemplo, el público puede ser, pero no necesita ser, el nombre de host del gateway de API. Puede especificar uno o varios públicos (hasta un máximo de cinco). Consulte Detalles del proveedor de identidad para usar en reclamaciones iss y aud y para el URI de JWKS.
      • "type": <"REMOTE_JWKS"|"STATIC_KEYS"> indica cómo desea que el gateway de API valide los JWT mediante claves de verificación públicas. Especifique REMOTE_JWKS para configurar el gateway de API para recuperar hasta diez claves de verificación públicas del proveedor del identidad en tiempo del ejecución. Especifique STATIC_KEYS para configurar el puerta de enlace de API con hasta diez claves públicas de verificación ya emitidas por un proveedor a nivel de identidad (lo que le permite al puerta de enlace de API verificar el JWT localmente sin tener que contactar con el proveedor a seguir).

      • <public-key-config> proporciona los detalles de la validación de JWT, según si especificó "REMOTE_JWKS" o "STATIC_KEYS" como el valor de "type": de la siguiente manera:

        • Si ha especificado "type": "REMOTE_JWKS" para configurar el gateway de API para validar los JWT recuperando claves de verificación públicas del proveedor de identidad en tiempo de ejecución, proporcione los detalles siguientes:

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

          donde:

          • "uri": "<uri-for-jwks>" especifica el URI desde el que se va a recuperar el juego de claves web JSON (JWKS) que se va a utilizar para verificar la firma en los JWT. Para obtener más información sobre el URI que se va a especificar, consulte Detalles del proveedor de identidad para usar en reclamaciones iss y aud y para el URI de JWKS. Tenga en cuenta que:
            • El URI debe poder dirigirse desde la subred que contiene el gateway de API en el que se despliega la API.
            • Si el gateway de API no recupera el JWKS, todas las solicitudes al despliegue de API devolverán un código de respuesta HTTP 500. Consulte el log de ejecución del gateway de API para obtener más información sobre el error (consulte Agregación de registro a despliegues de API).
            • Algunos parámetros de clave deben estar presentes en el JWKS para verificar la firma del JWT (consulte Parámetros de clave necesarios para verificar las firmas de JWT).
            • El JWKS puede contener hasta diez claves.
          • "maxCacheDurationInHours": <cache-time> especifica el número de horas (entre 1 y 24) que el gateway de API debe almacenar el JWKS en la caché después de recuperarlo.
          • "isSslVerifyDisabled": <true|false> indica si se debe desactivar la verificación SSL al comunicarse con el proveedor de identidad. Oracle recomienda no definir esta opción en trueporque puede comprometer la validación de JWT. El gateway de API confía en certificados de varias entidades de certificación emitidas para OCI IAM con dominios de identidad, Oracle Identity Cloud Service (IDCS), Auth0 y Okta.

          Por ejemplo:

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

        • Si ha especificado "type": "STATIC_KEYS", los detalles que se deben proporcionar dependen del formato de la clave ya emitida por el proveedor de identidad (independientemente del formato, puede especificar hasta diez claves):

          • Si la clave estática es una clave web JSON, especifique "format": "JSON_WEB_KEY", especifique el identificador de la clave estática utilizada para firmar el JWT como valor del parámetro "kid" y proporcione valores para otros parámetros para verificar la firma del JWT.

            Por ejemplo:

                            
      "publicKeys": {
        "type": "STATIC_KEYS",
        "keys": [
          {
            "format": "JSON_WEB_KEY",
            "kid": "master_key",
            "kty": "RSA",
            "n": "0vx7agoebGc...KnqDKgw",
            "e": "AQAB",
            "alg": "RS256",
            "use": "sig"
          }
        ]

            Tenga en cuenta que ciertos parámetros deben estar presentes en la clave estática para verificar la firma del JWT (consulte Parámetros de clave necesarios para verificar las firmas de JWT). Tenga en cuenta también que RSA es actualmente el único tipo de clave soportado (kty).

          • Si la clave estática es una clave pública codificada por PEM, especifique "format": "PEM", especifique el identificador de la clave estática utilizada para firmar el JWT como valor "kid" y proporcione la clave como valor "key".

            Por ejemplo:

                            
      "publicKeys": {
        "type": "STATIC_KEYS",
        "keys": [
          {
            "format": "PEM",
            "kid": "master_key"
            "key": -----BEGIN PUBLIC KEY-----XsEiCeYgglwW/KAhSSNRVdD60QlXYMWHOhXzSFDZCLf1WXxKMZCiMvVrsBIzmFEXnFmcsO2mxwlL5/8qQudomoP+yycJ2gWPIgqsZcQRheJWxVC5ep0MeEHlvLnEvCi9utpAnjrsZCQ7plfZVPX7XORvezwqQhBfYzwA27M2FgOOs8DOIYfqQ1Ki3DMqEppFnjLcjgQtknbTlT7YgG6tzobwig8M2KIrPjJ0BmbJAFH-----END PUBLIC KEY-----
          }
        ]

            Tenga en cuenta que los marcadores -----BEGIN PUBLIC KEY----- y -----END PUBLIC KEY----- son necesarios.

      • verifyClaims especifica opcionalmente nombres y valores de reclamación adicionales para una o más reclamaciones adicionales que se validarán en un JWT (hasta un máximo de diez).
        • "key": "<claim-name>" es el nombre de una reclamación que puede o debe incluirse en un JWT. El nombre de reclamación que especifique puede ser un nombre de reclamación reservado, como la reclamación de asunto (sub) o un nombre de reclamación personalizado emitido por un proveedor de identidad concreto.
        • "values": ["<acceptable-value>", "<acceptable-value>"] (opcionalmente) indica uno o más valores aceptables para la reclamación.
        • "isRequired": <true|false> indica si la reclamación se debe incluir en el JWT.

        Tenga en cuenta que los nombres y valores clave introducidos se manejan simplemente como cadenas y deben coincidir exactamente con los nombres y valores del JWT. No se soporta la coincidencia de patrones y otros tipos de datos

      • maxClockSkewInSeconds: <seconds-difference> especifica opcionalmente la diferencia de tiempo máxima entre los relojes del sistema del proveedor de identidad que emitió un JWT y el gateway de API. El valor especificado se tiene en cuenta cuando el gateway de API valida el JWT para determinar si sigue siendo válido, utilizando la reclamación de "no antes de" (nbf) (si está presente) y la reclamación de caducidad (exp) en el JWT. El mínimo (por defecto) es 0, el máximo, 120.

      Por ejemplo, la siguiente política authentication configura el gateway de API con una clave de verificación pública ya emitida por un proveedor de identidad para validar el JWT en la cabecera de solicitud de autorización:

      {
  "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. Agregue una política de solicitud authorization para cada ruta en la especificación de despliegue de API:

    1. Inserte una sección requestPolicies después de la sección backend de la primera ruta, si no existe ninguna. Por ejemplo:

      {
  "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. Agregue la siguiente política authorization a la sección 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>" ]
        }
      }
    }
  ]
}

      donde:

      • "type": <"AUTHENTICATION_ONLY"|"ANY_OF"|"ANONYMOUS"> indica cómo otorgar acceso a la ruta:

        • "AUTHENTICATION_ONLY": solo otorga acceso a usuarios finales que se hayan autenticado correctamente En este caso, la propiedad "isAnonymousAccessAllowed" de la política authentication de la especificación de despliegue de API no tiene ningún efecto.
        • "ANY_OF": solo otorga acceso a usuarios finales que se hayan autenticado correctamente, siempre que la reclamación scope del JWT incluya uno de los ámbitos de acceso que especifique en la propiedad allowedScope. En este caso, la propiedad "isAnonymousAccessAllowed" de la política authentication de la especificación de despliegue de API no tiene ningún efecto.
        • "ANONYMOUS": otorga acceso a todos los usuarios finales, incluso si no se han autenticado correctamente. En este caso, debe definir explícitamente la propiedad "isAnonymousAccessAllowed" en true en la política authentication de la especificación de despliegue de API.
      • "allowedScope": [ "<scope>" ] es una lista delimitada por comas de una o varias cadenas que corresponden a ámbitos de acceso incluidos en la reclamación scope del JWT. En este caso, debe definir la propiedad type en "ANY_OF" (la propiedad "allowedScope" se ignora si la propiedad type se define en "AUTHENTICATION_ONLY" o "ANONYMOUS"). También debe tener en cuenta que si especifica más de un ámbito, se otorga acceso a la ruta si cualquiera de los ámbitos que ha especificado se incluye en la reclamación scope del JWT.

      Por ejemplo, la siguiente política de solicitud define una ruta /hello que solo permite el acceso a los usuarios finales autenticados con el ámbito read:hello:

      {
  "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. Agregue una política de solicitud authorization para el resto de rutas de la especificación de despliegue de API.
    Nota

    Si no incluye ninguna política authorization para una ruta concreta, se otorga el acceso como si esa política existiera y la propiedad type se define en "AUTHENTICATION_ONLY". Es decir, independientemente de la configuración de la propiedad isAnonymousAccessAllowed en la política authentication de la especificación de despliegue de API:

    • solo pueden acceder a la ruta los usuarios finales autenticados
    • todos los usuarios finales autenticados pueden acceder a la ruta independientemente de los ámbitos de acceso en la reclamación de scope de JWT
    • los usuarios finales anónimos no pueden acceder a la ruta
  3. Guarde el archivo JSON que contiene la especificación de despliegue de API.

  4. Utilice la especificación de despliegue de API al crear o actualizar un despliegue de API de las siguientes formas:

    • Especificando el archivo JSON en la consola al seleccionar la opción Cargar API de despliegue existente
    • Especificando el archivo JSON en una solicitud para la API REST de gateway de API.

    Para obtener más información, consulte Despliegue de una API en un gateway del API mediante el despliegue de un despliegue de API y Actualización de un gateway del API.

  5. (Opcional) Confirme que la API se ha desplegado correctamente llamándola. Para ello, consulte Llamada a una API desplegada en un gateway de API.

Ejemplo: Migración de una Política de Solicitud JWT_AUTHENTICATION a una Política de Solicitud TOKEN_AUTHENTICATION

En esta sección, se muestra un ejemplo de una política de solicitud JWT_AUTHENTICATION existente migrada a una política TOKEN_AUTHENTICATION.

Una forma de abordar la migración es crear una política de solicitud TOKEN_AUTHENTICATION vacía y, a continuación, rellenarla con valores de la política de solicitud JWT_AUTHENTICATION

Antes de la migración:

La política de solicitud JWT_AUTHENTICATION original, antes de la migración:

{
  "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" ]
        }
      }
    }
  ]
}

Después de la migración:

La nueva política de solicitud TOKEN_AUTHENTICATION rellenada con valores de la política de solicitud JWT_AUTHENTICATION original:

{
  "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"
          ]
        }
      }
    }
  ]
}