Documentación de Oracle Cloud Infrastructure

Uso de la Consola para Agregar Políticas de Solicitud de Autorización y Autenticación de Token

Siga estos pasos para añadir políticas del pedido de autorización y autenticación a una especificación de despliegue del API mediante la consola.

  1. 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.

  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. 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.

  4. 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 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 Autenticación de token en la lista de opciones Tipo de autenticación y especifique:
    • Ubicación de token: indica si los tokens están incluidos en una cabecera de solicitud o en un parámetro de consulta.

    • Detalles de token de autenticación: según si los tokens están incluidos en una cabecera de solicitud o un parámetro de consulta, especifique:

      • Nombre de cabecera de token: y Esquema de autenticación: si los tokens están contenidos en una cabecera de solicitud, introduzca el nombre de la cabecera (por ejemplo Authorization) y la autenticación HTTP (actualmente solo soporta Bearer).
      • Nombre de parámetro del token: si los tokens están incluidos en un parámetro, introduzca el nombre del parámetro del parámetro.
  6. Especifique cómo desea que el gateway de API valide los tokens:

    1. Si desea que el gateway de API valide tanto tokens JWT como 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), seleccione Punto final de introspección de OAuth 2.0 en la lista Tipo y especifique:

      • ID de cliente: ID de cliente que se 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.
      • Almacén: nombre de un almacén en el servicio Vault que contiene el secreto de cliente que se va a enviar al punto final de introspección, desde la lista de almacenes del compartimento especificado. Para obtener un secreto de cliente, cree y registre una aplicación cliente con el servidor de autorización. Consulte Requisitos para la autenticación de token.
      • Secreto de almacén en <nombre de compartimento>: nombre de un secreto de almacén que contiene el secreto de cliente que se enviará al punto final de introspección, desde la lista de secretos de almacén en el compartimento especificado.
      • Número de versión del secreto de almacén: versión del secreto de almacén que contiene el secreto de cliente que se enviará al punto final de introspección.
      • URL de detección: URL conocida del 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.

      • Duración máxima de la caché en horas: número de horas (entre 1 y 24) que el gateway de API debe almacenar en la caché la respuesta desde el punto final de introspección.
      • Sesgo máximo de reloj en segundos: (opcional) diferencia de tiempo máxima entre los relojes del sistema del servidor de autorización que emitió un token y el gateway de API. El valor introducido aquí se tiene en cuenta cuando el gateway de API valida un 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, 120.
      • Desactivar Verificación SSL: indica si se deben desactivar las verificaciones SSL al comunicarse con el servidor de autorización. Por defecto, esta opción no está seleccionada. Oracle recomienda no seleccionar esta opción porque puede comprometer la validación de token. 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.

    2. 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, seleccione JWKS remoto en la lista Tipo y especifique:

      • URI JWKS: URI desde el que se va a utilizar el juego de claves web JSON (JWKS) para verificar la firma en los JWT. Por ejemplo, https://www.somejwksprovider.com/oauth2/v3/certs. 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.
      • Duración máxima de la caché en horas: el número de horas (entre 1 y 24) que el gateway de API debe almacenar en la caché el JWKS después de recuperarlo.
      • Sesgo máximo de reloj en segundos: (opcional) diferencia de tiempo máxima entre los relojes del sistema del servidor de autorización que emitió un token y el gateway de API. El valor introducido aquí se tiene en cuenta cuando el gateway de API valida un 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, 120.
      • Desactivar Verificación SSL: Indica si se debe desactivar la verificación de SSL al comunicarse con el proveedor de identidad. Por defecto, esta opción no está seleccionada. Oracle recomienda no seleccionar esta opción 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.

    3. Si desea que el gateway del API valide los JWT con claves de verificación públicas ya emitidas por un proveedor del identidad (lo que le permite al gateway del API verificar los JWT localmente sin tener que contactar con el proveedor del identidad), seleccione Claves estáticas en la lista Tipo y especifique un máximo de diez claves estáticas:

      • ID de clave: identificador de la clave estática utilizada para firmar el JWT. El valor debe coincidir con la reclamación kid en la cabecera de JWT. Por ejemplo, master_key.

      • Formato de clave: formato de la clave estática, ya sea una clave web JSON o una clave pública codificada por PEM.

        • Clave web de JSON: si la clave estática es una clave web de JSON, pegue la clave en este campo.

          Por ejemplo:

          {
  "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).

        • Clave pública con codificación PEM: si la clave estática es una claves pública con codificación PEM, pegue la clave en este campo. Por ejemplo:

          -----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.

      • Otra clave: seleccione esta opción para agregar claves adicionales (hasta un máximo de diez).
  7. (Opcional) Especifique detalles adicionales para la validación de token de JWT:

    1. En la sección Emisores, especifique los valores permitidos en la reclamación de emisor (iss) de un JWT que se esté utilizando para acceder al despliegue de API:

      • Emisores permitidos: especifique la URL (o una cadena del texto) para un proveedor del documento de identidad 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, introduzca https://identity.oraclecloud.com/. Consulte Detalles del proveedor de identidad para usar en reclamaciones iss y aud y para el URI de JWKS.
      • Otro emisor: seleccione esta opción para agregar proveedores para identidades adicionales (hasta un máximo de cinco).

    2. En la sección Públicos, especifique los valores permitidos en la reclamación de público (aud) de un JWT que se esté utilizando para acceder al despliegue de API:

    3. Verificar reclamaciones: (opcional) además de los valores para las reclamaciones de público aud y emisor iss que ya ha especificado, puede especificar nombres y valores para una o más reclamaciones adicionales para validar en un 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.

      • La reclamación es necesaria: especifique si la reclamación en el campo Clave de reclamaciones debe incluirse en el JWT.
      • Clave de reclamo: (opcional) especifique el nombre de una reclamación que puede o debe incluirse en un JWT. Si la reclamación se debe incluir en el JWT, seleccione Necesario. 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.
      • Valores de reclamo: (opcional) especifique un valor aceptable para la reclamación en el campo Clave de reclamo. Seleccione el signo más (+) para introducir otro valor aceptable. Si especifica uno o más valores aceptables para la reclamación, el gateway de API valida que la reclamación tenga uno de los valores especificados.

      Tenga en cuenta que puede especificar una reclamación en un JWT sin especificar un valor para él. Para ello, introduzca el nombre de la reclamación en el campo Clave de reclamación, deje el campo Valores de reclamación en blanco y defina La reclamación es necesaria según corresponda.

  8. Especifique 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) mediante la configuración de 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), seleccione Por defecto (HTTP 401 no autorizado).

    2. Si desea que el gateway de API utilice un flujo de autorización de OpenID Connect para obtener un nuevo token de acceso JWT, seleccione OAuth 2.0. Tenga en cuenta que esta opción solo está disponible si ha seleccionado Punto final de introspección de OAuth 2.0 en la lista Tipo de validación anterior. Especifique:

      • Ámbitos: uno o más ámbitos de acceso para 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, openid, email:read, profile.
      • Tipo de respuesta: tipo de respuesta necesaria del flujo de autorización. Introduzca code como tipo de respuesta.
      • Ruta de redireccionamiento de reserva: (opcional) 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.

      • Ruta de cierre de sesión: (opcional) ruta relativa a un backend de cierre de sesió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, /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.

      • Caducidad de respuesta en horas: (opcional) tiempo durante el que se almacena en caché el token de JWT generado por el flujo de autorización. El valor por defecto es 1 hora.
      • Usar credenciales de cliente de punto final de introspección de OAuth2: especifique si desea utilizar los mismos detalles de cliente que ha especificado anteriormente para el punto final de introspección de OAuth 2.0 para obtener un nuevo token de acceso JWT (que suele ser el caso). Si no desea utilizar los detalles especificados anteriormente, introduzca diferentes detalles de cliente para obtener un nuevo token de acceso JWT del servidor de autorización, de la siguiente manera:
        • ID de cliente: ID de cliente que se enviará al punto final de introspección. Por ejemplo, 5hsti38yhy5j2a4tas455rsu6ru8yui3wrst4n1
        • Almacén: nombre de un almacén en el servicio Vault que contiene el secreto de cliente que se va a enviar al punto final de introspección, desde la lista de almacenes del compartimento especificado.
        • Secreto de almacén: nombre del secreto de almacén que contiene el secreto de cliente que se va a enviar al punto final de introspección, desde la lista de secretos de almacén del compartimento especificado.
        • Número de versión del secreto de almacén: versión del secreto de almacén que contiene el secreto de cliente que se enviará al punto final de introspección.

      Opcionalmente, puede elegir almacenar en cookies los tokens y valores obtenidos durante los flujos de autorización de OpenID seleccionando Opciones avanzadas y seleccionando:

      • Usar PKCE: (opcional) especifique si se debe utilizar PKCE (clave de prueba para el 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.
      • Usar cookies para la sesión: (opcional) especifique 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:
        • Seleccione esta opción 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 al gateway de API (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.
        • No seleccione esta opción 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)

      • Usar cookies para pasos intermedios: (opcional) especifique cómo almacenar valores de pasos intermedios de flujo de autorización (por ejemplo, parámetros de solicitud). Seleccione esta opción para almacenar los valores en las cookies del explorador. Anule la selección de esta opción para almacenar los valores con el gateway de API.
    3. Si desea personalizar la respuesta a un intento incorrecto de validar un token que falta o no es válido, seleccione Respuesta personalizada y especifique un código de estado (y un cuerpo de mensaje opcional) para volver al cliente de API:
      • Código de estado de HTTP: introduzca un código de estado de HTTP alternativo. Por ejemplo, 500.
      • 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).
      • Opcionalmente, modifique 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.

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

  10. 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 enrutan 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:

  11. 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: indica cómo otorgar acceso a la ruta. Especifique:

      • Cualquiera: solo otorga acceso a usuarios finales que se hayan autenticado correctamente, siempre que JWT tenga una reclamación scope que incluya al menos uno de los ámbitos de acceso especificados en el campo Á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 el JWT 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 se hayan autenticado correctamente mediante el JWT. En este caso, la opción Activar acceso análogo de las políticas de autenticación no tiene ningún efecto.
    • Ámbito permitido si ha seleccionado Cualquiera en Tipo de autorización, introduzca una lista delimitada por comas de una o varias cadenas correspondientes a los ámbitos de acceso en el JWT. Solo se les otorgará acceso a los usuarios finales autenticados correctamente si el JWT tiene una reclamación de scope que incluya uno de los ámbitos de acceso que especifique. 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á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 en la reclamación de scope de JWT
    • los usuarios finales anónimos no pueden acceder a la ruta
  12. Seleccione Crear y, a continuación, seleccione Siguiente para revisar los detalles introducidos para el despliegue de API.
  13. Seleccione Crear o Actualizar 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.