This is going to vary based on your publishing system, but you can use FusionAuth's OIDC prompt=none to see if users have an active SSO session.

If the user has checked remember me and has logged in within the tenant session timeout, the request will succeed, otherwise it will fail.

Step 1: Main Page

This creates the iframe and listens for the result.

On your main page, create the hidden iframe targeting FusionAuth with prompt=none. You also listen for a message event from the iframe to know whether to display or hide the CTA <div>, which needs the id trial-cta:

// 1. Listen for the result sent back from the iframe callback page window.addEventListener('message', (event) => { // Verify the origin matches your application domain for security if (event.origin !== window.location.origin) { return; } const ctaDiv = document.getElementById('trial-cta'); if (event.data && event.data.type === 'SILENT_AUTH_RESPONSE') { if (event.data.status === 'authenticated') { // User has an active SSO session; keep CTA hidden if (ctaDiv) { ctaDiv.style.display = 'none'; } } else if (event.data.status === 'login_required') { // User is not authenticated; show the trial CTA popup/div if (ctaDiv) { ctaDiv.style.display = 'block'; } } } }); // 2. Create the hidden iframe to initiate the prompt=none request const iframe = document.createElement('iframe'); iframe.style.display = 'none'; iframe.src = 'https://<your-fusionauth-instance>/oauth2/authorize?' + 'client_id=<YOUR_CLIENT_ID>&' + 'response_type=code&' + 'redirect_uri=https://<your-app-domain>/silent-callback.html&' + 'scope=openid&' + 'prompt=none&' + 'state=<YOUR_STATE>'; document.body.appendChild(iframe); Step 2: Callback Page

Configure this page as an authorized redirect URI in your FusionAuth application [Request Parameters].

When FusionAuth redirects back with the authorization code code or error=login_required, this page parses the URL and communicates back to the parent window:

// Parse query parameters from the redirect URI const params = new URLSearchParams(window.location.search); const code = params.get('code'); const error = params.get('error'); if (code) { // Session exists: notify the parent window window.parent.postMessage({ type: 'SILENT_AUTH_RESPONSE', status: 'authenticated', code: code }, window.location.origin); } else if (error === 'login_required') { // No active session: notify the parent window to show CTA window.parent.postMessage({ type: 'SILENT_AUTH_RESPONSE', status: 'login_required' }, window.location.origin); } Cautions And Additional Considerations

This won't work across all browsers, especially those with privacy features or if your FusionAuth instance isn't on the same root domain as the application. More details here.

Test the scenarios you need to support.

The CTA should include information about how to sign up or log in if the user already has an account.

You may want to add server or client side logic to obfuscate the page contents.

Both entry points, and especially the anti-enumeration behavior on the known-tenant path, are best built by calling FusionAuth's passwordless APIs directly from your own UI rather than relying on the hosted login pages. Here's more on the difference.

Using the API is the only way to get full control over what the UI shows on a failure.

Known-tenant entry (acme.ourapp.com) Maintain your own slug/domain → tenantId table (outside FusionAuth), populated when you provision each tenant via the Tenant API. FusionAuth has no built-in hostname-to-tenant mapping. You can learn more in the multi-tenant guide. At request time, resolve the subdomain to a tenantId from that table (outside FusionAuth). If nothing matches, show "Workspace not found" — this never touches FusionAuth. Build your own "enter your email" screen for this workspace (not FusionAuth's hosted page — you need to control what's shown on failure, which the hosted page won't let you do). When the user submits an email, your backend calls /api/passwordless/start with that tenantId + your Universal Application id + the email as loginId. Universal Application docs here. Branch on the response, entirely inside your backend: 200, code sent → hang onto the returned code value, respond to your frontend with a generic "we sent you a code" message, and show your own "enter the code" screen. 404, no user found → this is the real signal Slack is hiding. FusionAuth returns a 404 with an empty body when no user matches the tenant. Instead of surfacing that: send your own "no account with this email in this workspace" notice through your own transactional email provider (outside FusionAuth or using the send email API), then respond to your frontend with the exact same "we sent you a code" message. Show the identical "enter the code" screen either way. Completing the challenge: Real branch: verify the code the user types via /api/passwordless/login (tenantId + code), which returns tokens; pair this with the Hosted Backend / BFF if it's a SPA. Alternatively, redirect the browser to /oauth2/passwordless/{code}?tenantId=<tenantId>&client_id=<id> and let FusionAuth's hosted page take over the code-entry step. This is the URL FusionAuth's own passwordless email template constructs for the "click to log in" link, so redirecting there yourself just skips the email round-trip. Fake branch: there is no FusionAuth code to hand off, so there's nothing to redirect to on FusionAuth's hosted domain — you have to own the "enter code" screen yourself here. Whatever the user types, respond with the same generic "invalid or expired code" error you'd give a real wrong code; never a distinct message. If you're using the hosted-page redirect for the real branch, don't try to fake that redirect for this branch — just render your own equivalent screen and always reject, rather than attempting a look-alike hosted destination. Pad the fake branch's response time to roughly match a real Start call, so the two paths don't diverge on timing, which would leak the same thing you're hiding in the UI. Generic entry (ourapp.com/login) Call /api/user/search with a global (not tenant-scoped) API key and no tenantId filter, searching by the submitted email. Each matching User record already includes its own tenantId, so this single call tells you every workspace the email belongs to. This pattern (global key, /api/user/search?queryString=<email>, results include per-tenant matches) is answered on the forum. Keep the key server-side only. If you'd rather not run a global-key search on every anonymous request (latency, or wanting the key confined to a webhook receiver instead of a public endpoint), you can maintain your own email → tenantId[] table fed by FusionAuth's user.create / user.update / user.delete webhooks instead. Docs at https://fusionauth.io/docs/extend/events-and-webhooks/. Either is fine — this is a trade-off, not a hard requirement. Branch on the result (outside FusionAuth): No match → "No account found," stop there. One match → continue with that tenant. Multiple matches → show a workspace picker, then continue with the chosen one. This is currently functionality you have to build yourself, though there is an open issue. Once a tenant is resolved, it's the same steps as section 1 from "build your own enter-email screen" onward — including the fake-challenge branch, if you want the same anti-enumeration behavior here too (Slack's generic "find your workspaces" entry also avoids confirming or denying a match directly, for the same reason). A few things worth flagging FusionAuth users are tenant-scoped records — the same person needs a separate User object per workspace they belong to. API key scope matters: the cross-tenant search in section 2 needs a global key; the tenant-specific calls in section 1 can safely use a tenant-scoped key. [Docs](Docs at https://fusionauth.io/docs/apis/api-keys). The SSO session cookie isn't tenant-aware across hostnames — FusionAuth doesn't currently support true multi-tenant SSO through the hosted pages, so the user behavior when switching tenants requires another login. Always pass tenantId explicitly on every call. Passwordless API reference for the exact Start/Login request and response shapes:

This behavior is likely due to changes introduced in FusionAuth 1.68.0 related to Intelligent MFA and Risk Signals.

Starting in 1.68.0, FusionAuth uses a variety of "Risk Signals" to determine when to trigger the Suspicious Login email. The email is sent whenever any enabled risk signal returns a HIGH value. One common signal that can cause this is:

DormantPassword: This signal triggers when a user's password hasn't been changed "in the last few months." If your users do not regularly rotate their passwords, this risk signal could be flagging every login as suspicious. Solution

You can fine-tune which Risk Signals are considered for your tenant:

Navigate to Tenants > Edit Tenant > Security > Customize Risk Signals Review the enabled risk signals Consider toggling off the Dormant Password signal if password rotation is not part of your security model, or adjust other signals as appropriate for your use case Testing

To verify this is the cause:

Try changing a user's password, then logging in again to see if the suspicious login email still triggers Alternatively, disable the Dormant Password risk signal temporarily and test login behavior

This should allow you to re-enable suspicious login notifications while avoiding false positives for normal login activity.

No, you cannot configure the same custom domain on two different FusionAuth Cloud deployments at the same time.

The recommended migration sequence is:

Remove the custom domain from the production deployment Configure the custom domain on the dev deployment Configure a CNAME record pointing your custom domain directly to the dev deployment's durable hostname Validate the certificate for the domain on the dev deployment Important Considerations

DNS Propagation Time

DNS changes take time to propagate Expect up to 30 minutes for DNS servers to recognize the changes Propagation may take longer depending on your DNS TTL settings Plan for this downtime window during your migration

Certificate Validation

Certificate validation uses DNS-based methods You must complete the DNS configuration before certificate validation can succeed

To minimize downtime, prepare all configurations on the dev deployment beforehand, then execute the domain removal, DNS update, and certificate validation in quick succession.

FusionAuth does not perform Unicode normalization on passwords before hashing.

Passwords are hashed using the raw bytes exactly as received from the client. This means:

If a user sets a password with Unicode characters, those exact byte sequences are hashed Different Unicode representations of visually identical characters (e.g., é as a single composed character U+00E9 vs. e + combining acute accent U+0065 U+0301) will result in different password hashes No normalization forms (NFC, NFD, NFKC, NFKD) are applied

This behavior means you should ensure consistent encoding at the application level if Unicode normalization is important for your use case. The password validation will only succeed if the exact same byte sequence is provided during authentication.

Additional Context

FusionAuth fully supports Unicode characters in passwords, which is recommended for both usability and security reasons. When FusionAuth validates passwords for special characters, it processes them as Unicode strings (using Java's Character.isAlphabetic() and Character.isDigit() methods on 16-bit Unicode values), confirming that passwords are handled as Unicode throughout the system.

There are no inherent limitations on which Unicode characters can be used in passwords stored in FusionAuth, though you can configure password validation rules to enforce specific requirements for your tenant.

Related Documentation Password-Hashing Algorithms - Overview of FusionAuth's password hashing schemes (PBKDF2, Bcrypt, etc.) Custom Password Hashing - Information on implementing custom password hashing schemes Password Validation Rules - API for retrieving and configuring password validation rules Client-side Password Rule Validation - Guide for implementing password validation in your client application Are there any disallowed characters in passwords? - Community discussion confirming no inherent character limitations

There are several ways to monitor your hosted FusionAuth deployment:

Basic Health Monitoring

You can use the System Status API to get basic information about your deployment, including whether it is healthy. For dedicated health checks (particularly useful for load balancers), there's also the Health API available since version 1.51.1.

Detailed Metrics with Prometheus

For more detailed performance monitoring, you can configure Prometheus to retrieve system metrics from FusionAuth. FusionAuth exposes:

JVM-level gauges: memory usage, garbage collection stats, thread counts, class loading, buffer pools Request timers: endpoint latency and request counts (e.g., prime_mvc_* metrics)

You can then set up Prometheus dashboards to visualize this data and track CPU, memory, and other performance metrics over time.

See the FusionAuth Prometheus documentation for configuration details and the Prometheus Metrics API for endpoint information.

Important Considerations for Hosted Deployments

If your hosted FusionAuth deployment has multiple compute nodes, be aware that both the Status API and Prometheus metrics endpoints return data per-node. Since requests are round-robined across nodes, successive API calls may hit different nodes and return inconsistent data. This makes direct polling less reliable for multi-node deployments.

Additional Monitoring Options

Beyond Prometheus, FusionAuth can integrate with other monitoring tools:

Datadog: Use the Datadog Agent with OpenMetrics integration CloudWatch: Monitor FusionAuth metrics in AWS environments Grafana: Visualize Prometheus data with pre-built dashboards

You can also access:

System logs: Available via API (exportable as ZIP files) Audit logs: Track administrative actions via API or webhook Event logs: Debug information for external integrations Login records: Successful login history with timestamps, IPs, and user details Webhooks: Get real-time notifications for specific events Related Documentation Monitoring FusionAuth Overview System Status API System Health API Prometheus Integration Guide Prometheus Metrics API Datadog Integration CloudWatch Integration

Yes, successfully logging in with a passkey will update the user's last login instant.

However, there are edge cases where a passkey can be used without updating the last login timestamp:

Scenarios where passkey use doesn't update last login:

Login flow interrupted — The user authenticates with the passkey, but the login is stopped before completion due to:

Failed MFA challenge User action requirement (e.g., forced password reset) Account lock or suspension Login validation Lambda or transactional webhook rejecting the login

WebAuthn assertion without login — If the user performed a WebAuthn assertion directly via the API, this counts as using the passkey but does not constitute a full login flow and therefore doesn't update the last login instant. The Complete a WebAuthn Passkey Assertion API validates the WebAuthn ceremony but "does not authenticate the user into an application." This is different from the Complete a WebAuthn Passkey Authentication API, which validates the passkey and authenticates the user, thus updating the last login instant.

Summary

A passkey being "used" is not the same as a completed login. The last login timestamp only updates when the authentication flow completes successfully and issues a token.

Related Documentation Complete a WebAuthn Passkey Authentication - The API that validates passkeys and authenticates users (updates last login) Complete a WebAuthn Passkey Assertion - The API that only validates passkeys without authenticating (does not update last login) Authentication With WebAuthn & Passkeys - Complete guide to WebAuthn/passkey authentication in FusionAuth Update Login Instant API - Manual API for updating login instants when implementing custom SSO Setting Up User Account Lockout - How account lockouts can interrupt login flows

You do not need to reindex users after upgrading FusionAuth.

The reindexing process will not impact:

Users' ability to log in User registration for applications

However, there may be a small increase in load times if the reindex occurs during a high-traffic period for your application. The reindexing primarily affects search and user count operations in the administrative console, not end-user authentication flows.

If you do choose to reindex (for other reasons such as search optimization), it can be done safely without blocking user authentication.

Additional Context

When Would Reindexing Be Needed?

While upgrading FusionAuth typically does not require reindexing, there are specific scenarios where it may be necessary:

Specific version upgrades: Certain version upgrades may require a reindex—this is always noted in the release notes. For example, version 1.17.2 noted: "A reindex may be necessary depending on how you have upgraded your Elasticsearch cluster." Database restoration: If you restore FusionAuth from a database dump without migrating the search index, you will need to reindex. User imports: If you import users via the User Import API, a reindex may be needed. Search engine switching: When switching from the database search engine to Elasticsearch, a reindex is required.

In general, even after a temporary Elasticsearch outage, the index will sync up automatically without manual reindexing.

Why Authentication Is Unaffected

Elasticsearch is only used for search operations in the admin UI and search APIs—it is not queried during authentication. FusionAuth does attempt to update the Elasticsearch index during authentication, but this is done asynchronously (since version 1.30.2) and is not required to complete the login. This means that even if Elasticsearch is temporarily unavailable or reindexing, authentication should not be blocked.

Performance Considerations

Reindexing is an expensive operation and should be avoided unless necessary. It causes additional CPU and I/O overhead until complete. However, performance has been significantly improved in recent versions, and beginning in version 1.48.0, index aliases are used to minimize disruption to API requests during a reindex.

Related Documentation Upgrade FusionAuth Guide - Best practices for upgrading FusionAuth Release Notes - Always check for version-specific reindexing requirements Re-indexing Documentation - When and why reindexing might be needed Rebuild the Elasticsearch Index API - How to trigger a reindex programmatically Switching Search Engines - Guide for switching between database and Elasticsearch search

To revoke all active user sessions and access tokens immediately during a security incident, you need to take a two-pronged approach: revoking sessions (refresh tokens) and invalidating access tokens.

1. Revoke All Sessions (Refresh Tokens)

Sessions in FusionAuth are represented by refresh tokens, and these can be directly revoked using the API:

Revoke all refresh tokens for all users in an application:

DELETE /api/jwt/refresh?applicationId={applicationId}

Revoke all refresh tokens for a specific user:

DELETE /api/jwt/refresh?userId={userId}

Revoke all refresh tokens for a specific user in a specific application:

DELETE /api/jwt/refresh?applicationId={applicationId}&userId={userId}

These API calls require an API key with appropriate permissions. When refresh tokens are revoked, users will be unable to obtain new access tokens and will need to re-authenticate.

2. Invalidate Access Tokens via Key Rotation

To invalidate access tokens (not just refresh tokens), you need to rotate the JWT signing keys:

In FusionAuth: Rotate the JWT signing keys used by your tenant/application. This will cause all subsequently validated tokens signed with the old key to fail validation.

In your application server: Update your application to use the new signing key for validating incoming JWTs. This ensures that tokens signed with the old key are no longer trusted.

This approach effectively invalidates all active access tokens because they were signed with the now-rotated key. When your application validates these tokens using the new key, validation will fail and users will need to re-authenticate.

Important Considerations Access tokens are stateless JWTs by design, so they cannot be revoked individually from FusionAuth's side once issued. This is why key rotation is the standard mechanism to invalidate all tokens at once. Key rotation is immediate and forceful: All existing access tokens become invalid immediately upon rotation, making this the appropriate response for security incidents. Ensure your application is updated to accept the new signing key before or immediately after rotation to prevent service disruption for legitimate re-authentication attempts. Short access token lifetimes (minutes, not hours) are strongly recommended as a defense-in-depth measure, since access tokens cannot be individually revoked. Use webhooks to notify your resource servers when refresh tokens are revoked, allowing them to maintain a blocklist of affected users if additional control is needed before access tokens naturally expire. Alternative: Maintain a Revocation List

For access tokens still within their validity period after key rotation, you can implement an application-level revocation mechanism:

Subscribe to the JWT Refresh Token Revoke webhook event When refresh tokens are revoked, record the affected users/tokens On each request, check if the user's token has been revoked before processing

This provides additional granular control but requires application-level implementation.

Related Documentation Revoke Refresh Tokens API - API for revoking refresh tokens by user, application, or token ID Key Rotation - Complete guide to rotating keys in FusionAuth, including JWT signing keys JWT Refresh Token Revoke Event - Webhook event triggered when refresh tokens are revoked Logout and Session Management - Overview of session management approaches in FusionAuth Can I Revoke an Access Token? - Community discussion on access token revocation limitations Configuring JWT Signing - How to configure JWT signing keys at the tenant and application level

To resolve this CloudFront conflict, you need to disassociate your custom domain from your CloudFront distribution.

Since AWS only allows one CloudFront distribution per hostname, and FusionAuth Cloud is implementing CloudFront on their infrastructure, you have two options:

Remove the custom domain from your CloudFront distribution — This allows FusionAuth to add the domain to their CloudFront distribution Set up your CloudFront as a proxy — Configure your distribution to proxy requests to FusionAuth's infrastructure

The recommended approach is to remove your custom domain from your CloudFront distribution entirely, as FusionAuth will handle CloudFront configuration as part of their cloud service.

How FusionAuth Custom Domains Work

When you configure a custom domain with FusionAuth Cloud, you create a CNAME record pointing from your custom domain to your deployment's durable URL (something like <random-string>.durable.fusionauth.dev). FusionAuth manages the CloudFront distribution and SSL certificates on their infrastructure, so you don't need to maintain your own CloudFront distribution for the custom domain.

The proper DNS setup should be:

Custom domain → CNAME → FusionAuth durable URL

This allows FusionAuth to provision and manage the entire CloudFront infrastructure, including SSL certificate validation and renewal, as part of their cloud service.

Related Documentation FusionAuth Cloud Custom Domains - Official guide for setting up custom domains on FusionAuth Cloud Adding a Custom Domain - Step-by-step walkthrough of the custom domain configuration process How to set up a Custom Domain for FusionAuth using AWS CloudFront - Guide for self-hosted FusionAuth installations (note: this is for self-hosted, not FusionAuth Cloud)

Note: If you're on a High Availability plan and want to use the Unlimited Custom Domains feature, or if you need assistance with the migration, open a support ticket.

The SocketTimeoutException: Read timed out error indicates that FusionAuth successfully initiates a connection to the external identity provider's discovery endpoint, but the provider doesn't respond within the configured timeout period. This is an intermittent connectivity issue between FusionAuth and the external provider.

Investigation Steps Check FusionAuth Event Logs: Navigate to System → Event Log to find specific instances of the timeout errors with timestamps. The Event Log contains messages from asynchronous code execution, including connection errors to external services. Verify the external endpoint: Test the discovery endpoint manually (e.g., via curl) to confirm it's responding correctly Look for patterns: Note the times when errors occur to identify if there's a pattern Enable debug logging: Turn on debugging in FusionAuth to get more detailed information about the OIDC connection attempts. This is a recommended first step when troubleshooting any OIDC connection issues. Root Cause

Based on investigation, when the external provider's endpoint:

DNS resolves correctly TLS handshake completes successfully Returns HTTP 200 with valid JSON during manual testing But still fails intermittently from FusionAuth

This indicates the external provider may be rate-limiting, blocking, or experiencing intermittent service issues that affect automated requests from FusionAuth.

Workaround

Instead of using the OpenID Connect Discovery URL, manually configure the endpoints in your FusionAuth identity provider settings. This bypasses the discovery mechanism and eliminates the timeout errors during the configuration resolution phase.

To configure manual endpoints:

Go to your OIDC Identity Provider configuration (Settings → Identity Providers) Toggle Discover endpoints to Off (disabled) Explicitly set the three required endpoints: Authorization endpoint: https://accounts.example.com/tenant/oauth/authorize Token endpoint: https://accounts.example.com/tenant/oauth/token Userinfo endpoint: https://accounts.example.com/tenant/oauth/userinfo

This manual configuration approach is commonly used with providers like GitHub and Discord that don't implement standard discovery endpoints, and can also be used to work around discovery endpoint reliability issues.

Note: If your external provider uses RS256 to sign tokens (rather than HS256), be aware that FusionAuth currently doesn't allow manual configuration of the JWKS URL when discovery is disabled. This may cause id_token signature verification issues. If you encounter this, you may need to continue using discovery or contact FusionAuth support for alternatives.

Next Steps

Contact your external identity provider to:

Report the intermittent timeout issues Share the timeout error logs and timestamps Ask if they're experiencing service issues or if FusionAuth's IP range needs to be whitelisted Inquire about any rate limiting policies that might affect discovery endpoint calls Related Documentation Add an OpenID Connect Identity Provider - Complete guide to configuring OIDC IdPs OIDC Troubleshooting - First steps for troubleshooting OIDC connections OpenID Connect API - API reference for managing OIDC identity providers Event Log API - How to access and query event logs programmatically

Rollback Process for FusionAuth Cloud

For FusionAuth Cloud deployments, the rollback process must be handled by FusionAuth support—it is not something you can perform yourself.

Plan Eligibility and Backup Retention Business and High Availability (HA) Deployments: Upgrade backups are retained and available for 30 days Basic Deployments: Backups are not included, so rollbacks cannot be performed How to Request a Rollback

If you identify an issue after performing the upgrade:

Open a support ticket with FusionAuth The support team will perform the complete database rollback for you Expected Downtime

The rollback operation typically takes 20 minutes to 2 hours, depending on:

Database size How quickly the operations team can complete the rollback

Note that this involves a complete database rollback, so plan for 1-2 hours of downtime.

Support During Upgrades

For production upgrades, FusionAuth can provide:

An engineer on standby during your scheduled upgrade window An on-call support number for emergency assistance Pre-Upgrade Best Practices

Before upgrading to 1.69.1:

Review Release Notes for breaking changes, database migrations, and API modifications Choose an Upgrade Strategy: Incremental (version-by-version) for lower risk Direct upgrade for speed (but requires thorough testing) Test in Staging to verify: Authentication flows, webhooks, and APIs function correctly Templates render properly Database migrations complete successfully Coordinate with Support to schedule the upgrade and have assistance available if needed

Currently, FusionAuth does not support recovery code regeneration within the hosted account pages, and there are no plans on the public roadmap for this feature.

Regarding your specific questions:

Hosted account page support: There is no current support for recovery code regeneration as a themeable template in the hosted account pages. Recovery codes are only generated and displayed when a user first enables an MFA method. As of version 1.68.0, recovery codes are hashed at rest using salted-pbkdf2-hmac-sha256 and cannot be retrieved after initial generation—they can only be regenerated through the API. This would need to be submitted as a feature request.

JWT authentication for the generate endpoint: The generate recovery codes endpoint (POST /api/user/two-factor/recovery-code/{userId}) currently only supports API key authentication. There is no JWT authentication variant available, and nothing in the current documentation or public roadmap indicates one is planned.

Recommended approach: Submit feature requests for both capabilities through the FusionAuth GitHub Issues repository. These features could be valuable for self-service MFA management scenarios. Note that feature requests, if accepted, do not have guaranteed timelines for implementation.

Current workarounds: You would need to implement this functionality in your own application with server-side code that uses an API key to call the generate recovery codes endpoint, though this moves the functionality outside the hosted pages where other MFA management occurs. When new codes are generated, all existing recovery codes are invalidated and replaced with a new set of 10 codes.

Related Documentation Multi-Factor Authentication (MFA) - Recovery Codes - Overview of how recovery codes work in FusionAuth Generate Recovery Codes API - API endpoint documentation for programmatic recovery code generation Self-Service Account Management - Documentation on the hosted account pages and available features Customizing Self-Service Account Management - Guide for customizing hosted account page templates API Authentication - Documentation on API key and JWT authentication methods FusionAuth 1.68 Release Notes - Hashed Recovery Codes - Information about recovery code hashing security enhancement

This issue is not actually related to FusionAuth itself, but rather to GCP Cloud NAT port allocation limits.

By default, Cloud NAT only allocates 64 TCP ports per VM for outbound connections. When your application makes many concurrent connections to FusionAuth (or any external service), you can quickly exhaust these ports, leading to connection timeouts.

Solution

Enable dynamic port allocation and increase the port range with this gcloud command:

gcloud compute routers nats update cloud-nat \ --router=<ROUTER> \ --region=<REGION> \ --project=<PROJECT> \ --enable-dynamic-port-allocation \ --min-ports-per-vm=1024 \ --max-ports-per-vm=32768

Replace <ROUTER>, <REGION>, and <PROJECT> with your actual GCP resource names.

This increases the available ports from 64 to between 1024-32768 per VM, which should resolve the connection timeout issues.

Additional Considerations

While this is primarily a GCP infrastructure issue, if you continue to experience connection problems after adjusting your NAT configuration, consider reviewing:

Network latency between FusionAuth and your database - High latency or unstable network connectivity can cause database connection pool exhaustion, which may manifest as API timeouts Connection pooling settings - Ensure your application is properly reusing HTTP connections to FusionAuth rather than creating new connections for each request Load patterns - Monitor whether timeouts occur during specific load patterns that might indicate resource constraints Related Documentation FusionAuth Networking Configuration - Configure how FusionAuth determines client IP addresses and network settings Troubleshooting Connection Issues - General guidance on troubleshooting API calls and connectivity Deploying FusionAuth on Google Kubernetes Engine - Best practices for running FusionAuth on GCP Google Cloud Platform with FusionAuth - Overview of deploying FusionAuth in GCP environments External Resources GCP Cloud NAT port allocation documentation Consider monitoring your NAT port usage to right-size these settings for your workload

This appears to be a bug in how FusionAuth handles the OAuth flow during password reset when an active session exists.

Root cause:

When a user clicks the password reset link from their email, the link doesn't include response_type=code in the URL. Normally, FusionAuth adds this parameter automatically during the OAuth flow.

However, when the user already has an active login session in their browser (even though their MFA trust has expired), FusionAuth detects that session and takes a shortcut. Instead of starting a fresh OAuth flow where it would add response_type=code automatically, it attempts to reuse the existing session's OAuth state.

This saved OAuth state is incomplete and missing the response_type parameter. When FusionAuth tries to redirect back to the application after MFA verification, it encounters an OAuth error because response_type was never included in the saved state.

Temporary workaround:

Manually add response_type=code to the password reset URL until a proper fix is available. While this works, it's a band-aid solution.

Status:

This issue appears to have been introduced in a version before 1.69.2 and may require a bug fix from the FusionAuth product team to properly handle OAuth state in password reset flows when active sessions are present. There's currently no tracking GitHub issue that I'm aware of.

FusionAuth follows RFC 5322 for standard email validation, which defines the local part as a dot-atom. However, FusionAuth does not expose a specific custom regex for email validation—it adheres to the RFC 5322 standard.

Can you override or customize email validation?

Yes, but only partially through FusionAuth's built-in features:

You can customize validation using Customizations > Form Fields in the FusionAuth admin UI. However, if you want to completely implement your own validation logic, you would need to handle that within your own application and your own pages/API. Resources

Here are some helpful links for managing user verification and email validation workflows:

How User Verification Works Gate Accounts Until User Email Verified

If you need exact custom validation logic, you'll need to implement it on your application side and potentially use custom form fields to enforce it during registration or profile updates.

Disabling Individual Signals

Yes, individual signals can be disabled (but not weighted). Navigate to Tenants → Your Tenant → Security → Client risk configuration and enable the Customize risk signals toggle. You can then turn off individual signals, including DormantPassword.

Disabled signals are excluded entirely from the composite risk calculation, so you can address the DormantPassword issue directly without needing a custom lambda.

Important caveat from the documentation: "Disabling all signals sets the risk score to HIGH." Disable signals selectively, not everything.

Risk Score Calculation Details

The exact weighting formula and thresholds for LOW/MEDIUM/HIGH composite scores are not fully documented. Individual signal scores combine into a composite score, and more HIGH signals raise the average, but the final result is bucketed as LOW, MEDIUM, or HIGH.

Trusted Devices and Risk Policies

No, a trusted device does NOT automatically skip the challenge when using the built-in Intelligent MFA policies (ChallengeOnMediumRisk and ChallengeOnHighRisk).

The risk policy still applies. From the documentation:

"The two risk policies ignore 'trust this device,' so users currently skipped by a trusted device are re-evaluated on risk and may be challenged."

A device marked as trusted can still trigger an MFA challenge if the composite risk score meets or exceeds the configured threshold.

Recommended Next Steps Disable the DormantPassword signal in your tenant's Client risk configuration Monitor your risk score distribution after this change Contact FusionAuth support if you need more details

Usually no, upgrades don't log users out or invalidate tokens.

The one exception is if your upgrade path includes v1.60.0, where some tokens may be invalidated. Even then, users with a refresh token should self-heal without needing to log in again.

For most upgrade scenarios, you can expect minimal impact on active user sessions.

@anarelynevarez, Thanks for looking us up. While Buckeye Union High School District may use FusionAuth, they own the implementation of FusionAuth. You will have to reach out to them for this kind of assistance.

It is useful in a few scenarios.

When you have users that share an email address, but are in the same tenant and have distinct accounts. FusionAuth enforces uniqueness on user.email per-tenant. When your users have a username (such as an account number) as a main unique identifier, but need self-service account recovery. When you have duplicate email addresses in a legacy system and are migrating them to FusionAuth, whether they point to the same account or not. You can move the users over and address email updates or account merges later.

Not all email related functionality is available when using user.data.email, but common workflows like forgot password are.