Adición de políticas de solicitud de autenticación y autorización

Para agregar políticas de solicitud de autorización y autenticación para tokens de acceso de varios argumentos a una especificación de despliegue de API mediante la consola:

1. Cree o actualice un despliegue de API con la consola, seleccione la opción Desde cero e introduzca los detalles en la página Información básica.

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

2. Seleccione Siguiente para mostrar la página Autenticación.

3. Seleccione Autenticación única para especificar que desea utilizar un único servidor de autenticación para todas las solicitudes.

   En estas instrucciones, se asume que desea utilizar un único servidor de autenticación. Como alternativa, si desea utilizar varios servidores de autenticación, seleccione Autenticación múltiple y siga las instrucciones de Uso de la consola para agregar varios servidores de autenticación al mismo despliegue de API.

4. Seleccione o anule la selección de la casilla de control Activar acceso anónimo: para especificar si los usuarios finales no autenticados (es decir, anónimos) pueden acceder a rutas en el despliegue de API.

   Por defecto, esta opción no está seleccionada. Si desea que los usuarios anónimos no puedan acceder a rutas, no seleccione esta opción. Tenga en cuenta que si selecciona esta opción, también deberá especificar explícitamente cada ruta en la que se permite el acceso anónimo, seleccionando Anónimo como Tipo de autorización en la política de autorización de cada ruta.

5. Seleccione Función de autorizador en la lista de opciones Tipo de autenticación.
6. Especifique la función de autorizador de varios argumentos que se va a utilizar para autenticar el token de acceso de varios argumentos:
   • Aplicación de Oracle Functions en <compartment-name>: nombre de la aplicación en OCI Functions que contiene la función de autorizador. Puede seleccionar una aplicación de otro compartimento.
   • Nombre de función: nombre de la función de autorizador en OCI Functions.
7. Seleccione Función de autorizador de varios argumentos para especificar que desea transferir uno o más elementos de una solicitud como token de acceso a una función de autorizador que pueda aceptar tokens de acceso de varios argumentos.
8. En el panel Argumentos de función, especifique una o más variables de contexto que proporcionen valores para transferir a la función de autorizador como argumentos con nombres de argumentos que introduzca:
   1. Especifique una variable de contexto que proporcione un valor para transferir a la función de autorizador como argumento:
      • Tabla de contexto: seleccione la tabla de contexto que contiene la variable de contexto de la lista:
        • Tabla de contexto request.query, que contiene valores y nombres de parámetros de consulta incluidos en la solicitud
        • Tabla de contexto request.headers, que contiene los nombres y valores de cabecera incluidos en la solicitud
        • Tabla de contexto request.cert, que contiene una versión codificada con Base64 del certificado presentado por un cliente de API y validado correctamente durante un establecimiento de comunicación mTLS
        • Tabla de contexto request.host, que contiene el nombre del host al que se ha enviado la solicitud (extracción del campo de cabecera Host de la solicitud)
        • Tabla de contexto request.body, que contiene el cuerpo de la solicitud
      • Nombre de cabecera o Nombre de parámetro de consulta: si ha seleccionado la tabla de contexto request.headers o request.params, introduzca el nombre de la cabecera o parámetro de consulta que desea transferir a la función de autorizador. Por ejemplo, X-Api-Key, state.
      • Nombre de argumento: introduzca el nombre del argumento al que desea asignar el valor de la variable de contexto. El argumento se transfiere a la función de autorizador. El nombre de argumento que introduzca debe corresponder al nombre de argumento que la función de autorizador espera recibir.
   2. Especifique argumentos y variables de contexto adicionales según sea necesario (seleccione Otro argumento si es necesario).

9. Opcionalmente, personalice cómo almacenar en caché la respuesta desde una función de autorizador de varios argumentos:

   1. Seleccione Mostrar Opciones Avanzadas.

      El panel Almacenamiento en caché de resultados de función muestra qué argumentos están presentes en la clave de caché. La clave de caché identifica de forma única la respuesta almacenada en caché devuelta por la función de autorizador mediante argumentos y valores de argumento transferidos en la solicitud de autenticación original. Por defecto, todos los argumentos y valores de argumento (excepto para un argumento con un valor de la tabla de contexto request.body) que ha especificado para transferir a la función de autorizador se utilizan para crear la clave de caché.

   2. Para agregar o eliminar argumentos de la clave de caché, seleccione Editar.
   3. Seleccione o anule la selección de los argumentos transferidos a la función de autorizador para incluirlos o excluirlos de la clave de caché.

   Consulte Notas sobre el Almacenamiento en Caché de Resultados de Funciones de Autorizador de Varios Argumentos.

10. Opcionalmente, puede personalizar cómo manejar una respuesta de autenticación fallida desde una función de autorizador de varios argumentos mediante la configuración de una política de fallo de validación:

    1. Seleccione Mostrar Opciones Avanzadas.

       El panel Respuesta personalizada para autenticación fallida muestra el código de estado HTTP y el cuerpo del mensaje que se devolverán al cliente de API si la función de autorizador no puede autenticar la solicitud. Por defecto, el gateway de API envía un código de estado HTTP 401 y la cabecera WWW-Authenticate en la respuesta. Consulte Notas sobre las políticas de fallos de validación y el manejo de respuestas de autenticación con fallos de funciones de autorizador de varios argumentos.

    2. Especifique un código de estado (y un cuerpo de mensaje opcional) para volver al cliente de API si la función de autorizador no puede autenticar la solicitud:
       • Código de estado HTTP: introduzca un código de estado HTTP alternativo (por ejemplo, 500). También puede incluir una variable de contexto para devolver el código devuelto por la función de autorizador. Por ejemplo, si la función de autorizador devuelve un código de respuesta en el parámetro responseCode, especifique request.auth[responseCode].
       • Cuerpo del mensaje: introduzca un cuerpo del mensaje. Por ejemplo, Unfortunately, authentication failed.El cuerpo del mensaje puede incluir cualquier variable de contexto (excepto request.body). Por ejemplo, Unfortunately, authentication failed ${request.auth[my-auth-variable]}.

    3. Opcionalmente, modifique las cabeceras de la respuesta que devuelve el gateway de API al cliente de API seleccionando Mostrar opciones avanzadas y especificando una política de respuesta de transformación de cabecera:

       • Para limitar las cabeceras incluidas en una respuesta, especifique:

         • Acción: filtrar.
         • Tipo: Bloquear para eliminar de la respuesta las cabeceras que muestra explícitamente o Permitir para permitir en la respuesta solo las cabeceras que muestra explícitamente (cualquier otra cabecera se elimina de la respuesta).
         • Nombres de cabecera: lista de cabeceras que se deben eliminar de la respuesta o permitir en la respuesta (según la configuración del Tipo). Los nombres que especifique no son sensibles a mayúsculas/minúsculas y no se deben incluir en ninguna otra política de respuesta de transformación para la ruta (con la excepción de los elementos que filtra según lo permitido). Por ejemplo, User-Agent.

       • Para cambiar el nombre de una cabecera incluida en una respuesta (manteniendo su valor original), especifique:

         • Acción: cambiar nombre.
         • Nombre de cabecera: el nombre original de la cabecera a la que está cambiando el nombre. El nombre especificado no es sensible a mayúsculas/minúsculas y no se debe incluir en ninguna otra política de respuesta de transformación para la ruta. Por ejemplo, X-Username.
         • Nuevo nombre de cabecera: el nombre nuevo de la cabecera a la que le va a cambiar de nombre. El nombre especificado no es sensible a mayúsculas/minúsculas (se pueden ignorar las mayúsculas) y no se debe incluir en ninguna otra política de respuesta de transformación para la ruta (con la excepción de los elementos de las listas ALLOW). Por ejemplo, X-User-ID.

       • Para agregar una nueva cabecera a una respuesta (o para cambiar o retener los valores de una cabecera existente ya incluida en una respuesta), especifique:

         • Acción: definir.

         • Comportamiento: si la cabecera ya existe, especifique qué hacer con el valor existente de la cabecera:

           • Sobrescribir para sustituir el valor existente de la cabecera por el valor especificado.
           • Agregar para agregar el valor especificado al valor existente de la cabecera.
           • Omitir para mantener el valor existente de la cabecera.
         • Nombre de cabecera: nombre de la cabecera que se va a agregar a la respuesta (o para cambiar el valor). El nombre que especifique no es sensible a mayúsculas/minúsculas y no se debe incluir en ninguna otra política de respuesta de transformación para la ruta (con la excepción de los elementos que filtra según lo permitido). Por ejemplo, X-Api-Key.
         • Valores: el valor de la nueva cabecera (o el valor que se va a sustituir o agregar al valor de una cabecera existente, según la configuración de Comportamiento). Puede especificar varios valores. El valor que especifique puede ser una cadena simple o puede incluir variables de contexto (excepto request.body) entre delimitadores ${...}. Por ejemplo, "value": "zyx987wvu654tsu321".

       Para obtener más información sobre las políticas de respuesta de transformación de cabecera, consulte Adición de Políticas de Respuesta de Transformación de Cabecera

11. Seleccione Siguiente para introducir detalles de rutas individuales en el despliegue de API en la página Rutas.

12. En la sección Ruta 1, especifique la primera ruta del despliegue de API que asigna una ruta de acceso y uno o varios métodos a un servicio de backend:

    • Ruta de acceso: ruta de acceso al servicio de backend para llamadas de API mediante los métodos enumerados. Tenga en cuenta que la ruta de acceso especificada:

      • Es relativa al prefijo de ruta de acceso de despliegue.
      • Debe estar precedida de una barra inclinada (/) y puede ser simplemente esa barra inclinada.
      • Puede contener varias barras inclinadas (siempre que no sean adyacentes) y puede terminar con una barra inclinada.
      • Puede incluir caracteres alfanuméricos en mayúscula y minúscula.
      • Puede incluir los caracteres especiales $ - _ . + ! * ' ( ) , % ; : @ & = .
      • Puede incluir parámetros y comodines (consulte Agregación de parámetros de ruta y comodines a rutas de acceso).
    • Métodos: uno o más métodos aceptados por el servicio backend, separados por comas. Por ejemplo, GET, PUT.

    • Agregar un único backend o Agregar varios backends: indica si se deben enrutar todas las solicitudes al mismo backend o si se deben enrutar a diferentes backends según la variable de contexto y las reglas introducidas.

      En estas instrucciones se supone que desea utilizar un único backend, por lo que seleccione Agregar un único backend. Como alternativa, si desea utilizar diferentes backends, seleccione Agregar varios backends y siga las instrucciones de Uso de la consola para agregar una selección de backend dinámica a una especificación de despliegue de API.

    • Tipo de backend: tipo del servicio de backend, como uno de los siguientes:
      • HTTP: para un backend HTTP, también debe especificar una URL, detalles de timeout, e indicar si se va a desactivar la verificación SSL (consulte Agregación de una URL de HTTP o HTTPS como un backend de gateway de API).
      • Oracle Functions: para el backend de OCI Functions, también debe especificar la aplicación y la función (consulte Agregación de una función en OCI Functions como backend de gateway de API).
      • Respuesta de stock: para un backend de respuesta de stock, también debe especificar el código de estado HTTP, el contenido del cuerpo de la respuesta y uno o varios campos de cabecera HTTP (consulte Agregación de respuestas de stock como backend de gateway de API).

13. Para especificar una política de autorización que se aplique a una ruta individual, seleccione Show Route Request Policies y seleccione el botón Add situado junto a Authorization y especifique:

    • Tipo de autorización: indica cómo otorgar acceso a la ruta. Especifique:

      • Cualquiera: solo otorga acceso a usuarios finales que se han autenticado correctamente, siempre que la función de autorizador también haya devuelto uno de los ámbitos de acceso especificados en el campo Ámbito permitido. En este caso, la opción Activar acceso anónimo de la política de autenticación no tiene ningún efecto.
      • Anónimo: otorga acceso a todos los usuarios finales, incluso si la función de autorizador no los ha autenticado correctamente. En este caso, debe haber seleccionado la opción Activar acceso anónimo de la política de autenticación.
      • Solo autenticación: solo otorga acceso a los usuarios finales que la función de autorizador haya autenticado correctamente. En este caso, la opción Activar acceso anónimo de la política de autenticación no tiene ningún efecto.
    • Ámbito permitido: si ha seleccionado Cualquiera como Tipo de autorización, introduzca una lista delimitada por comas de una o varias cadenas correspondientes a los ámbitos de acceso que devuelve la función de autorizador. Solo se otorgará acceso a los usuarios finales autenticados correctamente si la función de autorizador devuelve uno de los ámbitos de acceso especificados. Por ejemplo, read:hello
    Nota
    
    

    Si no incluye ninguna política de autorización para una ruta concreta, se otorga el acceso como si esa política existiera y Tipo de autorización se define en Solo autenticación. Es decir, con independencia de la configuración de la opción Activar acceso anónimo de la política de autenticación:

    • 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 devueltos por la función de autorizador
    • los usuarios finales anónimos no pueden acceder a la ruta
14. Seleccione Aplicar cambios y, a continuación, seleccione Siguiente para revisar los detalles introducidos para el despliegue de API.
15. Seleccione Crear o Guardar cambios para crear o actualizar el despliegue de API.
16. (Opcional) Confirme que la API se ha desplegado correctamente llamándola. Para ello, consulte Llamada a una API desplegada en un gateway de API.

Para agregar políticas de solicitud de autorización y autenticación para tokens de acceso de varios argumentos a una especificación de despliegue de API en un archivo JSON:

1. 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 básica de despliegue de API define una función sencilla de 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"
         }
       }
     ]
   }

2. 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": "<type-value>",
            "isAnonymousAccessAllowed": <true|false>,
            "functionId": "<function-ocid>",
            "parameters": {
              "<argument-n>": "<context-variable>",
              "<argument-n>": "<context-variable>",
              "<argument-n>": "<context-variable>"
            },
            "cacheKey": [
              "<cache-key-argument-n>", "<cache-key-argument-n>"
            ]
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            }
          }
        ]
      }

      donde:

      • <type-value> es el tipo de autenticación. Para utilizar una función de autorizador para la autenticación, especifique CUSTOM_AUTHENTICATION.
      • "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.
      • <function-ocid> es el OCID de la función de autorizador desplegada en OCI Functions.
      • <argument-n> es el nombre del argumento al que asignar el valor de una variable de contexto y solo una. El argumento se pasa a la función de autorizador. El nombre de argumento que introduzca debe corresponder al nombre de argumento que la función de autorizador espera recibir. Puede incluir varios pares de variables argumento-contexto.
      • <context-variable> es una variable de contexto cuyo valor desea asignar al argumento correspondiente. <context-variable> debe tener el formato <context-table-name> o <context-table-name>[<key>], donde <context-table-name> es uno de los siguientes:
        • request.query, una tabla de contexto que contiene nombres y valores de parámetros de consulta incluidos en la solicitud. Si desea especificar un parámetro de consulta, debe especificar la tabla de contexto request.query y el nombre del parámetro de consulta como clave, con el formato request.query[<query-parameter-name>]. Por ejemplo, request.query[state]
        • request.headers, una tabla de contexto que contiene nombres de cabecera y valores incluidos en la solicitud. Si desea especificar una cabecera, debe especificar la tabla de contexto request.headers y el nombre de la cabecera como clave, con el formato request.headers[<header-name>]. Por ejemplo, request.headers[X-Api-Key]
        • Tabla de contexto request.cert, que contiene una versión codificada con Base64 del certificado presentado por un cliente de API y validado correctamente durante un establecimiento de comunicación mTLS
        • request.host, tabla de contexto que contiene el nombre del host al que se ha enviado la solicitud (extracción del campo de cabecera Host de la solicitud)
        • request.body, una tabla de contexto que contiene el cuerpo de la solicitud.
      • "cacheKey": ["<cache-key-argument-n>", "<cache-key-argument-n>"] restringe opcionalmente la clave de caché a utilizar sólo los argumentos especificados. La clave de caché identifica de forma única la respuesta en caché devuelta desde la función de autorizador, mediante argumentos y valores de argumento transferidos en la solicitud de autenticación original. Por defecto, todos los argumentos y valores de argumento (excepto un argumento con un valor de la tabla de contexto request.body) de la lista parameters: {…} se utilizan para crear la clave de caché. Un argumento que especifique para <cache-key-argument-n> debe ser uno de los argumentos de la lista parameters: {…}. Consulte Notas sobre el Almacenamiento en Caché de Resultados de Funciones de Autorizador de Varios Argumentos.
   3. Opcionalmente, agregue validationFailurePolicy a la sección de política authentication:

      {
        "requestPolicies": {
          "authentication": {
            "type": "<type-value>",
            "isAnonymousAccessAllowed": <true|false>,
            "functionId": "<function-ocid>",
            "parameters": {
              "<argument-n>": "<context-variable>",
              "<argument-n>": "<context-variable>",
              "<argument-n>": "<context-variable>"
            },
            "cacheKey": [
              "<cache-key-argument-n>", "<cache-key-argument-n>"
            ],
            "validationFailurePolicy": {
              "type": "MODIFY_RESPONSE",
              "responseCode": "<alternative-response-code>",
              "responseMessage": "<custom-message-body>",
              "responseTransformations": {
                "headerTransformations": {
                  <valid-header-transformation-response-policy>
                }
              }
            }
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            }
          }
        ]
      }

      donde:

      • "validationFailurePolicy": {…} permite, de forma opcional, cambiar el código de estado HTTP, el cuerpo del mensaje y las cabeceras en la respuesta al cliente de API si la función de autorizador no puede autenticar una solicitud. Por defecto, el gateway de API envía un código de estado HTTP 401 y la cabecera WWW-Authenticate en la respuesta. Consulte Notas sobre políticas de fallos de validación y manejo de respuestas de autenticación fallidas desde funciones de autorizador de varios argumentos.
      • <policy-type> es el tipo de política de fallos de validación. Para modificar la respuesta, especifique MODIFY_RESPONSE.
      • "responseCode": "<alternative-response-code>" especifica un código de estado HTTP alternativo. Por ejemplo, "responseCode": "500". También puede incluir una variable de contexto para devolver el código devuelto por la función de autorizador. Por ejemplo, si la función de autorizador devuelve un código de respuesta en el parámetro responseCode, especifique "request.auth[responseCode]".
      • "responseMessage": "<custom-message-body>" especifica el contenido que se va a incluir en el cuerpo del mensaje. Por ejemplo, "responseMessage": "Unfortunately, authentication failed.". El cuerpo del mensaje puede incluir cualquier variable de contexto (excepto request.body). Por ejemplo, "responseMessage": "Unfortunately, authentication failed ${request.auth[my-auth-variable]}".
      • "headerTransformations": {<valid-header-transformation-response-policy>} es una política de respuesta de transformación de cabecera válida. Consulte Edición de un archivo JSON para agregar políticas de respuesta de transformación de cabecera.

3. 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": "CUSTOM_AUTHENTICATION",
            .
            .
            .
          }
        },
        "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": "CUSTOM_AUTHENTICATION",
            .
            .
            .
          }
        },
        "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 función de autorizador haya devuelto también uno de los ámbitos de acceso especificados 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 devueltos por la función de autorizador. 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 la función de autorizador devuelve alguno de los ámbitos especificados.

      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": "CUSTOM_AUTHENTICATION",
            .
            .
            .
          }
        },
        "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 devueltos por la función de autorizador
   • los usuarios finales anónimos no pueden acceder a la ruta
4. Guarde el archivo JSON que contiene la especificación de despliegue de API.

5. 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.
   • 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 de API mediante la creación de un despliegue de API y Actualización de un gateway de API.

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

La siguiente especificación de despliegue de API define:

• Política de solicitud de autenticación que llama a una función de autorizador de varios argumentos para realizar la autenticación.
• Una política de solicitud de autorización que especifica lo que pueden hacer los usuarios finales autenticados.

{
  "requestPolicies": {
    "authentication": {
      "type": "CUSTOM_AUTHENTICATION",
      "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaac2______kg6fq",
      "isAnonymousAccessAllowed": true,
      "parameters": {
        "xapikey": "request.headers[X-Api-Key]",
        "referer": "request.headers[Referer]",
        "state": "request.query[state]",
        "city": "request.query[city]",
        "cert": "request.cert",
        "body": "request.body",
        "host": "request.host"
        },
      "cacheKey": [
        "xapikey", "referer"
        ],
      "validationFailurePolicy": {
        "type": "MODIFY_RESPONSE",
        "responseCode": "request.auth[responseCode]",
        "responseMessage": "Unfortunately, authentication failed.",
        "responseTransformations": {
        "headerTransformations": {
          "setHeaders": {
            "items": [
              {
                "name": "Location",
                "values": [
                  "${request.auth[location]}"
                  ]
                }
              ]
            },
          "filterHeaders": {
            "type": "BLOCK",
            "items": [
              {
                "name": "topSecret"
                }
              ]
            }
          }
        }
      }
    }
  },
  "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" ]
        }
      }
    }
  ]
}

La política de solicitud de autenticación en esta especificación de despliegue de API:

• Especifica la función de autorizador de varios argumentos a la que llamar para realizar la autenticación y define los argumentos xapikey, referer, state, city, cert, body y host para transferir a la función de autorizador. Los valores de estos argumentos se obtienen de variables de contexto que tienen valores de la solicitud original.
• Define una clave de caché personalizada para identificar de forma única la respuesta en caché devuelta por la función de autorizador. En lugar de utilizar la clave de caché por defecto (que incluye todos los argumentos enviados a la función de autorizador y se recomienda), esta política de solicitud de autenticación especifica que la clave de caché debe incluir solo los valores de los argumentos xapikey y referrer transferidos a la función de autorizador.
• Incluye una política de fallo de validación que modifica la respuesta de fallo de validación por defecto para sustituir el código de estado HTTP 401 por defecto por el valor de la variable de contexto request.auth[responseCode]. La variable de contexto request.auth[responseCode] tiene el valor de un parámetro de autenticación (en este caso, denominado responseCode) devuelto por la función de autorizador. Del mismo modo, el mensaje de fallo de validación por defecto se sustituye por una cadena de mensaje personalizada ("Unfortunately, authentication failed.").
• Incluye una política de solicitud de transformación de cabecera dentro de la política de fallo de validación que agrega la cabecera location a la respuesta de fallo de validación. La cabecera location tiene el valor de la variable de contexto request.auth[location], que tiene el valor de un parámetro de autenticación (en este caso, denominado location) devuelto por la función de autorizador. La política de solicitud de transformación de cabecera también elimina las cabeceras denominadas topSecret de la respuesta.

La política de solicitud de autorización de esta especificación de despliegue de API solo permite a los usuarios finales autenticados por la función de autorizador y con el ámbito read:hello acceder a la ruta /hello.

Para agregar políticas de solicitud de autorización y autenticación para tokens de acceso de un solo argumento a una especificación de despliegue de API mediante la consola:

1. Cree o actualice un despliegue de API con la consola, seleccione la opción Desde cero e introduzca los detalles en la página Información básica.

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

2. Seleccione Siguiente para mostrar la página Autenticación.

3. Seleccione Autenticación única para especificar que desea utilizar un único servidor de autenticación para todas las solicitudes.

   En estas instrucciones, se asume que desea utilizar un único servidor de autenticación. Como alternativa, si desea utilizar varios servidores de autenticación, seleccione Autenticación múltiple y siga las instrucciones de Uso de la consola para agregar varios servidores de autenticación al mismo despliegue de API.

4. Seleccione o anule la selección de la casilla de control Activar acceso anónimo: para especificar si los usuarios finales no autenticados (es decir, anónimos) pueden acceder a rutas en el despliegue de API.

   Por defecto, esta opción no está seleccionada. Si desea que los usuarios anónimos no puedan acceder a rutas, no seleccione esta opción. Tenga en cuenta que si selecciona esta opción, también deberá especificar explícitamente cada ruta en la que se permite el acceso anónimo, seleccionando Anónimo como Tipo de autorización en la política de autorización de cada ruta.

5. Seleccione Función de autorizador en la lista de opciones Tipo de autenticación.
6. Especifique la función de autorizador de un argumento que se utilizará para autenticar el token de acceso de un argumento:
   • Aplicación de Oracle Functions en <compartment-name>: nombre de la aplicación en OCI Functions que contiene la función de autorizador. Puede seleccionar una aplicación de otro compartimento.
   • Nombre de función: nombre de la función de autorizador en OCI Functions.
7. Seleccione Función de autorizador de un solo argumento para especificar que desea transferir un token de acceso de un solo argumento en un parámetro de cabecera o consulta a una función de autorizador de un solo argumento.
8. En el panel Token de acceso, identifique el token de acceso que se utilizará para la autenticación:
   • Ubicación del token: seleccione Cabecera o Parámetro de consulta para especificar la ubicación del token de acceso en la solicitud.
   • Nombre de cabecera de token o Nombre de parámetro de token: según la ubicación del token de acceso, introduzca el nombre de la cabecera o el parámetro de consulta que contiene el token de acceso.

9. Seleccione Siguiente para introducir detalles de rutas individuales en el despliegue de API en la página Rutas.

10. En la sección Ruta 1, especifique la primera ruta del despliegue de API que asigna una ruta de acceso y uno o varios métodos a un servicio de backend:

    • Ruta de acceso: ruta de acceso al servicio de backend para llamadas de API mediante los métodos enumerados. Tenga en cuenta que la ruta de acceso especificada:

      • Es relativa al prefijo de ruta de acceso de despliegue.
      • Debe estar precedida de una barra inclinada (/) y puede ser simplemente esa barra inclinada.
      • Puede contener varias barras inclinadas (siempre que no sean adyacentes) y puede terminar con una barra inclinada.
      • Puede incluir caracteres alfanuméricos en mayúscula y minúscula.
      • Puede incluir los caracteres especiales $ - _ . + ! * ' ( ) , % ; : @ & = .
      • Puede incluir parámetros y comodines (consulte Agregación de parámetros de ruta y comodines a rutas de acceso).
    • Métodos: uno o más métodos aceptados por el servicio backend, separados por comas. Por ejemplo, GET, PUT.

    • Agregar un único backend o Agregar varios backends: indica si se deben enrutar todas las solicitudes al mismo backend o si se deben enrutar a diferentes backends según la variable de contexto y las reglas introducidas.

      En estas instrucciones se supone que desea utilizar un único backend, por lo que seleccione Agregar un único backend. Como alternativa, si desea utilizar diferentes backends, seleccione Agregar varios backends y siga las instrucciones de Uso de la consola para agregar una selección de backend dinámica a una especificación de despliegue de API.

    • Tipo de backend: tipo del servicio de backend, como uno de los siguientes:
      • HTTP: para un backend HTTP, también debe especificar una URL, detalles de timeout, e indicar si se va a desactivar la verificación SSL (consulte Agregación de una URL de HTTP o HTTPS como un backend de gateway de API).
      • Oracle Functions: para el backend de OCI Functions, también debe especificar la aplicación y la función (consulte Agregación de una función en OCI Functions como backend de gateway de API).
      • Respuesta de stock: para un backend de respuesta de stock, también debe especificar el código de estado HTTP, el contenido del cuerpo de la respuesta y uno o varios campos de cabecera HTTP (consulte Agregación de respuestas de stock como backend de gateway de API).

11. Para especificar una política de autorización que se aplique a una ruta individual, seleccione Show Route Request Policies y seleccione el botón Add situado junto a Authorization y especifique:

    • Tipo de autorización: indica cómo otorgar acceso a la ruta. Especifique:

      • Cualquiera: solo otorga acceso a usuarios finales que se han autenticado correctamente, siempre que la función de autorizador también haya devuelto uno de los ámbitos de acceso especificados en el campo Ámbito permitido. En este caso, la opción Activar acceso anónimo de la política de autenticación no tiene ningún efecto.
      • Anónimo: otorga acceso a todos los usuarios finales, incluso si la función de autorizador no los ha autenticado correctamente. En este caso, debe haber seleccionado la opción Activar acceso anónimo de la política de autenticación.
      • Solo autenticación: solo otorga acceso a los usuarios finales que la función de autorizador haya autenticado correctamente. En este caso, la opción Activar acceso anónimo de la política de autenticación no tiene ningún efecto.
    • Ámbito permitido: si ha seleccionado Cualquiera como Tipo de autorización, introduzca una lista delimitada por comas de una o varias cadenas correspondientes a los ámbitos de acceso que devuelve la función de autorizador. Solo se otorgará acceso a los usuarios finales autenticados correctamente si la función de autorizador devuelve uno de los ámbitos de acceso especificados. Por ejemplo, read:hello
    Nota
    
    

    Si no incluye ninguna política de autorización para una ruta concreta, se otorga el acceso como si esa política existiera y Tipo de autorización se define en Solo autenticación. Es decir, con independencia de la configuración de la opción Activar acceso anónimo de la política de autenticación:

    • 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 devueltos por la función de autorizador
    • los usuarios finales anónimos no pueden acceder a la ruta
12. Seleccione Siguiente para revisar los detalles introducidos para el despliegue de API.
13. Seleccione Crear o Guardar cambios para crear o actualizar el despliegue de API.
14. (Opcional) Confirme que la API se ha desplegado correctamente llamándola. Para ello, consulte Llamada a una API desplegada en un gateway de API.

Pasos para agregar políticas de solicitud de autorización y autenticación para tokens de acceso de argumento único a una especificación de despliegue de API en un archivo JSON:

1. 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 básica de despliegue de API define una función sencilla de 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"
         }
       }
     ]
   }

2. 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": "<type-value>",
            "isAnonymousAccessAllowed": <true|false>,
            "functionId": "<function-ocid>",
            <"tokenHeader"|"tokenQueryParam">: <"<token-header-name>"|"<token-query-param-name>">
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            }
          }
        ]
      }

      donde:

      • <type-value> es el tipo de autenticación. Para utilizar una función de autorizador para la autenticación, especifique CUSTOM_AUTHENTICATION.
      • "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.
      • <function-ocid> es el OCID de la función de autorizador desplegada en OCI Functions.
      • <"tokenHeader"|"tokenQueryParam">: <"<token-header-name>"|"<token-query-param-name>"> indica si se trata de una cabecera de solicitud que contiene el token de acceso (y, si lo contiene, también indica el nombre de la cabecera) o un parámetro de consulta que contiene el token de acceso (y, si lo contiene, también indica el nombre del parámetro de consulta). Tenga en cuenta que puede especificar "tokenHeader": "<token-header-name>" o "tokenQueryParam": "<token-query-param-name>">, pero no los dos.

      Por ejemplo, la siguiente política authentication especifica una función de OCI que validará el token de acceso en la cabecera de solicitud de autorización:

      {
        "requestPolicies": {
          "authentication": {
            "type": "CUSTOM_AUTHENTICATION",
            "isAnonymousAccessAllowed": false,
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaac2______kg6fq",
            "tokenHeader": "Authorization"
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            }
          }
        ]
      }

3. 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": "CUSTOM_AUTHENTICATION",
            "isAnonymousAccessAllowed": false,
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaac2______kg6fq",
            "tokenHeader": "Authorization"
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
               "type": "ORACLE_FUNCTIONS_BACKEND",
               "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            },
            "requestPolicies": {}
          }
        ]
      }

   2. Agregue la siguiente política authorization a la sección requestPolicies:

      {
        "requestPolicies": {
          "authentication": {
            "type": "CUSTOM_AUTHENTICATION",
            "isAnonymousAccessAllowed": false,
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaac2______kg6fq",
            "tokenHeader": "Authorization"
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            },
            "requestPolicies": {
              "authorization": {
                "type": <"AUTHENTICATION_ONLY"|"ANY_OF"|"ANONYMOUS">, 
                "allowedScope": [ "<scope>" ]
              }
            }
          }
        ]
      }

      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 función de autorizador haya devuelto también uno de los ámbitos de acceso especificados 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 devueltos por la función de autorizador. 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 la función de autorizador devuelve alguno de los ámbitos especificados.

      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": "CUSTOM_AUTHENTICATION",
            "isAnonymousAccessAllowed": false,
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaac2______kg6fq",
            "tokenHeader": "Authorization"
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            },
            "requestPolicies": {
              "authorization": {
                "type": "ANY_OF",
                "allowedScope": [ "read:hello" ]
              }
            }
          }
        ]
      }

   3. 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 devueltos por la función de autorizador
   • los usuarios finales anónimos no pueden acceder a la ruta
4. Guarde el archivo JSON que contiene la especificación de despliegue de API.

5. 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.
   • 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 de API mediante la creación de un despliegue de API y Actualización de un gateway de API.

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