Userfront Software Engineer Declan Brady actively participates in numerous local sports leagues in his hometown of Washington D.C., which boasts a vibrant young adult sports community. His sporting activities range from volleyball, which he's playing this summer, to basketball, kickball, softball… For Declan, these sports are not just about competition, but they also give him the opportunity to step outdoors, engage in some physical activity, and most importantly, share enjoyable moments with friends.

It's with the same spirit of sharing and cooperation that Declan talked with the DevEx team about his cool new feature, JWT custom claims. We're as excited as Declan is to share that you now have more options for customizing the JWT access token payload. Go team-sports team players!

When to customize the JWT payload

Before going into the customization and flexibility of JSON Web Tokens (JWTs) in our platform, Declan talked about a few things and used some terms we'd like to share with you here.

A JWT (JSON Web Token) payload, also known as a JWT Claims Set, contains the claims—key-value statements—about an entity (typically, the user) and additional metadata. The payload is a Base64Url-encoded JSON object. It's not encrypted, so it can be decoded and read by anyone who has access to the token. (This means sensitive information should not be stored in the payload unless it is encrypted.)

The Userfront JWT access token payload feature allows you to customize the JWT access token format to be issued to users when they log in. When would you want to do this? Here are just some examples:

• Enhanced Security: Fine-tune JWTs for optimal security by including only necessary information.
• Streamlined Authorization: Simplify authorization flows by embedding relevant user permissions directly in the token. You can see an example of this in the default authorization field.
• Personalized Experiences: Tailor user interactions by including preferences or settings within the JWT. You could ask the user for their nickname, add the OIDC claim for nickname and use that in the UI.
• Improved Efficiency: Reduce database lookups by carrying essential user data within the token itself.
• Compatibility with third-parties: Your application may integrate with a third-party service or API, such as a social media platform or a payment gateway. These services often require specific user information to be included in the authentication or authorization process. You can add the OIDC claim for email or phone_number. Then, you can extract the email and phone number directly from the JWT payload and include them in the API requests as required by the payment gateway.
• Auditing requirements: In some industries or jurisdictions, maintaining an audit trail that includes IP addresses may be necessary for compliance purposes. You can create a custom claim and name it something like auditUserId or actorId.

Declan's update: from one to all

Previously, you could update an individual user payload, as shown in the auth/jwt call for a single user.

Declan updated the JWT access token payload feature by allowing the creation or the update of the JWT access token format to be issued to all users when they log in. The object of claims is included in the payload of the tenant JWT access token. When you update the payload, any JWTs currently in circulation continue to work with the old format until the user logs in again. This means your payload update does not disrupt the current usage of JWTs. It applies to new sessions.

Choosing between either pre-defined and developer-defined claims

Declan has built a flexible feature so you can create, set, and source claims easily. You can:

• Do nothing. This means you'll have access to Userfront's pre-defined defaults (a combination of Userfront-required claims and all of Userfront's optional claims). When designing your JWT payload it's a good idea to have a sense of the four types of JWT claims.
• Add OIDC-predefined claims. OIDC claims may fulfill a specific requirement.
• Create your custom developer-defined claim and map it to a data source.

Choosing among the four types of claims

Claims play a crucial role in conveying information about the user, their tenant, or their session. As a developer, understanding the different types of claims available and when to use each one can significantly enhance the functionality and security of your application. 

You can utilize four types of claims when working with Userfront. Each type of claim serves a unique purpose and offers different benefits.

[✓] Userfront-required claims are essential for authentication and identification, ensuring the JWT's authenticity and secure communication. These claims are preset and not editable.

[✓] Userfront-optional claims provide additional context about the user's roles and permissions, offering customization based on your application's needs. These claims are included by default but can be customized or removed as needed. For instance, if your application requires role-based access control or needs to verify multi-factor authentication, these optional claims become particularly valuable. They help maintain a fine-grained control over user access and authorization.

[✓] OIDC-predefined claims follow the OpenID Connect standard (which you can read about in Darin's blog post, OpenID Connect: An Overview), providing a comprehensive set of user attributes for compatibility with OIDC-compliant services. These claims are beneficial when you need to integrate with OIDC-compliant services or ensure compatibility with existing OIDC-based systems. For example, if your application relies on standardized user profile data such as name, email, or phone number, leveraging these claims ensures consistency and interoperability. Additionally, you can populate the user.data object to include more detailed user information like profile URLs or locale settings, enhancing the user experience in applications that require personalized content.

[✓] Developer-defined claims offer the ultimate flexibility, allowing you to add custom data specific to your application's needs. Understanding these claims and their uses will empower you to create more secure, efficient, and personalized applications. Whether you need to include additional metadata, custom user attributes, or session-specific information, these claims can be tailored to meet your requirements. For instance, if you need to track custom user preferences, developer-defined claims offer a straightforward way to achieve this. By placing custom sources on the user.data object, you can ensure your JWT payload contains all the necessary information for your application to function seamlessly.

Explore JWT custom claims through the dashboard

Head over to your Userfront dashboard and explore the enhanced JWT customization options. Go to your dashboard and select Authentication > JWT access tokens > Format tab.

Get a sense of the power of custom JWT access token payloads. You'll find intuitive tools to manage each claim type and create custom claims, as well as a link to the custom format docs.

Next steps

Besides having the right tools for each stage of your journey, Userfront’s pricing fits each part of your journey.

• Sign up for our free trial.
• Quickly build your proof-of-concept.
• ‍Contact us to share your journey or to get help along the way.

Keep up to date with Userfront on Twitter & LinkedIn.