Configuration Auth0 - ashleydavis/photosphere GitHub Wiki

This guide explains how to create an Auth0 account and configure the necessary environment variables for running the Photosphere backend.

Creating an Auth0 Account

  1. Sign up for Auth0

    • Visit https://auth0.com
    • Click "Sign up" and create a free account
    • Choose your region (select the one closest to your users)

  2. Create a New Application

    • In the Auth0 Dashboard, navigate to "Applications"
    • Click "Create Application"
    • Choose a name (e.g., "Photosphere Backend")
    • Select "Regular Web Application" as the application type
    • Click "Create"

  3. Configure Application Settings

    • In your application settings, configure:
      • Allowed Callback URLs: http://localhost:3000/callback (add production URLs as needed)
      • Allowed Logout URLs: http://localhost:3000 (add production URLs as needed)
      • Allowed Web Origins: http://localhost:3000 (add production URLs as needed)
    • Save changes

  4. Create an API

    • Navigate to "APIs" in the Auth0 Dashboard
    • Click "Create API"
    • Set a name (e.g., "Photosphere API")
    • Set an identifier (e.g., https://api.photosphere.com)
    • Keep the signing algorithm as RS256
    • Click "Create"

Required Environment Variables

Add the following environment variables to your .env file:

# Auth0 Configuration
AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_CLIENT_ID=your-client-id
AUTH0_CLIENT_SECRET=your-client-secret
AUTH0_AUDIENCE=https://api.photosphere.com
AUTH0_ISSUER_BASE_URL=https://your-tenant.auth0.com
AUTH0_SECRET=your-session-secret

# Additional Auth0 Settings (Optional)
AUTH0_SCOPE="openid profile email"
AUTH0_CALLBACK_URL=http://localhost:3000/callback
AUTH0_LOGOUT_URL=http://localhost:3000

Where to Find These Values

  • AUTH0_DOMAIN: Found in your Auth0 Dashboard under "Applications" → Your App → "Settings" → "Domain"
  • AUTH0_CLIENT_ID: Found in "Applications" → Your App → "Settings" → "Client ID"
  • AUTH0_CLIENT_SECRET: Found in "Applications" → Your App → "Settings" → "Client Secret" (keep this secure!)
  • AUTH0_AUDIENCE: The identifier you set when creating your API
  • AUTH0_ISSUER_BASE_URL: Same as https://{AUTH0_DOMAIN}
  • AUTH0_SECRET: A random string for session encryption (generate with openssl rand -hex 32)

Security Best Practices

  1. Never commit .env files to version control
  2. Rotate secrets regularly in production
  3. Use different Auth0 applications for development, staging, and production
  4. Enable MFA on your Auth0 account
  5. Configure rate limiting in Auth0 Dashboard under "Attack Protection"

Testing Your Configuration

To verify your Auth0 setup is working:

  1. Start your Photosphere backend with the environment variables configured
  2. Navigate to your authentication endpoint
  3. You should be redirected to the Auth0 login page
  4. After successful login, you should be redirected back to your application

Troubleshooting

Common issues and solutions:

  • "Callback URL mismatch": Ensure your callback URLs in Auth0 match exactly with your application's URLs
  • "Invalid token": Check that your AUTH0_AUDIENCE matches the API identifier
  • "Unauthorized": Verify that your AUTH0_DOMAIN and AUTH0_CLIENT_ID are correct