Why is `act` claim now reserved in 1.70.0? Lambda silently fails with no warning

[FASupportBot]

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.

[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.