The open-source Spring Cloud Gateway project includes a number of built-in filters for use in Gateway routes. The following commercial filters provided by VMware Spring Cloud Gateway for Kubernetes can be used in addition to those included in the OSS project.

BasicAuth

The BasicAuth filter relays Basic Authorization credentials to a route. It does not authenticate requests. It also does not return an HTTP 401 Unauthorized status line with a WWW-Authenticate header for unauthenticated requests.

To use the BasicAuth filter:

  1. Store the basic auth username and password in a Kubernetes secret, using their respective keys, username and password.

    To do this, run:

    kubectl create secret generic basic-auth-secret \
  --from-literal=username=***** \
  --from-literal=password=*****

    The secret must be created in the same namespace as the SpringCloudGatewayRouteConfig that will reference it.

  2. In your SpringCloudGatewayRouteConfig, enter the name of the secret you created at spec.basicAuth.secret.

  3. Add the BasicAuth filter to the route.

    For example:

    apiVersion: "tanzu.vmware.com/v1"
kind: SpringCloudGatewayRouteConfig
metadata:
  name: test-gateway-routes
spec:
  service:
    name: myapp
  basicAuth:
    secret: basic-auth-secret
  routes:
    - predicates:
        - Path=/api/**
      filters:
        - StripPrefix=0
        - BasicAuth

    If you have multiple routes, the Basic Auth credentials are relayed only to the routes that include the BasicAuth filter.

  4. If the secret cannot be found, a Kubernetes event is emitted in the namespace, as shown here:

    $ kubectl get event
LAST SEEN   TYPE      REASON                      OBJECT                                               MESSAGE
117s        Warning   RoutesDefinitionException   springcloudgatewaymapping/test-gateway-mapping       Failed to retrieve routes from route config in mapping test-gateway-mapping: Failed to find secret 'basic-auth-secret' in the 'user-namespace' namespace.

    This will also be logged in the scg-operator pod, which runs in the spring-cloud-gateway namespace by default:

    $ kubectl logs deployment.apps/scg-operator
2021-06-16 19:38:01.459 ERROR 1 --- [ingController-2] c.v.t.s.route.RoutesDefinitionResolver   : Failed to find secret 'basic-auth-secret' in the 'user-namespace' namespace.

Important You cannot use the BasicAuth filter with the TokenRelay filter, because both filters use the Authorization header.

BasicAuth filter in standalone mode

When using the BasicAuth filter in a Gateway instance running in standalone mode, you must add the Base64-encoded credentials alongside the filter in the form username:password.

The following examples show the encoding and configuration when the username and password are respectively my-username and my-password:

$ echo -n 'my-username:my-password' | base64
bXktdXNlcm5hbWU6bXktcGFzc3dvcmQ=

spring:
  cloud:
    gateway:
      routes:
        - id: basic-auth-relay
          uri: https://example.org
          filters:
            - BasicAuth=bXktdXNlcm5hbWU6bXktcGFzc3dvcmQ=

BlockAccess

The BlockAccess filter provides the ability to block access to requests by IP address, domain, or JWT claims.

This filter works globally across the entire Gateway instance, so it is configured using environment variables in the SpringCloudGateway resource, rather than per-route in SpringCloudGatewayRouteConfig.

To activate the filter, first use the SpringCloudGateway resource to set the spring.cloud.gateway.k8s.block.access.enabled environment variable to true.

Three variables are used to set up the blocking rules.

Blocking by IP or domain

The spring.cloud.gateway.k8s.block.access.domains variable accepts a comma-separated list of IP addresses or domains. Any request coming from any of these origins will be blocked.

For example, the following configuration causes all requests originating from 192.168.0.1 or test.com to be blocked:

apiVersion: "tanzu.vmware.com/v1"
kind: SpringCloudGateway
metadata:
  name: my-gateway
spec:
  env:
    - name: spring.cloud.gateway.k8s.block.access.enabled
      value: "true"
    - name: spring.cloud.gateway.k8s.block.access.domains
      value: "192.168.0.1,test.com"

Blocking by JWT claim value

The spring.cloud.gateway.k8s.block.access.claimValues variable accepts a comma-separated list of JWT claim values. When configured, the Gateway blocks any authenticated request if any of the configured values are present in the claims.

For example, the following configuration causes all authenticated requests containing any JWT claim with a value of client.write or cc_testuser to be blocked:

apiVersion: "tanzu.vmware.com/v1"
kind: SpringCloudGateway
metadata:
  name: my-gateway
spec:
  env:
    - name: spring.cloud.gateway.k8s.block.access.enabled
      value: "true"
    - name: spring.cloud.gateway.k8s.block.access.claimValues
      value: "client.write,cc_testuser"

Blocking by JWT claim name and value

The spring.cloud.gateway.k8s.block.access.claimNames variable is complementary to spring.cloud.gateway.k8s.block.access.claimValues, and must be used with it. It works by restricting the search for JWT claim values to a defined set of claim names.

The variable accepts a comma-separated list of claim names. When configured, the Gateway blocks any authenticated request in which a claim with one of the specified names contains any value specified in the spring.cloud.gateway.k8s.block.access.claimValues variable.

For example, the following configuration causes any authenticated request containing a value of write or cc_testuser in the JWT sub claim to be blocked:

apiVersion: "tanzu.vmware.com/v1"
kind: SpringCloudGateway
metadata:
  name: my-gateway
spec:
  env:
    - name: spring.cloud.gateway.k8s.block.access.enabled
      value: "true"
    - name: spring.cloud.gateway.k8s.block.access.claimNames
      value: "sub"
    - name: spring.cloud.gateway.k8s.block.access.claimValues
      value: "write,cc_testuser"

Note The JWT Claim BlockAccess global filter only supports blocking requests with the Authorization header. It does not support blocking by cookie session.

Cors

Caution The Cors filter from previous versions of Spring Cloud Gateway for Kubernetes has been deprecated in favor of the new metadata.cors section.

Previous versions of Spring Cloud Gateway supported a Cors filter configuration as shown in the example below:

apiVersion: "tanzu.vmware.com/v1"
kind: SpringCloudGatewayRouteConfig
metadata:
  name: my-gateway-routes
spec:
  routes:
    - uri: https://example
      predicates:
        - Path=/get/**
      filters:
        - Cors=[allowedOrigins:https://origin-1,allowedMethods:GET;POST;DELETE,allowedHeaders:*,maxAge:400,allowCredentials:true,allowedOriginPatterns:https://*.test.com:8080]

This format has now been deprecated, and can be converted to the equivalent configuration in the newly supported format, as shown in the example below:

apiVersion: "tanzu.vmware.com/v1"
kind: SpringCloudGatewayRouteConfig
metadata:
  name: my-gateway-routes
spec:
  routes:
    - uri: https://example
      predicates:
        - Path=/get/**
      metadata:
        cors:
          allowedOrigins: https://origin-1
          allowedMethods: [GET,POST,DELETE]
          allowedHeaders: '*'
          maxAge: 400
          allowCredentials: true
          allowedOriginPatterns: https://*.test.com:8080

See Configuring per-route Cross-Origin Resource Sharing (CORS) behavior using metadata guide for further information.

check-circle-line exclamation-circle-line close-line
Scroll to top icon