OpenShift Setup#

In case you have an OpenShift deployment with OAuth properly configured (see the following sections for a quick reference), you should set the client ID and secret by the environment variables OAUTH_CLIENT_ID, OAUTH_CLIENT_SECRET and OAUTH_CALLBACK_URL.

Prior to OpenShift 4.0, the OAuth provider and REST API URL endpoints can be specified by setting the single environment variable OPENSHIFT_URL. From OpenShift 4.0 onwards, these two endpoints are on different hosts. You need to set OPENSHIFT_AUTH_API_URL to the OAuth provider URL, and OPENSHIFT_REST_API_URL to the REST API URL endpoint.

The OAUTH_CALLBACK_URL should match http[s]://[your-app-route]/hub/oauth_callback

Global OAuth (admin)#

As a cluster admin, you can create a global OAuth client in your OpenShift cluster creating a new OAuthClient object using the API:

oc create -f - <<EOF
apiVersion: v1
kind: OAuthClient
metadata:
   name: <OAUTH_CLIENT_ID>
redirectURIs:
- <OUAUTH_CALLBACK_URL>
secret: <OAUTH_SECRET>
EOF

Service Accounts as OAuth Clients#

As a project member, you can use the Service Accounts as OAuth Clients scenario. This gives you the possibility of defining clients associated with service accounts. You just need to create the service account with the proper annotations:

oc create -f - <<EOF
apiVersion: v1
kind: ServiceAccount
metadata:
   name: <name>
   annotations:
      serviceaccounts.openshift.io/oauth-redirecturi.1: '<OUAUTH_CALLBACK_URL>'
EOF

In this scenario your OAUTH_CLIENT_ID will be system:serviceaccount:<serviceaccount_namespace>:<serviceaccount_name>, the OAUTH_CLIENT_SECRET is the API token of the service account (oc sa get-token <serviceaccount_name>) and the OAUTH_CALLBACK_URL is the value of the annotation serviceaccounts.openshift.io/oauth-redirecturi.1. More details can be found in the upstream documentation.

JupyterHub configuration#

Your jupyterhub_config.py file should look something like this:

c.JupyterHub.authenticator_class = "openshift"
c.OAuthenticator.oauth_callback_url = "https://[your-domain]/hub/oauth_callback"
c.OAuthenticator.client_id = "[your oauth2 application id]"
c.OAuthenticator.client_secret = "[your oauth2 application secret]"

Additional configuration#

OpenShiftOAuthenticator expands OAuthenticator with the following config that may be relevant to read more about in the configuration reference: