Clerk Changelog

The Clerk team recently identified and patched a critical security vulnerability in the @clerk/nextjs SDK that allows malicious actors to gain privileged access or act-on-behalf-of other users.

If you use @clerk/nextjs, please upgrade immediately to 4.29.3

In addition to releasing this patch, we have collaborated with a number of cloud providers to mitigate attacks at the network layer. Below, you will find details about these mitigations, as well as additional details about the vulnerability, and our plans to prevent future reoccurrence.

Proactive network layer mitigation

Upon discovery of the vulnerability, we immediately recognized its severity and reached out to cloud infrastructure providers for help protecting our customers’ applications.

We are pleased to share that Vercel, Netlify, and Cloudflare have deployed mitigations at the network layer. Applications using these providers are already protected. We are incredibly grateful for their fast response and close collaboration to reach the best possible resolution.

It is important to understand that these mitigations are not permanent, and should not be seen as a substitute for immediately upgrading your SDK.

Additional details

• The vulnerability was discovered on Tuesday, January 9 during an internal audit.
• The vulnerability impacts @clerk/nextjs version 4.7.0 to 4.29.2.
• The vulnerability impacts applications that use a Next.js backend. Specifically, those that call auth() in the App Router, or getAuth() in the Pages Router.
• Applications that only use Next.js for its frontend and middleware functionality are not impacted.
• Only the @clerk/nextjs SDK is impacted. Other SDKs, including other Javascript-based SDKs, are not impacted.
• While we are not aware of any exploit, we unfortunately cannot be sure without access to the server’s logs. Detailed instructions for inspecting logs for an attack will be made available to impacted customers who request them, but will not be published publicly. Please email security@clerk.dev if you would like those instructions.
• For the avoidance of doubt, the vulnerability does not grant unauthorized access to Clerk's systems.

Preventing reoccurrence

Security is Clerk’s most important responsibility, and we are continually improving our processes to ensure your application and your users remain safe.

Along with releasing this patch, we have already updated our internal test suites to ensure this particular vulnerability will not be introduced again, or into any other Clerk framework SDK.

In the coming weeks, we will conduct a full post-mortem, which we expect to generate additional preventive measures.

These steps are in addition to our regular independent security audits of our codebase, regular penetration testing, and the continual reports we receive from external security researchers. If you believe you have found a security vulnerability, please report it to us through our vulnerability disclosure program.

Additional support is available

If you have questions or concerns, please do not hesitate to reach out to security@clerk.dev.

From now on when a user attempts to authenticate using OAuth/SSO with an email address domain that is already managed by an Enterprise connection, the user is redirected to their IdP in order to complete the flow

More powerful authorization options

Previously within our Organizations product you had 2 role types to work with (Admin and Member) out-of-the-box. Those roles came with a bunch of default assumptions about how they operated and what rights they each had. For many of our customers, this worked fine – but for a large amount of our more mature customers, you required more. That's where Custom Roles and Permissions comes into play.

With Custom Roles and Permisisons you can now model your application with whatever roles map to your use-case, assign those roles the specific permissions they need and you're on your way. This data gets automatically reflected in your session tokens as claims, ready for you to build out authorization flows within your app.

Customizing your application

We didn't just stop at allowing you to model your application's roles and permissions and enrich your Sessions and JWTs. In pursuit of the best possible DX, like with our <SignUp /> and <SignIn /> components, we took it a step further.

Introducing has(), protect(), and <Protect> - our new authorization helpers. These helpers allow the convenient integration of your custom authorization needs directly inside your apps.

<Protect role="org:admin">
	<Link href="/admin">Admin Panel</Link>
</Protect>

Head to the verifying a user's permissions docs to see all 3 helpers in action.

Learn more

As of today, custom roles and permissions is in public beta. Simply head to the Dashboard and start configuring your application's roles today.

If you're looking for more detail about the release, read through our announcement blog post, or dive right into the Roles and Permission docs.

We're excited to see what you build 🚀.

Other improvements

• We added a more visible Dashboard UI when you’re in the context of a Development instance. This helps to better indicate that actions taken, such as copying and rotating keys, or modifying other settings, will not apply to the production environment.
• We've improved caching and latency to a handful of our production endpoints.
• We've improved the performance of WAU and MAU calculation for the Dashboard. In some of our larger applications, this was preventing you from seeing data beyond a 6 month lookback.

Filter Users by their latest activity

Use the new last_active_at_since parameter to filter users according to their latest activity date.

For example, if you were interested to know which users were active between 2023-11-23 and the current day, you could construct a query like this:

GET /v1/users?last_active_at_since=1700690400000

Note that session activity is registered continuously throughout the day so a query using a condition with the current day is perfectly valid.

You can also use last_active_at as an ordering parameter to sort users by how recently they were active:

GET /v1/users?order_by=last_active_at

Retrieve a single user's latest activity data

You will also now get last_active_at in your response when retrieving user details with the GET /users/{user_id} endpoint.

Simplified pricing structure

We've completely overhauled and simplified our pricing structure. All plans now include 10k MAUs! Our announcement blog post explains the rationale behind this major shift. For a complete break down, check out our beautifully redesigned pricing page.

Updated Billing Dashboard

We've also overhauled the Plan & Billing section of our Dashboard so you can more easily understand your current plans usage. If you're one of the folks who shared that our old billing section was inadequate, this update is for you.

A preview of more to come...

You may notice a new look and feel that it's disjointed with the rest of our site. We're working hard behind the scenes on a complete overhaul of our dashboard! Stay tuned for an improved experience...

What is Account Lockout?

Account Lockout is a feature that protects you and your users from brute-force attacks where bots or other nefarious actors repeatedly attempt to gain access. In addition to our other methods of bot detection, now, when a configurable limit of attempts is exceeded – the user's account will be temporarily locked, and they will be prompted to wait for a cooldown period before they can try again.

This prevents malevolent actors from guessing users' credentials by trying out multiple possible codes in rapid succession (brute-force attack).

What do I need to do to activate it?

Well, nothing. We've enabled Account Lockout on all accounts with default settings that shouldn't be intrusive for your users but will certainly inconvenience bots and scripts.

Starting today, you can head to our User & Authentication > Attack Protection and configure the settings to your application's needs. Specifically, you're able to adjust the number of failed attempts before a user's account is locked and the duration for which they will be prevented from signing in afterwards.

It is also possible to disable Account Lockout, but we highly recommend you keep it on :)

Head to our docs to learn more about brute force attacks and locking user accounts.

Install the middleware

To install the Clerk middleware for Hono, follow the instructions provided to set up and configure the middleware in Hono.

npm i hono @hono/clerk-auth @clerk/backend

Configure the middleware

Before you start using the Clerk middleware, you'll need to set the following environment variables:

CLERK_SECRET_KEY=<your-secret-key>
CLERK_PUBLISHABLE_KEY=<your-publishable-key>

Use the middleware

Here is a quick example on how to use the Clerk middleware for Hono:

import { clerkMiddleware, getAuth } from '@hono/clerk-auth'
import { Hono } from 'hono'
 
const app = new Hono()
 
app.use('*', clerkMiddleware())
app.get('/', (c) => {
  const auth = getAuth(c)
 
  if (!auth?.userId) {
    return c.json({
      message: 'You are not logged in.',
    })
  }
 
  return c.json({
    message: 'You are logged in!',
    userId: auth.userId,
  })
})
 
export default app

And that's it. Your app is now secured and running on the edge. Find more about Clerk's Hono middleware on GitHub.

Previously if you were using Clerk's <UserProfile /> and <OrganizationProfile /> to allow your user's to view and manage their own profile settings your ability to extend them was fairly limited. This meant if you wanted to provide controls for other options outside of what Clerk's defaults, you were stuck. With our latest release, these components now allow for much richer customization. Allowing you to extend Clerk's pre-built components with whatever context is right for your app and your users.

UserProfile Customization

The <UserProfile /> component now supports (view docs):

• Custom Pages: Add your app's custom pages inside Clerk's <UserProfile /> UI by passing our new <UserProfile.Page> compound component
• External Links: Add external links to the navigation sidebar using the <UserProfile.Link> component
• Reordering: Create a custom sidebar by reordering the routes (like our defaults: Account and Security)

Here what an example of how to use our new React API for UserProfile customization:

<UserProfile>
  <UserProfile.Page label="Custom Page" url="custom" labelIcon={<CustomIcon />}>
    <MyCustomPageContent />
  </UserProfile.Page>
  <UserProfile.Link label="External" url="/home" labelIcon={<Icon />} />
  <UserProfile.Page label="account" />
  <UserProfile.Page label="security" />
</UserProfile>

OrganizationProfile Customization

Just like UserProfile, the <OrganizationProfile /> component offers similar customization options for organization profiles (view docs)

• Custom Pages
• External Links
• Reordering (our defaults Members and Settings)

Here is an example of how to use the React API for OrganizationProfile customization:

<OrganizationProfile>
  <OrganizationProfile.Page label="Custom Page" url="custom" labelIcon={<CustomIcon />}>
    <MyCustomPageContent />
  </OrganizationProfile.Page>
  <OrganizationProfile.Link label="External" url="/home" labelIcon={<Icon />} />
  <OrganizationProfile.Page label="members" />
  <OrganizationProfile.Page label="settings" />
</OrganizationProfile>

For more information and implementation instructions, please refer to our documentation for <UserProfile /> and <OrganizationProfile />.

Other Fixes & Improvements

• Added support for creating users with SHA-256 algorithm password hashes, via the Backend API. SHA-256 password hashes will be transparently migrated to the more secure Bcrypt algorithm, the first time the user signs in

Up until now, we've been using our blog to share regular updates about the latest Clerk feature releases, but that ends today. Going forward we'll use the all-new Clerk changelog to keep you up-to-date with our latest releases. Come for the feature updates, stay for the scrolling comet tail in the sidebar.

Proxying Clerk's Frontend API

Do you dream about setting up a domain within Clerk but you're unable to use CNAMEs or want more control over your integration (Weird dream buddy BUT we're not judging)? We're here to make those dreams a reality with our new proxying capability for our Frontend API. Configure your proxy of choice (like NGINX) to directly talk to our Frontend API and that's it.

This is a particularly useful feature for folks using our multi-domain functionality, as you now don't need to set up DNS records for each of your satellite domains. Head to the docs to learn about more using a proxy in your project - and don't continue to let your dreams be dreams. Clerk believes in you.

Coalescing in your JWT Templates

This next one is likely a crowd pleaser... You're now able to have fallback conditions right inside of your JWT Templates. This reduces the amount of code you have to maintain inside your apps, while also making your templates simpler and more concise. Along with interpolation that was released a few months ago, this was one of the most commonly requested features in JWT Templates.

// an example template
{
  "greeting": "{{ user.full_name || 'Awesome user' }}",
  "verified": "{{ user.has_verified_phone || user.has_verified_email }}",
  "level": "{{ user.public_metadata.level || 9999 }}"
}
 
// the output from the example template
{
  "greeting": "Awesome user",
  "verified": true,
  "level": 9999
}

Use the || to set default values right inside the JWT template. Have a read through our JWT Template docs to learn more.

Some scheduled maintenance

Our primary database is scheduled for routine maintenance on Tuesday, 23/10/23, at 06:00 AM UTC. The maintenance is expected to last 60 seconds or less. Follow along at status.clerk.com

Other Fixes & improvements

• We've upgraded our TLS certificates for the Frontend API and Accounts domains to version 1.2

Prefill Sign Up & Sign In Components

You are now able to prefill email address, username, and phone numbers in the <SignUp /> and <SignIn /> components, either by passing an initialValues prop or by using query strings. Check out the docs to learn more!

Here, we want to build session management in Next.js without using any authentication library to show you what is really happening under the hood.

Improved SAML Account Linking

Users who exist in your account before you enable SAML can now authenticate with your IdP and link an enterprise connection to their account.

Stable Remix v2 Support

The newly released @clerk/remix package introduces stable support for Remix v2, without the need for the V2_ prefixes of “future-flags”. Since this is a breaking change, a major bump was needed (v3) – to get the latest version, use npm i @clerk/remix@latest.

Other Fixes & Improvements

• Updated Email Blocking so that blocking an email address will also block all its subaddresses
• Added support in the Clerk Expo Starter for the file-system-based router that was introduced with Expo Router v2

Improved Account Portal

Previously known as “Hosted Pages”, the Account Portal gives you an upgraded section in the Clerk Dashboard for much easier configuration for all of your application’s key screens. The Account Portal is also the fastest way to add authentication and user management to your application. We provide fully managed and hosted Sign-in, Sign-up, and User Profile views that live on your domain, so you don’t have to build it all yourself.

Head to the docs to learn about more about the Account Portal and how simple it is to get started.

Other Fixes & Improvements

• Added support in Clerk Expo for swapping your keys without needing a new build
• Improved clock skew detection in development
• Enhanced path ignoring in @clerk/clerk-react to make it more reliable
• Improved Next.js middleware static file detection
• Created new OG images for our Docs pages and Blog Posts

Satellite Domains

Introducing multi-domain support via the Clerk dashboard. Now you can configure multiple domains under your application – users will only have to sign in once but can access all your properties!

The new Domains page will display information about your instance’s development and production domains; you can even add satellite domains for your instance from the dashboard.

Verified Organization Domains

To ensure your users have email addresses that come from your company’s domain, Organization admins can now set an email domain requirement within the Organization.

To set the domain, admins can visit the Organization Settings page in the Dashboard and can also choose between two enrollment modes:

• Automatic Invitation: Users with a matching email domain receive an invitation to join the organization during sign-up.
• Automatic Suggestion: Users with a matching email domain receive a suggestion to request to join the Organization. Admins must accept the request before the user is added to the organization.

To support these changes, we have updated the <OrganizationSwitcher /> component to list invitations and suggestions, allowing users to accept them within the app. The <OrganizationProfile /> component has also been updated to enable admins to add and verify domains, and handle organization requests.

Other Fixes & Improvements

• Improved Organization Invitations: If there are pending organization invitations with a matching email address, they will be associated with the new user. Users can accept these invitations within the app using the <OrganizationSwitcher /> component, instead of relying solely on the email link.
• Hard limit of 500 Users on Dev Instances: To prevent accidental production use, we've implemented a hard limit of 500 users on dev instances. This ensures clear separation between development and production environments.