Spring Cloud Gateway for Kubernetes supports authentication and authorization using Single Sign-On (SSO) with an OpenID identity provider which supports OpenID Connect Discovery protocol.

On top of using a SSO authentication workflow, you can also set up filters to support:

Configure Single Sign-On (SSO)

You can configure Spring Cloud Gateway for Kubernetes to authenticate requests via Single Sign-On (SSO), using an OpenID identity provider.

To configure a Gateway instance to use SSO:

  1. Create a file called sso-credentials.txt, including the following properties:


    For the client-id, client-secret, and issuer-uri values, use values from your OpenID identity provider. For the scope value, use a list of scopes to include in JWT identity tokens. This list should be based on the scopes allowed by your identity provider.

    issuer-uri configuration should follow Spring Boot convention, as described in the official Spring Boot documentation:

    The provider needs to be configured with an issuer-uri which is the URI that the it asserts as its Issuer Identifier. For example, if the issuer-uri provided is "https://example.com", then an OpenID Provider Configuration Request will be made to "https://example.com/.well-known/openid-configuration". The result is expected to be an OpenID Provider Configuration Response.

    Note that only authorization servers supporting OpenID Connect Discovery protocol can be used.

  2. Configure external authorization server to allow redirects back to the gateway. Please refer to your authorization server's documentation and add https://<gateway-external-url-or-ip-address>/login/oauth2/code/sso to the list of allowed redirect URIs.

  3. In the Spring Cloud Gateway for Kubernetes namespace, create a Kubernetes secret using the sso-credentials.txt file created in the previous step:

    $ kubectl create secret generic my-sso-credentials --from-env-file=./sso-credentials.txt
  4. Examine the secret using the kubectl describe command. Verify that the Data column of the secret contains all of the required properties listed above.

  5. Add the SSO secret in the SpringCloudGateway definition in the spec.sso.secret field. In the routes list of the SpringCloudGatewayRouteConfig object, add the setting ssoEnabled: true to each route that must have authenticated access. See the following updated gateway-config.yaml and route-config.yaml files:

    apiVersion: "tanzu.vmware.com/v1"
    kind: SpringCloudGateway
      name: my-gateway
        serverUrl: https://my-gateway.my-example-domain.com
        title: Animal Rescue APIs
        description: Make and track adoption requests for animals that need to be rescued.
        version: "1.0"
        secret: my-sso-credentials
    apiVersion: "tanzu.vmware.com/v1"
    kind: SpringCloudGatewayRouteConfig
      name: my-gateway-routes
      - uri: https://github.com
        ssoEnabled: true
          - Path=/github/**
          - StripPrefix=1

    With ssoEnabled set to true, the Gateway instance will use SSO for all API routes that are configured to allow authenticated access only.

  6. Apply the updated Gateway and RouteConfig definition file:

    $ kubectl apply -f gateway-config.yaml
    $ kubectl apply -f route-config.yaml

Update Single Sign-On credentials

To update the SSO credentials for the gateway:

  1. Update the value in secret (e.g. my-sso-credentials) by deleting the old secret then recreate it again:

    $ kubectl delete secret my-sso-credentials
    $ kubectl create secret generic my-sso-credentials --from-env-file=./sso-credentials-updated.txt

    Alternatively, edit existing secret with new base64 encoded values:

    $ echo $NEW_CLIENT_SECRET | base64 | pbcopy
    $ kubectl edit secret my-sso-credentials
  2. Rollout restart the gateway statefulset to enforce secret update:

    kubectl rollout restart statefulset my-gateway

Refer to SSO Setup Guide for Animal Rescue demo app with Okta Identity Provider for more details.

OpenAPI security schemes (SSO)

When SSOEnabled is set to true on any route, two securityScheme (See https://swagger.io/docs/specification/authentication) are registered as a component in the OpenAPI spec generated:

  • AuthBearer to enable a dialog for providing a Bearer Authorization header
  • OpenId to enable a dialog for getting a token from an OIDC configuration and adding it as a header

And, the schemes are bound to any of those routes. Other routes will not be affected and the scheme will not be applied on them.

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