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 will not authenticate requests. It will also not return an HTTP 401 Unauthorized status line with a WWW-Authenticate header for unauthenticated requests.

To use it, you must first store the basic auth username and password in a Kubernetes secret, using their respective keys, username and password.

This can be done via:

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.

Next, in your SpringCloudGatewayRouteConfig, enter the name of the secret you created at spec.basicAuth.secret.

Finally, add the BasicAuth filter to the route.

An example is shown below:

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 will only be relayed to the routes that include the BasicAuth filter.

If the secret cannot be found, a Kubernetes event will be emitted in the namespace, like so:

$ 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 The BasicAuth filter will not work together with the TokenRelay filter, since 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 examples below 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. Because of this, 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.

There are then three further variables which 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 will cause 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 will block any authenticated request if any of the configured values are present in the claims.

For example, the following configuration will cause 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

Finally, the spring.cloud.gateway.k8s.block.access.claimNames variable is complementary to spring.cloud.gateway.k8s.block.access.claimValues, and must be used together 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 will block 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 will cause 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

Please refer to the Configuring per-route Cross-Origin Resource Sharing (CORS) behavior via metadata guide for further information.

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