AuthKit

Introduction {{ "visibility": "no-quick-nav" }}

Integrating AuthKit into your app is quick and easy. In this guide, we'll walk you through adding a hosted authentication flow to your application using AuthKit.

In addition to this guide, there are a variety of example apps available to help with your integration.

Before getting started {{ "visibility": "no-quick-nav" }}

To get the most out of this guide, you'll need:

A WorkOS account
Your WorkOS API Key and Client ID

Additionally you'll need to activate AuthKit in your WorkOS Dashboard if you haven't already. In the Overview section, click the Set up User Management button and follow the instructions.

(1) Configure your project

Let's add the necessary dependencies and configuration in your WorkOS Dashboard.

Install dependencies

$ frontend="client-only"

For a client-only approach, use the authkit-react library to integrate AuthKit directly into your React application. Start by installing the library to your project via npm.
```
npm install @workos-inc/authkit-react
```
$ frontend="nextjs"

For a Next.js integration, use the authkit-nextjs library. Start by installing it in your Next.js project via npm.
```
npm install @workos-inc/authkit-nextjs
```

Configure a redirect URI

A redirect URI is a callback endpoint that WorkOS will redirect to after a user has authenticated. This endpoint will exchange the authorization code returned by WorkOS for an authenticated User object. We'll create this endpoint in the next step.

You can set a redirect URI in the Redirects section of the WorkOS Dashboard. While wildcards in your URIs can be used in the staging environment, they and query parameters cannot be used in production.

$ frontend="client-only"

For the client-only integration, make sure to set the callback URI as the same route where you require auth.
$ frontend="nextjs, remix, vanilla, react"

When users sign out of their application, they will be redirected to your app's Logout redirect location which is configured in the same dashboard area.

Configure initiate login URL

$ frontend="client-only"

All login requests must originate at your application for the PKCE code exchange to work properly. In some instances, requests may not begin at your app. For example, some users might bookmark the hosted login page or they might be led directly to the hosted login page when clicking on a password reset link in an email.
$ frontend="nextjs, remix, vanilla, react"

Login requests should originate from your application. In some instances, requests may not begin at your app. For example, some users might bookmark the hosted login page or they might be led directly to the hosted login page when clicking on a password reset link in an email.

In these cases, AuthKit will detect when a login request did not originate at your application and redirect to your application's login endpoint. This is an endpoint that you define at your application that redirects users to sign in using AuthKit. We'll create this endpoint in the next step.

You can configure the initiate login URL from the Redirects section of the WorkOS dashboard.

$ frontend="client-only"

Configure CORS

Since your user's browser will be making calls to the WorkOS API directly, it is necessary to add your domain to the allow list in your WorkOS Settings. This can be configured in the Configure CORS dialog on the Authentication page of the WorkOS dashboard.

While building your integration in the Staging environment you should add your local development URL here. In the example below we're adding http://localhost:5173 to the list of allowed web origins.
$ frontend="nextjs, remix"

Set secrets

To make calls to WorkOS, provide the API key and the client ID. Store these values as managed secrets and pass them to the SDKs either as environment variables or directly in your app's configuration depending on your preferences.

$ frontend="nextjs"

WORKOS_API_KEY='sk_example_123456789'
WORKOS_CLIENT_ID='client_123456789'
WORKOS_COOKIE_PASSWORD="<your password>" # generate a secure password here

# configured in the WorkOS dashboard
NEXT_PUBLIC_WORKOS_REDIRECT_URI="http://localhost:3000/callback"

The NEXT_PUBLIC_WORKOS_REDIRECT_URI uses the NEXT_PUBLIC prefix so the variable is accessible in edge functions and middleware configurations. This is useful for configuring operations like Vercel preview deployments.

$ frontend="remix"

WORKOS_API_KEY='sk_example_123456789'
WORKOS_CLIENT_ID='client_123456789'

WORKOS_REDIRECT_URI="http://localhost:3000/callback" # configured in the WorkOS dashboard
WORKOS_COOKIE_PASSWORD="<your password>" # generate a secure password here

$ frontend="nextjs, remix"

The SDK requires you to set a strong password to encrypt cookies. This password must be at least 32 characters long. You can generate a secure password by using the 1Password generator or the openssl library via the command line:
```
openssl rand -base64 32
```
Preview Deployment Configuration

For Vercel preview deployments, configure the following environment variables in your Vercel Project Settings:
```
WORKOS_API_KEY='sk_example_123456789'
WORKOS_CLIENT_ID='client_123456789'
WORKOS_COOKIE_PASSWORD='<your-generated-password>'
```
Important Notes:
- The middleware uses redirectUri option which overrides any WORKOS_REDIRECT_URI environment variable
- VERCEL_BRANCH_URL and VERCEL_URL are automatically provided by Vercel at runtime
- Do not set WORKOS_REDIRECT_URI=https://${VERCEL_URL}/callback - Vercel won't interpolate it
- Configure wildcard redirect URIs in the WorkOS Dashboard: https://*-gitethanwoos-projects.vercel.app/callback
- Keep a non-wildcard default redirect URI (e.g., https://yourdomain.com/callback) for production
- The middleware computes the redirect URI at startup using Vercel system environment variables

The code examples use your staging API keys when signed in

(2) Add AuthKit to your app

Let's integrate the hosted authentication flow into your app.

$ frontend="nextjs"

Provider

The AuthKitProvider component adds protections for auth edge cases and is required to wrap your app layout.

Middleware

Next.js middleware is required to determine which routes require authentication.

Implementing the middleware

When implementing, you can opt to use either the complete authkitMiddleware solution or the composable authkit method. You'd use the former in cases where your middleware is only used for authentication. The latter is used for more complex apps where you want to have your middleware perform tasks in addition to auth.
- | Complete
  
  The middleware can be implemented in the middleware.ts file. This is a full middleware solution that handles all the auth logic including session management and redirects for you.
  
  With the complete middleware solution, you can choose between page based auth and middleware auth.
  
  Page based auth
  
  Protected routes are determined via the use of the withAuth method, specifically whether the ensureSignedIn option is used. Usage of withAuth is covered further down in the Access authentication data section.
  
  Middleware auth
  
  In this mode the middleware is used to protect all routes by default, redirecting users to AuthKit if no session is available. Exceptions can be configured via an allow list.
  
  In the above example, the home page / can be viewed by unauthenticated users. The /account page and its children can only be viewed by authenticated users.
- | Composable
  
  The middleware can be implemented in the middleware.ts file. This is a composable middleware solution that handles the session management part for you but leaves the redirect and route protection logic to you.
Callback route

When a user has authenticated via AuthKit, they will be redirected to your app's callback route. Make sure this route matches the WORKOS_REDIRECT_URI environment variable and the configured redirect URI in your WorkOS dashboard.

Initiate login route

We'll need an initiate login endpoint to direct users to sign in using AuthKit before redirecting them back to your application. We'll do this by generating an AuthKit authorization URL server side and redirecting the user to it.

Access authentication data

AuthKit can be used in both server and client components.
- | Server component
  
  The withAuth method is used to retrieve the current logged in user and their details.
- | Client component
  
  The useAuth hook is used to retrieve the current logged in user and their details.
Protected routes

For routes where a signed in user is mandatory, you can use the ensureSignedIn option.
- | Server component
- | Client component
Ending the session

Finally, ensure the user can end their session by redirecting them to the logout URL. After successfully signing out, the user will be redirected to your app's Logout redirect location, which is configured in the WorkOS dashboard.
$ frontend="remix"

Callback route

When a user has authenticated via AuthKit, they will be redirected to your app's callback route. In your Remix app, create a new route and add the following:

Initiate login route

We'll need an initiate login endpoint to direct users to sign in using AuthKit before redirecting them back to your application. We'll do this by generating an AuthKit authorization URL server side and redirecting the user to it.

Access authentication data in your Remix application

We'll need to direct users to sign in (or sign up) using AuthKit before redirecting them back to your application. We'll do this by generating an AuthKit authorization URL server side and redirecting the user to it.

Use authkitLoader to configure AuthKit for your Remix application routes. You can choose to return custom data from your loader, like for instance the sign in and sign out URLs.

Protected routes

For routes where a signed in user is mandatory, you can use the ensureSignedIn option in your loader.

Ending the session

Finally, ensure the user can end their session by redirecting them to the logout URL. After successfully signing out, the user will be redirected to your app's Logout redirect location, which is configured in the WorkOS dashboard.
$ frontend="vanilla, react"

Set up the frontend

To demonstrate AuthKit, we only need a simple page with links to logging in and out.
$ frontend="vanilla"
$ frontend="react"
$ frontend="vanilla, react"

Clicking the "Sign in" and "Sign out" links should invoke actions on our server, which we'll set up next.
$ backend="nodejs, ruby, php, go, python, java"

Add an initiate login endpoint

We'll need an initiate login endpoint to direct users to sign in (or sign up) using AuthKit before redirecting them back to your application. This endpoint should generate an AuthKit authorization URL server side and redirect the user to it.

You can use the optional state parameter to encode arbitrary information to help restore application state between redirects.
$ backend="nodejs"

For this guide we'll be using the express web server for Node. This guide won't cover how to set up an Express app, but you can find more information in the Express documentation.
$ backend="ruby"

For this guide we'll be using the sinatra web server for Ruby. This guide won't cover how to set up a Sinatra app, but you can find more information in the Sinatra documentation.
$ backend="python"

For this guide we'll be using the flask web server for Python. This guide won't cover how to set up a Flask app, but you can find more information in the Flask documentation.
$ backend="nodejs, ruby, python"

WorkOS will redirect to your Redirect URI if there is an issue generating an authorization URL. Read our API Reference for more details.

Add a callback endpoint

Next, let's add the callback endpoint (referenced in Configure a redirect URI) which will exchange the authorization code (valid for 10 minutes) for an authenticated User object.
$ backend="nodejs"
$ backend="ruby"
$ backend="python"
$ backend="nodejs, ruby, python"

(3) Handle the user session

Session management helper methods are included in our SDKs to make integration easy. For security reasons, sessions are automatically "sealed", meaning they are encrypted with a strong password.

Create a session password

The SDK requires you to set a strong password to encrypt cookies. This password must be 32 characters long. You can generate a secure password by using the 1Password generator or the openssl library via the command line:
```
openssl rand -base64 32
```
Then add it to the environment variables file.
```
WORKOS_API_KEY='sk_example_123456789'
WORKOS_CLIENT_ID='client_123456789'

# +diff-start
WORKOS_COOKIE_PASSWORD='<your password>'
# +diff-end
```
Save the encrypted session

Next, use the SDK to authenticate the user and return a password protected session. The refresh token is considered sensitive as it can be used to re-authenticate, hence why the session is encrypted before storing it in a session cookie.
$ backend="nodejs"

Protected routes

Then, use middleware to specify which routes should be protected. If the session has expired, use the SDK to attempt to generate a new one.

Add the middleware to the route that should only be accessible to logged in users.

Ending the session

Finally, ensure the user can end their session by redirecting them to the logout URL. After successfully signing out, the user will be redirected to your app's Logout redirect location, which is configured in the WorkOS dashboard.
$ backend="ruby"

Protected routes

Then, use a helper method to specify which routes should be protected. If the session has expired, use the SDK to attempt to generate a new one.

Call the helper method in the route that should only be accessible to logged in users.

Ending the session

Finally, ensure the user can end their session by redirecting them to the logout URL. After successfully signing out, the user will be redirected to your app's Logout redirect location, which is configured in the WorkOS dashboard.
$ backend="python"

Protected routes

Then, use a decorator to specify which routes should be protected. If the session has expired, use the SDK to attempt to generate a new one.

Use the decorator in the route that should only be accessible to logged in users.

Ending the session

Finally, ensure the user can end their session by redirecting them to the logout URL. After successfully signing out, the user will be redirected to your app's Logout redirect location, which is configured in the WorkOS dashboard.

If you haven't configured a Logout redirect in the WorkOS dashboard, users will see an error when logging out.

Validate the authentication flow

Navigate to the authentication endpoint we created and sign up for an account. You can then sign in with the newly created credentials and see the user listed in the Users section of the WorkOS Dashboard.

FilesExpand file tree

WorkOS_Guide.md

Latest commit

History

WorkOS_Guide.md

File metadata and controls

AuthKit

Introduction {{ "visibility": "no-quick-nav" }}

Before getting started {{ "visibility": "no-quick-nav" }}

(1) Configure your project

Install dependencies

Configure a redirect URI

Configure initiate login URL

Configure CORS

Set secrets

Preview Deployment Configuration

(2) Add AuthKit to your app

Provider

Middleware

Implementing the middleware

Page based auth

Middleware auth

Callback route

Initiate login route

Access authentication data

Protected routes

Ending the session

Callback route

Initiate login route

Access authentication data in your Remix application

Protected routes

Ending the session

Set up the frontend

Add an initiate login endpoint

Add a callback endpoint

(3) Handle the user session

Create a session password

Save the encrypted session

Protected routes

Ending the session

Protected routes

Ending the session

Protected routes

Ending the session

Validate the authentication flow