Auth0

Configure Auth0 with Serverless API Gateway. Set up Auth0 client ID, client secret, JWKS, callback URLs, and OAuth 2.0 authorization flow.

Integrate Auth0 with the Serverless API Gateway to add OAuth 2.0 / OpenID Connect authentication to your API. This page covers the required configuration parameters, environment variables, path setup, and the authorization flow.

For general authentication concepts and comparison with other providers, see the Authentication Guide. For JWT-based authorization without a third-party provider, see Authorizer.

Prerequisites

Before configuring the Serverless API Gateway, create an Auth0 application:

1. Log in to your Auth0 Dashboard

2. Go to Applications and click Create Application

3. Choose Regular Web Application or Single Page Application depending on your use case

4. Note the Domain, Client ID, and Client Secret from the application settings

5. Under Allowed Callback URLs, add your gateway callback URL (e.g. https://your-api-url/api/v1/auth0/callback)

Configuration Parameters

{
    "authorizer": {
        "type": "auth0",
        "domain": "your-auth0-domain.auth0.com",
        "client_id": "your-client-id",
        "client_secret": "your-client-secret",
        "redirect_uri": "https://your-api-url/api/v1/auth0/callback",
        "jwks": "{JSON Escaped JWKS}",
        "jwks_uri": "https://your-auth0-domain.auth0.com/.well-known/jwks.json",
        "scope": "openid profile email"
    }
}

Parameters Explained

• type: Specifies the type of authorizer being used. In this case, it is set to "auth0".

• domain: The Auth0 domain associated with your account. Replace your-auth0-domain with your actual Auth0 domain.

• client_id: The unique identifier for your Auth0 application. Found in the Auth0 Dashboard under Applications > your app > Settings. Replace your-client-id with your actual client ID.

• client_secret: The secret key associated with your Auth0 application. This value should be stored as a Wrangler secret, not in plain text. Replace your-client-secret with your actual client secret.

• redirect_uri: The URI to which Auth0 will redirect users after authentication. This must match one of the Allowed Callback URLs in your Auth0 application settings.

• jwks: A JSON Web Key Set (JWKS) containing the public keys used to verify the JWT signatures. Replace the values in the n, kid, x5t, and x5c fields with your actual key values. Either jwks or jwks_uri is required.

• jwks_uri: The URI to retrieve the JWKS from Auth0. Replace your-auth0-domain with your actual Auth0 domain. Either jwks or jwks_uri is required.

• scope: The permissions being requested from the user. Common scopes include openid, profile, and email.

Environment Variables and Secrets

Store sensitive Auth0 credentials securely:

# Environment variables (in wrangler.toml)
AUTH0_DOMAIN=your-domain.us.auth0.com
AUTH0_CLIENT_ID=your_client_id_here

# Secrets (use wrangler secret put)
wrangler secret put AUTH0_CLIENT_SECRET
# Optional: if you use "jwks" instead of "jwks_uri" in the authorizer config
wrangler secret put AUTH0_JWKS

Reference these in your api-config.json using the $env. and $secrets. prefixes:

{
    "authorizer": {
        "type": "auth0",
        "domain": "$env.AUTH0_DOMAIN",
        "client_id": "$env.AUTH0_CLIENT_ID",
        "client_secret": "$secrets.AUTH0_CLIENT_SECRET",
        "redirect_uri": "https://your-api-url/api/v1/auth0/callback",
        "jwks_uri": "https://your-domain.us.auth0.com/.well-known/jwks.json",
        "scope": "openid profile email"
    }
}

Important Notes

• Ensure that sensitive information such as client_secret is stored securely using wrangler secret put and not exposed in public repositories or logs.

• Update the placeholders in the configuration with your actual Auth0 account details before deployment.

• Test the configuration in a safe environment before moving to production.

Path Configurations

This section outlines the path configuration for handling the Auth0 OAuth flow. Add these paths to the paths array in your api-config.json.

Callback Handler

{
    "method": "GET",
    "path": "/api/v1/auth0/callback",
    "integration": {
        "type": "auth0_callback"
    }
}

This integration handles the callback from Auth0, receiving an authorization code. It exchanges this code for access and ID tokens and returns them to the client.

Login Redirect

{
    "method": "GET",
    "path": "/api/v1/auth0/callback-redirect",
    "integration": {
        "type": "auth0_callback_redirect"
    },
    "auth": false
}

This integration facilitates the redirection to the Auth0 login page (/authorize), allowing users to authenticate via Auth0. It provides a seamless way to initiate the login process based on the Auth0 configuration.

User Info

{
    "method": "GET",
    "path": "/api/v1/auth0/profile",
    "integration": {
        "type": "auth0_userinfo"
    },
    "auth": true
}

This integration retrieves user information from Auth0 using the /userinfo endpoint. It allows applications to access user profile data after successful authentication.

Auth0 OAuth Flow

The complete authorization flow with Serverless API Gateway and Auth0 works as follows:

1. Initiate Login -- Direct the user to your /api/v1/auth0/callback-redirect endpoint. This redirects them to the Auth0 login page.

2. User Authenticates -- The user logs in through Auth0 (username/password, social login, etc.).

3. Callback -- Auth0 redirects back to your /api/v1/auth0/callback endpoint with an authorization code.

4. Token Exchange -- The gateway exchanges the authorization code for access and ID tokens automatically.

5. Access Protected Routes -- Use the returned token in the Authorization: Bearer <token> header to call endpoints that have "auth": true.

CORS Configuration

If your frontend calls the Auth0 endpoints from a browser, configure CORS in your api-config.json:

{
  "cors": {
    "allow_origins": ["https://your-frontend.example.com"],
    "allow_methods": ["GET", "POST", "OPTIONS"],
    "allow_headers": ["Authorization", "Content-Type"],
    "allow_credentials": true,
    "max_age": 3600
  }
}

Related Pages

• Authentication Guide -- full authentication setup overview

• Authorizer Configuration -- JWT and provider-based authorization details

• CORS Configuration -- cross-origin request settings

• Supabase OTP Integration -- alternative authentication with Supabase

• Auth0 Quickstart -- step-by-step Auth0 quickstart

• Auth0 Documentation -- official Auth0 docs