User Management Guide

This guide covers user management via the Admin Panel (web interface) and CLI scripts.

Prerequisites

# Install dependencies
pip install pandas openpyxl requests

Initial Setup

Auto-Admin on Helm Install

When custom.adminUser.enabled: true is set in values.yaml, helm install automatically:

  1. Generates random API token and admin password

  2. Creates jupyterhub-admin-credentials secret

  3. Configures admin user with admin privileges on hub startup

The API token is associated with the admin user for script operations.

Get credentials after install:

# Get admin password
kubectl -n jupyterhub get secret jupyterhub-admin-credentials \
  -o go-template='{{index .data "admin-password" | base64decode}}'

# Get API token
export JUPYTERHUB_TOKEN=$(kubectl -n jupyterhub get secret jupyterhub-admin-credentials \
  -o go-template='{{index .data "api-token" | base64decode}}')

Manual Setup (if auto-admin disabled)

If custom.adminUser.enabled: false, create credentials manually:

# Create secret with random token and password
kubectl -n jupyterhub create secret generic jupyterhub-admin-credentials \
  --from-literal=api-token=$(openssl rand -hex 32) \
  --from-literal=admin-password=$(openssl rand -base64 12)

# Restart hub to apply
kubectl -n jupyterhub rollout restart deployment/hub

Daily Usage

Set Environment Variables

# Get token from Kubernetes secret
export JUPYTERHUB_TOKEN=$(kubectl -n jupyterhub get secret jupyterhub-admin-credentials \
  -o go-template='{{index .data "api-token" | base64decode}}')
export JUPYTERHUB_URL="http://localhost:30890"  # Or your hub URL

Or add to your shell profile (~/.bashrc or ~/.zshrc):

alias jhtoken='export JUPYTERHUB_TOKEN=$(kubectl -n jupyterhub get secret jupyterhub-admin-credentials -o go-template="{{index .data \"api-token\" | base64decode}}")'

Web Interface (Admin Panel)

Access the Admin Panel at /hub/admin/users.

User Table

The user table displays:

  • Username - Click to view user details

  • Admin - Admin status badge

  • Quota - Current quota balance (if quota system enabled)

  • Server - Server status (Running/Stopped)

  • Last Activity - Last login or activity time

Create User

  1. Click “Create Users” button

  2. Enter usernames (one per line for batch creation)

  3. Choose password option:

    • Generate random passwords (default) - Each user gets a unique password

    • Set password - Enter a password for all users

  4. (Optional) Check “Force password change on first login”

  5. (Optional) Check “Grant admin privileges”

  6. Click “Create Users”

  7. After creation, copy the username/password table to share with users

Edit User

  1. Click the pencil icon on a user row to view user details

  2. Click “Edit User” to enter edit mode

  3. Available modifications:

    • Username - Rename the user (warning: user must login with new name)

    • Admin status - Grant or revoke admin privileges

    • Groups - Assign user to groups

  4. Click “Save Changes”

Set Password

  1. Click the key icon on a user row

  2. Enter new password, or click “Generate” for a random password

  3. (Optional) Check “Force password change on next login”

  4. Click “Set Password”

  5. After success, copy the password to share with the user

Server Control

  • Stop: Click the red stop button to stop a user’s running server

  • Start: Click the green play button to start a user’s server

Batch Operations

  1. Select multiple users using checkboxes

  2. Available batch actions:

    • Start All Selected - Start servers for selected users

    • Stop All Selected - Stop servers for selected users

    • Set Quota - Set quota for selected users (see Quota System)

Search and Filter

  • Use the search box to filter users by username

  • Toggle “Only Active Servers” to show only users with running servers

  • Click column headers to sort by that column

Manage Groups

Click “Manage Groups” to navigate to the group management page.

Script Usage

1. Generate User Templates

Create user list templates for batch operations.

# Generate 50 students
python scripts/generate_users_template.py --prefix student --count 50 --output users.csv

# Generate AUP users (AUP01, AUP02, ...)
python scripts/generate_users_template.py --prefix AUP --count 30 --start 1 --output aup_users.xlsx

# Generate with 3-digit padding
python scripts/generate_users_template.py --prefix student --count 100 --digits 3 --output users.csv

# Custom usernames
python scripts/generate_users_template.py --names alice bob charlie --output custom.csv

Output format (CSV/Excel):

username,admin
student01,false
student02,false
student03,false

2. Manage Users

Perform batch operations via JupyterHub API.

# Create users from file
python scripts/manage_users.py create users.csv

# List all users
python scripts/manage_users.py list

# Export users to backup file
python scripts/manage_users.py export backup.xlsx

# Delete users (with confirmation)
python scripts/manage_users.py delete remove_list.csv

# Delete users (skip confirmation)
python scripts/manage_users.py delete remove_list.csv --yes

3. Manage Admin Privileges

Grant or revoke admin privileges for existing users.

# Grant admin to single user
python scripts/manage_users.py set-admin teacher01

# Grant admin to multiple users
python scripts/manage_users.py set-admin teacher01 teacher02 teacher03

# Grant admin from file
python scripts/manage_users.py set-admin -f admins.csv

# Revoke admin privileges
python scripts/manage_users.py set-admin --revoke student01

# Batch revoke
python scripts/manage_users.py set-admin --revoke -f demote_list.csv

4. Set Passwords

Set default passwords for users (requires kubectl access).

Note: For quota management commands (set-quota, add-quota, list-quota), see the User Quota System documentation.

# Set passwords from file with password column
python scripts/manage_users.py set-passwords users_with_passwords.csv

# Generate random passwords for users
python scripts/manage_users.py set-passwords users.csv --generate -o passwords_output.csv

# Set same default password for all users
python scripts/manage_users.py set-passwords users.csv --generate --default-password "Welcome123"

# Set passwords without forcing change on first login
python scripts/manage_users.py set-passwords users.csv --no-force-change

Common Workflows

Create New Users

# Step 1: Generate template
python scripts/generate_users_template.py \
  --prefix student \
  --count 50 \
  --output new_students.csv

# Step 2: (Optional) Edit CSV to customize
# Edit new_students.csv if needed

# Step 3: Create users in JupyterHub
python scripts/manage_users.py create new_students.csv

Expected output:

✅ Connected to JupyterHub at http://localhost:30890
📄 Loaded 50 users from new_students.csv

🔄 Creating 50 users...
  ✅ Created user: student01 (admin=False)
  ✅ Created user: student02 (admin=False)
  ...

==================================================
📊 Results:
  ✅ Created: 50
  ⚠️  Already exist: 0
  ❌ Failed: 0
==================================================

Promote Users to Admin

# Single user
python scripts/manage_users.py set-admin teacher01

# Multiple users
python scripts/manage_users.py set-admin teacher01 teacher02

# From file (any CSV with username column)
python scripts/manage_users.py set-admin -f new_admins.csv

Backup Users

# Backup current users
python scripts/manage_users.py export users_backup_$(date +%Y%m%d).xlsx

# Later: restore users
python scripts/manage_users.py create users_backup_20260113.xlsx

Remove Users

# Step 1: Export current users
python scripts/manage_users.py export all_users.csv

# Step 2: Edit CSV, keep only users to delete
# Create remove_list.csv with usernames to delete

# Step 3: Delete users
python scripts/manage_users.py delete remove_list.csv

File Format

Both scripts support CSV and Excel (.xlsx) formats.

Required column:

  • username - Username to create/delete

Optional columns:

  • admin - Set to true for admin users (default: false)

  • password - Password for set-passwords command

Example CSV:

username,admin
student01,false
student02,false
teacher01,true

Troubleshooting

Connection Issues

Symptom: “Connection refused”

Solutions:

# Check hub is running
kubectl --namespace=jupyterhub get pods

# For local dev
export JUPYTERHUB_URL="http://localhost:30890"

# For production
export JUPYTERHUB_URL="https://your-domain.com"

# Test connection
curl $JUPYTERHUB_URL/hub/api/

Authentication Issues

Symptom: “Authentication failed”

Solutions:

# Verify token is set
echo $JUPYTERHUB_TOKEN

# Test token
curl -X GET $JUPYTERHUB_URL/hub/api/ \
  -H "Authorization: token $JUPYTERHUB_TOKEN"

Common Errors

“User already exists”

  • This is just a warning, not an error

  • The user is already in the system

“File must contain ‘username’ column”

  • Ensure your file has a username column header

Notes

  • Auto-Admin: Initial admin is created automatically on helm install

  • Additional Admins: Use set-admin command or Admin Panel

  • First Login: Native users must set their password on first login

  • Safety: Delete operations ask for confirmation (use --yes to skip)

  • Batch Size: No limit, but larger batches (1000+) may be slow

Help

Get detailed help for each script:

python scripts/generate_users_template.py --help
python scripts/manage_users.py --help