Topics created by wesley

Existing Role Limitations in FusionAuth FusionAuth provides predefined Admin UI roles, which are not modifiable. You can review the available roles here:
FusionAuth Admin UI Roles The default FusionAuth application roles cannot be changed, which means read-only roles are not currently available. Requesting Read-Only Roles as a Feature FusionAuth does not currently support read-only access roles for applications or tenants. The likely reason for this is that users who need to view application/tenant properties often also need to update them. However, you can submit a feature request to suggest adding read-only roles:
Submit a Feature Request Workaround: Implement a Custom Read-Only View

If immediate read-only access is required, consider:

Using the FusionAuth APIs to create a custom dashboard where users can view but not edit data. Relevant APIs for this purpose: Application API Tenant API

Summary

No built-in read-only roles exist for applications or tenants. FusionAuth Admin UI roles are not modifiable. You can request read-only roles as a feature via GitHub. A workaround is to build a custom, API-based read-only view.

1. User Linking Issues Between SP & IdP-Initiated Logins

No, this behavior is not expected—you should not need to drop and re-link users every time they switch login methods.

Troubleshooting Steps:

Are these configured as two separate Identity Providers in FusionAuth? If so, ensure they are both linked to the same FusionAuth user. If they are separate, FusionAuth may be treating them as different authentication sources, causing conflicts. Is Azure using the same application for both login flows? If different applications are used in Azure, they may be sending different user identifiers to FusionAuth. Enable Debug Logging in FusionAuth: Go to System > Event Log and enable Debug Mode in the Identity Provider settings. Compare the SAML attributes (claims) being sent in SP vs. IdP-initiated logins. If they differ, you may need to adjust Azure’s claim mappings to ensure consistency.

2. Ensuring Correct Redirect URL in IdP-Initiated Flow

Yes, RelayState works in FusionAuth, but there are specific requirements:

Check Your FusionAuth Version

RelayState support was added in FusionAuth 1.41.0+. If you are on an older version, FusionAuth will default to the first redirect URL in the list.

Correct RelayState Configuration

Ensure the target redirect URL is listed as an "Authorized Redirect URL" in the FusionAuth application settings. URL-encode the redirect URL before appending it to RelayState. Example: https://example.com/welcome → https%3A%2F%2Fexample.com%2Fwelcome Append the encoded URL to the ACS URL in Azure.

Example ACS URL with RelayState:

https://your-fusionauth-instance/samlv2/acs?RelayState=https%3A%2F%2Fexample.com%2Fwelcome Test by logging in via IdP-initiated flow and checking if FusionAuth respects the RelayState.

Additional References:

SAML Redirects in FusionAuth IdP-Initiated SAML Login

Summary:

User linking issues are likely caused by different SAML claims or separate Identity Provider configurations in FusionAuth. Enable debugging to check for mismatched attributes. RelayState should work in IdP-initiated logins if you are on FusionAuth 1.41.0+, URL-encode the redirect URL, and ensure it is allowed in the application's settings.

This behavior is due to FusionAuth’s default settings for email templates. The Magic Link URL is template-driven, and by default, it may reference a local development environment unless explicitly configured.

How to Fix This:

Customize the Magic Link URL in Email Templates

FusionAuth allows you to update the email template directly. You may want to use the FusionAuth CLI and version control to manage email templates. Refer to the note in this documentation for details:
Email Templates & Replacement Variables

Update the Tenant Configuration

If you want to avoid changes to the email templates, you can put the link in the tenant object and have your template pull from there. To ensure Magic Links point to the correct domain (auth.example.com), update your tenant’s data object using the Tenant API:
Update a Tenant API This API allows you to populate the tenant.data object. Then you can use it in your email templates.

Summary

Magic Links use email templates, which may default to localhost:9011. Updating tenant settings allows you to set the correct domain dynamically. Use the Tenant API to configure the Magic Link domain properly.

There is no direct way to determine from the user object whether a password has been set.

1. Tracking Login Method (But Not Password Status)

You can determine how a user logged in by using the authentication_type field in the user.login.success webhook event. This will tell you if they authenticated via Google, Password, or another IdP, but it does not indicate whether a password exists. Webhook Reference: User Login Success Event

2. Allowing Users to Set or Update a Password

If you want IdP users to be able to set a password, you can enable the User Self-Service Form in FusionAuth.

How to Enable Self-Service Password Management:

Navigate to: Application > Registration > Form Settings > User Self Service The default self-service form includes a password field, but you can customize it or create a new form under Customizations > Forms. Once enabled, users can access their account management page to update their password. The Account URL can be found by "Viewing" the FusionAuth Application in the UI.

FusionAuth Account Management

Summary

FusionAuth does not provide a direct flag to check if a user has a password. You can track login methods via webhooks but not password existence. The best approach is to enable self-service password management, allowing users to set a password themselves.

Your request body looks correct for a basic search by email and should return a result if a user with that exact email address exists in your system.

1. Ensure You Are Using POST (or Use GET with Query Parameters)

The /api/user/search endpoint supports both POST and GET, but they expect different input formats.

If using GET, you must provide query parameters, such as:

GET /api/user/search?ids=<user_id>

2. Searching for Partial Matches

If you want to find all users with a certain email domain, try using a wildcard search:

{ "search": { "queryString": "*@email.com" } }

3. Verify API Key Permissions

If you still get empty results, ensure that:

Your API key has sufficient permissions to query user data. The user records exist in the database.

4. Further Reading on User Search

For more details on how to construct search queries, refer to:

Elasticsearch Search in FusionAuth User Search with Elasticsearch

Yes, you can manually construct a registration URL that includes PKCE values.

1. Understanding the Registration URL with PKCE

The /oauth2/register endpoint works similarly to the /oauth2/authorize endpoint but is used for user registration. Both support PKCE.
Example URLs:

Standard Authorization URL: https://your-fusionauth-instance/oauth2/authorize? client_id=yourClientId& response_type=code& redirect_uri=https://yourapp.com/oauth-callback Registration URL (Same Structure, Different Endpoint): https://your-fusionauth-instance/oauth2/register? client_id=yourClientId& response_type=code& redirect_uri=https://yourapp.com/oauth-callback

Since PKCE is enabled, you must append PKCE parameters:

code_challenge (derived from code_verifier) code_challenge_method=S256

2. Generating PKCE Parameters

Your application must generate a code_verifier and code_challenge before redirecting to FusionAuth’s registration page.

Node.js Example:

const crypto = require('crypto'); function base64URLEncode(str) { return str.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, ""); } function sha256(buffer) { return crypto.createHash("sha256").update(buffer).digest(); } function generateVerifier() { return base64URLEncode(crypto.randomBytes(32)); } function generateChallenge(verifier) { return base64URLEncode(sha256(verifier)); } // Generate PKCE values const codeVerifier = generateVerifier(); const codeChallenge = generateChallenge(codeVerifier); console.log("Code Verifier:", codeVerifier); console.log("Code Challenge:", codeChallenge);

3. Constructing the Registration URL

Once you have the code challenge, construct the registration URL as follows:

https://your-fusionauth-instance/oauth2/register? client_id=yourClientId& response_type=code& redirect_uri=https://yourapp.com/oauth-callback& code_challenge=yourGeneratedCodeChallenge& code_challenge_method=S256

4. Completing the PKCE Flow After Registration

After the user completes registration, FusionAuth will redirect them to your app with an authorization code.
Your app must then exchange this code for an access token by sending the code_verifier to /oauth2/token.

For full details on the PKCE flow, see:

Using OAuth and PKCE with FusionAuth

Summary

There’s no auto-generated PKCE registration URL, but you can manually construct one. Generate the PKCE values before redirecting users to /oauth2/register. Complete the PKCE flow by exchanging the authorization code with the code_verifier.

When upgrading FusionAuth, we recommend the following approach to ensure a smooth transition:

1. Review Release Notes

Each release may include breaking changes, bug fixes, and security updates. Be sure to check the release notes for any database migrations, template changes, or API modifications that may impact your environment. FusionAuth Release Notes

2. Choose an Upgrade Strategy

You can incrementally upgrade from 1.32.x → 1.42.x version-by-version or upgrade all at once. The recommended approach depends on your risk tolerance: Incremental Upgrades: Allows for testing each version before moving forward. Direct Upgrade: Faster but requires careful testing, especially if there are major changes.

3. Database Migrations & Maintenance Mode

FusionAuth automatically manages DB migrations in maintenance mode or silent mode. If you are using advanced configurations, refer to the manual upgrade process to apply database migrations carefully. FusionAuth Advanced Installation Guide

4. Testing in a Staging Environment

Before upgrading production, test the new version in a staging environment to verify that: All integrations (e.g., authentication flows, webhooks, APIs) function as expected. Templates render correctly (in case of UI or email template updates). Database migrations do not introduce issues.

5. Backup & Rollback Plan

Before upgrading, take full database and configuration backups in case a rollback is needed.

By following these best practices, you can minimize risks while upgrading to the latest version.

FusionAuth does not provide a built-in way to specify a fixed IP address for outbound emails. However, you can determine the current IP of your deployment and update your SPF records accordingly.

Please open a support ticket for guidance on finding the IP address of a FusionAuth Cloud deployment.

Yes, this is expected behavior because access tokens cannot be revoked by default.

Why /oauth2/logout Doesn’t Invalidate Access Tokens:

Access tokens are stateless and do not require real-time validation with FusionAuth after issuance. For this reason, access tokens are typically short-lived, reducing security risks. Logout via /oauth2/logout only removes the SSO cookie and does not affect issued tokens.

How to Handle Token Revocation:

Use Short-Lived Access Tokens The recommended approach is to issue short expiration times for access tokens and rely on refresh tokens for continued access. Implement a Token Revocation Strategy If you need a way to invalidate access tokens, consider implementing a denylist-based revocation workflow. FusionAuth provides guidance on how to do this: Revoking JWTs in FusionAuth Ensure Full Logout by Removing All Session Identifiers If the user is also authenticated via a refresh token or other session identifiers, these must be explicitly removed to fully log out the user. FusionAuth provides more details in:
Logout Endpoint Documentation
User Sessions in FusionAuth

Summary

By default, access tokens remain valid until expiration, even after logging out. To ensure access is revoked immediately, you will need to either implement a denylist mechanism or rely on short-lived tokens with refresh token workflows.

Yes, FusionAuth provides this information via the authenticationType claim in the JWT. This claim indicates the authentication method used, such as PASSWORD, GOOGLE, SAML, etc.

How to Access Authentication Type:

From the JWT: The authenticationType claim is included in the JWT access token. Documentation: JWT Access Token Claims From a Webhook Event (Alternative Approach): The same authenticationType value is included in the user.login.success webhook event. This may be useful if your system processes authentication events via webhooks instead of decoding JWTs. Documentation: User Login Success Webhook

For additional details on JWT structure and claims, refer to: JWT Components Explained

FusionAuth Cloud does not currently provide built-in analytics for MFA adoption. However, you can gather this data using the following approaches:

Retrieve Users with MFA Enabled Use the User Search API to retrieve all users for a specific application with MFA enabled. Here’s a sample queryString to retrieve all the users with an MFA configuration field. It may be empty, so you should check after retrieving them: _exists_:twoFactor Reference: Get All Users for an Application You should be able to combine these two queries to get what you want. Track New MFA Setups Per Day Set up a Webhook to listen for the user.two-factor.method.add event. This event fires when a user adds a new two-factor authentication method. Your backend can record these events daily for reporting purposes. Webhook Guide: Writing a Webhook

FusionAuth's cloud-hosted HA deployments run on AWS, meaning webhook requests will originate from AWS infrastructure.

Please open a support ticket for guidance on setting up firewall rules.

FusionAuth does not currently support the UMA grant type or Token Exchange (RFC 8693).

However, we track feature requests and open issues on GitHub. Both have been requested features, and you can upvote the requests and/or add comments with your use cases to show interest:

GitHub Issue: UMA Support GitHub Issue: Token Exchange RFC

At this time, there is no confirmed ETA for implementing these features, but community interest plays a role in prioritization. Here’s more on our roadmap process.

Yes, this behavior occurs because creating a user via the API returns an access token, which indirectly updates lastLoginInstant.

Workarounds:

Use the Import API Instead The Import API allows you to create users without generating an access token, preventing the lastLoginInstant field from being updated. API Reference: Import Users API Track Logins Using Webhooks If lastLoginInstant is needed for business logic or reporting, consider tracking actual user logins via webhooks instead. FusionAuth provides user.login.* webhook events to capture real login activity. API Reference: User Login Webhooks

By using the Import API for user creation and webhooks for tracking real logins, you can avoid the unintended side effect of lastLoginInstant being updated upon user creation.

FusionAuth does not support configuring a read-only database, as most database interactions involve writes, particularly from login events.

For additional context on high-availability database configurations with FusionAuth, refer to this forum discussion:

Does FusionAuth Support High-Availability Database Configurations?

If read replication is critical for your setup, you may need to handle database routing at the infrastructure level (e.g., using a proxy like Pgpool-II for PostgreSQL or ProxySQL for MySQL) rather than within FusionAuth itself.

FusionAuth Cloud supports active/passive DR which is further outlined here. This may be helpful to you as you build out your high availability FusionAuth system.

Based on observed import speeds, 100,000 users take approximately 1-2 minutes to import.

Using this estimate, importing 5 million users could take about 50 to 100 minutes, depending on system performance, database speed, and network conditions.

If you are importing into FusionAuth Cloud, follow the steps here to add your importing system’s IP address to our allow list.

To assist with the migration process, FusionAuth provides import scripts:

FusionAuth Import Scripts

FusionAuth is compatible with Mailgun, and we have customers who have successfully integrated it. FusionAuth works with any email provider that supports SMTP configuration, so Mailgun should function correctly.

Troubleshooting Steps:

Verify SMTP Settings: Ensure your Mailgun SMTP credentials are correctly configured in Settings > Email within FusionAuth. Review FusionAuth’s Email Troubleshooting Guide: FusionAuth Email Troubleshooting Use SWAKS for Debugging: SWAKS (Swiss Army Knife for SMTP) can help diagnose SMTP issues by testing the connection between FusionAuth and Mailgun. Enable Debug Logging: Debug logs will provide more detailed information about what might be causing the issue.

These steps should help pinpoint the problem.

This behavior is a result of session management at the identity provider level (Azure AD), not FusionAuth. When federating authentication to an external IdP, FusionAuth does not control how sessions are managed within that IdP—Azure AD determines session persistence and re-authentication policies.

Why This Happens:

When UserA logs out of your application, their Azure AD session remains active unless explicitly ended. When UserB attempts to log in, Azure AD automatically reuses the existing session (UserA’s session) instead of prompting for new credentials. Since FusionAuth relies on the identity assertion from Azure AD, it issues a token based on the session provided by Azure AD, resulting in UserA’s credentials being used.

How to Prevent This:

1. Ensure Proper Logout from Azure AD

When logging out a user, also log them out from Azure AD to end their IdP session. This is typically done by redirecting the user to Azure AD’s logout URL during the sign-out process.

Example for Microsoft Entra ID (formerly Azure AD):

https://login.microsoftonline.com/common/oauth2/logout?post_logout_redirect_uri={your-app-logout-url} This ensures that UserA is fully logged out before a new user attempts to sign in.

2. Disable "Keep Me Signed In"

Many IdPs, including Azure AD, offer a "Keep me signed in" option. If the machine is shared, instruct users not to enable this option, as it maintains the session even after closing the browser.

3. Enforce Re-authentication

Some IdPs provide settings to force authentication on each login attempt.
*In Azure AD, you can modify your SSO session policies to require fresh authentication after logout or in specific conditions (e.g., IP changes, new browser sessions).

If your application requires frequent user switching, consider enforcing authentication via the prompt=login parameter in the Azure AD authentication request:

https://login.microsoftonline.com/{tenant_id}/oauth2/authorize?prompt=login

Summary

FusionAuth trusts the session response from Azure AD, so this issue must be resolved at the IdP level. Logout must also happen at Azure AD, not just your application. Session settings in Azure AD should be configured to ensure proper user switching. For shared devices, instruct users not to use "Keep me signed in."

For more details, refer to Azure AD’s session management documentation or configure logout redirects properly within your FusionAuth setup.

JWTs Cannot Be Revoked: Once a JWT is issued, it remains valid until it expires. JWTs are decoupled authentication tokens, meaning they do not require continuous validation against a central authority. While OAuth2 includes a token introspection endpoint, it is only useful for access tokens and does not support JWT revocation. What the /oauth2/introspect Endpoint Does: This endpoint verifies whether an access token is valid based on its signature, expiration time, and format. It does not check whether a user’s account has been locked or disabled. Impact of a Locked Account on JWTs: If a user’s account is locked, they will not be able to obtain a new access token. However, any previously issued JWTs will continue to be valid until they expire, unless you implement additional measures. How to Handle JWT Revocation:
Since OAuth2 does not include JWT revocation natively, you can implement one of the following approaches: Use Short Token Lifetimes: Issue JWTs with short expiration times and rely on refresh tokens for continued access. Leverage Webhooks for Denylisting: Use FusionAuth’s event system to notify services when a user is locked or a token should no longer be valid. Services can then maintain a blacklist of invalidated JWTs.

For more details, refer to:

Revoking JWTs in FusionAuth