docs: openid-connect Auth0 plugin for passwordless login (email)

[ivanovic99]

Current State

Current State

The documentation for the OpenID-Connect plugin is missing detailed guidance on configuring the plugin for Auth0 passwordless email login flows. This configuration requires specific setup across two routes with subtle but critical differences.

Problems Users Face

1. No dual-route architecture documentation: Users don't know they need two separate routes (login and callback) with the plugin configured differently on each
2. Missing critical parameter guidance: The unauth_action parameter difference between routes is not documented, leading to authentication loops
3. No cross-domain session examples: Lack of clear examples for session configuration in cross-domain authentication scenarios
4. No Auth0-specific guidance: Users attempting passwordless authentication with Auth0 don't have a reference implementation

Impact

Users attempting to implement Auth0 passwordless email authentication with Apache APISIX face significant challenges:

• Trial-and-error configuration leading to wasted development time
• Common misconfigurations causing authentication failures
• Callback URL mismatch errors
• Session cookie issues in production environments
• Authentication redirect loops due to incorrect unauth_action settings

Current Documentation Gap

The existing OpenID-Connect plugin documentation covers basic OAuth2/OIDC setup but lacks:

• Real-world integration examples with major identity providers (Auth0, Okta, etc.)
• Explanation of authentication flow patterns requiring multiple routes
• Guidance on parameter differences between login initiation and callback handling
• Troubleshooting section for common passwordless authentication issues

Desired State

Desired State

The OpenID-Connect plugin documentation should include a comprehensive guide for implementing Auth0 passwordless email authentication, with clear explanations of the dual-route architecture and configuration requirements.

What Should Be Added

1. Overview Section

Add a dedicated section explaining:

• The authentication flow architecture for passwordless login
• Why two routes are needed (login initiation vs. callback handling)
• How the OpenID-Connect plugin integrates with Auth0

2. Required Routes Architecture

Route 1: Login Route (/api/v1/auth/login)

• Purpose: Initiates the authentication flow
• Behavior: Redirects unauthenticated users to Auth0
• Key Configuration: unauth_action: "deny"

Route 2: Callback Route (/api/v1/auth/callback)

• Purpose: Handles the OAuth2 callback from Auth0
• Behavior: Processes the authorization code and establishes the session
• Key Configuration: unauth_action: "auth"

3. Complete Configuration Examples

Login Route Configuration:

{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_SECRET",
  "discovery": "https://your-tenant.auth0.com/.well-known/openid-configuration",
  "scope": "openid profile email offline_access",
  "redirect_uri": "https://your-domain.com/api/v1/auth/callback",
  "post_logout_redirect_uri": "https://your-frontend-domain.com",
  "logout_path": "/logout",
  "realm": "apisix",
"ssl_verify": false,

"timeout": 3,

"use_pkce": true,

"use_nonce": false,
"authorization_params": {

"audience": "https://your-api-audience.com"

},
"session": {

"secret": "RANDOM_AUTOGENERATED_SECRET",

"cookie": {

"secure": true,

"httponly": true,

"domain": ".your-domain.com",

"samesite": "None",

"path": "/"

}

},
"set_access_token_header": true,

"set_id_token_header": true,

"set_userinfo_header": true,

"set_refresh_token_header": false,

"access_token_in_authorization_header": false,
"bearer_only": false,

"unauth_action": "deny",

"force_reauthorize": false,
"renew_access_token_on_expiry": true,

"revoke_tokens_on_logout": false,

"access_token_expires_leeway": 0,

"iat_slack": 120,
"token_endpoint_auth_method": "client_secret_basic",

"introspection_endpoint_auth_method": "client_secret_basic",

"client_jwt_assertion_expires_in": 60,

"introspection_interval": 0,
"accept_none_alg": false,

"accept_unsupported_alg": true,

"jwt_verification_cache_ignore": false,

"jwk_expires_in": 86400

}

Callback Route Configuration:

{
  "unauth_action": "auth"
  // All other settings remain identical to the login route
}

Critical Note: The callback route uses the exact same configuration as the login route, with only ONE parameter changed: unauth_action must be set to "auth" instead of "deny".

4. Parameter Reference Table

Parameter	Login Route	Callback Route	Purpose
unauth_action	"deny"	"auth"	Critical difference: "deny" blocks access and redirects; "auth" processes OAuth callback
redirect_uri	Must point to callback route	Same	Must match callback URL registered in Auth0
use_pkce	true	true	Enables Proof Key for Code Exchange for enhanced security
session.cookie.samesite	"None"	"None"	Required for cross-domain authentication
session.cookie.secure	true	true	Mandatory when using samesite: "None"
authorization_params.audience	Your API identifier	Same	Required by Auth0 to include correct audience in tokens
scope	"openid profile email offline_access"	Same	Defines requested user information and token types

5. Auth0 Application Setup Guide

Document the required Auth0 configuration:

1. Application Type: Regular Web Application
2. Allowed Callback URLs: https://your-domain.com/api/v1/auth/callback
3. Allowed Logout URLs: Your frontend domain
4. Allowed Web Origins: Your frontend domain for CORS
5. Connections: Enable "Passwordless" → "Email"
6. Advanced Settings:
   • Grant Types: Authorization Code, Refresh Token
   • PKCE: Enabled

6. Step-by-Step Testing Guide

1. Navigate to your login route: https://your-domain.com/api/v1/auth/login
2. Verify redirect to Auth0 passwordless login page
3. Enter email address and submit
4. Check email for authentication link/code
5. Complete authentication via email
6. Verify successful redirect back to application
7. Confirm session cookie is set (check browser DevTools)
8. Test protected routes with established session

7. Troubleshooting Section

Common issues and solutions:

Issue: "Callback URL mismatch" error

Error: The redirect_uri MUST match the registered callback URL

Solution: Ensure redirect_uri in plugin config exactly matches URL in Auth0 settings

Issue: Session cookies not being set

User appears unauthenticated after successful login

Solution:

• Verify cookie.domain matches your domain structure
• Ensure secure: true with samesite: "None" for cross-domain
• Check browser console for cookie errors

Issue: Authentication loop (continuous redirects)

Browser keeps redirecting between login and Auth0

Solution:

• Verify callback route has unauth_action: "auth" (not "deny")
• Ensure both routes have identical session secrets
• Check that redirect_uri points to callback route

Issue: CORS errors

Access blocked by CORS policy

Solution: Add your frontend domain to Auth0's "Allowed Web Origins"

8. Complete Working Example

Provide a complete APISIX route configuration example showing both routes configured:

# Route 1: Login Initiation
routes:
  - uri: /api/v1/auth/login
    name: auth-login-route
    plugins:
      openid-connect:
        # [Full login configuration here]
        unauth_action: "deny"
    upstream:
      type: roundrobin
      nodes:
        "your-backend:8080": 1
Route 2: OAuth Callback

uri: /api/v1/auth/callback

name: auth-callback-handler

plugins:

openid-connect:

# [Same configuration as above]

unauth_action: "auth"

upstream:

type: roundrobin

nodes:

"your-backend:8080": 1

Expected Benefits

After adding this documentation:

• Users can implement Auth0 passwordless authentication in under 30 minutes
• Reduced support requests and GitHub issues about OpenID-Connect configuration
• Clear reference for similar OIDC provider integrations
• Improved developer experience and APISIX adoption
• Community contributions of additional provider examples (Okta, Keycloak, etc.)

Documentation Location

This content should be added to:

1. Primary location: /docs/en/latest/plugins/openid-connect.md (new section: "Auth0 Passwordless Integration")
2. Cross-reference from: Plugin overview page under "Authentication Patterns"
3. Consider creating: /docs/en/latest/tutorials/auth0-passwordless.md for step-by-step tutorial

Related Documentation

This enhancement would complement existing docs on:

• OAuth2/OIDC concepts
• Session management in APISIX
• Route configuration best practices
• Security considerations for API gateways

[Baoyuantop]

Does this document meet your needs? https://docs.api7.ai/apisix/how-to-guide/authentication/set-up-sso-with-auth0/

[ivanovic99]

Hi! Thanks, sure.
This issue was more of a doc for future bloods with oidc problems than an actual issue since we already resolved it but thanks!