Posts made by FASupportBot

The act claim was reserved in FusionAuth 1.70.0 because it is defined in RFC 8693 (OAuth 2.0 Token Exchange) as a standard claim representing the "actor" in delegated token scenarios. FusionAuth began enforcing this reservation to ensure compliance with the RFC and prevent conflicts with the claim's intended usage in token exchange flows.

Why This Is Classified as Minor

FusionAuth follows semantic versioning, and this change was classified as minor rather than breaking because:

• The act claim is a standardized RFC claim with a specific defined purpose
• Using non-standard values in RFC-defined claims can cause interoperability issues with other OAuth/OIDC systems
• The change aligns FusionAuth's behavior with industry standards

However, the lack of logging when a reserved claim is silently discarded is a valid concern and makes troubleshooting difficult.

Recommended Solutions

1. Use a Custom Claim Namespace

Instead of using act directly, use a namespaced custom claim that won't conflict with RFC-defined claims:

// In your JWT populate lambda
jwt['https://yourapp.com/actor'] = 'your-actor-id';

This approach is standard practice in OAuth/OIDC and prevents future collisions with reserved claims.

2. Use applicationId or Other Non-Reserved Claims

If the actor represents an application or service account, consider using the built-in applicationId claim or another custom claim that describes your specific use case (e.g., actorId, serviceAccountId).

Why Reserved Claims Cannot Be Overridden

Reserved claims like act, sub, iss, aud, etc., are protected because they have specific meanings defined by RFCs and must maintain consistent behavior for:

• Interoperability: Other systems expect these claims to have specific formats and meanings
• Security: Claims like iss and aud are critical for token validation and cannot be arbitrarily changed
• Standards Compliance: FusionAuth aims to be a standards-compliant identity provider

Migration Path

If you're currently using act in production:

1. Update your JWT populate lambda to use a namespaced custom claim
2. Update your application to read from the new claim name
3. Test thoroughly in a non-production environment before upgrading

If you need to maintain backward compatibility during migration, you could temporarily set both claims in your lambda (the custom namespaced one and attempt to set act, knowing it will be discarded) and update your application to check for both, prioritizing the custom claim.

---

Related Documentation

• JWT Populate Lambda - Documentation on customizing JWT claims with lambdas
• Client Credentials JWT Populate Lambda - Documentation for lambdas in the Client Credentials grant
• OAuth Token Exchange (RFC 8693) - FusionAuth's implementation of RFC 8693, which defines the act claim
• FusionAuth 1.70.0 Release Notes - Release notes for version 1.70.0
• FusionAuth 1.70 Announcement: Token Exchange - Blog post explaining the new token exchange feature and scoped delegation
• GitHub Issue #1721: JWT claim overriding, namespacing or the ability to unreserve claims - Open issue discussing the ability to override or unreserve claims

Additional Context on Reserved Claims

As of FusionAuth 1.70.0, the following claims are reserved in JWT Populate Lambdas and cannot be modified:

• act (added in 1.70.0)
• amr
• auth_time
• authenticationType
• cnf
• fa_uid
• gty
• iat
• sub
• tid
• tty

Note: The exp claim can be lowered (shortened) but not extended or removed.

For other lambda types (Client Credentials, UserInfo, Token Exchange), different sets of reserved claims apply. Always use namespaced custom claims (e.g., https://example.com/my-claim) to avoid conflicts with current or future reserved claims.

After upgrading to FusionAuth 1.70.0, a JWT populate lambda that was previously setting the act claim now silently fails. The lambda executes successfully, but the act claim is discarded without any warning or error log.

The application had been using act to represent the actor while maintaining internal user IDs (since sub cannot be overridden). This worked fine in earlier versions, but after upgrading to 1.70.0, the claim is no longer present in the JWT, breaking authentication.

Questions:

1. Why was act made a reserved claim in 1.70.0?
2. Is there any way to override reserved claims or disable this behavior?
3. Why is there no warning log when FusionAuth discards a reserved claim set by a lambda?
4. How is this considered a minor change rather than a breaking change when it silently breaks existing implementations?

This pattern seems risky — any claim name in use today could become reserved in a future RFC, causing working implementations to fail after an upgrade with no visibility into what changed.

This is a confirmed bug in FusionAuth 1.69.2. The issue is in how FusionAuth validates the origin from clientDataJSON during WebAuthn registration.

This has been fixed and will be released in the next release. Subscribe to the release announcements to be notified when that happens.

After upgrading FusionAuth from 1.55.x to 1.69.2, WebAuthn passkey registration is failing for a native Android application using Credential Manager.

Setup

• FusionAuth Server: 1.69.2
• WebAuthn workflow: reauthentication
• Relying Party ID: a web domain (e.g., dashboard.example.com)
• Android implementation: Credential Manager API
• Digital Asset Links configured correctly between the web domain and Android app

The Problem

When completing registration via POST /api/webauthn/register/complete, FusionAuth returns HTTP 400:

{
  "statusCode": 400,
  "exception": {
    "fieldErrors": {
      "origin": [
        {
          "code": "[invalid]origin",
          "message": "The [origin] property is not valid. The provided value must match the value returned by the authenticator. Expected [android:apk-key-hash:<certificate-hash>] but found [dashboard.example.com]."
        }
      ]
    }
  }
}

The Android Credential Manager produces an origin in the clientDataJSON with the format:

android:apk-key-hash:<base64url-sha256-of-signing-certificate>

This is the standard Android format and cannot be modified by the application. FusionAuth 1.69.2 appears to validate this origin against the web RP domain and rejects it.

What Changed

Before 1.69.0, the implementation supplied top-level origin and rpId fields when completing registration. According to the current documentation, these fields are deprecated and ignored starting with 1.69.0. The new implementation now passes only:

await fusionAuthClient.completeWebAuthnRegistration({
  userId,
  credential,
});

FusionAuth now reads the origin directly from the signed clientDataJSON and validates it strictly. While this is correct from a security perspective, it doesn't recognize the Android APK hash format as a valid origin associated with the configured web RP through Digital Asset Links.

Questions

1. Does FusionAuth 1.69.2 support passkey registration and authentication initiated directly from a native Android application using Credential Manager?
2. Does the new relying-party validation support origins in the android:apk-key-hash:<certificate-hash> format?
3. Is there a tenant or application setting where trusted Android APK origins can be allowlisted?
4. Is this a known limitation introduced by the WebAuthn security changes in 1.69.0?
5. Is there a recommended workaround other than moving the ceremony into a browser/Custom Tab?

The data sub-object containing auth_time and authentication_type in refresh token metadata is not currently a documented or officially supported feature in FusionAuth. Its presence is inconsistent across authentication flows, as you've observed — it appears for some authentication types but not others (notably absent for MFA + PASSWORD flows).

According to the official documentation, the only documented fields within refresh token metaData are:

• metaData.device — An object containing device information (name, type, description, lastAccessedAddress, lastAccessedInstant)
• metaData.scopes — An array of OAuth scopes associated with the token
• metaData.resources — An array of resource URIs per RFC 8707 (available since v1.67.0)

The data sub-object with auth_time and authentication_type that you're observing is not part of the documented API contract. Because this is undocumented behavior, you should not rely on it in production code, as it may change or be removed in future versions without notice.

Important Distinction: auth_time on JWTs vs Refresh Tokens

Note that auth_time is a standard and documented claim on access tokens and ID tokens (the JWTs themselves), where it represents the time of initial authentication. However, it is not a documented field on the refresh token record itself when queried via the retrieval API.

Related Documentation

• Retrieve Refresh Tokens API — Official API documentation including the complete response body structure for refresh tokens
• Access Token and ID Token Claims — Where auth_time is officially documented as a JWT claim
• Multi-Factor Authentication (MFA) — Guide to implementing MFA in FusionAuth
• JWT Refresh API — How to use refresh tokens to obtain new access tokens

When querying the refresh token endpoint GET /api/jwt/refresh?userId={userId}, some refresh tokens include a data sub-object under metaData containing fields like auth_time and authentication_type.

This metadata appears to be present for the following authentication types:

• PASSWORD
• PASSWORDLESS
• SAMLv2IdpInitiated
• SAMLv2

However, when users authenticate using MFA + PASSWORD, the data sub-object is missing from the refresh token metadata.

Is this data object (specifically auth_time and authentication_type) something that can be reliably used across all authentication flows in current and future versions of FusionAuth? Or is its presence inconsistent and not intended as a stable API feature?

Currently, there is no sorting logic implemented for deployments in the FusionAuth Cloud account portal. The order of deployments is not sorted alphabetically or by any other consistent criteria at this time.

This has been noted as a feature request to add sorting capabilities (or the ability to manually sort) deployments in the account portal. This would help prevent accidental selection of the wrong instance when managing multiple FusionAuth Cloud deployments.

In the meantime, extra care should be taken when selecting deployments from the list to ensure you're working with the correct instance. You can use the Rename feature (available in the Action dropdown menu for each deployment) to give your deployments descriptive names that help distinguish between different products or environments.

Related Documentation

• Managing Your Deployments - Overview of managing FusionAuth Cloud deployments in the account portal
• The Account Portal - Documentation on accessing and using the account portal
• FusionAuth Account Portal Reference - Complete reference for the FusionAuth account portal features

When viewing deployments at account.fusionauth.io/account/deployment, the sort order appears inconsistent or random.

This becomes problematic when managing multiple deployments for different products or environments, as it's easy to accidentally select the wrong instance.

Is there a current sorting mechanism for deployments in the account portal? It would be helpful to have deployments sorted alphabetically by name or URL to prevent accidental misclicks when working with multiple instances.

FusionAuth Cloud deployments can provide static outbound IP addresses for email delivery and other outbound connections. The availability and process depend on when your deployment was created.

Getting Static IP Addresses

For new FusionAuth Cloud deployments: Static IP addresses are already configured automatically.

For existing deployments: You need to open a support ticket to get static IP addresses assigned.

How to Request Your Deployment's IP Addresses

To retrieve the specific outbound IP addresses for your deployment (e.g., to allowlist them with your SMTP provider):

1. Open a support ticket
2. Include the name of the deployment for which you need the outbound IP addresses

Once assigned, these IP addresses will remain static and won't change during upgrades, restarts, or normal operations.

Important Notes About the IP Addresses

• The provided IP addresses are for outbound traffic only (firewalls, allowlists, SPF records, etc.) — they will not respond to HTTP API calls
• You should add these IPs to your SPF DNS record for your sending domain to prevent password reset and other transactional emails from landing in spam
• Multiple IP addresses may be provided for high availability

Recommended Approach

If you have both production and development environments:

1. Request and configure the static IPs for your development instance first
2. Test email delivery with the allowlisted IPs
3. Once verified, request and configure the production deployment's static IPs

Related Documentation

• FusionAuth Cloud - Deployment IP Addresses - Official documentation on obtaining IP addresses for your FusionAuth Cloud deployment
• Configure SMTP - Complete guide to configuring email delivery in FusionAuth
• SMTP Best Practices - Recommendations for maintaining good sender reputation including SPF records
• GitHub Issue #1393 - Original feature request for static IP addresses in FusionAuth Cloud

We're configuring email delivery for our FusionAuth Cloud deployments, and our email service provider requires us to allowlist the IP addresses of any client connecting to its SMTP server.

Could you please provide the outbound (egress) IP address(es) used by our hosted instances?

A few related questions:

• Are these IPs static, or can they change (e.g. during upgrades, restarts, or region failover)?
• If they can change, will we be notified in advance, or is there a static egress IP option available?
• Are there any additional IPs we should allowlist (e.g. for high-availability nodes)?

The behavior you're experiencing is likely related to the SSO Session Timeout setting in your Tenant configuration.

Understanding the "Remember Me" Checkbox

The "Remember Me" checkbox (labeled "Keep me signed in" in the default theme) controls the FusionAuth SSO session. When checked, it creates a persistent cookie that allows users to remain logged in across browser sessions. However, even with this option checked, the session will still expire based on your configured Session Timeout value.

Check Your SSO Session Timeout

Navigate to:

• Tenants → (your tenant) → OAuth tab
• Look for the Session timeout setting
• The default value is 3600 seconds (1 hour)

This setting controls how long the FusionAuth SSO session remains valid. When this duration expires, users are logged out and must re-authenticate, even if they previously selected "Remember Me."

The one-hour expiration you're seeing matches the default Session Timeout setting, which explains why users are consistently logged out after that time period.

To Resolve This Issue

1. Increase the Session timeout value to a longer period (e.g., 86400 seconds for 24 hours, 2592000 seconds for 30 days, or whatever suits your security requirements)
2. Save the Tenant configuration
3. Have users log in again with "Remember Me" checked

The new timeout will apply to all new SSO sessions created after the configuration change.

Related Documentation

• Logout and Session Management - SSO Session Timeouts
• FusionAuth Cookies Reference
• Does FusionAuth support Remember Me functionality?
• Configure Session Timeout

We are experiencing an issue where the "Remember Me" checkbox on the FusionAuth login page does not work as expected. Users are consistently logged out after approximately one hour, regardless of whether they check the "Remember Me" option.

Environment:

• Using the standard OAuth redirect flow for authentication
• Tested on the latest FusionAuth version with the default login template
• Users are often logged into multiple applications simultaneously

Observed behavior:

• After about one hour, users receive the message "You have been logged out" on the FusionAuth login screen
• This happens even when the Remember Me checkbox is selected during login
• User sessions are visible in FusionAuth (though these appear to be primarily for the refresh token flow)
• No logs in FusionAuth indicate why the user was logged out

What we've tried:

• Verified the issue occurs with the unmodified default FusionAuth template
• Confirmed users have active sessions showing in their profile

Is there a configuration setting or known issue that would cause FusionAuth to expire user sessions after one hour regardless of the Remember Me selection? How can we keep users logged in for longer periods when they've opted to be remembered?

Yes, this is feasible, but you cannot integrate AWS SNS Notify directly with FusionAuth's Generic Messenger. You'll need to implement a middleware relay to bridge the two systems.

Architecture

The Generic Messenger can only POST JSON to a URL, while AWS Notify requires AWS-signed API calls. The solution is to place a relay service between FusionAuth and AWS SNS.

Recommended approach:

1. Set up an AWS API Gateway endpoint backed by a Lambda function as your relay
2. Configure FusionAuth's Generic Messenger to POST to this API Gateway endpoint
3. The Lambda function receives the phone number and message from FusionAuth
4. The Lambda extracts the MFA code from the payload
5. The Lambda calls AWS SNS SendNotifyTextMessage with the code as a template variable
6. AWS SNS delivers the SMS using your pre-approved template

Important constraint

You must configure AWS Notify to use "you generate the code" mode, because FusionAuth generates and validates its own MFA codes internally.

Additionally, AWS SNS Notify only sends pre-approved message templates for compliance reasons, so FusionAuth's custom message wording will not reach the end user — only the MFA code itself will be inserted into your AWS template.

I want to enable SMS-based MFA in FusionAuth using AWS SNS Notify as the delivery mechanism. Is it possible to integrate AWS Notify with FusionAuth's Generic Messenger for sending MFA codes via SMS?

I'm aware that FusionAuth's Generic Messenger can POST to HTTP endpoints, but I'm not sure if it can directly integrate with AWS Notify's API requirements.

Login records in FusionAuth (via the Login Report) don't distinguish between authentication methods. The response fields include applicationId, applicationName, loginId, loginIdType, instant, ipAddress, and userId, but none indicate the credential type used (token vs. password vs. SSO).

Recommended Approach

You can determine token usage by checking the lastLoginInstant field on user registrations:

1. Use the Retrieve User Registration endpoint (GET /api/user/registration/{userId}/{applicationId}) or search for users with tokens
2. For each registration with an authenticationToken, check the lastLoginInstant against your time windows (30 days, 90 days, 1 year)
3. If lastLoginInstant falls within your time window for any user, someone authenticated to that application during that period

Here's a Python script approach:

import requests
from datetime import datetime, timedelta

# Define time windows
windows = {
    '30d': datetime.now() - timedelta(days=30),
    '90d': datetime.now() - timedelta(days=90),
    '1y': datetime.now() - timedelta(days=365)
}

# Pull registrations for your application
# Check each registration's lastLoginInstant against cutoffs
# Count how many fall within each window

If all time windows return 0 users: Nobody authenticated to that application during those periods, so the tokens weren't used.

If users show up: The lastLoginInstant can't distinguish whether they used the token, password, or SSO. In this case, you have two additional options:

1. Check proxy/application logs for /api/login API calls and examine the request body to see if loginId and password were provided, or if it was a token-based authentication

2. Check webhook events: If you have webhooks configured, examine user.login.success events for the authenticationType field. When a user authenticates with an application authentication token, the value will be APPLICATION_TOKEN. Other possible values include PASSWORD, REFRESH_TOKEN, identity providers like GOOGLE or FACEBOOK, and many more.

3. Check JWTs: If you capture or log JWTs, the access token contains an authenticationType claim that indicates the authentication method used. For authentication tokens, this will be set to APPLICATION_TOKEN.

Related Documentation

• Application Authentication Tokens - Overview of application authentication tokens and how they work
• Retrieve a User Registration API - API documentation for retrieving user registration details including authenticationToken and lastLoginInstant
• Search Login Records API - API for searching login records (note: does not include authenticationType)
• User Login Success Event - Webhook event that includes authenticationType field
• Authentication Types Reference - Complete list of authentication types including APPLICATION_TOKEN, PASSWORD, and others
• Login API - API for authenticating users with various methods including authentication tokens

We have authentication tokens enabled for some applications in FusionAuth, and we want to determine if these tokens have actually been used for authentication in the last 30/90/365 days before disabling the feature.

We have approximately 225 users with authentication tokens assigned to their registrations. We can identify which users have tokens using an Elasticsearch query:

{
  "bool": {
    "must": [
      {
        "nested": {
          "path": "registrations",
          "query": {
            "exists": {
              "field": "registrations.authenticationToken"
            }
          }
        }
      }
    ]
  }
}

However, we need to confirm whether these tokens have been actively used for authentication. Is there a way to audit authentication token usage through login records or other mechanisms in FusionAuth?

For modeling an OAuth2 system in FusionAuth, here are the key architectural considerations:

Tenants

• Use separate tenants when you need complete isolation between environments (e.g., different customers in a multi-tenant SaaS product, or separate production/staging environments with distinct user bases)
• Use a single tenant when your users and applications share the same authentication realm
• Tenants provide the highest level of separation — each has its own users, applications, groups, and configuration

Entities and Entity Types

• Entity Types define categories of non-user objects in your system (e.g., "Device", "API Client", "Organization", "Service Account")
• Entities are instances of those types (e.g., a specific device, a specific organization)
• Use entities to represent OAuth2 concepts like:
  • Client credentials for machine-to-machine authentication
  • Devices in device authorization flows
  • Organizations or business units that own applications
  • Non-human actors that need permissions or relationships to users

Common Pattern

A typical OAuth2 architecture in FusionAuth might look like:

• Tenant = Your authentication realm/environment
• Applications = Your OAuth2 clients (registered apps that can authenticate users)
• Entity Types = Categories like "Organization", "Device", or "API Client"
• Entities = Specific instances (e.g., "Acme Corp" as an Organization entity)
• Users = End users who authenticate

The key is mapping your OAuth2 concepts to FusionAuth's primitives based on whether they represent users (User objects), applications (Application objects), or other non-user actors/resources (Entities).

I'm working on representing an OAuth2 system within FusionAuth and need guidance on the architectural design. Specifically, I'm unsure how to properly split different components across:

• Tenants — when to use separate tenants vs. a single tenant
• Entities — what should be modeled as an entity instance
• Entity Types — how to define entity types to represent OAuth2 concepts

What are the best practices for structuring an OAuth2 architecture using these FusionAuth primitives? Are there common patterns or design considerations I should follow?

Finding Users with Email MFA Configured

You can search for users with email MFA using the query string pattern in either the Admin UI search bar or via the Search API:

twoFactor.methods.method:email

This follows the same pattern used for searching users by any MFA method.

Getting an Accurate Count Efficiently

To get a count without retrieving all user records, use the Search API with accurateTotal enabled and a minimal numberOfResults:

{
  "search": {
    "accurateTotal": true,
    "queryString": "twoFactor.methods.method:email",
    "numberOfResults": 1,
    "startRow": 0
  }
}

The response will include a total field containing the exact count of matching users.

Last-Used MFA Information

Unfortunately, FusionAuth does not store a timestamp for when a user last used their MFA method. However, each MFA method object includes a lastUsed boolean field at users[x].twoFactor.methods[x].lastUsed that indicates which method was most recently used by that user. This is a boolean flag rather than a timestamp, so you can identify which method was used last but not when it was used.

I need to query FusionAuth to:

1. Find all users who have email-based MFA (two-factor authentication) configured
2. Get an accurate count of these users without retrieving all user records
3. Determine when a user last used their MFA method

Is there a way to efficiently search for users by their configured MFA methods and get timestamp information about MFA usage?