Authenticating via REST API


I am trying to use the hubs REST API from a custom UI and wanted to avoid using an API token and instead use the custom keycloak OAuth authenticator I have setup. Currently the authenticator works when using the provided hub UI, but I cannot figure out how to authenticate with it via the REST API. After combing through the documentation, I’ve only been able to find information on using API keys to authenticate the REST API.

Expected behavior

If the API supports this functionality add documentation describing the flow of API calls needed to authenticate through the REST API. If the API doesn’t support this, add in support on the REST API to utilize the configured authenticators to authenticate.

Actual behavior

Custom authenticator authenticates users correctly when using the provide hub UI, but all requests to the API via postman receive a 4xx error. The API errors are caused because I am not sure how to authenticate via the REST API.

How to reproduce

I am running jupyterhub via kubernetes and helm following the zero-to-jupyterhub guide. I have outlined the steps below to reproduce my environment and see the bug/issue I am seeing.


      enable_auth_state: true
      auto_login: true 
      client_id: <keycloak client_id>
      client_secret: <keycloak client_secret>
      oauth_callback_url: http://localhost:80/hub/oauth_callback
      authorize_url: https://<keycloak_uri>/auth/realms/<realm>/protocol/openid-connect/auth
      token_url: https://<keycloak_uri>/auth/realms/<realm>/protocol/openid-connect/token
      userdata_url: https://<keycloak_uri>/auth/realms/<realm>/protocol/openid-connect/userinfo
      login_service: Keycloak
      username_key: sub
        state: state
      authenticator_class: generic-oauth 

  enabled: true
  1. Create Namespace
kubectl create namespace jupyterhub
  1. Run Helm Chart
helm repo add jupyterhub
helm repo update
helm upgrade --install jupyterhub jupyterhub/jupyterhub --cleanup-on-fail --namespace jupyterhub --create-namespace --version=2.0.0 --values values-local.yaml

  1. Visit localhost and sign-in to see the hub UI authentication work.

  2. Attempt some of the hub API calls to see 400 error.

Your personal set up
OS: mac OS

I have tried to follow this suggested workaround and ran into some issues. Since the jupyterhub UI is not running I cannot access the api token page referenced in your link, and without the code from the /hub/api/oauth/authorize endpoint I cannot request an API token via the /hub/api/oauth/token endpoint. So here are my following questions.

  • How are you supposed to use the /hub/api/oauth/token endpoint if you cannot generate the code from the /hub/api/oauth/authorize? Is there another way to get that code value?
  • Can I configure jupyterhub to allow me to use a token from keycloak to use the API and bypass getting a token from the hub?

Related github issue

I don’t understand what you mean by “add in support on the REST API to utilize the configured authenticators to authenticate.”

Authentication happens on the front-end, e.g. with Keycloak a user is redirected from the JupyterHub UI to the Keycloak UI. Assuming they login successfully the user is then redirected back to JupyterHub, and eventually JupyterHub creates an API token that JupyterLab (or any other frontend) uses.

If you’re doing everything with the JupyterHub backend only, then there’s no way to redirect the user to Keycloak.

If you’re writing a custom UI you’ll need to implement authentication with Keycloak there, and give your front-end a privileged token that allows it to create tokens for users.

I ended up using a service to handle api calls and interaction with the jupyterhub and jupyter-server . We are leaving the auth to our company api-gateway .