Skip to content

Auth0 User Registration and Role Management Setup Guide

Overview

Your Auth0 integration now includes comprehensive role-based access control with a "pending" state for new users. Here's what's been implemented:

๐Ÿ”’ Security Model

User Registration Flow

  1. Anyone can register via Auth0 (Google, email/password, etc.)
  2. New users get "pending" role automatically
  3. Pending users cannot access protected content
  4. Admin must approve users and assign proper roles
  5. Only approved users can access medical data and search

Role Hierarchy

  • pending - New users, no access to protected content
  • patient - Basic access to medical data
  • clinician - Enhanced access to technical documentation
  • admin - Full access + user management capabilities

๐Ÿš€ Setup Steps

1. Environment Configuration

Create a .env file (copy from .env.example):

# Auth0 Configuration
AUTH0_DOMAIN=auth.jmdaling.co.za
AUTH0_API_AUDIENCE=https://remission-api

# Auth0 Management API (for user management)
AUTH0_MANAGEMENT_CLIENT_ID=your_m2m_client_id
AUTH0_MANAGEMENT_CLIENT_SECRET=your_m2m_client_secret

2. Auth0 Dashboard Setup

A. API Configuration

  1. Go to Auth0 Dashboard > Applications > APIs
  2. Create/update your API:
  3. Name: Remission Health API
  4. Identifier: https://remission-api
  5. Signing Algorithm: RS256

B. Machine-to-Machine App (for Management API)

  1. Go to Applications > Create Application
  2. Choose Machine to Machine
  3. Name: Remission User Management
  4. Authorize for: Auth0 Management API
  5. Required Scopes:
  6. read:users
  7. update:users
  8. read:roles
  9. update:user_roles
  10. Copy Client ID and Secret to your .env file

C. Default Role Action

  1. Go to Auth0 Dashboard > Actions > Flows
  2. Select Login flow
  3. Create new Action: "Assign Default Pending Role"
exports.onExecutePostLogin = async (event, api) => {
  const namespace = 'https://remission.health/roles';

  // Check if user has any roles assigned
  const userRoles = event.user.app_metadata?.roles || [];

  // If no roles, assign 'pending'
  if (userRoles.length === 0) {
    api.user.setAppMetadata('roles', ['pending']);
  }

  // Add roles to token
  api.idToken.setCustomClaim(namespace, userRoles);
  api.accessToken.setCustomClaim(namespace, userRoles);
};
  1. Deploy the Action and add to Login flow

3. Frontend Configuration

Copy the Auth0 config template:

cp docs/javascripts/auth0-config.template.js docs/javascripts/auth0-config.js

Edit docs/javascripts/auth0-config.js with your credentials:

window.auth0Config = {
    domain: 'your-tenant.us.auth0.com',
    clientId: 'your_spa_client_id',
    audience: 'https://remission-api',
    redirectUri: window.location.origin,
    scope: 'openid profile email'
};

4. Build and Deploy

# Rebuild with new dependencies
docker compose down
docker compose up -d --build

๐Ÿ‘‘ Admin Interface Usage

Accessing Admin Panel

  1. Log in with admin role
  2. Go to /admin page
  3. View dashboard with user statistics

Managing Users

View Pending Approvals

  • See all users waiting for approval
  • Quick approve individual users
  • Bulk approve all as "patient" role

User Management

  • Search users by email
  • Filter by role
  • Change user roles
  • Revoke access (return to pending)

Available Actions

  • Approve as Patient - Basic medical data access
  • Approve as Clinician - Enhanced documentation access
  • Promote to Admin - Full system access
  • Revoke Access - Return to pending status

๐Ÿ”ง API Endpoints

Protected Endpoints (Require Authentication)

  • POST /search - Vector search (approved users only)
  • POST /ask - RAG question answering (approved users only)

Admin Endpoints (Admin Role Required)

  • GET /api/admin/stats - User statistics
  • GET /api/admin/users/pending - Pending users list
  • GET /api/admin/users - All users (paginated)
  • POST /api/admin/users/approve - Approve single user
  • POST /api/admin/users/bulk-approve - Approve multiple users
  • PUT /api/admin/users/{id}/role - Change user role
  • DELETE /api/admin/users/{id} - Revoke user access

๐Ÿ›ก๏ธ Security Features

JWT Verification

  • RSA256 signature verification
  • Audience validation (https://remission-api)
  • Issuer validation (https://your-domain.auth0.com/)
  • Token expiration handling

Role-Based Access

  • require_approved_user() - Blocks pending users
  • require_role("admin") - Requires specific role
  • require_any_role(["clinician", "admin"]) - Multiple role options

Data Isolation

  • Multi-tenant support via get_tenant_id()
  • Each user can only access their own data
  • Admin can manage all users

๐Ÿงช Testing

Test User Registration

  1. Open site in incognito window
  2. Register new account
  3. Verify you see "pending approval" message
  4. Log in as admin, approve the user
  5. Test approved user can access protected content

Test Role Changes

  1. Create test users with different roles
  2. Verify access levels for each role
  3. Test role changes via admin interface
  4. Confirm immediate effect (may need re-login)

๐Ÿšจ Troubleshooting

Common Issues

"Account pending approval" message for admin - Check Action is deployed and in Login flow - Verify admin user has roles in app_metadata - Check custom claims namespace matches

Admin interface shows "Insufficient permissions" - Ensure user has admin role in Auth0 - Check roles are added to JWT token - Verify custom claims Action is working

API calls fail with 401 - Check environment variables are set - Verify Auth0 domain and audience match - Confirm JWTs include required claims

Debug Commands

# Check environment variables
docker exec remission env | grep AUTH0

# View user token in browser console
console.log(localStorage.getItem('access_token'))

# Test Management API connection
docker exec remission python -c "
from src.auth.auth0_management import Auth0ManagementAPI
api = Auth0ManagementAPI()
print(api.get_role_statistics())
"

๐Ÿ“ Next Steps

  1. Set up email notifications for new user registrations
  2. Add user onboarding flow with role-specific welcome messages
  3. Implement user self-service for basic profile management
  4. Add audit logging for admin actions
  5. Configure production domains and CORS settings

This guide covers the complete Auth0 setup for secure, role-based access to your health platform.