Yes, you can use FreeMarker logic in FusionAuth email templates to dynamically customize content per tenant without duplicating templates.

Solution

Store tenant-specific branding data in the tenant.data field (custom JSON). For example:

{ "branding": { "logoUrl": "https://cdn.example.com/acme/logo.png", "primaryColor": "#0057b8", "buttonTextColor": "#ffffff", "subjectPrefix": "[Acme]", "supportEmail": "help@acme.com", "companyName": "Acme" } }

Then reference this data in your email templates using FreeMarker syntax. Here's an example for email verification:

[#assign b = (tenant.data.branding)!{}] [#assign color = b.primaryColor!"#333333"] <div style="font-family: Arial, sans-serif;"> <img src="${b.logoUrl!'https://cdn.example.com/default-logo.png'}" alt="${b.companyName!tenant.name}" height="40"> <p>Hi ${user.firstName!'there'},</p> [#if verificationOneTimeCode??] <p>Your verification code:</p> <p><strong>${verificationOneTimeCode}</strong></p> [#else] [#assign url = "${baseUrl}/email/verify/${verificationId}?client_id=${(application.oauthConfiguration.clientId)!''}&tenantId=${tenant.id}"] <a href="${url?html}" style="background:${color}; color:${b.buttonTextColor!'#ffffff'}; padding:12px 24px; text-decoration:none; border-radius:4px;"> Verify email </a> [/#if] </div> How it works [#assign b = (tenant.data.branding)!{}] safely extracts the branding object or defaults to an empty object ${b.logoUrl!'default-value'} provides fallback values if a property is missing The same template works across all tenants, pulling each tenant's specific branding from tenant.data

This approach works for all FusionAuth email templates (email verification, forgot password, email MFA). The complexity and depth of customization you can achieve depends on your specific needs, but this pattern handles most common branding requirements.

There's no form for editing tenant data, but you can do so using one of the client libraries and your own custom form.

FusionAuth supports customization for some of these scenarios through themes, but not all:

1. Root Path Customization

This is possible. The Index page can be customized through your FusionAuth theme. You can add a redirect (for example, using JavaScript or a meta refresh tag) to send users to your application's login page.

Important: When FusionAuth can't identify the tenant (including when browsing to / without client_id or tenantId parameters), it uses the default tenant. To theme the root page:

Create a copy of the built-in theme — the default theme is immutable because it ships with FusionAuth Edit the index template in your copy to include your redirect (using JavaScript like window.location.href = "https://yourapp.com/login" or HTML meta refresh) Apply this theme to ALL tenants, including the default tenant Test with tenant specified — try the root URL with tenantId or client_id to confirm your edited theme renders

See the Advanced Themes troubleshooting guide for more details on theme issues.

Related: GitHub Issue #378

2. OAuth Error Handling

This is also possible. The OAuth error page can be customized in your theme, so you can implement the same redirect approach for customers who saved stale or broken login links. The OAuth error template is available for customization and you can add JavaScript or meta refresh redirects to handle these scenarios.

Note that OAuth errors can also be returned as redirect parameters to your application's callback URL (depending on the OAuth flow), which allows your application to handle errors directly rather than showing the FusionAuth-hosted error page.

3. 404 Pages for Invalid URLs

This is NOT currently customizable. The 404 page cannot be customized, including on Cloud deployments. Requests to invalid paths (like /whatever) will show the default error page. This is a known limitation tracked in GitHub Issue #404, which requests additional themed error pages (including 404 and 500 pages).

Summary

You can handle root path and OAuth error redirects through theme customization by adding JavaScript redirects to the index and OAuth error templates. However, true 404 pages remain uncustomizable. CloudFront configuration is not exposed to customers on cloud deployments, so there's no workaround at that layer.

Related Documentation Advanced Themes Documentation - Complete guide to customizing FusionAuth themes Theme Templates - Full list of available templates including Index and OAuth error Theme Template Variables - Variables available in each template Index Template Variables - Specific to the root page OAuth Error Template Variables - Specific to OAuth error page OAuth Error API Documentation - How OAuth errors are returned Default Tenant Configuration - Understanding the default tenant

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.

@billyudi We are working on a update to the upgrade guide which will discuss how to map the new theme files and changes.

You can follow along with it here:

https://github.com/FusionAuth/fusionauth-site/pull/2166

I get your larger question though, which is, if I customize my theme, and then I upgrade from 1.45 to 1.46 and 1.46 introduces a new themed page, what does that new themed page look like?

Have you tried testing this out?

The best way to do this is to put a value on the tenant.data object. From there you can access it in each theme.

So, for the tenant in the dev environment, set tenant.data.assethost to dev.example.com. For the prod environment, set tenant.data.assethost to dev.example.com.

Then, in your theme, you'd have something like this:

<link rel="stylesheet" href="${tenant.data.assethost}/styles.css"/>

The reason to use the tenant object is that it is available on every theme template.

This does mean that your tenant configuration will differ slightly between environments. You can also replicate this field value between tenants if you are using multiple tenants.

The way to do this is to use the user.data or registration.data objects as a transfer mechanism.

If you are using OIDC (SAML is much the same, but I'll use OIDC as an example), you can create a OIDC Reconcile Lambda. It might look like this:

// Using the JWT returned from UserInfo, reconcile the User and User Registration. function reconcile(user, registration, jwt) { user.data.favoriteColor = jwt.favoriteColor; }

So the jwt in this case is that returned from the OIDC identity provider. We store the data in user.data.

Now we need to pull it off of the user.data object using a JWT populate lambda. That might look a little something like this:

// Using the user and registration parameters add additional values to the jwt object. function populate(jwt, user, registration) { jwt.favoriteColor = user.data.favoriteColor; }

favoriteColor is now available as a claim in the JWT produced by FusionAuth.

Don't forget to assign your lambdas to the correct operations. The OIDC Identity provider needs to be configured with the reconcile lambda. The application's JWT tab is the right place to configure the use of the JWT populate lambda.

More information on all the lambda options available here: https://fusionauth.io/docs/v1/tech/lambdas/

You have a few options to do this. Unfortunately the login page, while very customizable in terms of look and feel via themes, is less customizable in terms of functionality and adding fields. Here are some options:

don't use our hosted login pages, instead build your own login pages (and all the other stuff like reset password, etc) using the Login API. You get total control of the login experience, at the cost of more custom code. check for consent when the application is loaded, after authentication. You could store a consent variable on the user object (in the data field) or use our consent model. Basically, after the user authenticates, take them to an interstitial page unless they have given consent. Put that logic in the application page they first land on. use javascript and customize the theme. Add a consent checkbox to the login form, and set a cookie once the user consented so you don't record the consent multiple times. Make a call via javascript to an API (which you'd have to write) to record when the consent was given.

Another option would be to use advanced registration forms for self registration and create a consent that would be required at sign up. Naturally, this doesn't help if you aren't using self service registration.

Hi @harunkilic ,

Welcome to the FusionAuth community! I am glad you like the software.

You can't create group fields. What you can do is assign roles to a group. If a user is in that group and registered for an application with those roles, they will assume the roles. For example:

User A is in Group B. Group B has roles 1, 2, and 3. Role 1 is in Application Z. Role 2 and 3 are in Application X.

If user A is registered for application X and is in Group B, they will have roles 2 and 3. They won't have role 1 because that is associated with application Z, which they are not registered for.

You can't build your own entities, though that is on our roadmap. Follow this issue to be updated on when that feature is implemented. Full transparency, it will likely be a feature limited to our paid editions; learn more about our paid editions here.

Whether groups make sense depends on a lot of things.

Some questions to consider:

Are you limiting application access by group? Are you going to be using the API to do so, or do you want to have the information in the JWTs and available after authentication? Does each company have an application? Are you going to use the hosted login pages or build your own?

I can't give extensive architectural advice, but maybe if you talk a bit more about your use case the choice will be clearer.

There's additional localization and internationalization doc that was written recently here: https://fusionauth.io/docs/v1/tech/core-concepts/localization-and-internationalization/

You can put whatever you want in the theme pages, but it's a good idea to keep them lean so the user has a quick login experience. After all, most folks don't care about auth except when it doesn't work!

You can optionally pass info in the state parameter, that will come back to the caller. This can be encoded JSON, as long as it is url safe. You will want to make sure that you don't put too much stuff in there, as there are URL length limits for browsers (though I learned that chrome has a URL size limit of 2MB!). Here's an example of using the state parameter for application state.

Or if you have different applications and redirect URLs, then just gathering metrics on the URLs may give you insight into who is using login, and from where.

Sort of depends upon what type of analytics you need.

In order to use a custom font within a publicly accessible FusionAuth template for a hosted deployment, pull the font from a CDN or other server hosting the font.

FusionAuth doesn't have any persistent storage for custom theme assets. You can use any font you like as long as it can be included via a tag.

@dan I would love for this to be included in the themes documentation since it's something that every theme developer needs to figure out, and of course the default theme's assets (favicon etc.) are hosted locally and served by the FusionAuth server itself - so the answer that this can't be done for your own theme assets is non-obvious!

Hiya,

The issue is that the identityProviders map needs to be populated for that login script to work, and the class behind this page doesn't provide that map. So for now I don't see a way to do this.

There is an open github issue to allow identity providers to be displayed on the registration page. I'd suggest adding your use case to that issue: https://github.com/FusionAuth/fusionauth-issues/issues/554 and I'm happy to rename it to something more general. Alternatively you can file a new issue if you feel the use case is distinct enough.

If you have your own login form, you'll either be using the Login API or the OAuth Password grant. You will use one or the other, not both, each option will provide you roughly the same functionality. Totally up to you, the Login API is our own creation, the Password grant is defined by the OAuth RFC.

High level:

Collect email and password Call the Login API or the Token endpoint using the Password grant Collect the JSON response which will contain an access token (JWT)

Login API docs: https://fusionauth.io/docs/v1/tech/apis/login#authenticate-a-user

Password Grant: https://fusionauth.io/docs/v1/tech/oauth/endpoints#resource-owner-password-credentials-grant-request
https://fusionauth.io/docs/v1/tech/oauth/#example-resource-owner-password-credentials-grant

You can now do so as of FusionAuth 1.32.

More details in the issue 628 linked above.

While we continue to improve FusionAuth (and will always have a free community edition), if you are interested in paying for a specific feature to be built, we're happy to chat. Please contact us and we'll be happy to discuss costs and timelines.