Adición de Políticas de Solicitud de Autenticación y Autorización para Tokens de Acceso de Argumento Único y Funciones de Autorizador

Agregue políticas de solicitud para proporcionar autenticación y autorización mediante tokens de acceso de un solo argumento y funciones de autorizador de un solo argumento.

Puede agregar políticas de solicitud mediante:

uso de la consola
edición de un archivo JSON

Nota

Oracle recomienda el uso de funciones de autorizador de varios argumentos en lugar de funciones de autorizador de un solo argumento debido a su versatilidad adicional. Las funciones de autorizador de un solo argumento se proporcionaron en versiones anteriores y siguen estando soportadas. Sin embargo, dado que las funciones de autorizador de varios argumentos también pueden aceptar tokens de acceso de un solo argumento incluidos en las cabeceras de solicitud y el parámetro de consulta, no hay razón para crear nuevas funciones de autorizador de un solo argumento. Además, las funciones de autorizador de un solo argumento están planificadas para desuso en futuras versiones.

Uso de la consola para agregar políticas de solicitud para autenticación y autorización de un solo argumento

Siga estos pasos a fin de agregar políticas de autorización y autenticación para tokens de acceso de un solo argumento a una especificación del despliegue del API mediante la consola:

Cree o actualice un despliegue del API con la consola, seleccione la opción Crear despliegue 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 del API mediante el despliegue de un despliegue de API y Actualización de un gateway del API.
Seleccione Siguiente para mostrar la página Autenticación.
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. También, 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.
Seleccione o anule la selección de Activar acceso anónimo para especificar si los usuarios finales no autenticados (es decir, anónimos) pueden acceder a rutas en el despliegue de la 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 tendrá que especificar explícitamente cada ruta de acceso anónimo en la que se permita el acceso anónimo seleccionando Anónimo en Tipo de Autorización, en la directiva de autorización de cada ruta.
Seleccione Función de autorizador en la lista de opciones Tipo de autenticación.
Especifique la función de autorizador de argumento único que se va a utilizar para autenticar el token de acceso de argumento único:
- Aplicación de Oracle Functions: nombre de la aplicación en OCI Functions que contiene la función de autorizador. Puede seleccionar una aplicación de otro compartimento.
- Function Name: nombre de la función del autorizador de OCI Functions.
Seleccione Función de autorizador de argumento único para especificar que desea transferir un token de acceso de argumento único en un parámetro de cabecera o consulta a una función de autorizador de argumento único.
En el panel Token de acceso, identifique el token de acceso que se va a utilizar para la autenticación:
- Ubicación de 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.
Seleccione Siguiente para introducir detalles para rutas individuales en el despliegue del API en el página Rutas.
Seleccione Agregar ruta y especifique la primera ruta al despliegue de API que asigna una ruta y uno o más 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: si se enrutan todas las solicitudes al mismo backend o se direccionan solicitudes a diferentes backends según la variable de contexto y las reglas que introduzca.
  
  En estas instrucciones se supone que desea utilizar un único backend, por lo que debe seleccionar Agregar un único backend. También, si desea utilizar backends diferentes, 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 un 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 puerta de enlace de API).
  - Respuesta de stock: en el caso de un backend de respuesta de stock, también debe especificar el código de estado HTTP, el contenido en el cuerpo de la respuesta y uno o más campos del encabezado HTTP (consulte Agregación de respuestas de stock como backend de puerta de enlace de API).
  - Cerrar sesión: para un backend de desconexión, también debe especificar una lista de URL permitidas a las que se puede redirigir una solicitud para revocar tokens y, opcionalmente, datos para transferir a la URL de desconexión (consulte Adición de desconexión como backend de gateway de API).
Para especificar una política de autorización que se aplique a una ruta individual, seleccione Mostrar políticas de solicitud de ruta, haga clic en el botón Agregar situado junto a Autorización y especifique:
- Tipo de autorización: cómo otorgar acceso a la ruta. Especifique:
  - Cualquiera: solo otorga acceso a usuarios finales que se hayan autenticado correctamente, siempre y cuando la función del autorizador también haya devuelto uno de los ámbitos que especifique en el campo Agregar ámbito permitido. En este caso, la opción Activar acceso análogo de las políticas 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 las políticas 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álogo de las políticas de autenticación no tiene ningún efecto.
- Añadir ámbito permitido: si ha seleccionado Cualquiera en tipo de autorización, introduzca una lista delimitada por comas de uno o varias cadenas correspondientes a las áreas de acceso que devuelve la función del 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 una directiva de autorización para una ruta concreta, se otorga el acceso como si esa directiva existiera y el 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álogo de las políticas 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
Seleccione Crear y, a continuación, seleccione Siguiente para revisar los detalles introducidos para el despliegue de API.
Seleccione Crear o Actualizar para crear o actualizar el despliegue de 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.

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

Siga estos pasos a fin de agregar políticas para solicitudes de autorización y autenticación para tokens de acceso de un solo argumento a una especificación de despliegue del API 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, un 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"
      }
    }
  ]
}
```
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 del 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"
      }
    }
  ]
}
```
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
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

Adición de Políticas de Solicitud de Autenticación y Autorización para Tokens de Acceso de Argumento Único y Funciones de Autorizador

Uso de la consola para agregar políticas de solicitud para autenticación y autorización de un solo argumento

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