This week was particularly special for Clerk: our team finally met in person!

We raised our initial seed funding as just 2 founders in March 2020, right as the pandemic was spreading across the globe. We've grown to 16 since then, but we hadn't met in person until this week's retreat in Greece. It was thrilling for the team to finally meet each other in person.

This week also marked a major milestone for Clerk as we launched the beta for "Authentication v2."

This is a brand new approach to how developers authenticate their end-users in their backend. We set out to resolve the biggest concerns and most frequent challenges raised by our early customers, namely:

Authentication now uses short-lived JWTs instead of requiring a network request to Clerk, significantly speeding up the process

For cross-origin architectures, the authentication token is now passed through the 

 header to simplify Cross-Origin Resource Sharing settings

Clerk now works with applications that are rendered server-side

Clerk now works with backends hosted on the naked domain

Our own website has been running Authentication v2 for the past month and we're excited to open the beta to everyone. To get started, 

Soon, all new applications built on Clerk will default to Authentication v2.

Photo credit: Mark Pitsilos, Clerk engineer and photographer extraordinaire

Changelog Oct 15, 2021

Authentication has always been a critical aspect of web development, with user data security being paramount.

As the digital world continues to evolve, so does the need for more efficient and secure authentication methods. However, users do not necessarily want to remember secure logins for every app they use.

This is where OAuth Single Sign-On (SSO) comes into play. OAuth simplifies the user authentication process by allowing users to log in with accounts they already have with other services like Google, Facebook, or Microsoft.

In this article, we will explore how to incorporate OAuth SSO into a Next.js project with 

 and Next.js’s new app router, and later see how Clerk, an authentication service, can help simplify this and make it more secure. We will focus on GitHub SSO for simplicity, but most other OAuth providers can be implemented similarly.

Before we get started, if you ever need to look at the full source, code, the 

Before we start, make sure you are on Node v18+. You can check this by running 

 to scaffold our project. First, you will want to open a terminal in the directory you want to put the project in and run:

If you want to use a different package manager, use their own counterpart to 

 will ask you some questions about your project. Name the project whatever you want; it doesn’t matter. For TypeScript, ESLint, Tailwind, and using 

, select no. For the app router, select yes. Finally, leave the import aliases unmodified. After, the output should look like this:

Now, open that directory in a code editor of your choice. You will need to install jsonwebtoken, which we will use for verifying JWTs.

Next, we will need to create the OAuth app in GitHub. Go to 

 and fill out the information. Set the homepage URL to 

 (if you are running the Next.js server on a port other than 3000, you can replace 3000 with that port). You can leave device flow unchecked. Click register and you will be sent to the new application page.

Now, let’s go back to the code for a minute. Create a new file called 

. This is where you will store your environment variables, which are variables that specify service keys or other configuration that is specific to each deployment and are specified by writing 

. This will contain your GitHub OAuth application’s id. Note that the 

 prefix tells Next.js to allow the env variable to be accessed by replacing all calls to 

 with the value of the variable at build time. If you did not include this prefix, only the server would be able to access the value, which is good for secrets. With that aside, we need to get the GitHub OAuth application id, which you can find on the application dashboard you were sent to earlier. Copy it and paste it into the .env file.

We also need to get a secret, which we will put with the variable 

. On the dashboard, you can click “Generate a client secret” to get a new secret. Copy it and paste it in the .env file under the new variable.

, which should be a random password we use for encrypting JWTs. You can use a 

That is it for set up! Remember not to give anyone any of the secrets unless you trust them, as they can be used to impersonate users and gain unauthorized access to the application.

Our next step is to allow people to sign in by adding a sign in button on the homepage that links to the GitHub OAuth verification page. Open 

 and insert the following below the Next.js logo (You should be able to find it by looking for an 

The link will send people to a page where they can authorize the OAuth app’s access to their account information to allow the app to verify their identity. You might notice 

 contains a style that does not currently exist. We will fix this next. In 

This just provides some simple styling for the button. In order to use it, we need to import it in 

To get the layout correct, we also have to add this to 

If you click “Sign in with GitHub,” you should be redirected to a GitHub page asking you to authorize your OAuth app. However, if you click authorize, you will get a 404 error. That is because we have not implemented a callback page yet, which we will do next.

Before we start this step, a bit of explaining is required. You might have seen OAuth flows implemented differently, and this is perfectly fine. There are multiple ways to handle OAuth codes and retrieve access tokens. In this case, we are using 

, which is where the OAuth provider (GitHub in this case) sends a request to the specified callback URL (which we are implementing now) with a code. Then, the server sends a request to GitHub with the code, and GitHub responds with the access token. This is generally the most secure method, but for mobile apps or SPAs, it does not always work. With that explained, we will get started on implementing the callback.

 inside callback. This tells Next.js’s filesystem router that 

We will go through this step by step. First, we import a few different things:

 is for creating JWTs, which we use to store the userdata and allow us to verify that bad actors did not change it (we will do this later)

 is for setting cookies on the client. This function is an abstraction over the 

 is for redirecting users. Similar to the 

 function, this function abstracts over HTTP responses by automatically responding with an HTTP 3xx status code (read: a redirect) with the 

After that, we export a new function named 

 as a parameter. This function handles all HTTP requests to 

, which is the method used for typical requests that do not contain a body. 

 contains all of the information about the request.

The next part retrieves the code from the 

 query parameter in the URL. You can refer to the explanation at the start of this section to learn how this is used. If there is no code, the function returns a 400 error.

Now that we have the code, we send it back to GitHub to get the access token. After getting the response, we parse the JSON body and extract the access token. If there is no access token, another error is returned.

We sign the token to allow us to store it in a cookie with confidence that it cannot change without the JWT secret. Using the signed token, we set the 

 cookie for the user. The parameters we passed are very important. 

 makes sure JavaScript cannot access the cookie’s value, 

 makes sure that when deployed in production, the cookie cannot be sent over unencrypted HTTP, and 

 prevents the cookie from being sent to third party websites. 

 is the default in modern browsers, but it is still a good idea to make it explicit.

. If you run this code, you should end up at another 404 at 

Once again, we need to create a file named 

. Because this is a page rather than an API route, the naming is different. Copy the following into 

Once again, we will go through this step by step. The imports are largely the same as the callback. The only difference is the addition of 

, which is the CSS file we created earlier for button styling.

, because this is a page, we export a function named 

. Of course, because it is a default export in this case, the naming doesn’t really matter.

Next, we get the auth cookie. If no auth cookie is found, the user is not signed in, so we redirect the user to the sign in.

If there is an auth cookie, we verify the JWT contained in it. This is how we make sure the value was not tampered with. JWTs have a header, payload, and signature. The payload’s value can be accessed without the JWT secret. However, the JWT cannot be modified, as the signature is generated using the JWT secret and payload value. Therefore you need both of those to generate a valid signature. What we are doing here is both decrypting the payload and making sure the signature is valid.

Now that we have verified the JWT and extracted the payload, we use the access token in the JWT to request the user’s data from the GitHub API. The 

 parameter disables Next.js’s AOT caching/static generation. Normally we would do this inside a 

 with Next.js, this is the idiomatic way of using 

 (remember that this renders once on the server and does not render on the client period). We then parse the response body to get the userdata.

After that, we just have some markup that renders a welcome message with the user’s name and a logout button. We use inline styles for the header because creating another CSS file just for two rules didn’t make sense. You might notice that the logout button links to 

, which does not exist yet. We will fix that.

This is pretty simple. The first thing to do is to create another route, just like what we did for 

 in the new folder. Insert the following in the new file:

As you can see, this script is pretty simple. We just intercept GET requests to 

, and redirect the user to the homepage. Note that if the user tries to log in again, it might seem as if they are still signed in, as GitHub will silently send the access token and redirect the user when they click login. However, if you implement a more complete sign in solution, this will allow users to sign in to another account with a different method.

That is all! You now have a basic system for OAuth authentication. However, there are a few issues.

While this works, there are some problems:

There is no protection against CSRF (Cross Site Request Forgery)

There are no refresh tokens, and access tokens can last indefinitely (this is a limitation of GitHub OAuth apps)

GitHub is currently the only sign in method (non OAuth sign requires many more security measures due to the need to store information in a database)

There is support if issues arise with authentication

We could solve most of these problems, but it would take a significant amount of time (this tutorial is already almost 3,000 words) and increase maintenance. However, there is a better solution: you can use a service like 

. Clerk is a user management platform that allows you to easily and securely implement most of the popular OAuth providers along with standard email/password sign in, magic link/passwordless, and even Metamask.

and select the same choices as previously (any name, everything “no” except for the app router). Then, run:

This installs the Clerk SDK for Next.js. Now, we need to set up a Clerk app. Go to 

 (create an account if you did not already) and go through the configuration. For authentication providers, you can stick to just GitHub again or add as many providers as you want. It doesn’t change the process, and you can change it later. After that, you should be redirected to a page where you see a snippet containing 

. Copy this and paste it into a new file named 

. This includes the environment variables that store your public and private Clerk keys.

To allow us to use Clerk React components in our project, we first need to insert the 

 provides the context necessary to allow Clerk components to function properly, and due to it being 

Next, we need to create the sign in button, just like in the first version. Open 

 and insert this below the Next.js logo (the image with 

This checks if the user is signed in. If they are, it shows a link to the dashboard, and if not, it shows a button to sign in. To make this work, you will also need to import two things at the top of the file:

The first line contains the functions and components needed from the Clerk SDK, and the second is for the styling. You will want the same styling as in the previous version, so create a new file named button.module.css and insert this into it:

Now sign in should work, but we still need to implement the dashboard. First, we need to create a JavaScript file at the project root named middleware.js (make sure to put this at the project root, not/app). Paste the following in the new file:

This is a basic setup for the authentication middleware. You can configure it more to exclude specific routes, but this should work in most cases.

The next step is to create a folder called 

 inside it, just like with the implementation we already made. Inside the file, paste this:

We import multiple different functions and components from the Clerk SDK. The first, 

, helps us get the current user’s information. The second, 

, which is also exported, is a component that redirects the user to a sign in page. Finally, we have 

, which creates a button to allow the user to log out.

 file, which we use for the log out button.

 to get the user’s information. If it does not exist (meaning the user is signed out), we redirect to a sign in page using a client side redirect.

Finally, using the userdata, we return markup containing a header with the user’s email and a button to log out.

Now, sign in, the dashboard, and sign out should all work.

Social SSO in Next.js

We've introduced a new feature that allows users to easily delete their user accounts from your application. With the Self Service Delete feature, users can now delete their accounts directly through the

 component. This convenient functionality can be enabled through the Clerk Dashboard.

For our B2B customers, we've also extended this capability to administrators, who can now delete organizations directly through the 

 component. This provides enhanced control and management options for organizations within your application.

🔒 Permissions for Organization Creation

We have introduced a new feature that allows admins to have granular control over organization creation permissions for application users. With this feature, administrators can now decide whether users are allowed to create organizations. This provides you with extra control over the number of organizations within your Clerk application, ensuring that it aligns with your specific requirements and organizational structure. Note: You are still only billed on the number of active organizations in use, not the total number of organizations.

The organization creation permission setting is respected across all our stacks, including Clerk’s UI components, frontend API, and backend API.

🤖 Enhanced Bot Detection for Hosted Pages

We have introduced enhanced bot protection for our customers who are using Clerk’s 

 feature to help detect and mitigate bot attacks. In order to maintain the integrity of your application, all production instances now include additional measures against bot activity. If a suspicious bot attempts to access Hosted Pages, a “Verification Challenge” will be triggered.

This challenge serves as a verification process, similar to a CAPTCHA, to ensure that the user accessing the pages is human.

Implemented PKCE (Proof Key for Code Exchange) support for 

, improving security for user authentication and authorization code exchanges.

 parameter has been officially removed from the 

Improved Clerk Images with optimizations including:

Implementation of dynamic format negotiation that supports 

 when needed, yielding a ~50% size reduction.

Images are now scaled down to a max width of 1920 and a default quality of 80 for improved performance.

Enhanced dashboard experience now offers a cleaner, unified interface for editing and viewing SAML connections.

 endpoint in the dashboard is now deprecated and replaced with the more secure 

 endpoint. This new endpoint requires the inclusion of the old password, enhancing the security of password changes.

The Expo SDK now supports base64 image uploads for user profile images and organization logos.

Dive into AI applications at the Pinecone Hackathon, proudly sponsored by Clerk. This week-long event challenges you to devise solutions for real-world issues using Generative AI tools. The deadline for participation is Jun 26, 2023, at 12:00am EDT.

 Martin from a16z open sourced a Javascript AI “getting started” stack to allow devs to quickly spin up AI projects. Read all about it in 

We’ve got two editions of How We Roll for you this week, which covers how Clerk implements authentication, both from Clerk’s own 

 The 5th chapter of "How We Roll" covers the various ways developers can customize Clerk's UI components.

: The 6th chapter of “How We Roll” covers how Clerk’s <UserProfile /> component allows users to control their data.

Migrating User Authentication to Clerk.dev:

 wrote a step-by-step guide outlining the process of migrating user authentication from Supabase to Clerk.

, a Type-Safe, Full-Stack Starter Kit for React Native + Web, offering easy integration to Cloudflare services and built-in support for Clerk.

Congratulations to our Clerk Community member 

. Sociafy lets you curate elegant pages that reflect your individuality, and utilizes Clerk for user authentication.

A round of applause for Clerk Community member 

, a web application that leverages the power of Clerk and 

. Artisan, an AI-driven coach, is here to help you achieve your self-guided learning goals with greater consistency.

Stay tuned for future updates. If you have feedback or suggestions, leave us feedback on the docs via 

Company

Company

Changelog Oct 15, 2021

"Authentication v2"

Start Now,
No Strings Attached

Pricing built for

businesses of all sizes.

Newsletter!

Company

Company

Changelog Oct 15, 2021

Start Now,No Strings Attached

Pricing built for

businesses of all sizes.

Newsletter!

Start Now,
No Strings Attached