Skip to content

Auth0 Custom Domain - Quick Checklist

✅ Configuration Checklist

Use this checklist to ensure all components are updated for custom domain auth.jmdaling.co.za.

DNS & Auth0 Dashboard

  • [ ] DNS CNAME record added for auth.jmdaling.co.za
  • [ ] Custom domain verified in Auth0 Dashboard
  • [ ] SSL certificate provisioned (status: Ready)
  • [ ] Logo configured in Universal Login settings (https://health.jmdaling.co.za/images/logo.png)
  • [ ] Primary color set to #009688 (teal)
  • [ ] Company name set to "My Health Portal"
  • [ ] Email templates updated (if using Auth0 emails)

Environment Variables

Local .env file: - [ ] AUTH0_DOMAIN=auth.jmdaling.co.za - [ ] AUTH0_TENANT_DOMAIN=dev-80t8a4t7gbp2h55c.eu.auth0.com (for Management API) - [ ] AUTH0_API_AUDIENCE=https://remission-api - [ ] Management API credentials configured

Production .env file (on server): - [ ] AUTH0_DOMAIN=auth.jmdaling.co.za - [ ] AUTH0_TENANT_DOMAIN=dev-80t8a4t7gbp2h55c.eu.auth0.com - [ ] AUTH0_API_AUDIENCE=https://remission-api - [ ] Production Management API credentials

Frontend Configuration

File: docs/javascripts/auth0-config.js - [ ] domain: 'auth.jmdaling.co.za' (updated) - [ ] clientId: '51vX1kTQOAAeOARHyDXVKKMVvc72d64Y' (unchanged) - [ ] audience: 'https://health.jmdaling.co.za' (unchanged)

Backend Configuration

File: src/auth/auth0_management.py - [ ] Uses AUTH0_TENANT_DOMAIN for Management API (tenant domain) - [ ] Falls back to AUTH0_DOMAIN if AUTH0_TENANT_DOMAIN not set

File: src/auth/auth0_verifier.py - [ ] Uses AUTH0_DOMAIN from environment (custom domain) - [ ] JWKS endpoint uses custom domain

Auth0 Application Settings

In Auth0 Dashboard → Applications → My Health Portal:

Allowed Callback URLs: - [ ] http://localhost:8002 (for local dev) - [ ] https://health.jmdaling.co.za (for production)

Allowed Logout URLs: - [ ] http://localhost:8002 - [ ] https://health.jmdaling.co.za

Allowed Web Origins: - [ ] http://localhost:8002 - [ ] https://health.jmdaling.co.za

Allowed Origins (CORS): - [ ] http://localhost:8002 - [ ] https://health.jmdaling.co.za

Social Connections (If Applicable)

If using social login providers, update callback URLs:

Google OAuth: - [ ] Authorized redirect URI: https://auth.jmdaling.co.za/login/callback

GitHub OAuth: - [ ] Authorization callback URL: https://auth.jmdaling.co.za/login/callback

Other Providers: - [ ] Updated callback URLs to use custom domain

Testing

Local Testing: - [ ] Login flow redirects to https://auth.jmdaling.co.za - [ ] Login successful, returns to application - [ ] User info displays correctly - [ ] JWT token has iss claim: https://auth.jmdaling.co.za/ - [ ] Backend JWT verification works - [ ] API calls with token succeed

Production Testing: - [ ] Production login flow works - [ ] No mixed content warnings (all HTTPS) - [ ] Backend logs show custom domain - [ ] Management API operations work (uses tenant domain)

Documentation Updates

  • [ ] README.md mentions custom domain (if applicable)
  • [ ] PRODUCTION_DEPLOY.md updated with custom domain
  • [ ] docs/technical/auth0-rbac-reference.md updated
  • [ ] docs/technical/auth0-user-management-guide.md updated
  • [ ] New guide created: docs/technical/auth0-custom-domain-setup.md

🔍 Verification Commands

# Check DNS propagation
dig auth.jmdaling.co.za CNAME

# Test HTTPS certificate
curl -I https://auth.jmdaling.co.za/.well-known/jwks.json

# Verify environment variables
docker exec remission env | grep AUTH0

# Check backend logs
docker logs remission-search-web --tail 50 | grep -i auth0

# Test login flow
open http://localhost:8002
# Click "My Account", observe redirect URL

⚠️ Common Issues

Issue Solution
"Invalid domain" error Wait for DNS propagation, verify CNAME record
JWT verification fails Check AUTH0_DOMAIN env var, restart containers
Management API fails Ensure using AUTH0_TENANT_DOMAIN (tenant domain)
Login redirects to old domain Clear browser cache, update auth0-config.js
Social login fails Update callback URLs in provider dashboard

📋 Domain Reference

Purpose Domain to Use
User Login/Logout auth.jmdaling.co.za ✅
JWT Verification auth.jmdaling.co.za ✅
JWKS Endpoint auth.jmdaling.co.za/.well-known/jwks.json ✅
Management API dev-80t8a4t7gbp2h55c.eu.auth0.com ⚠️
Token Requests auth.jmdaling.co.za/oauth/token ✅
Social Callbacks auth.jmdaling.co.za/login/callback ✅

Last Updated: 2025-12-05