Using Single Sign-On

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 setup 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:

    scope=openid,profile,email
    client-id={your_client_id}
    client-secret={your_client_secret}
    issuer-uri={your-issuer-uri}
    

    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
    metadata:
      name: my-gateway
    spec:
      api:
        serverUrl: https://my-gateway.spring.animalrescue.online
        title: Animal Rescue APIs
        description: Make and track adoption requests for animals that need to be rescued.
        version: 1.0
      sso:
        secret: my-sso-credentials
    
    apiVersion: "tanzu.vmware.com/v1"
    kind: SpringCloudGatewayRouteConfig
    metadata:
      name: my-gateway-routes
    spec:
      routes:
      - uri: https://github.com
        ssoEnabled: true
        predicates:
          - Path=/github/**
        filters:
          - 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.