Topics created by dan

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.

I think the way I'd approach this is:

import all users into FusionAuth

At cutover time:

look at local database to see which password hashes had changed pull the user data from FusionAuth for each of these users delete the user re-import the user with the new password hash and the FusionAuth data, maintaining the same userId (if you provide the UUID, we'll use that)

I get that is an additional complexity, but hopefully that helps.

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.

Yes.

A few options. Let's assume you have a FusionAuth instance hosted in your cloud (the cloud instance) and that you'll be running an instance on the cruise ship (the cruise ship instance). The cloud instance contains all user data. The cruise ship instance is going to be set up fresh for each cruise, with a copy of data from the cloud instance. It'll contain just the users on the cruise ship, and applications on the cruise ship will be set up to authenticate against it.

Overview Table Option Use When Notes Works With FusionAuth Cloud Use The Cloud Instance You have connectivity. Included for completeness. Yes Cruise Ship FusionAuth With QR Codes You only want to let the user modify their profile, are okay with the risk of the QR code being stolen and the user being impersonated. Need to use the API/SDKs to fully implement. Yes Cruise Ship FusionAuth With Existing Passwords You want the cruise ship instance to be the source of truth for users on the ship. No Cruise Ship FusionAuth With Existing Passwords And Changes Allowed to Cloud FusionAuth If accounts of cruise ship users need to be modifiable by people on the cruise ship and on land. Requires careful profile and credential merge logic. No Use The Cloud Instance

Use the cloud FusionAuth instance for all requests. This is the simplest solution, though it may be costly or lead to degraded functionality.

This is mentioned for completeness, but doesn't really address the core issue of missing or intermittent internet connectivity.

Cruise Ship FusionAuth With QR Codes

Here you are migrating the source of truth for these users to the cruise ship instance, excluding passwords, and then syncing the profile data back.

The main reason to choose this option is because it works with a FusionAuth Cloud hosted cloud instance, where you do not have access to the password hashes.

Steps: Copy user profile data to the cruise ship instance using the User API. Create a QR code that is associated with each user and add it to the ticket (or provide it separately). The user can then log in by scanning their phone. The QR code should include the user's login Id. Implement using the passwordless API, starting the passwordless login with the users id, and completing the login by catching the code and using the complete login API call. Mark the accounts as 'on-cruise' in the user.data field. By doing this, you can clearly differentiate between the users on the cruise and anyone else in your CIAM system. This makes it easier to merge their profile data after the cruise. Set up a webhook to disable any updates to these user accounts in the cloud FusionAuth instance while on the cruise. You can do this by setting up a transactional webhook on user.update that fails when the user being updated has the 'on-cruise' attribute set. When on the ship, users can log in with these credentials and access applications, as well as update their profiles. After the cruise is done, compare the profile update timestamps for all users in the cruise instance with the same account on the cloud instance. If the update timestamps do not match, update the cloud instance with the new profile data. Do not move the password hashes. Remove the 'on-cruise' attribute from users in the cloud instance.

Security Warning: This is a security risk! Understand the security model of an account takeover in the cruise ship instance. If anyone else scans the QR code, they can get access to the user's account.

The benefit is simple merging of data. You also don't need access to the database of the cloud instance, because all the data you are merging is available via the API.

After successfully pushing the data to the cloud server, wipe the cruise ship FusionAuth instance.

Cruise Ship FusionAuth With Existing Passwords

Here you are migrating the source of truth for these users to the cruise ship instance, including passwords, and then syncing them back.

Steps: Build an import script by reading the password hashes and other password data from the cloud instance for the users who are going on the cruise. This requires direct database access to the cloud instance. Import the users using the Import API to the cruise ship instance. Mark the accounts as 'on-cruise' in the user.data field. By doing this, you can clearly differentiate between the users on the cruise and anyone else in your CIAM system. This makes it easier to merge their profile and credential data after the cruise. Set up a webhook to disable any updates to these user accounts in the cloud FusionAuth instance while on the cruise. Do this by setting up a transactional webhook on user.update that fails when the user being updated has the 'on-cruise' attribute set. When on the ship, users can log in with their normal credentials and access applications, as well as update their profiles and password. After the cruise is done, compare the update timestamps for all users in the cruise instance with the same account on the cloud instance. If the update timestamps do not match, build an import file with the profile data and updated credentials. Read the credentials from the cruise ship instance database. Remove the 'on-cruise' attribute from users in the cloud instance. Delete the users' accounts in the cloud instance and import the user data from the cruise ship generated file.

The benefit is simple merging back to the cloud instance, because only one instance accepts changes at a time. A user is either managed by the cloud instance or by the cruise ship instance.

Automated account recovery won't work, so plan to allow staff to reset passwords if needed.

After successfully pushing the data to the cloud server, wipe the cruise ship FusionAuth instance.

Cruise Ship FusionAuth With Existing Passwords And Changes Allowed to Cloud FusionAuth

Here you are migrating these users to the cruise ship instance, including passwords, and then merging them back.

Steps: Build an import script by reading the password hashes and other password data from the cloud instance for the users who are going on the cruise. This requires direct database access to the cloud instance. Import the users using the Import API to the cruise ship instance. Mark the accounts as 'on-cruise' in the user.data field so that we'll know which users to merge. When on the ship, users can log in with their normal credentials and access applications, as well as update their profiles and password. The same accounts can be updated in the cloud instance by users or automated processes on land. After the cruise is done, compare the update timestamps for all users in the cruise instance with the same account on the cloud instance. If the update timestamps do not match, build an import file with the profile data and updated credentials. For the latter, you'll need to read from the cruise ship database. Prepare to merge the data from the cruise ship and cloud instances. Read all accounts with the 'on-cruise' from the cloud instance with an update date later than the start of the cruise. Find all the users on the cruise ships with an update date later than the start of the cruise. For each account, see what changes were made: If a cloud instance did not change and the cruise ship instance did not change, remove the 'on-cruise' data marker and do nothing else. If a cloud instance changed and the cruise ship instance did not, remove the 'on-cruise' data marker and do nothing else. If a cruise ship instance changed and the cloud instance did not, prepare an import entry from the cruise ship instance for this user. Delete the cloud instance account and then import the cruise ship instance account. If a cruise ship instance changed and the cloud instance did as well, prepare an import entry from the merged cruise ship and cloud instances. How you do this is business dependent. There may be user profile data that should be merged, and other data that might belong to either the cruise ship instance or cloud instance. The most recent password, wherever it lives, is the one that you should use for the import. When the merge is complete, write an import entry to a file. Remove the 'on-cruise' attribute at the same time. When all accounts have been merged successfully, delete the cloud instance account and then import the merged account.

Automated account recovery won't work, so plan to allow staff to reset passwords if needed.

After successfully pushing the data to the cloud server, wipe the cruise ship FusionAuth instance.

Other Considerations

If you are only allowing the user to change their profile data, you can move data without accessing the database. If users can change their passwords, you have to have access to the database to re-import them. (Or you can force a password reset.) The same applies to other secrets such as passkeys or TOTP secrets.

Options 1 and 2 work with FusionAuth Cloud hosted servers, but the other options do not because you don't have access to the database with FusionAuth Cloud.

If you allow a user to register on the cruise ship server, you will have to check for merge conflicts. If someone registered on the cruise ship, it is possible someone could have done the same on the cloud instance during the time of the cruise. Since you know all the cruise ship users, you can alternatively create accounts for everyone and disallow on ship registration.

When reading the password hashes, make sure you consult the schema for your version of FusionAuth, because the location of password hashes may change over time.

Account recovery is not available on the cruise ship, so make sure staff understands how to reset a user's password directly via the admin UI.

What is outlined above takes the final state of the user from the cruise ship and propagates it back the cloud instance. If you need to keep track of changes to the user on the cruise ship instance and replay them in order, use the webhook and event log to capture the events locally. Then replay them when the cruise ship docks using kafka.

We have an open issue to make passkeys one of the supported MFA methods.

But you can perform a step up passkey challenge using the APIs or the SDKs by doing the following:

User tries to access a restricted resource Customer app sees if the user has already been granted access (via the presence of a cookie, or some other mechanism). If they have, let them through. If the user hasn’t been granted access, perform a webauthn assertion workflow Call the /api/webauthn/start to get the workflow started Interact with the authenticator to produce the signature and whatever other information is needed. This is authenticator-specific. Call the /api/webauthn/assert to complete the workflow and prove possession of the authenticator If the workflow is successful Write a cookie or whatever if you want to remember this permission Let the user through If the workflow isn’t successful Deny access

If someone doesn't have a passkey enabled, which you can check by calling the /api/webauthn?userId={userId} API, direct them to the self-service account management passkey management pages.

Here are the API docs for the webauthn API.

Yes, I believe so.

It appears that connecting MitID to an application (also called an SP) requires utilizing an approved broker. A broker is essentially an OIDC connector.

Here is a list of official brokers: https://www.mitid.dk/en-gb/broker/current-brokers/.

We haven’t tested this, but based on reviewing Signicat’s OIDC documentation, the process seems fairly straightforward. They are one of the MitID brokers.

You can create two values for the FusionAuth url:

internalFusionAuthURL="http://fusionauth:9011" externalFusionAuthURL="http://localhost:9011"

So basically whenever you are sending the redirect to the browser (pretty much just the authorize and logout URLs) you use externalFusionAuthURL which references localhost.

When you are communicating with FusionAuth from the application backend (the express app) you use the internalFusionAuthURL which references the docker domain name.

I tested that out and it seems to work fine.

Give that a try.

Yes. You can use FusionAuth's OpenID Connect Identity Provider.

I did this a few weeks ago, so am writing these instructions from memory.

Prerequisites:

A yahoo account A running FusionAuth instance (localhost is fine)

Steps:

Go to the Yahoo! developer network and create an app. The redirect URI for Yahoo is https://<your instance>/oauth2/callback Save off the provided Client ID (Consumer Key) and Client Secret (Consumer Secret). Then go to FusionAuth and create an OpenID Connect Identity Provider: <your instance>/admin/identity-provider/add/OpenIDConnect Put the Client ID (Consumer Key) and Client Secret (Consumer Secret) into the Client Id and Client secret fields, respectively. Uncheck Discover Endpoints. Manually configure the endpoints: Set the Authorization Endpoint to https://api.login.yahoo.com/oauth2/request_auth Set the Token Endpoint to https://api.login.yahoo.com/oauth2/get_token Set the Userinfo Endpoint to https://api.login.yahoo.com/openid/v1/userinfo Set the Scope to openid email profile and any other scopes you might need. (I was unable to find an authoritative list, but here's info about the mail scopes.) Update the Button text and Button image as needed. Enable it for applications as needed. Save the Identity Provider.

This is due to non-ASCII characters in headers causing an issue in the FusionAuth parsing code. Cloudflare sends headers with non-ASCII characters (such as cf-region: São Paulo) which triggers this issue.

This is a java-http bug that was fixed in 2024, and released in FusionAuth version 1.51.2.

So, two options:

upgrade to a version of FusionAuth 1.51.2 or newer. This is the recommended approach, but may require some work. as an interim workaround, you can disable the "Add visitor location headers" option from your CloudFlare console. This should not have any negative impact, since we do not inspect those headers.

This is not available today without some glue code.

Currently our suggestion is to use Javascript on the Login page to jam the claim into a meta field that is shown on a Webhook payload, like jamming stuff into event.info.deviceDescription .

Then you create user.login.success webhook, making sure it is transactional. On login, the event is fired that off to your system and then you extract the claim off the event.info.deviceDescription field and make a PATCH call to FusionAuth. In that PATCH call, you add this to a field on user.data.x.

Then once that PATCH is successful, the 200 response back to the user.login.success event which completes the login and triggers the JWT populate lambda. That lambda extracts the claim off the user.data.x field and puts it into the JWT.

It's not pretty but it is the only way to have this work for now. (For self-service registration you can use a custom hidden field, much easier.)

Relevant docs:

https://fusionauth.io/docs/extend/code/lambdas/jwt-populate https://fusionauth.io/docs/extend/events-and-webhooks/events/user-login-success https://fusionauth.io/docs/apis/users#update-a-user

This is possible in a couple of ways.

First, to allow users to register for an application on login, you need to turn on self-service registration. From the docs:

When you enable self-service registration for an application and a user who does not have a registration for that application successfully logs in to that application, the user will automatically be registered for that application, and have a registration added.

Then the question becomes, how can you disable the hosted login pages self-service registration form?

To do so, take the following steps:

update your theme to remove the link to the "Don't have an account? Create one" link from any pages, including the login page. You can also remove all the content from the registration themed page and replace it with not implemented or similar. However, a sinister user may still be able to post to the register endpoint and create a user if you are self-hosting, block access to the /register endpoint using a proxy if you are not self-hosting, prevent self-service registration by adding an encrypted secret value to all user accounts you create via the API. Then, create self-service registration validation lambda which will examine the user object. If the user object comes through without the secret value, fail the registration. Otherwise allow it through because it is a user who has logged in.

The self-service lambda may not fire unless there are required fields on the registration form, but that behavior is undocumented and may change.