Clerk is best-known for our dead-simple authentication with
<SignUp/> components. But since launching our B2B SaaS Suite for onboarding business customers, our top feature request has become better authorization capabilities: not just helping developers determine who a user is, but also what permissions they have within their organization.
Today we’ve launched two new features to make robust authorization easy:
- Custom roles and permissions
<Protect>– our new authorization helpers
In Clerk’s dashboard, developers can now define custom roles, which their business customers can assign to their employees. Previously, roles were restricted to just “admin” and “member.”
In addition, fine-grained permissions can now be defined and mapped to roles. When used properly, this extra layer of abstraction allows developers to create additional roles as-needed, without making any changes to their codebase.
Each role and permission defined in Clerk’s dashboard has a corresponding key, like
To make it easy to leverage permissions for authorization checks, we’ve introduced three new helpers in our SDKs.
Developers can use the
has() function on both the frontend and the backend to determine if the active user “has” a particular role or permission.
has() can be used anywhere that Clerk returns an “auth” object:
auth()in Next.js App Router
useAuth()in client components, including during SSR
getAuth(request)in server contexts outside of the App Router (Remix Loaders, Node, Express, Fastify, etc)
protect() function is a declarative extension of
has(), which takes definitive action to block further processing, instead of allowing developers to manually handle the unauthorized case. It is intended to be used in cases where unauthorized users are assumed to be attackers.
Consider an endpoint that your product would never issue a request to unless the current user is authorized. For example, you may have a page with a button that can issue requests to that endpoint, but the page is only accessible to authorized users. That is the perfect place to use
protect() – you don't need a precisely-written error, just confidence that an attacker's requests will fail.
protect() has launched in Next.js only, though we will extend the helper to other frameworks in the future. Please use feedback.clerk.com to request the feature for your framework.
Similar to the
protect() function, the
<Protect> component is intended to block further processing. It only renders children for authorized users, and optionally renders a
fallback for unauthorized users.
<Protect> can be used across all React frameworks, in CSR, SSR, and RSC contexts.
For full details and usage information, please see our updated Organization documentation, including:
- Roles and Permissions overview
- Create Roles and assign Permissions
- Verify the active user’s permissions
With today’s launch, authorization has become a core feature of Clerk, and you will see significant, continued investment in the future.
In 2024, we will extend our authorization helpers to support entitlements, so Clerk can be used to gate features based on the subscription plan a customer selected.
Further, you likely noticed above that every role and permission is namespaced with the
org: prefix, which relates to the Organization resource. We recognize this is limiting, and in the future we will be extending our authorization helpers to work with other resources.