ivanovic99 opened a new issue, #12876:
URL: https://github.com/apache/apisix/issues/12876
### 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
<html>
<body>
<!--StartFragment--><html><head></head><body><h2>Desired State</h2>
<p>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.</p>
<h3>What Should Be Added</h3>
<h4>1. Overview Section</h4>
<p>Add a dedicated section explaining:</p>
<ul>
<li>The authentication flow architecture for passwordless login</li>
<li>Why two routes are needed (login initiation vs. callback handling)</li>
<li>How the OpenID-Connect plugin integrates with Auth0</li>
</ul>
<h4>2. Required Routes Architecture</h4>
<p><strong>Route 1: Login Route</strong>
(<code>/api/v1/auth/login</code>)</p>
<ul>
<li><strong>Purpose</strong>: Initiates the authentication flow</li>
<li><strong>Behavior</strong>: Redirects unauthenticated users to Auth0</li>
<li><strong>Key Configuration</strong>: <code>unauth_action:
"deny"</code></li>
</ul>
<p><strong>Route 2: Callback Route</strong>
(<code>/api/v1/auth/callback</code>)</p>
<ul>
<li><strong>Purpose</strong>: Handles the OAuth2 callback from Auth0</li>
<li><strong>Behavior</strong>: Processes the authorization code and
establishes the session</li>
<li><strong>Key Configuration</strong>: <code>unauth_action:
"auth"</code></li>
</ul>
<h4>3. Complete Configuration Examples</h4>
<p><strong>Login Route Configuration:</strong></p>
<pre><code class="language-json">{
"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
}
</code></pre>
<p><strong>Callback Route Configuration:</strong></p>
<pre><code class="language-json">{
"unauth_action": "auth"
// All other settings remain identical to the login route
}
</code></pre>
<p><strong>Critical Note:</strong> The callback route uses the exact same
configuration as the login route, with only ONE parameter changed:
<code>unauth_action</code> must be set to <code>"auth"</code> instead of
<code>"deny"</code>.</p>
<h4>4. Parameter Reference Table</h4>
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
<h4>5. Auth0 Application Setup Guide</h4>
<p>Document the required Auth0 configuration:</p>
<ol>
<li><strong>Application Type</strong>: Regular Web Application</li>
<li><strong>Allowed Callback URLs</strong>:
<code>https://your-domain.com/api/v1/auth/callback</code></li>
<li><strong>Allowed Logout URLs</strong>: Your frontend domain</li>
<li><strong>Allowed Web Origins</strong>: Your frontend domain for CORS</li>
<li><strong>Connections</strong>: Enable "Passwordless" → "Email"</li>
<li><strong>Advanced Settings</strong>:
<ul>
<li>Grant Types: Authorization Code, Refresh Token</li>
<li>PKCE: Enabled</li>
</ul>
</li>
</ol>
<h4>6. Step-by-Step Testing Guide</h4>
<ol>
<li>Navigate to your login route:
<code>https://your-domain.com/api/v1/auth/login</code></li>
<li>Verify redirect to Auth0 passwordless login page</li>
<li>Enter email address and submit</li>
<li>Check email for authentication link/code</li>
<li>Complete authentication via email</li>
<li>Verify successful redirect back to application</li>
<li>Confirm session cookie is set (check browser DevTools)</li>
<li>Test protected routes with established session</li>
</ol>
<h4>7. Troubleshooting Section</h4>
<p>Common issues and solutions:</p>
<p><strong>Issue: "Callback URL mismatch" error</strong></p>
<pre><code>Error: The redirect_uri MUST match the registered callback URL
</code></pre>
<p><strong>Solution</strong>: Ensure <code>redirect_uri</code> in plugin
config exactly matches URL in Auth0 settings</p>
<p><strong>Issue: Session cookies not being set</strong></p>
<pre><code>User appears unauthenticated after successful login
</code></pre>
<p><strong>Solution</strong>:</p>
<ul>
<li>Verify <code>cookie.domain</code> matches your domain structure</li>
<li>Ensure <code>secure: true</code> with <code>samesite: "None"</code> for
cross-domain</li>
<li>Check browser console for cookie errors</li>
</ul>
<p><strong>Issue: Authentication loop (continuous redirects)</strong></p>
<pre><code>Browser keeps redirecting between login and Auth0
</code></pre>
<p><strong>Solution</strong>:</p>
<ul>
<li>Verify callback route has <code>unauth_action: "auth"</code> (not
"deny")</li>
<li>Ensure both routes have identical session secrets</li>
<li>Check that <code>redirect_uri</code> points to callback route</li>
</ul>
<p><strong>Issue: CORS errors</strong></p>
<pre><code>Access blocked by CORS policy
</code></pre>
<p><strong>Solution</strong>: Add your frontend domain to Auth0's "Allowed
Web Origins"</p>
<h4>8. Complete Working Example</h4>
<p>Provide a complete APISIX route configuration example showing both routes
configured:</p>
<pre><code class="language-yaml"># 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
</code></pre>
<h3>Expected Benefits</h3>
<p>After adding this documentation:</p>
<ul>
<li>Users can implement Auth0 passwordless authentication in under 30
minutes</li>
<li>Reduced support requests and GitHub issues about OpenID-Connect
configuration</li>
<li>Clear reference for similar OIDC provider integrations</li>
<li>Improved developer experience and APISIX adoption</li>
<li>Community contributions of additional provider examples (Okta, Keycloak,
etc.)</li>
</ul>
<h3>Documentation Location</h3>
<p>This content should be added to:</p>
<ol>
<li><strong>Primary location</strong>:
<code>/docs/en/latest/plugins/openid-connect.md</code> (new section: "Auth0
Passwordless Integration")</li>
<li><strong>Cross-reference from</strong>: Plugin overview page under
"Authentication Patterns"</li>
<li><strong>Consider creating</strong>:
<code>/docs/en/latest/tutorials/auth0-passwordless.md</code> for step-by-step
tutorial</li>
</ol>
<h3>Related Documentation</h3>
<p>This enhancement would complement existing docs on:</p>
<ul>
<li>OAuth2/OIDC concepts</li>
<li>Session management in APISIX</li>
<li>Route configuration best practices</li>
<li>Security considerations for API gateways</li>
</ul></body></html><!--EndFragment-->
</body>
</html>
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
