API Gateway:Configure custom authentication and authorization

Contexto

Por lo general, los servidores dependen de credenciales (tokens) en las solicitudes del cliente para proteger las comunicaciones de las API expuestas al exterior.

• Si sus tokens son JSON Web Tokens (JWT), puede validar sus firmas en cualquier lugar mediante una clave pública, sin necesidad de acceder a un servicio de autenticación centralizado.

• Si sus tokens usan un formato personalizado, el servidor debe llamar a un servicio centralizado para comprobar la autenticación y la autorización. Este proceso protege las comunicaciones de la API. Cloud-native API Gateway es compatible con este método de autenticación y autorización personalizado.

A continuación se ilustra el flujo de procesamiento de solicitudes después de integrar Cloud-native API Gateway con un servicio de autenticación personalizado.

1. Un cliente envía una solicitud de autenticación al gateway, por ejemplo, una operación de inicio de sesión.

2. El gateway reenvía la solicitud de autenticación directamente al servicio de autenticación.

3. El servicio de autenticación valida las credenciales de la solicitud, como el nombre de usuario y la contraseña. Si la validación se completa correctamente, devuelve un token al gateway, que luego lo transmite al cliente.

4. El cliente envía una solicitud de negocio, por ejemplo, una petición a la ruta /order para crear un pedido. La solicitud incluye el token emitido tras la autenticación correcta.

5. El gateway intercepta la ruta (incluidos los parámetros de consulta), el método HTTP (como GET o POST) y el token de la solicitud de negocio original. Utiliza esta información para construir una nueva solicitud y la envía al servicio de autenticación personalizado para obtener la autorización. En la consola del gateway, debe configurar el encabezado HTTP donde se encuentra el token. También puede permitir que se incluya el cuerpo de la solicitud original.

   Si la API de autenticación del servicio personalizado es /validateToken, el gateway forma la ruta real de la solicitud de autorización al agregar la ruta de la solicitud de negocio original a la ruta de la API de autenticación. El resultado es /validateToken/order.

6. Cuando el servicio de autenticación recibe la solicitud de autorización, valida el token y comprueba si el cliente tiene permiso para acceder a la ruta de la solicitud original.

   • Si su servicio de autenticación puede modificar el código de estado HTTP en su respuesta, utilice dicho código para indicar el resultado de la autorización.

     • Un código de estado HTTP 200 indica que el token es válido y tiene autorización para acceder al recurso del backend. El gateway reenvía entonces la solicitud de negocio original al servicio del backend protegido. Después de recibir la respuesta del backend, el gateway la reenvía al cliente y así finaliza la operación de creación del pedido.

     • Un código de estado HTTP 401 o 403 indica que el token no es válido o carece de autorización para acceder al recurso del backend. El gateway devuelve inmediatamente la respuesta del servicio de autenticación al cliente, lo que provoca que la operación de creación del pedido falle.

   • Si por restricciones de negocio su servicio de autenticación siempre debe devolver un código de estado HTTP 200, utilice el encabezado HTTP integrado x-mse-external-authz-check-result.

     • Si el servicio de autenticación devuelve una respuesta con el encabezado x-mse-external-authz-check-result establecido en true, significa que el token es válido y tiene permiso para acceder al recurso del backend. El gateway reenvía entonces la solicitud original al servicio del backend protegido y transmite la respuesta de vuelta al cliente, con lo cual finaliza la operación de creación del pedido.

     • Si el servicio de autenticación devuelve una respuesta con el encabezado x-mse-external-authz-check-result establecido en false, significa que el token no es válido o no tiene permiso para acceder al recurso del backend. El gateway devuelve la respuesta del servicio de autenticación directamente al cliente, lo que provoca que la operación de creación del pedido falle.

Crear una regla de autenticación personalizada

1. Inicie sesión en la consola de API Gateway.

2. En el panel de navegación izquierdo, haga clic en Cloud-native API Gateway > Instance. En la barra de navegación superior, seleccione una región.

3. En la página Instance, haga clic en el nombre de la instancia de gateway de destino.

4. En el panel de navegación izquierdo, haga clic en Security Management > Global Authentication.

5. En la página Global Authentication, haga clic en Create Authentication. En el panel Create Authentication, configure los parámetros y haga clic en OK.

   Parámetro	Descripción: Custom Authentication Service
   Enable	Indica si se habilita la autenticación y autorización para Cloud-native API Gateway.
   Authentication Name	Nombre personalizado para la regla de autenticación y autorización.
   Authentication Type	Seleccione Custom Authentication Service.
   Authentication Service	Servicio del backend que se utiliza para la autenticación y autorización. Puede agregar servicios en la gestión de servicios. Para más información, consulte Add a service. Nota Solo se admiten servicios que utilizan el protocolo HTTP. No son compatibles los servicios que emplean otros protocolos, como Dubbo. Si un Kubernetes Service tiene varios puertos, se usa el primero de manera predeterminada. Si desea utilizar un puerto distinto, cree un Kubernetes Service adicional en Container Service for Kubernetes (ACK) que exponga únicamente el puerto de destino.
   Authentication API	Ruta de la API proporcionada por el servicio de autenticación. El gateway utiliza esta ruta para la coincidencia de prefijos. Por ejemplo, si su servicio de autenticación está desarrollado con Spring MVC, expone la API de autenticación /check y desea gestionar las solicitudes de rutas que comienzan con /check/, configúrelo de la siguiente manera: @RequestMapping("/check/") public ResponseEntity<RestResult<String>> check(){}
   Token Location	Ubicación del token en el encabezado de la solicitud, normalmente Authorization o Cookie. Para establecer la ubicación del token, puede Select una opción de la lista o bien usar Add Manually.
   Allowed Headers in Authentication Rrequest	Especifica qué encabezados de la solicitud original del cliente deben reenviarse al servicio de autenticación. Nota Los encabezados Host, Method, Path y Content-Length se incluyen de manera predeterminada y no es necesario agregarlos manualmente.
   Allowed Headers in Authentication Response	Define qué encabezados de la respuesta del servicio de autenticación se agregan a la solicitud enviada al servicio del backend. Nota Si un encabezado especificado aquí ya existe en la solicitud del cliente, el gateway sobrescribe su valor.
   Allow Body in Authentication Request	Allow Body in Authentication Request: incluye el cuerpo de la solicitud original del cliente en la solicitud enviada al servicio de autenticación. Maximum Body Size: tamaño máximo del cuerpo de la solicitud que se puede reenviar, en bytes.
   Timeout Period	Tiempo máximo de espera, en segundos, para recibir una respuesta del servicio de autenticación. Valor predeterminado: 10.
   Mode	Determina el comportamiento cuando el servicio de autenticación no está disponible. Son compatibles Loose Mode y Strict Mode. Se recomienda usar Loose Mode. Loose Mode: si el servicio de autenticación no está disponible (por ejemplo, si falla la conexión o el servicio devuelve un error 5xx), el gateway permite que la solicitud del cliente continúe. Strict Mode: si el servicio de autenticación no está disponible (por ejemplo, si falla la conexión o el servicio devuelve un error 5xx), el gateway rechaza la solicitud del cliente.
   Simple Conditions	Junto a Authorization, haga clic en Simple Conditions. Este modo es compatible con Whitelist Mode y Blacklist Mode. Whitelist Mode: las solicitudes que coinciden con los hosts y las rutas de la lista de permitidos pueden omitir la validación. Todos los demás hosts y rutas requieren validación. Blacklist Mode: las solicitudes que coinciden con los hosts y las rutas de la lista de bloqueados requieren validación. Se puede acceder directamente a todos los demás hosts y rutas. Haga clic en Rule Condition para establecer condiciones basadas en el dominio, la ruta y los encabezados de la solicitud. Domain Name: dominio del host solicitado. Path: ruta de la API solicitada. Path Match Condition: la ruta se puede evaluar mediante coincidencia exacta, coincidencia de prefijo o coincidencia de expresión regular. Exact Match: introduzca una ruta completa, por ejemplo, /app/v1/order. Prefix Match: introduzca un prefijo de ruta que termine con un asterisco (). Por ejemplo, para coincidir con todas las solicitudes que comiencen con /app, introduzca /app/. Regular Expression Match: la sintaxis sigue el estándar Google RE2. Para más información, consulte Sintaxis de RE2. Case sensitive: hace que la coincidencia de rutas distinga entre mayúsculas y minúsculas. Header: encabezado de la solicitud. Haga clic en Request Header para configurar varios encabezados. Se aplica una operación lógica AND entre ellos. HeaderKey: nombre del campo de encabezado. Condition: condición de coincidencia para el encabezado. Equals To: el valor del encabezado especificado es igual al valor introducido. Does Not Equal To: el valor del encabezado especificado no es igual al valor introducido. Exists: el encabezado especificado existe en la solicitud. Does Not Exist: el encabezado especificado no existe en la solicitud. Contains: el valor del encabezado especificado contiene el valor introducido. Excludes: el valor del encabezado especificado no contiene el valor introducido. Prefix: el valor del encabezado especificado comienza con el valor introducido. Suffix: el valor del encabezado especificado termina con el valor introducido. Regular Expression Match: el valor del encabezado especificado coincide con la expresión regular introducida. La sintaxis sigue el estándar Google RE2. Para más información, consulte Sintaxis de RE2. Value: valor con el que se compara el campo de encabezado.
   Complex Conditions	Junto a Authorization, haga clic en Complex Conditions. Este modo le permite definir reglas de autorización mediante una configuración YAML de la estructura de datos permission de Envoy. Puede crear reglas que combinen lógica AND, OR y NOT. El gateway envía a autenticación las solicitudes que coinciden con las condiciones configuradas. Las solicitudes que no coinciden pueden acceder directamente a los recursos. Nota Para consultar la descripción completa de los campos de la estructura de datos permission, revise la documentación oficial de Envoy. Para ver ejemplos de configuración, consulte Complex condition authorization examples.

   Regrese a la página Global Authentication. Si la nueva regla aparece en la lista, se creó correctamente.

Consultar y gestionar servicios de autenticación

1. Inicie sesión en la consola de API Gateway.

2. En el panel de navegación izquierdo, haga clic en Cloud-native API Gateway > Instance. En la barra de navegación superior, seleccione una región.

3. En la página Instance, haga clic en el nombre de la instancia de gateway de destino.

4. En el panel de navegación izquierdo, haga clic en Security Management > Global Authentication.

5. En la página Authentication, busque la regla de autenticación de destino y haga clic en Description en la columna Actions. Desde ahí puede consultar la Basic Information y la Authentication Configuration, además de gestionar la Authorization Information.

   La sección Authentication Configuration incluye campos como Authentication Service, Authentication API, Token Location, Timeout Period, Mode (por ejemplo, Loose Mode), Allow Body in Authentication Request, Allowed Headers in Authentication Request y Allowed Headers in Authentication Response. La sección Authorization Information muestra el modo actual (como Whitelist Mode). Varias condiciones de regla mantienen entre sí una relación lógica "OR". La lista de reglas de autorización incluye columnas como Request Domain, Request Path Matchers, case-sensitive y Request Header Matchers.

   En la sección Authorization Information, haga clic en Create Authorization. En el cuadro de diálogo que aparece, introduzca el Request Domain Name y la Request Path, seleccione un Match Mode y, a continuación, haga clic en OK para agregar la regla de autorización.

Operaciones relacionadas

• Habilitar la autenticación y autorización: en la página Global Authentication, busque la regla de destino y haga clic en Enable en la columna Actions para activarla.

• Deshabilitar la autenticación y autorización: en la página Global Authentication, busque la regla de destino y haga clic en Close en la columna Actions para desactivarla.

• Editar la autenticación y autorización: en la página Global Authentication, busque la regla de destino y haga clic en Edit en la columna Actions para modificar su configuración.

• Eliminar la autenticación y autorización: en la página Global Authentication, busque la regla de destino y haga clic en Delete en la columna Actions para quitarla.

Ejemplos de autorización con condiciones complejas

permissions:
# and_rules: Triggers authentication if all the following rules are met.
- and_rules:
    rules:
      - url_path:
          # Path prefix matching.
          path:
            prefix: /
      - header:
          # Regular expression matching.
          safe_regex_match:
            regex: "(exampleA\\.com|exampleB\\.com)"
          # The domain name can be obtained from the ":authority" header,
          # according to the HTTP pseudo-header specification.
          name: ":authority"

permissions:
# or_rules: Triggers authentication if any of the following rules are met.
- or_rules:
    rules:
      # and_rules: This rule is met only if all the following sub-rules are met.
      # Rule 1
      - and_rules:
          rules:
            - url_path:
                path:
                  exact: /api/appc/bbb/ccc
            - header:
                exact_match: "exampleB.com"
                name: ":authority"
      # Rule 2                
      - and_rules:
          rules:
            - url_path:
                path:
                  exact: /api/appc/ccc/ddd
            - header:
                exact_match: "exampleB.com"
                name: ":authority"
      - and_rules:
          rules:
            # Rule 3
            - url_path:
                path:
                  prefix: /api/
            # not_rule: Matches if the nested rule does not match.
            # Rule 4
            - not_rule:
                url_path:
                  path:
                    exact: /api/appa/bbb
            # Rule 5
            - not_rule:
                url_path:
                  path:
                    exact: /api/appb/ccc                                
            - header:
                exact_match: "exampleA.com"
                name: ":authority"                                
      - and_rules:
          rules:
            # Rule 6
            - url_path:
                path:
                  prefix: /
            # not_rule: Matches if the nested rule does not match.
            # Rule 7
            - not_rule:
                url_path:
                  path:
                    exact: /api/appa/bbb
            # Rule 8
            - not_rule:
                url_path:
                  path:
                    exact: /api/appb/ccc
            # Rule 9
            - not_rule:
                url_path:
                  path:
                    prefix: /api/appc/                                         
            - header:
                exact_match: "exampleB.com"
                name: ":authority"