User credentials OAuth with Keycloak

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

Before you begin

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.

• Username: user1, password: password, email: user1@example.com
• Username: user2, password: password, email: user2@solo.io

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 https://raw.githubusercontent.com/solo-io/workshops/master/gloo-mesh-2-3/all/data/steps/deploy-keycloak/keycloak.yaml
   

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)
   export KEYCLOAK_URL=http://${ENDPOINT_KEYCLOAK}
   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)
   echo $KEYCLOAK_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}
   echo $KEYCLOAK_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}
   echo $KEYCLOAK_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": {"claim.name": "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": "user1@example.com", "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": "user2@solo.io", "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.

1. Create a Kubernetes secret with the Keycloak OIDC secret.

   kubectl 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 apply -f - <<EOF
   apiVersion: admin.gloo.solo.io/v2
   kind: ExtAuthServer
   metadata:
     name: ext-auth-server
     namespace: httpbin
   spec:
     destinationServer:
       ref:
         cluster: $CLUSTER_NAME
         name: ext-auth-service
         namespace: gloo-mesh-addons
       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 apply -f - <<EOF
   apiVersion: networking.gloo.solo.io/v2
   kind: RouteTable
   metadata:
     name: httpbin
     namespace: httpbin
     labels:
       expose: "true"
   spec:
     hosts:
       - '*'
     virtualGateways:
       - name: istio-ingressgateway
         namespace: bookinfo
         cluster: $CLUSTER_NAME
     workloadSelectors: []
     http:
       - name: httpbin
         labels:
           oauth: "true"
         matchers:
         - uri:
             exact: /get
         - uri:
             prefix: /callback
         forwardTo:
           destinations:
           - kind: SERVICE
             ref:
               name: httpbin
               namespace: httpbin
               cluster: $CLUSTER_NAME
             port:
               number: 8000
   EOF
   

4. Create an external auth policy that uses Keycloak for OIDC.

   kubectl 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_NAME
       glooAuth:
         configs:
         - oauth2:
             oidcAuthorizationCode:
               appUrl: "https://${INGRESS_GW_IP}:443"
               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.

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.

Cleanup

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