User credentials OAuth with Keycloak

Follow along with an OIDC OAuth example that uses Keycloak as an identity provider.

This feature is available with a Gloo Mesh Gateway license only.

Before you begin

  1. Complete the demo setup to install Gloo Mesh, Istio, Bookinfo, httpbin, and Keycloak in your cluster.

  2. Create the Gloo Mesh resources for this policy in the management and workload clusters.

    The following files are examples only for testing purposes. Your actual setup might vary. You can use the files as a reference for creating your own tests.

    1. Download the following Gloo Mesh resources:

    2. Apply the files to your management cluster.

      kubectl apply -f kubernetes-cluster_gloo-mesh_cluster-1.yaml --context ${MGMT_CONTEXT}
      kubectl apply -f kubernetes-cluster_gloo-mesh_cluster-2.yaml --context ${MGMT_CONTEXT}
      kubectl apply -f workspace_gloo-mesh_anything.yaml --context ${MGMT_CONTEXT}
      
    1. Download the following Gloo Mesh resources:

    2. Apply the files to your workload cluster.

      kubectl apply -f virtual-gateway_bookinfo_north-south-gw.yaml --context ${REMOTE_CONTEXT1}
      kubectl apply -f workspace-settings_bookinfo_anything.yaml --context ${REMOTE_CONTEXT1}
      

Configure an OAuth policy

Create the external auth policy that uses Keycloak as an identity provider.

You can do the following steps in a different order, depending on when you want the policy to take effect. For example, you might want the policy to always take effect as soon as the route is created. To do so, you can create the policy before you add the route to the route table.
  1. Create a Kubernetes secret with the Keycloak OIDC secret. For more information, see Step 5: Install Keycloak of the demo setup.
    kubectl --context ${REMOTE_CONTEXT1} apply -f - <<EOF
    apiVersion: v1
    kind: Secret
    metadata:
      name: oauth
      namespace: httpbin
    type: extauth.solo.io/oauth
    data:
      client-secret: $(echo -n ${KEYCLOAK_SECRET} | base64)
    EOF
    
  2. Create an external auth server to use for your policy.
    kubectl --context ${REMOTE_CONTEXT1} apply -f - <<EOF
    apiVersion: admin.gloo.solo.io/v2
    kind: ExtAuthServer
    metadata:
      name: ext-auth-server
      namespace: httpbin
    spec:
      destinationServer:
        ref:
          cluster: cluster-1
          name: ext-auth-service
          namespace: gloo-mesh
        port:
          name: grpc
    EOF
    
  3. Create a route table for the httpbin app and external auth policy. Note that the route table selects the virtual gateway that you created before you began, and routes to the httpbin service.
    kubectl --context ${REMOTE_CONTEXT1} apply -f - <<EOF
    apiVersion: networking.gloo.solo.io/v2
    kind: RouteTable
    metadata:
      name: httpbin
      namespace: httpbin
      labels:
        expose: "true"
    spec:
      hosts:
        - '*'
      virtualGateways:
        - name: north-south-gw
          namespace: bookinfo
          cluster: cluster-1
      workloadSelectors: []
      http:
        - name: httpbin
          labels:
            oauth: "true"
          matchers:
          - uri:
              exact: /get
          - uri:
              prefix: /callback
          forwardTo:
            destinations:
            - ref:
                name: httpbin
                namespace: httpbin
              port:
                number: 8000
    EOF
    
  4. Create an external auth policy that uses Keycloak for OIDC.
    kubectl --context ${REMOTE_CONTEXT1} apply -f - <<EOF
    apiVersion: security.policy.gloo.solo.io/v2
    kind: ExtAuthPolicy
    metadata:
      name: httpbin
      namespace: httpbin
    spec:
      applyToRoutes:
      - route:
          labels:
            oauth: "true"
      config:
        server:
          name: ext-auth-server
          namespace: httpbin
          cluster: cluster-1
        glooAuth:
          configs:
          - oauth2:
              oidcAuthorizationCode:
                appUrl: https://${INGRESS_GW_HTTPS}
                callbackPath: /callback
                clientId: ${KEYCLOAK_CLIENT}
                clientSecretRef:
                  name: oauth
                  namespace: httpbin
                issuerUrl: "${KEYCLOAK_URL}/realms/master/"
                scopes:
                - email
                session:
                  failOnFetchFailure: true
                  redis:
                    cookieName: keycloak-session
                    options:
                      host: redis:6379
                headers:
                  idTokenHeader: jwt
    EOF
    

Review the following table to understand this configuration. For more information, see the API reference.

Setting Description
applyToRoutes Configure which routes to apply the policy to, by using labels. The label matches the app and the route from the route table. If omitted, the policy applies to all routes in the workspace.
server The external auth server to use for the policy.
oauth2 Configure the OAuth 2.0 protocol details to use to authenticate requests. The example uses Keycloak as the external identity provider.
appUrl The public URL of the app that you want to set up external auth for. This setting is used in combination with the callbackPath attribute.
callbackPath The callback path, relative to the appUrl setting. After a user authenticates, the identity provider redirects the user to this callback URL. Gloo Mesh intercepts requests with this path, exchanges the authorization code received from the IdP for an ID token, places the ID token in a cookie on the request, and forwards the request to its original destination.
The callback path must have a matching route in the route table that is associated with the external auth policy. For example, you could simply have a / path-prefix route which would match any callback path. The important part of this callback “catch all” route is that the request goes through the routing filters including external auth.
clientId The client ID token that you got when you registered your app with the identity provider. In this example, you set the client ID before you began in the demo setup.
clientSecretRef The Kubernetes secret that has the client secret that you got when you registered your app with the identity provider. In this example, you created the secret in an earlier step.
issuerUrl The URL of the OpenID Connect identity provider. Gloo Mesh automatically discovers OIDC configuration by querying the .well-known/openid-configuration endpoint on the issuer_url. In this example, Gloo Mesh expects to find OIDC discovery information at "${KEYCLOAK_URL}/realms/master/".
scopes Scopes to request in addition to the openid scope, such as email in this example.
session Details on how to store the user session details. In this example, the cookie is stored as by the name keycloak-session in a Redis instance.
idTokenHeader Forward the ID token to the destination after successful authentication. In this example, the ID token is sent as a JWT.

Verify the OAuth policy

  1. In your web browser, open the path to your application. You are redirected to the authentication page from the Keycloak identity provider.
  2. Enter the user credentials from Keycloak, such as the following values from the demo setup.
    • Username: user1
    • Password: password

You are authenticated and returned back to the httpbin home page.