JupyterHub

Connect JupyterHub to Oleria to see who can use your hub and what they can reach. That covers every user and administrator, the groups and roles they belong to, the services and API tokens that act on the hub, and the notebook servers people share with each other or through share links. Oleria reads this from the JupyterHub REST API with an API token. This integration is for self-hosted JupyterHub 5.x and 6.x, including hubs deployed with Zero to JupyterHub on Kubernetes or The Littlest JupyterHub. One Oleria connection maps one hub. Connect additional hubs as separate instances.

What Oleria discovers

Once connected, Oleria continuously discovers and maps the following from the hub:

Users - every user on the hub, with their name and email when the authenticator provides them, when they were created, and their last activity. Administrators are marked as such. Users blocked in the hub configuration show as disabled.
Sign-in and MFA - whether users sign in through single sign-on (OAuth/OIDC, LDAP, or LTI) or with a password, based on the hub’s authenticator. With an OIDC identity provider that reports how the user authenticated, Oleria also shows whether each user signed in with multi-factor authentication. See MFA status.
Groups - groups, their members, and their properties.
Roles - the built-in admin and user roles and every custom role assigned to a user, group, or service, with each assignment.
Non-human identities - services, and every API token on the hub: tokens users created on the Token page, the tokens the hub issues to notebook servers, and OAuth tokens issued to services. Each token is paired with a credential that shows its permissions (scopes), expiry, and last use, and the user it acts as. Oleria never reads token values.
Share links - share codes, the invitation links that grant access to a notebook server to anyone who has the link. Each one appears with its expiry and last use, and an active link marks the server as reachable by link holders.
Notebook servers - each user’s default and named servers, running or stopped, with who can access them: the owner, administrators, and the users and groups the server is shared with.
Activity - API token creation, the most recent use of each token, users’ most recent activity, and share-link redemptions. See Known limitations.

Notebook contents, files, and server logs are not synced.

Prerequisites

A JupyterHub 5.0 or later, reachable over HTTPS from the internet at a public address. Hubs that are only reachable on a private network or VPN, or whose address resolves to a private IP, can’t be connected.
Oleria allowed to reach your hub’s address. Contact support@oleria.com with the hub’s host name before you connect.
A JupyterHub administrator account, or access to the hub configuration to add a service.

Create an API token

Oleria needs an API token with the read permissions in the table below. Use one of these two options.

Option 1: A token from an administrator account

Sign in to JupyterHub with an administrator account. We recommend a dedicated account for Oleria rather than a person’s account: JupyterHub marks the token’s user as active on every request Oleria makes, so Oleria doesn’t report last activity for that user.

Request the token

Select Token in the top menu. Enter a note such as “Oleria”, choose an expiration, and in Permissions enter the scopes from the tables below, separated by spaces. Select Request new API token, and copy the token. JupyterHub shows it only once.

Option 2: A service in the hub configuration

Define a service and a role for Oleria in jupyterhub_config.py (or in your Helm values for Zero to JupyterHub), and restart the hub:

import os

c.JupyterHub.services = [
    {"name": "oleria", "api_token": os.environ["OLERIA_JUPYTERHUB_TOKEN"]},
]
c.JupyterHub.load_roles = [
    {
        "name": "oleria-reader",
        "scopes": [
            "list:users", "read:users", "read:roles", "read:hub",
            "list:groups", "read:groups", "list:services", "read:services",
            "read:tokens", "read:servers", "read:shares", "admin:auth_state",
        ],
        "services": ["oleria"],
    },
]

Generate a long random value for OLERIA_JUPYTERHUB_TOKEN (for example with openssl rand -hex 32), and keep it in a secret store rather than in the file. A service is the recommended option: its requests don’t count as any user’s activity. Read scopes, for discovery:

Scope	What it adds
`list:users`, `read:users` (required)	Users, their names, groups, servers, and last activity.
`read:hub`	The hub version and authenticator, which tell Oleria whether users sign in with SSO or a password.
`read:roles`	Role assignments, and which users are blocked.
`list:groups`, `read:groups`	Groups, their members, and their properties.
`list:services`, `read:services`	Services and their roles.
`read:tokens`	API tokens and their permissions.
`read:servers`	Notebook servers.
`read:shares`	Server shares and share links.
`admin:auth_state`	Users’ email and MFA status from the identity provider. See MFA status.

If you leave out an optional scope, Oleria skips that part and still syncs the rest. A token can only carry scopes its owner holds, so request it from an administrator account or a service whose role grants them. Write scopes, only for remediation actions. Each action also needs the read scope for what it changes, for example read:groups for group membership or read:tokens for revoking tokens:

Scope	What it allows
`admin:users`	Creating users, and granting and removing the `admin` role. Changing the `admin` role also needs `read:groups` and `read:roles:groups`, and the token’s owner must be an administrator (see below).
`delete:users`	Deleting users, and undoing a user Oleria created.
`admin:groups`	Creating groups, and undoing a group Oleria created.
`groups`	Adding users to groups and removing them, including when creating a user with groups.
`tokens`	Revoking API tokens.
`shares`	Revoking server shares and share links.
`read:users:name`, `read:groups:name`	Undoing a revoked server share. JupyterHub requires them to share a server with a user or group by name.

JupyterHub lets only an administrator grant or remove the admin role, whatever scopes the token holds. To use those two actions, request the token from an administrator account, or add "admin": True to the Oleria service in c.JupyterHub.services. That makes the service a hub administrator with every admin scope. Without it, Oleria reports that the admin role can’t be changed and runs the other actions as usual.

MFA status

JupyterHub doesn’t track multi-factor authentication itself; your identity provider does. Oleria reads each user’s MFA status from the authentication record the identity provider returned at their last sign-in. This works when all of the following hold:

The hub uses an OIDC authenticator (for example GenericOAuthenticator) with enable_auth_state = True and a JUPYTERHUB_CRYPT_KEY set.
The identity provider includes the amr claim (how the user authenticated) in its user information.
The token has the admin:auth_state scope.

Otherwise, MFA shows as unavailable. Oleria uses the profile and the amr claim only, and never stores the access or refresh tokens that JupyterHub keeps in the authentication record.

Connect JupyterHub to Oleria

Open the integration

Go to your Oleria workspace, select Integrations -> select JupyterHub.

Complete the connection form

Field	Notes
Hub URL	Required. The HTTPS address of the hub, the part before `/hub/`, for example `https://hub.example.org` or `https://example.org/jupyter`. You can’t change the URL after the integration is saved.
API token	Required. The token you created. When you edit the integration later, leave it blank to keep the stored token.

Authenticate

Select Authenticate to validate and save the integration. Oleria checks that the token is valid and can list and read users before saving.

Verify the integration

Confirm the hub appears on the Connected tab of your Oleria Integrations page. After the first sync completes, review the discovered users, groups, tokens, and servers in your Oleria workspace.

Remediation actions

Beyond discovery, Oleria can act on JupyterHub access to remediate risk. Remediation needs the write scopes described above. Oleria checks that the token holds them before an action runs, and reports any that are missing.

Action	What it does	Reversible?
Grant or remove the admin role	Makes the user a hub administrator, or removes administrator rights.	Yes - applies the opposite change.
Add to or remove from a group	Changes the user’s group membership.	Yes - applies the opposite change.
Revoke an API token	Deletes the token, so it stops working immediately. For an OAuth token issued to a service or server, JupyterHub also deletes the user’s other tokens for that service or server, and Oleria lists them in the result.	No - the user must create a new token, or sign in to the service again.
Revoke a share link	Deletes one share code, so the link stops working. People who already accepted it keep their access until you revoke that too.	No - the server’s owner must create a new link.
Revoke access to a server	Removes a user’s or group’s share of a notebook server.	Yes - shares the server again with the same permissions.
Revoke all share links for a server	Deletes every share code for the server.	No - the server’s owner must create new links.
Delete user	Deletes the user, along with their servers, tokens, shares, and group memberships.	No - everything the user had on the hub is gone. Whether they can sign in again depends on your authenticator.
Create user	Adds a user by username, optionally to existing groups. JupyterHub stores only the name, normalized the way the authenticator normalizes it at sign-in (by default, lowercased), so the new user matches the person who signs in; Oleria reports the stored name. The authenticator supplies the profile when the user signs in.	Yes - deletes the user. An existing user is left unchanged.
Create group	Adds an empty group.	Yes - deletes the group. An existing group is left unchanged.

Oleria refuses to:

delete the user the integration’s token belongs to, change their roles or groups, or revoke their tokens
change custom roles. These are defined in the hub configuration, which the API can’t change. Edit load_roles instead.
remove the admin role from a user who is an administrator through a group. The group’s role is assigned in load_roles, so Oleria names the group, and you remove the user from it there or in JupyterHub.
disable services. These are defined in the hub configuration. Remove the service there.
revoke the owner’s own access to their server

If you remove the admin role from a user listed in the authenticator’s admin_users setting, JupyterHub makes them an administrator again the next time the hub restarts. Remove them from admin_users too.

Known limitations

No audit log. JupyterHub doesn’t keep an audit log. Oleria derives activity from timestamps the API exposes: when a token was created and by whom, each token’s most recent use, each user’s most recent activity, and share-link redemptions. Sign-ins, server starts and stops, and admin changes aren’t available.
MFA depends on your identity provider. See MFA status. With NativeAuthenticator, the two-factor setting is stored outside the JupyterHub API, so MFA shows as unavailable.
Custom role permissions aren’t shown. JupyterHub exposes role names, but not the scopes a custom role grants, which live in the hub configuration. Built-in roles show their documented permissions.
Blocked users are inferred. JupyterHub has no user status. Users in the authenticator’s blocked_users setting lose all their roles when the hub starts, and Oleria shows a user with no roles as disabled.
Service tokens from the configuration aren’t listed. The API doesn’t list tokens defined in jupyterhub_config.py, so services appear without their configuration token.
No last password change. Passwords belong to your identity provider or authenticator, not JupyterHub.
Sessions can’t be revoked. JupyterHub has no API that ends a user’s sign-in; the login cookie stays valid until it expires (cookie_max_age_days, 14 days by default). To cut access sooner, delete the user or block them in the authenticator.
No last activity for the token’s user. If the token belongs to a user rather than a service, JupyterHub records that user as active on every request Oleria makes, so Oleria doesn’t show last activity for that user, and doesn’t report its own token’s use as activity.

Contact us

For questions about this integration, contact us at support@oleria.com.

Overview

Generic connectors

Identity providers

HR systems

Cloud infrastructure

Applications

Ticketing

Messaging

What Oleria discovers

Prerequisites

Create an API token

Option 1: A token from an administrator account

Option 2: A service in the hub configuration

MFA status

Connect JupyterHub to Oleria

Verify the integration

Remediation actions

Known limitations

Contact us

​What Oleria discovers

​Prerequisites

​Create an API token

​Option 1: A token from an administrator account

​Option 2: A service in the hub configuration

​MFA status

​Connect JupyterHub to Oleria

​Verify the integration

​Remediation actions

​Known limitations

​Contact us

What Oleria discovers

Prerequisites

Create an API token

Option 1: A token from an administrator account

Option 2: A service in the hub configuration

MFA status

Connect JupyterHub to Oleria

Verify the integration

Remediation actions

Known limitations

Contact us