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

If you import or export resources across workspaces, your policies might not apply. For more information, see Import and export policies.

Before you begin

This guide assumes that you use the same names for components like clusters, workspaces, and namespaces as in the getting started, and that your Kubernetes context is set to the cluster you store your Gloo config in (typically the management cluster). If you have different names, make sure to update the sample configuration files in this guide.

Follow the getting started instructions to:

  1. Set up Gloo Gateway in a single cluster.

  2. Deploy sample apps.

  3. Configure an HTTP listener on your gateway and set up basic routing for the sample apps.

  4. Make sure that the external auth service is installed and running. If not, install the external auth service in your single or multicluster environment.

    kubectl get pods -A -l app=ext-auth-service

Install Keycloak

You might want to test how to restrict access to your applications to authenticated users, such as with external auth or JWT policies. You can install Keycloak in your cluster as an OpenID Connect (OIDC) provider.

The following steps install Keycloak in your cluster, and configure two user credentials as follows.

Install and configure Keycloak:

  1. Create a namespace for your Keycloak deployment.

    kubectl create namespace keycloak
  2. Create the Keycloak deployment.

    kubectl -n keycloak apply -f
  3. Wait for the Keycloak rollout to finish.

    kubectl -n keycloak rollout status deploy/keycloak
  4. Set the Keycloak endpoint details from the load balancer service.

    export ENDPOINT_KEYCLOAK=$(kubectl -n keycloak get service keycloak -o jsonpath='{.status.loadBalancer.ingress[0].*}'):8080
    export HOST_KEYCLOAK=$(echo ${ENDPOINT_KEYCLOAK} | cut -d: -f1)
    export PORT_KEYCLOAK=$(echo ${ENDPOINT_KEYCLOAK} | cut -d: -f2)
    echo $KEYCLOAK_URL
  5. Set the Keycloak admin token. If you see a parsing error, try running the curl command by itself. You might notice that your network is blocking the requests, which might require updating the security settings so that the request can be processed.

    export KEYCLOAK_TOKEN=$(curl -d "client_id=admin-cli" -d "username=admin" -d "password=admin" -d "grant_type=password" "$KEYCLOAK_URL/realms/master/protocol/openid-connect/token" | jq -r .access_token)
  6. Use the admin token to configure Keycloak with the two users for testing purposes. If you get a 401 Unauthorized error, run the previous command and try again.

    # Create initial token to register the client
    read -r client token <<<$(curl -H "Authorization: Bearer ${KEYCLOAK_TOKEN}" -X POST -H "Content-Type: application/json" -d '{"expiration": 0, "count": 1}' $KEYCLOAK_URL/admin/realms/master/clients-initial-access | jq -r '[.id, .token] | @tsv')
    export KEYCLOAK_CLIENT=${client}
    # Register the client
    read -r id secret <<<$(curl -k -X POST -d "{ \"clientId\": \"${KEYCLOAK_CLIENT}\" }" -H "Content-Type:application/json" -H "Authorization: bearer ${token}" ${KEYCLOAK_URL}/realms/master/clients-registrations/default| jq -r '[.id, .secret] | @tsv')
    export KEYCLOAK_SECRET=${secret}
    # Add allowed redirect URIs
    curl -k -H "Authorization: Bearer ${KEYCLOAK_TOKEN}" -X PUT -H "Content-Type: application/json" -d '{"serviceAccountsEnabled": true, "directAccessGrantsEnabled": true, "authorizationServicesEnabled": true, "redirectUris": ["*"]}' $KEYCLOAK_URL/admin/realms/master/clients/${id}
    # Add the group attribute in the JWT token returned by Keycloak
    curl -H "Authorization: Bearer ${KEYCLOAK_TOKEN}" -X POST -H "Content-Type: application/json" -d '{"name": "group", "protocol": "openid-connect", "protocolMapper": "oidc-usermodel-attribute-mapper", "config": {"": "group", "jsonType.label": "String", "user.attribute": "group", "id.token.claim": "true", "access.token.claim": "true"}}' $KEYCLOAK_URL/admin/realms/master/clients/${id}/protocol-mappers/models
    # Create first user
    curl -H "Authorization: Bearer ${KEYCLOAK_TOKEN}" -X POST -H "Content-Type: application/json" -d '{"username": "user1", "email": "", "enabled": true, "attributes": {"group": "users"}, "credentials": [{"type": "password", "value": "password", "temporary": false}]}' $KEYCLOAK_URL/admin/realms/master/users
    # Create second user
    curl -H "Authorization: Bearer ${KEYCLOAK_TOKEN}" -X POST -H "Content-Type: application/json" -d '{"username": "user2", "email": "", "enabled": true, "attributes": {"group": "users"}, "credentials": [{"type": "password", "value": "password", "temporary": false}]}' $KEYCLOAK_URL/admin/realms/master/users
  7. Open the Keycloak frontend.

    open $KEYCLOAK_URL
  8. Log in to the admin console, and enter admin as the username and admin as your password.

  9. In the Keycloak admin console, go to Manage > Users, and verify that the users that created earlier are displayed. You might need to click on View all users to see them.

  10. In the Keycloak admin console, go to Configure > Clients, and verify that you can see a client that equals the output of $KEYCLOAK_CLIENT.

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.
    kubectl apply -f - <<EOF
    apiVersion: v1
    kind: Secret
      name: oauth
      namespace: httpbin
      client-secret: $(echo -n ${KEYCLOAK_SECRET} | base64)
  2. Create an external auth server to use for your policy.
    kubectl apply -f - <<EOF
    kind: ExtAuthServer
      name: ext-auth-server
      namespace: httpbin
          cluster: $CLUSTER_NAME
          name: ext-auth-service
          namespace: gloo-mesh-addons
          name: grpc
  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 apply -f - <<EOF
    kind: RouteTable
      name: httpbin
      namespace: httpbin
        expose: "true"
        - '*'
        - name: istio-ingressgateway
          namespace: bookinfo
          cluster: $CLUSTER_NAME
      workloadSelectors: []
        - name: httpbin
            oauth: "true"
          - uri:
              exact: /get
          - uri:
              prefix: /callback
            - kind: SERVICE
                name: httpbin
                namespace: httpbin
                cluster: $CLUSTER_NAME
                number: 8000
  4. Create an external auth policy that uses Keycloak for OIDC.
    kubectl apply -f - <<EOF
    kind: ExtAuthPolicy
      name: httpbin
      namespace: httpbin
      - route:
            oauth: "true"
          name: ext-auth-server
          namespace: httpbin
          cluster: $CLUSTER_NAME
          - oauth2:
                appUrl: "https://${INGRESS_GW_IP}:443"
                callbackPath: /callback
                clientId: ${KEYCLOAK_CLIENT}
                  name: oauth
                  namespace: httpbin
                issuerUrl: "${KEYCLOAK_URL}/realms/master/"
                - email
                  failOnFetchFailure: true
                    cookieName: keycloak-session
                      host: redis:6379
                  idTokenHeader: jwt

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

Setting Description
applyToRoutes Use labels to configure which routes to apply the policy to. This example label matches the app and route from the example route table that you previously applied. 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 Gateway 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. The secret must exist on the same cluster as the ExtAuthServer resource that this policy refers to. In this example, you created the secret in an earlier step.
issuerUrl The URL of the OpenID Connect identity provider. Gloo Gateway automatically discovers OIDC configuration by querying the .well-known/openid-configuration endpoint on the issuer_url. In this example, Gloo Gateway 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. Copy the output of the following command and open the path in your web browser to access the httpbin app. You are redirected to the authentication page from the Keycloak identity provider.
    echo "https://${INGRESS_GW_IP}:443/get"
  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.


You can clean up the resources that you created in this guide by running the following commands.

  1. Remove Keycloak from your cluster.
    kubectl delete namespace keycloak
  2. Delete the resources that you created for the external auth policy.
    kubectl delete secret -n httpbin oauth
    kubectl delete routetable -n httpbin httpbin
    kubectl delete extauthserver -n httpbin ext-auth-server
    kubectl delete extauthpolicy -n httpbin httpbin