Keycloak

We are using Keycloak for web SSO (Single Sign-On). Clients may use Keycloak for authenticating users via SAML or OIDC (OpenID Connect).

• Admin login: https://keycloak.csclub.uwaterloo.ca/auth/admin
• Regular user login: https://keycloak.csclub.uwaterloo.ca/auth/realms/csc/account
• OIDC Auto Discovery URL: https://keycloak.csclub.uwaterloo.ca/auth/realms/csc/.well-known/openid-configuration

Prerequisites

OK so before we get started, there's this really useful feature in Keycloak called "Conditional user attribute" which allows you to create a flow which branches based on attributes a user may have. For some reason, this is enabled in the test suite for Keycloak, but is not available from the main application. So we're going to compile and inject it ourselves.

Clone https://git.csclub.uwaterloo.ca/public/keycloak-spi and run mvn clean package. This will create a JAR file called csc-keycloak-spi.jar in the target directory; upload this to somewhere where it can be easily downloaded, e.g. your www directory.

Database setup

Go to biloba or chamomile, run mysql, and run the following:

CREATE USER 'keycloak' IDENTIFIED BY 'replace_this_password';    
CREATE DATABASE keycloak CHARACTER SET utf8 COLLATE utf8_unicode_ci;    
GRANT ALL PRIVILEGES ON keycloak.* TO 'keycloak';    
FLUSH PRIVILEGES;

Kubernetes setup

We are running Keycloak on Kubernetes. This introduces some complications because it gets reverse proxied twice, and we also can't (or at least shouldn't) modify the filesystem of the Pod where it's running, since that Pod can get destroyed at any time. We still need to load that JAR file we just created, though, so we're going to place it into a PersistentVolume instead. We're going to do this by first creating a PersistentVolumeClaim, then claiming it in a temporary Pod which we'll use for shell access:

cat <<EOF | kubectl apply -f    
apiVersion: v1    
kind: PersistentVolumeClaim    
metadata:    
  namespace: syscom    
  name: keycloak-spi-pvc    
spec:    
  storageClassName: cloudstack-storage    
  accessModes:    
    - ReadWriteOnce    
  resources:    
    requests:    
      storage: 5Mi    
---    
apiVersion: v1    
kind: Pod    
metadata:    
  namespace: syscom    
  name: temp-pod    
spec:    
  containers:    
    - name: temp    
      image: alpine    
      volumeMounts:    
        - mountPath: "/data"    
          name: keycloak-spi-pv    
      stdin: true    
      stdinOnce: true    
      tty: true    
  volumes:    
    - name: keycloak-spi-pv    
      persistentVolumeClaim:    
        claimName: keycloak-spi-pvc
EOF

Run kubectl -n syscom get pods a few times to check if the pod is ready; once it is, attach to it:

kubectl -n syscom exec -it temp-pod -- sh
cd /data
mkdir keycloak-spi
chmod a+w keycloak-spi
cd keycloak-spi
wget https://csclub.uwaterloo.ca/~merenber/csc-keycloak-spi.jar
exit

Now delete the pod since we don't need it anymore:

kubectl -n syscom delete pod temp-pod

Create some secrets (use the MySQL password which you chose earlier):

kubectl -n syscom create secret generic keycloak-secret \
  --from-literal=DB_USER=some_user \
  --from-literal=DB_PASSWORD=some_password \
  --from-literal=KEYCLOAK_USER=some_user \
  --from-literal=KEYCLOAK_PASSWORD=some_password

Now apply the main manifest:

kubectl apply -f https://git.csclub.uwaterloo.ca/cloud/manifests/src/branch/master/keycloak.yaml

DNS setup

From Infoblox, make keycloak.csclub.uwaterloo.ca a CNAME for rr-public-cloud.csclub.uwaterloo.ca; that record points to biloba and chamomile, which know how to reverse proxy requests to Kubernetes.

NGINX setup

Pretty standard stuff:

server {
  listen 80;
  listen [::]:80;
  server_name keycloak.csclub.uwaterloo.ca;
  return 301 https://$host$request_uri;
}

server {
  listen 443 ssl http2;
  listen [::]:443 ssl http2;
  server_name keycloak.csclub.uwaterloo.ca;
  ssl_certificate /etc/ssl/private/csclub.uwaterloo.ca.chain;
  ssl_certificate_key /etc/ssl/private/csclub.uwaterloo.ca.key;
  
  location / {
    proxy_pass http://k8s;
  }
  include proxy_params;

  access_log /var/log/nginx/keycloak-access.log;
  error_log /var/log/nginx/keycloak-error.log;
}

Also make sure you have the following snippet in /etc/nginx/proxy_params:

# Increase buffer size
# See https://ma.ttias.be/nginx-proxy-upstream-sent-big-header-reading-response-header-upstream/
proxy_buffer_size 128k;
proxy_buffers 4 256k;

Don't forget to enable the site and reload NGINX on both chamomile and biloba.

Web UI setup

If all went well, you should now be able to visit https://keycloak.csclub.uwaterloo.ca from your browser. Create a new realm called 'csc'. Set the Display Name to 'Computer Science Club'.