Topics created by dan

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:

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.

Entities are one of the most flexible parts of FusionAuth and can be used to represent links and/or permissions between domain objects and users.

Entity types are like classes in an object-oriented programming language, which define the permissions that an entity can have.

Entities are similar to objects, in that they are an instantiation of an entity type. No behavior though, and no inheritance.

Entities are connected to users and other entities via grants. You can think of this setting up a directed permission graph that can be traced.

0 to N permissions are attached to each grant.

There are three major uses for entities:

the client credentials grant (agentic, machine to machine or service account authentication) building limited fine grain authentication (FGA-ish) systems that don't need full ReBAC, but do want to use a permission graph or dynamically add and remove permissions modelling permissions on something you don't log into

A few notes about entities:

you'll want to get familiar with the API or the client libraries; entities are managed in code. Both in creating the graph and reading it from your application. each entity has a data field which can handle arbitrary JSON and is searchable the graph can be cyclic if you make bidirectional grants between entities. Users cannot accept grants, they can only be granted permissions to entities. if you need full ReBAC or ABAC, you want FusionAuth FGA. More functionality, including automatic relationship graph traversal. The downside is you have to sync data and run a separate service.

You want to modify the Two-Factor Login duration in the Tenant Settings, which applies across to SMS and MFA methods.

https://fusionauth.io/docs/get-started/core-concepts/tenants#advanced has more details.

Here are two scenarios for using the FusionAuth API MCP Server, which is an MCP server that connects over STDIO and can be used to configure a FusionAuth instance.

Local development — letting an agent configure FusionAuth and recording the steps for later automation Production read-only — using an agent to safely query a production instance

⚠ Preview Warning: The FusionAuth MCP server is a preview release and may break, change, or be discontinued. It is intended for development and test instances. Never give an MCP client unrestricted access to a production instance.

Prerequisites A running FusionAuth instance (local or remote) Node.js installed An MCP-compatible client (e.g., Claude Desktop) Scenario 1: Local Development

This lets you configure FusionAuth and record steps to apply to other instances.

Create a read-write API key. In your local FusionAuth instance, create an API key with the permissions you need. For full configuration work, you may want broad permissions, but always follow the principle of least privilege — for example, if you're only working with applications and themes, grant only those permissions. Configure your MCP client. For Claude Desktop on macOS, edit ~/Library/Application Support/Claude/claude_desktop_config.json to add the FusionAuth MCP server. Since you want full configuration access, omit the USE_TOOLS restriction (note: you'll need a model that can handle ~200k tokens): { "mcpServers": { "fusionauth-mcp-api": { "command": "npx", "args": [ "@fusionauth/mcp-api" ], "env": { "API_KEY_APIKEYAUTH": "<your-read-write-api-key>", "API_BASE_URL": "http://localhost:9011" } } } }

Restart Claude Desktop after saving.

Verify the connection. Open Claude Desktop and ask:

"Which tools do you have access to?"

You should see a list of all FusionAuth API tools (300+).

Configure FusionAuth using natural language. Now you can describe what you want in plain English. For example:

"Set up a custom registration form for the Pied Piper application. Require email address and password, but allow first name and favorite color to be optional. Put them all on one page."

Or:

"Add a user with an email address of test@example.com and a password of password."

The agent will make the appropriate API calls on your behalf.

Export your configuration for automation. Once you've configured things the way you want, ask the agent to export the configuration so you can turn it into repeatable scripts:

"Please export the configuration for the Pied Piper application to a kickstart file."

"Export the current tenant configuration as a Terraform file."

This gives you a reproducible artifact you can commit to source control or use in CI/CD pipelines.

You can reduce tool scope. If you only need to work with specific operations (e.g., no deletes), you can reduce the tool list to improve performance and limit risk:

"env": { "API_KEY_APIKEYAUTH": "<your-api-key>", "API_BASE_URL": "http://localhost:9011", "USE_TOOLS": "create,update,retrieve,search,other" }

This omits the delete APIs and reduces the tool list by ~20%.

Scenario 2: Production Read-Only Queries with an Agent

The security model of this approach consists of three layers: the instance you connect to, the tool categories you expose, and the permissions on the API key itself. Combining a read-only API key with USE_TOOLS="retrieve,search" gives you defense in depth for production queries.

Create a read-only API key. In your production FusionAuth instance, create an API key scoped to read-only operations only. This is the most important security step — the API key defines the ceiling of what the agent can do. Configure your MCP client with read-only tools. Edit your MCP client config to point at your production instance and restrict tools to retrieve and search only: { "mcpServers": { "fusionauth-mcp-api-prod": { "command": "npx", "args": [ "@fusionauth/mcp-api" ], "env": { "API_KEY_APIKEYAUTH": "<your-read-only-api-key>", "API_BASE_URL": "https://your-production-fusionauth-instance.com", "USE_TOOLS": "retrieve,search" } } } }

Setting USE_TOOLS="retrieve,search" reduces the tool list by 66% and ensures the agent cannot create, update, patch, or delete anything. This is a second layer of defense.

Verify read-only access. Ask the agent:

"Which tools do you have access to?"

Confirm that only retrieve and search tools are listed — no create, update, delete, or patch tools should appear.

Query production data. You can now safely ask questions like:

"Is PKCE enforced for all my applications?" "How many users do I have in my FusionAuth instance?" "How many FusionAuth applications do I have?"

The agent will use the read-only API tools to answer your questions without modifying anything.

You have a couple of options.

If you use the hosted login pages/authorization code grant, disabling all grants in the application settings page will prevent people from logging in. If you use the login API and have customer-based API keys, you could turn on the 'require API key for login API' and then disable the customer's API key. If you have the Enterprise plan, you could set up an IP ACL for a unroutable IP range.

However, the easiest way to make sure an application cannot be logged into is to deactivate the application.

Lots of options!

Self-service password recovery — SMS or Email based forgot password flows out of the box, with hosted pages that require no custom UI. If a user's login ID is a phone number, the reset is delivered via SMS automatically. API-driven recovery — The full forgot password flow is triggerable via POST /api/user/forgot-password with an email, phone, or username as the login ID, giving teams complete control over the UI and recovery experience. Admin and support-assisted recovery — Support staff can trigger resets or force password changes directly from the admin UI, no email required. Admins can also remove MFA methods directly from the user record. MFA recovery — Recovery codes generated at MFA enrollment let users bypass a lost second factor. Self-service MFA configuration — Users can add, remove, and manage their own MFA methods (TOTP, SMS, email) from a hosted self-service account page without any admin involvement. Removing a method requires completing an MFA challenge first, which prevents unauthorized removal. If an admin removes a user's MFA method and the tenant or application policy is set to Required, the user will be prompted to set up MFA again on next login. Webhooks and event-driven recovery — FusionAuth fires events like user.login.failed and user.password.reset that your backend can listen to and act on, enabling custom recovery logic, audit trails, and downstream notifications. Account linking and IdP recovery — For users who log in via a social or enterprise IdP, FusionAuth can be configured to link that identity to a FusionAuth user record. If the IdP connection is the issue, the user can still go through the standard forgot password flow as long as an phone number or email is on their account, so recovery isn't solely dependent on the IdP being available.

You want to use search parameters like those outlined in this sample script.

use a key limited to POST on /api/user/search set accurateTotal on the request set numberOfResults to 1 on the request

In the response, look at the total field.

This will let you get exact numbers while reducing load on your instance.

Beginning in version 1.65.0, FusionAuth offers Complete Registration. Full docs here.

How this would work:

enable a registration form for the application your users are logging into select certain attributes as required. If you are using a basic form, you could select 'birth date'. If you are using an advanced form, you can select whatever profile attributes you need set the Registration mode to Complete registration. This setting means that users cannot self-register, but can complete missing information from an existing registration. save the application

Now, your admin user can create a user with a minimal amount of data (perhaps just an email address).

The user will, at first login, be prompted to fill out their profile data, including all fields you've marked required.

This is not full progressive registration, but can be useful in certain circumstances.

The cleanest way to do it is with asymmetric JWT verification plus a bounded offline grace period.** Here's the pattern.

FusionAuth signs JWTs with a private key it holds. The matching public key is published at the JWKS endpoint (/.well-known/jwks.json). Your mobile app — or any resource server — can verify a token's signature locally, with zero network calls, as long as it has that public key. You can even bundle the public key with the application and avoid the retrieving it.

That's the property that makes offline auth possible. You're not asking "is this token still good?" over the wire; you're asking "did FusionAuth sign this, and has it expired?" using math the device can do on its own.

See JWT signing configuration and the JWKS endpoint docs.

The Flow

1. First login (online, required). The user authenticates against FusionAuth via OAuth with the offline_access scope, or via the Login API with loginId + password + applicationId. You get back two things:

A short-lived access token (signed JWT, RS256, EdDSA, or ES256) A long-lived refresh token (opaque, default 30 days, configurable per tenant or application)

Refresh token details are in the refresh token settings docs.

2. Cache the JWKS on the device. Fetch /.well-known/jwks.json once and store it. You'll match incoming tokens to the right key using the kid in the JWT header. For fully air-gapped scenarios, you can bundle the JWKS into the app at build time — see the air-gapping article.

3. Online operation. The app uses the access token for API calls. When it expires, the app calls the Refresh a JWT API with the refresh token to mint a new access token.

4. Offline operation. The app validates the cached access token locally:

Find the key in the JWKS where kid matches the JWT header Verify the signature with that public key Check exp, iss, aud, and any custom claims you care about

If the token is past exp but the device is offline, allow a bounded grace period (e.g., 24 hours past expiration). After that, degrade functionality until the device reconnects and refreshes. For instance, you could allow read operations but nothing that changes data.

5. On reconnect. Refresh immediately. If the refresh token has been revoked server-side, the call will fail and the user must re-authenticate.

Token lifetime tuning

This is where you make your security/availability tradeoff explicit. FusionAuth lets you tune both lifetimes per tenant or per application:

Access token TTL (ttl_seconds😞 set this short for online use (5–15 minutes is typical), but if you want longer offline windows without the grace-period workaround, you can extend it. Whatever you pick is the maximum revocation lag for compromised tokens. Refresh token duration: default is ~30 days. Use a Sliding Window with Maximum Lifetime policy if you want active devices to keep working but inactive ones to expire automatically. One-Time Use refresh tokens: rotates the token value on every refresh. Strongly recommended — if a refresh token is stolen and used, the legitimate device's next refresh will fail and the theft is detected.

What FusionAuth gives you for revocation

Refresh tokens can be revoked automatically on password change, MFA enrollment, or any action that prevents login. You can also call the Revoke Refresh Tokens API directly. The catch: revocation only takes effect the next time the device tries to refresh. Already-issued access tokens remain valid until their exp.

Tradeoffs you're signing up for

Be honest with yourself about this approach. These aren't FusionAuth limitations, they're inherent to offline auth:

Delayed revocation. A stolen device retains access until the access token expires and the offline grace period elapses. Shorter access token TTLs mean faster revocation but more refresh traffic and shorter offline windows. Pick where on that curve you want to sit. Clock trust. Offline exp checks rely on the device clock, which the user controls. If that matters for your threat model, store a "last known server time" on each refresh and refuse to validate tokens if the clock has moved backward. Stale claims. If a user's roles or permissions change, the old claims persist in the cached token until the next refresh. Acceptable for most apps, not for high-stakes authorization. Local credential storage. If you want users to "log in" while offline (PIN/biometric to unlock the cached session), you're storing something derivable from their credential on the device. Use the platform secure storage (iOS Keychain, Android Keystore) and a slow KDF like Argon2id for any password-derived material. Key rotation. If you bundle JWKS into the app, you have to ship app updates ahead of key rotations (or plan to create a bunch of keys ahead of time). If you fetch JWKS dynamically, you need a cache strategy and a fallback when the cache is stale and the network is down. MFA degrades offline. Push and SMS-based factors require connectivity. Offline auth typically falls back to device-bound factors (the refresh token + a local PIN/biometric), which is different than your online MFA flow. Decide whether that's acceptable.

Practical starting point

Here's an example of the configuration:

Access token TTL: 15 minutes Refresh token: 30 days, sliding window, one-time use Offline grace period (app-enforced): 24 hours past exp JWKS: fetched on first launch, refreshed weekly when online, with a bundled fallback Mandatory online check-in: every 7 days (refuse to operate offline beyond this)

Tighten the numbers for higher-sensitivity apps, loosen them for field-work apps where availability matters more than instant revocation.

Some further reading for you:

Building a Secure JWT Revoking JWTs Token storage best practices Air-gapping FusionAuth

The short version: FusionAuth gives you all the primitives:

asymmetric signing JWKS configurable lifetimes refresh token revocation

The offline policy is yours to design, and the design is mostly about choosing how much revocation lag you can tolerate in exchange for how much offline runway your users need.

Because advanced themes are so customizable, they can be hard to upgrade. Here's some ways to make it easier.

When you create a new theme, start from the default version. Commit it to git before you change anything. Use the FusionAuth CLI to download/upload your theme during development and CI/CD. When a new theme comes out, clone or pull the latest from the theme history repo. Run this command to see what has changed: git format-patch 1.61.0..1.64.1 --stdout > update-themes.patch (this shows the changes between 1.61.0 and 1.64.1; adjust as needed for your installed version and the target version). Go to your theme git repo and apply the changes: git am --3way update-themes.patch which will attempt to automatically merge the changes. If there are conflicts, you can resolve them manually and then run git am --continue.

You can also use a 3 way diffing tool like diff3 or kdiff3 to visualize the changes.

These upgrade notes also provide detailed human friendly instructions on the changes.

There are a couple different scenarios where a login record could have a blank application Id. Usually it is #1 or #2. It occurs in scenarios where the user can have a JWT/access token that does not have the application Id in it.

If a user is not registered for the Application they are logging into FusionAuth makes a login record when a user is created since FA makes a JWT upon user creation If you use the Login API, you can log in without an App ID because you don't have to provide an application on the API call.

As of 1.69.0, you can now update the password hash using the User API.

From the documentation, the passwordFieldType is the API field to use. This field:

Describes what user.password in the request is. The possible values are:

HASHED - user.password is an already hashed value. When this value is supplied, user.encryptionScheme, user.factor, user.password, and user.salt are required.
PLAINTEXT - user.password is a plain text/unhashed value. FusionAuth will hash this value according to user.encryptionScheme and user.factor.

This is totally possible.

You want to start by understanding FusionAuth passkey setup and the normal flow.

Then, in your application, probably using one of the client libraries, you want to do the following for a user:

see if a user has a passkey set up, using the "retrieve a passkey" API. If this returns 0 passkeys, show the prompt. for the prompt, you have two options: use the API/client library to start the passkey registration process from within your application directly send them to the user management page to add a passkey (requires a paid license)

The right way to do the latter depends on your application needs (are you okay with a redirect) and whether or not you have at least a starter license.

For reporting on the number of users that have set up passkeys, unfortunately you have to query all your users and then pull the passkey data individually. There's no way to use the elasticsearch syntax to do the query as of yet. There's an open github issue to add that functionality.

@dan said in Claims to check when using google as an idp for google workspace:

You should start by checking the relevant google documentation.

As of writing, this is what their doc says:

Using the email, email_verified and hd fields, you can determine if Google hosts and is authoritative for an email address. In the cases where Google is authoritative, the user is known to be the legitimate account owner, and you may skip password or other challenge methods.

Cases where Google is authoritative:

email has a @gmail.com suffix, this is a Gmail account. email_verified is true and hd is set, this is a Google Workspace account.

Users may register for Google Accounts without using Gmail or Google Workspace. When email does not contain a @gmail.com suffix and hd is absent, Google is not authoritative and password or other challenge methods are recommended to verify the user. email_verified can also be true as Google initially verified the user when the Google account was created, however ownership of the third party email account may have since changed.

So in this case, you want to check that hd is set as well as that email_verified is true.

With FusionAuth, you can check this using a reconcile lambda and looking at the id_token:

https://fusionauth.io/docs/extend/code/lambdas/google-reconcile https://fusionauth.io/docs/extend/code/lambdas/openid-connect-response-reconcile

Thank you from bringing this to light.