Background

Keycloak is a popular, open-source authentication and authorization capability that provides username-password as well as X509 certification authentication that integrates well with Jupyterhub.

Keycloak Kubernetes Deployment

Helm Chart

I personally use the Bitnami Keycloak Helm chart. I use all the defaults with the exception of the Postgres database, which I deploy separately.

Postgres Database Deployment

The Postgres deployment utilizes the Persistent Volume with a local-storage class along with a values.yaml.

Persistent Volume (PV)

apiVersion: v1
kind: PersistentVolume
metadata:
  name: postgres
spec:
  capacity:
    storage: 1Gi
  accessModes:
  - ReadWriteOnce
  persistentVolumeReclaimPolicy: Retain
  storageClassName: local-storage
  hostPath:
    path: /mnt/k8s/postgres/keycloak

The kubectl deployment is as follows:

kubectl apply -f keycloak-postgres-pv.yaml

Persistent Volume Claim (PVC)

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: keycloak-postgres
spec:
  storageClassName: "local-storage"
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi

The kubectl deployment is as follows:

kubectl apply -f keycloak-postgres-pvc.yaml

Postgres Helm Deployment

values.yaml

An example values.yaml file per the Bitnami postgres values.yaml specification is as follows:

global:
  storageClass: local-storage
  postgresql:
    auth:
      #existingSecret: keycloak-postgres
      database: keycloak
      username: keycloak
      password: changeit
      postgresPassword: changeit
primary:
  persistence:
    existingClaim: keycloak-postgres

Deployment Command

# Add bitnami helm repo
helm repo add bitnami https://charts.bitnami.com/bitnami

# specify values.yaml file (in this case, named bitnami-postgres-values.yaml)
helm install keycloak-postgres -f bitnami-postgres-values.yaml bitnami/postgresql

Postgres Database Administration

Logging in as postgres

psql -U postgres -d postgres

Creating and Configuring Keycloak Postgres Resources

# Grant keycloak Database Privileges
grant all on database keycloak TO keycloak;

Bitnami Keycloak Deployment

Keycloak values.yaml

Open a file entitled keycloak-values.yaml and add the following:

postgresql:
  enabled: false
externalDatabase:
  host: postgres
  user: keycloak
  password: <keycloak password>
  database: keycloak

Keycloak Helm Deployment Command

helm install keycloak -f keycloak-values.yaml bitnami/keycloak

Keycloak-Jupyterhub Integration

Jupyterhub Authenticator

Authenticator Class

The GenericOAuthenticator is used for Keycloak authentication/authorization for Jupyterhub.

Configuring KeyCloak-Jupyterhub Authenticator

          c.JupyterHub.authenticator_class = GenericOAuthenticator
          c.GenericOAuthenticator.oauth_callback_url = 'http://$JUPYTERHUB_HOST:$JUPYTERHUB_PORT/hub/oauth_callback'
          c.GenericOAuthenticator.client_id = $SLURM_CLIENT_ID
          c.GenericOAuthenticator.client_secret = $SLURM_CLIENT_SECRET
          c.GenericOAuthenticator.authorize_url = 'https://$KEYCLOAK_HOST:$KEYCLOAK_PORT/auth/realms/master/protocol/openid-connect/auth'
          c.GenericOAuthenticator.token_url = 'https://$KEYCLOAK_HOST:$KEYCLOAK_PORT/auth/realms/master/protocol/openid-connect/token'
          c.GenericOAuthenticator.userdata_url = 'https://$KEYCLOAK_HOST:$KEYCLOAK_PORT/auth/realms/master/protocol/openid-connect/userinfo'
          c.GenericOAuthenticator.login_service = 'keycloak'
          c.GenericOAuthenticator.auto_login = False
          c.GenericOAuthenticator.username_key = 'preferred_username'
          c.GenericOAuthenticator.userdata_params = {"state": "state"}
          c.GenericOAuthenticator.admin_users={'<comma-delimited list of users with admin privileges>'}
          c.GenericOAuthenticator.scope = ['openid', 'profile']