Edición de un archivo de JSON para agregar políticas de solicitud de autorización y autenticación de token

Agregue políticas a una especificación de despliegue en un archivo JSON.

Con el editor de JSON de su elección, modifique la especificación de despliegue de API existente a la que desea agregar la funcionalidad de autenticación y autorización o cree una nueva especificación de despliegue de API (consulte Creación de una especificación de despliegue de API).

Como mínimo, la especificación de despliegue de API incluirá una sección routes que contiene:
- Una ruta de acceso. Por ejemplo, /hello.
- Uno o varios métodos. Por ejemplo, GET
- Una definición de backend. Por ejemplo, una URL o el OCID de una función en OCI Functions.
Por ejemplo, la siguiente especificación del despliegue básico del API define una función sencilla del Hello World sin servidor en OCI Functions como un único backend:
```
{
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```

Inserte una sección requestPolicies antes de la sección routes (si aún no existe una) para crear una política de solicitud authentication que se aplique a todas las rutas de la especificación de despliegue de API. Por ejemplo:


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

Agregue la política de solicitud authentication de la siguiente manera:
```
{
  "requestPolicies": {
    "authentication": {
      "type": "TOKEN_AUTHENTICATION",
      <"tokenHeader"|"tokenQueryParam">: <"<token-header-name>"|"<token-query-param-name>">,
      "tokenAuthScheme": "<authentication-scheme>",
      "isAnonymousAccessAllowed": <true|false>,
      "maxClockSkewInSeconds": <seconds-difference>,
      "validationPolicy": {<validation-policy-config>},
    }
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
         "type": "ORACLE_FUNCTIONS_BACKEND",
         "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```
donde:
- "authentication": {"type": "TOKEN_AUTHENTICATION"... especifica que desea utilizar tokens para la autenticación.
- <"tokenHeader"|"tokenQueryParam">: <"<token-header-name>"|"<token-query-param-name>"> indica si se trata a una cabecera de solicitud que contiene el token (y, si lo contienen, también es el nombre de la cabecera) o un parámetro que contiene el token de consulta (y, si lo contienen, también es indica el nombre del parámetro a consultar). Tenga en cuenta que puede especificar "tokenHeader": "<token-header-name>" o "tokenQueryParam": "<token-query-param-name>">, pero no los dos. Por ejemplo, "tokenHeader": "Authorization"
- <tokenAuthScheme> es el nombre del Esquema de Autenticación que se va a utilizar si el token está incluido en una cabecera del pedido. Por ejemplo, "Bearer".
- "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.
- 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 que especifique 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 y el máximo es 120.
- "validationPolicy": {<validation-policy-config>} especifica una política de validación para validar tokens, como se describe en los siguientes pasos.
Si desea que el gateway de API valide tanto los tokens JWT como los tokens no JWT con un punto final de introspección del servidor de autorización OAuth 2.0 mediante credenciales de cliente (incluido un secreto de cliente recuperado de un almacén en el servicio Vault), agregue la siguiente política de validación a la sección validationPolicy vacía:
```
      "validationPolicy": {
        "type": "REMOTE_DISCOVERY",          
        "clientDetails": {
          "type": "CUSTOM",
          "clientId": "<client-id>",
          "clientSecretId": "<secret-ocid>",
          "clientSecretVersionNumber": <secret-version-number>
        },          
        "sourceUriDetails": {
          "type": "DISCOVERY_URI",
          "uri": "<well-known-uri>"
        },
        "isSslVerifyDisabled": <true|false>,
        "maxCacheDurationInHours": <cache-time>,
        "additionalValidationPolicy": {
          "issuers": ["<issuer-url>", "<issuer-url>"],
          "audiences": ["<intended-audience>"],
          "verifyClaims": [{
            "key": "<claim-name>",
            "values": ["<acceptable-value>", "<acceptable-value>"],
            "isRequired": <true|false>
          }]
        }
      }
```
donde:
- "validationPolicy": {"type": "REMOTE_DISCOVERY"...} especifica que desea validar tokens con un punto final de introspección del servidor de autorización OAuth 2.0 mediante credenciales de cliente (incluido un secreto de cliente recuperado de un almacén en el servicio Vault).
- clientDetails": {"type": "CUSTOM"...} especifica los detalles del secreto de cliente que se va a recuperar de un almacén en el servicio Vault:
  - "clientId": "<client-id>" especifica el ID de cliente que se va a enviar al punto final de introspección. Para obtener un ID de cliente, cree y registre una aplicación cliente con el servidor de autorización. Por ejemplo, 5hsti38yhy5j2a4tas455rsu6ru8yui3wrst4n1 . Consulte Requisitos para la autenticación de token.
  - "clientSecretId": "<secret-ocid>" especifica el OCID del secreto de almacén que contiene el secreto de cliente que se va a enviar al punto final de introspección. Por ejemplo, ocid1.vaultsecret.oc1.iad.amaaaaaa______cggit3q
  - "clientSecretVersionNumber": <secret-version-number> especifica la versión del secreto de almacén que contiene el secreto de cliente que se enviará al punto final de introspección. Por ejemplo, 1
- "uri": "<well-known-uri>" especifica la URL conocida de un servidor de autorización desde el que el gateway de API va a obtener puntos finales de metadatos de autorización. Por ejemplo, https://my-idp/oauth2/default/.well-known/openid-configuration. Tenga en cuenta que la URL debe poder direccionarse desde la subred que contiene el gateway del API en el que se despliega la API.
- "isSslVerifyDisabled": <true|false> indica si se debe desactivar el control SSL al comunicarse con el servidor de autorización. Oracle recomienda no definir esta opción en true porque 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.
- "maxCacheDurationInHours": <cache-time> especifica el número de horas (entre 1 y 24) que el gateway de API debe almacenar la respuesta en la caché desde el punto final de introspección.
- "additionalValidationPolicy": {"issuers": ...} especifica detalles adicionales para la validación de token:
  - <issuer-url> es la URL (o una cadena del texto) para un servidor de autorización que esté permitido en la reclamación de emisor (iss) de un JWT y que se utilizará para acceder al despliegue del API. Por ejemplo, para permitir que un JWT emitido por OCI IAM con dominios de identidad se utilice para acceder al despliegue de API, especifique https://identity.oraclecloud.com/. Puede especificar uno o varios servidores de autorización (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.
  - <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.
  - "verifyClaims": {...} especifica opcionalmente nombres y valores de reclamación adicionales para una o más reclamaciones adicionales que deben validarse 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 del siniestro que especifique puede ser un nombre del siniestro reservado, como el siniestro (sub) o un nombre del siniestro personalizado emitido por un servidor de autorización 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
Por ejemplo, la siguiente política authentication configura el gateway de API para validar un token en la cabecera de solicitud de autorización mediante credenciales de cliente (incluido un secreto de cliente recuperado de un almacén en el servicio Vault) transferido a un punto final de introspección de OAuth 2.0):
```
{
  "requestPolicies": {
    "authentication": {
      "type": "TOKEN_AUTHENTICATION",
      "tokenHeader": "Authorization",
      "tokenAuthScheme": "Bearer",
      "isAnonymousAccessAllowed": false,
      "maxClockSkewInSeconds": 10,
      "validationPolicy": {
        "type": "REMOTE_DISCOVERY",
        "clientDetails": {
          "type": "CUSTOM",
          "clientId": "5hsti38yhy5j2a4tas455rsu6ru8yui3wrst4n1",
          "clientSecretId": "ocid1.vaultsecret.oc1.iad.amaaaaaa______cggit3q",
          "clientSecretVersionNumber": 1
        },          
        "sourceUriDetails": {
          "type": "DISCOVERY_URI",
          "uri": "https://my-idp/oauth2/default/.well-known/openid-configuration"
        },
        "isSslVerifyDisabled": false,
        "maxCacheDurationInHours": 2,
        "additionalValidationPolicy": {
          "issuers": ["https://identity.oraclecloud.com/"],
          "audiences": ["api.dev.io"],
          "verifyClaims": [{
            "key": "is_admin",
            "values": ["service:app", "read:hello"],
            "isRequired": true
          }]
        }
      }
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```
Si desea que el gateway de API valide los JWT recuperando claves de verificación públicas del proveedor de identidad en tiempo de ejecución, agregue la siguiente política de validación a la sección validationPolicy vacía:
```
      "validationPolicy": {
        "type": "REMOTE_JWKS",
        "uri": "<uri-for-jwks>",
        "isSslVerifyDisabled": <true|false>,
        "maxCacheDurationInHours": <cache-time>,
        "additionalValidationPolicy": {
          "issuers": ["<issuer-url>", "<issuer-url>"],
          "audiences": ["<intended-audience>"],
          "verifyClaims": [{
            "key": "<claim-name>",
            "values": ["<acceptable-value>", "<acceptable-value>"],
            "isRequired": <true|false>
          }]
        }
      }
```
donde:
- "validationPolicy": {"type": "REMOTE_JWKS"... especifica que desea configurar el gateway de API para recuperar hasta diez claves de verificación públicas del proveedor de identidad en tiempo de ejecución.
- "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.
- "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 true porque 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.
- "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.
- "additionalValidationPolicy": {"issuers": ...} especifica detalles adicionales para la validación de token:
  - <issuer-url> es la URL (o una cadena del 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 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.
  - <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.
  - 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
Por ejemplo, la siguiente política authentication configura el gateway de API para validar el JWT en la cabecera de solicitud de autorización mediante la recuperación de claves de verificación públicas del proveedor de identidad en tiempo de ejecución:
```
{
  "requestPolicies": {
    "authentication": {
      "type": "TOKEN_AUTHENTICATION",
      "tokenHeader": "Authorization",
      "tokenAuthScheme": "Bearer",
      "isAnonymousAccessAllowed": false,
      "validationPolicy": {
        "type": "REMOTE_JWKS",
        "uri": "https://my-tenant-id.identity.oraclecloud.com/admin/v1/SigningCert/jwk",
        "isSslVerifyDisabled": false,
        "maxCacheDurationInHours": 2,
        "additionalValidationPolicy": {
          "issuers": ["https://identity.oraclecloud.com/"],
          "audiences": ["api.dev.io"],
          "verifyClaims": [{
            "key": "is_admin",
            "values": ["service:app", "read:hello"],
            "isRequired": true
          }]
        }
      }
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```
Si desea que el Gateway de API valide los JWT con claves de verificación públicas ya emitidas por un proveedor de identidad (lo que le permite al Gateway de API verificar los JWT localmente sin tener que contactar con el proveedor de identidad), agregue la siguiente política de validación a la sección validationPolicy vacía:
```
      "validationPolicy": {
        "type": "STATIC_KEYS",
        "keys": [{<key-config>}],
        "isSslVerifyDisabled": <true|false>,
        "maxCacheDurationInHours": <cache-time>,
        "additionalValidationPolicy": {
          "issuers": ["<issuer-url>", "<issuer-url>"],
          "audiences": ["<intended-audience>"],
          "verifyClaims": [{
            "key": "<claim-name>",
            "values": ["<acceptable-value>", "<acceptable-value>"],
            "isRequired": <true|false>
          }]
        }
      }
```
donde:
- "validationPolicy": {"type": "STATIC_KEYS"... especifica que desea configurar el gateway de API con hasta diez claves públicas de verificación ya emitidas por un proveedor de identidad (lo que le permite al gateway de API verificar el JWT localmente sin tener que ponerse en contacto con el proveedor de identidad).
- "keys": [{<key-config>}] especifica el identificador de la clave estática utilizada para firmar el JWT. 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:
```
        "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:
```
        "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.
- "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 true porque 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.
- "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.
- "additionalValidationPolicy": {"issuers": ...} especifica detalles adicionales para la validación de token:
  - <issuer-url> es la URL (o una cadena del 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 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.
  - <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.
  - 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
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": "TOKEN_AUTHENTICATION",
      "tokenHeader": "Authorization",
      "tokenAuthScheme": "Bearer",
      "isAnonymousAccessAllowed": false,
      "validationPolicy": {
        "type": "STATIC_KEYS",
        "keys": [
          {
            "format": "JSON_WEB_KEY",
            "kid": "master_key",
            "kty": "RSA",
            "n": "0vx7agoebGc...KnqDKgw",
            "e": "AQAB",
            "alg": "RS256",
            "use": "sig"
          }
        ],
        "isSslVerifyDisabled": false,
        "maxCacheDurationInHours": 2,
        "additionalValidationPolicy": {
          "issuers": ["https://identity.oraclecloud.com/"],
          "audiences": ["api.dev.io"],
          "verifyClaims": [{
            "key": "is_admin",
            "values": ["service:app", "read:hello"],
            "isRequired": true
          }]
        }
      }
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```
(Opcional) Puede especificar cómo desea que el gateway de API maneje una respuesta de autenticación fallida (devuelta después de un intento incorrecto de validar un token faltante o no válido) configurando una política de fallo de validación:
1. Si desea que el gateway de API envíe un código de estado HTTP 401 y la cabecera WWW-Authenticate en la respuesta (la respuesta por defecto a un token que falta o no es válido), no defina una política de fallo de validación.
2. Si desea que el gateway de API utilice un flujo de autorización de OpenID Connect para obtener un nuevo token de acceso de JWT, defina una política de fallo de validación de tipo OAUTH2. Tenga en cuenta que esta opción solo está disponible si ha especificado un validationPolicy de tipo REMOTE_DISCOVERY anteriormente. Especifique:
```
{
  "requestPolicies": {
    "authentication": {
      "type": "TOKEN_AUTHENTICATION",
      ...
      "validationPolicy": {
        "type": "REMOTE_DISCOVERY",
        ...
      },
      "validationFailurePolicy": {
        "type": "OAUTH2",
        "scopes": ["<scope>", "<scope"],
        "clientDetails": {
          "type": "<VALIDATION_BLOCK|CUSTOM>",
          "clientId": "<client-id>",
          "clientSecretId": "<secret-ocid>",
          "clientSecretVersionNumber": <secret-version-number>
          },
        "sourceUriDetails": {
          "type": "VALIDATION_BLOCK"
          },
        "maxExpiryDurationInHours": <number-of-hours>,
        "useCookiesForSession": <true|false>,
        "useCookiesForIntermediateSteps": <true|false>,
        "usePkce": <true|false>,
        "responseType": "code",
        "fallbackRedirectPath": "<redirect-path>",
        "logoutPath": "<logout-path>"
      }
    }
  },
  "routes": [
    ...
  ]
}
```
  donde:
  - "scopes": ["<scope>", "<scope"] especifica uno o más ámbitos de acceso que se deben incluir en una reclamación scope enviada al servidor de autorización. Para utilizar el flujo de autorización de OpenID Connect, debe incluir openid como uno de los ámbitos. Por ejemplo, "scopes": ["openid", "email:read", "profile"]
  - clientDetails": {...} especifica los detalles de cliente que se van a utilizar para obtener un nuevo token de acceso JWT del servidor de autorización, de la siguiente forma:
    - "type": "<VALIDATION_BLOCK|CUSTOM>" especifica si se deben utilizar los mismos detalles de cliente o diferentes a los especificados en validationPolicy anterior. Si desea utilizar los mismos detalles de cliente que antes (que suele ser el caso), especifique "type": "VALIDATION_BLOCK" y no proporcione detalles adicionales. Si desea utilizar diferentes detalles de cliente, especifique "type": "CUSTOM" y defina valores para "clientId", "clientSecretId" y "clientSecretVersionNumber".
    - "clientId": "<client-id>" especifica el ID de cliente que se va a enviar al punto final de introspección. Solo se utiliza si "type": "CUSTOM". Por ejemplo, 5hsti38yhy5j2a4tas455rsu6ru8yui3wrst4n1
    - "clientSecretId": "<secret-ocid>" especifica el OCID del secreto de almacén que contiene el secreto de cliente que se va a enviar al punto final de introspección. Solo se utiliza si "type": "CUSTOM". Por ejemplo, ocid1.vaultsecret.oc1.iad.amaaaaaa______cggit3q
    - "clientSecretVersionNumber": <secret-version-number> especifica la versión del secreto de almacén que contiene el secreto de cliente que se enviará al punto final de introspección. Solo se utiliza si "type": "CUSTOM". Por ejemplo, 1
  - "sourceUriDetails": {"type": "VALIDATION_BLOCK"} especifica que desea utilizar la misma URL que la especificada en la versión anterior validationPolicy que la URL conocida de un servidor de autorización desde el que el gateway de API va a obtener puntos finales de metadatos de autorización.
  - "maxExpiryDurationInHours": <number-of-hours> especifica el período de tiempo que se debe almacenar en caché el token de JWT generado por el flujo de autorización. El valor por defecto es 1.
  - "useCookiesForSession": <true|false> especifica cómo almacenar los tokens de JWT recién generados como cadenas no legibles por el usuario al final de un flujo de autorización de OpenID Connect:
    - Defina esta opción en true si desea almacenar el nuevo token de JWT en una cookie de sesión. Para evitar posibles ataques CSRF, cuando el gateway de API almacena el TOKEN en una cookie de sesión, también devuelve un TOKEN CSRF en una cabecera de respuesta X-CSRF-TOKEN. Las solicitudes posteriores (aparte de las solicitudes GET) deben incluir el TOKEN CSRF en una cabecera de solicitud X-CSRF-TOKEN, además del TOKEN JWT en la cookie de sesión que se incluye automáticamente.
    - Defina esta opción en false si no desea almacenar el nuevo token de JWT en una cookie de sesión. En su lugar, el gateway de API devuelve un TOKEN no legible para el usuario en una cabecera de respuesta X-APIGW-TOKEN. Las solicitudes posteriores al gateway de API deben incluir el mismo TOKEN en una cabecera de solicitud X-APIGW-TOKEN.
    Consulte Notas sobre la protección contra la falsificación de solicitudes entre sitios (CSRF)
  - "useCookiesForIntermediateSteps": <true|false> especifica cómo almacenar los valores de paso intermedio del flujo de autorización (por ejemplo, parámetros de solicitud). Defina esta opción en true para almacenar los valores en las cookies del explorador. Defina esta opción en false para almacenar los valores con el gateway de API.
  - "usePkce": <true|false> especifica si se debe utilizar PKCE (Clave de prueba para intercambio de código) para una seguridad adicional. PKCE es una extensión de seguridad OAuth 2.0 para evitar ataques de inyección de código de autorización y CSRF (Cross-Site Request Forgery). PKCE no sustituye a un secreto de cliente, y se recomienda PKCE incluso si se utiliza un secreto de cliente. Para obtener más información sobre PKCE, consulte la documentación de OAuth 2.0.
  - "responseType": "code" especifica el tipo de respuesta necesaria del flujo de autorización. Especifique code como tipo de respuesta.
  - "fallbackRedirectPath": "/home" también especifica una ruta de acceso relativa en el despliegue de API actual a la que redirigir clientes de API si la solicitud original era una solicitud PUT o una solicitud POST. Por ejemplo, /home.
    Si la solicitud original era una solicitud GET, el procesamiento de la solicitud se reanuda con un nuevo token de acceso JWT, por lo que no se utiliza una ruta de acceso de reserva.
  - "logoutPath": "<revoke-path>"opcionalmente especifica una ruta de acceso relativa a un backend de desconexión en el despliegue de API actual. La ruta que especifique debe coincidir con la ruta definida para el backend de desconexión. Por ejemplo, "logoutPath": "/revoke".
    Un cliente de API puede llamar al backend de desconexión para revocar tokens. Una llamada al backend de desconexión puede incluir una URL posterior a la desconexión como un parámetro de consulta denominado postLogoutUrl. Consulte Adición de desconexión como backend de gateway de API.
  Por ejemplo:
```
{
  "requestPolicies": {
    "authentication": {
      "type": "TOKEN_AUTHENTICATION",
      ...
      "validationPolicy": {
        "type": "REMOTE_DISCOVERY",
        ...
      },
      "validationFailurePolicy": {
        "type": "OAUTH2",
        "scopes": ["openid", "email:read", "profile"],
        "clientDetails": {
          "type": "VALIDATION_BLOCK"
          },
        "sourceUriDetails": {
          "type": "VALIDATION_BLOCK"
        },
        "maxExpiryDurationInHours": 2,
        "useCookiesForSession": true,
        "useCookiesForIntermediateSteps": true,
        "usePkce": true,
        "responseType": "code",
        "fallbackRedirectPath": "/home",
        "logoutPath": "/revoke"
      }
    }
  },
  "routes": [
    ...
  ]
}
```
3. Si desea personalizar la respuesta a un intento incorrecto de validar un token que falta o no es válido, defina una política de fallo de validación de tipo MODIFY_RESPONSE y especifique un código de estado (y un cuerpo de mensaje opcional) para volver al cliente de API, de la siguiente forma:
```
{
  "requestPolicies": {
    "authentication": {
      "type": "TOKEN_AUTHENTICATION",
      ...
      "validationPolicy": {
        ...
      },
      "validationFailurePolicy": {
        "type": "MODIFY_RESPONSE",
        "responseCode": "<alternative-response-code>",
        "responseMessage": "<custom-message-body>",
        "responseTransformations": {
          "headerTransformations": {
            <valid-header-transformation-response-policy>
          }
        }
      }
    }
  },
  "routes": [
    ...
  ]
}
```
  donde:
  - responseCode: especifica un código de estado HTTP alternativo. Por ejemplo, 500.
  - responseMessage: (opcionalmente) especifica un cuerpo de mensaje. Por ejemplo, Unfortunately, authentication failed. El cuerpo del mensaje puede incluir cualquier variable de contexto (excepto request.body).
  - responseTransformations: (opcionalmente) modifica las cabeceras de la respuesta que el gateway de API devuelve al cliente de API especificando una política de respuesta de transformación de cabecera. Para obtener más información sobre las políticas de transformación de cabecera, consulte Adición de políticas de respuesta de transformación de cabecera.
  Por ejemplo:
```
{
  "requestPolicies": {
    "authentication": {
      "type": "TOKEN_AUTHENTICATION",
      ...
      "validationPolicy": {
        ...
      },
      "validationFailurePolicy": {
        "type": "MODIFY_RESPONSE",
        "responseCode": "500",
        "responseMessage": "Unfortunately, authentication failed.",
      }
    }
  },
  "routes": [
    ...
  ]
}
```
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": "TOKEN_AUTHENTICATION",
      "tokenHeader": "Authorization",
      "tokenAuthScheme": "Bearer",
      "isAnonymousAccessAllowed": false,
      "validationPolicy": {
        "type": "STATIC_KEYS",
        "keys": [
          {
            "format": "JSON_WEB_KEY",
            "kid": "master_key",
            "kty": "RSA",
            "n": "0vx7agoebGc...KnqDKgw",
            "e": "AQAB",
            "alg": "RS256",
            "use": "sig"
          }
        ],
        "isSslVerifyDisabled": false,
        "maxCacheDurationInHours": 2,
        "additionalValidationPolicy": {
          "issuers": ["https://identity.oraclecloud.com/"],
          "audiences": ["api.dev.io"],
          "verifyClaims": [{
            "key": "is_admin",
            "values": ["service:app", "read:hello"],
            "isRequired": true
          }]
        }
      }
    }
  },
  "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 nueva sección requestPolicies:
```
      "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": "TOKEN_AUTHENTICATION",
      "tokenHeader": "Authorization",
      "tokenAuthScheme": "Bearer",
      "isAnonymousAccessAllowed": false,
      "validationPolicy": {
        "type": "STATIC_KEYS",
        "keys": [
          {
            "format": "JSON_WEB_KEY",
            "kid": "master_key",
            "kty": "RSA",
            "n": "0vx7agoebGc...KnqDKgw",
            "e": "AQAB",
            "alg": "RS256",
            "use": "sig"
          }
        ],
        "isSslVerifyDisabled": false,
        "maxCacheDurationInHours": 2,
        "additionalValidationPolicy": {
          "issuers": ["https://identity.oraclecloud.com/"],
          "audiences": ["api.dev.io"],
          "verifyClaims": [{
            "key": "is_admin",
            "values": ["service:app", "read:hello"],
            "isRequired": true
          }]
        }
      }
    }
  },
  "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
Guarde el archivo JSON que contiene la especificación de despliegue de API.
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.
(Opcional) Confirme que la API se ha desplegado correctamente llamándola. Para ello, consulte Llamada a una API desplegada en un gateway de API.

Documentación de Oracle Cloud Infrastructure

Edición de un archivo de JSON para agregar políticas de solicitud de autorización y autenticación de token