Add authentication to your Next.js (App Router) application

tip:

The sample project is available on our SDK repository.
The example is based on Next.js App Router.
The tutorial video is available on our YouTube channel.

Prerequisites

A Logto Cloud account or a self-hosted Logto.
A Logto traditional application created.

Installation

Install Logto SDK via your favorite package manager:

npm
pnpm
yarn

npm i @logto/next

pnpm add @logto/next

yarn add @logto/next

Integration

Prepare configs

Prepare configuration for the Logto client:

app/logto.ts
import { LogtoNextConfig } from '@logto/next';

export const logtoConfig: LogtoNextConfig = {
  appId: '<your-application-id>',
  appSecret: '<your-app-secret-copied-from-console>',
  endpoint: '<your-logto-endpoint>', // E.g. http://localhost:3001
  baseUrl: '<your-nextjs-app-base-url>', // E.g. http://localhost:3000
  cookieSecret: 'complex_password_at_least_32_characters_long',
  cookieSecure: process.env.NODE_ENV === 'production',
};

Configure redirect URIs

Before we dive into the details, here's a quick overview of the end-user experience. The sign-in process can be simplified as follows:

Your app invokes the sign-in method.
The user is redirected to the Logto sign-in page. For native apps, the system browser is opened.
The user signs in and is redirected back to your app (configured as the redirect URI).

This authentication process follows the OpenID Connect (OIDC) protocol, and Logto enforces strict security measures to protect user sign-in.
If you have multiple apps, you can use the same identity provider (Logto). Once the user signs in to one app, Logto will automatically complete the sign-in process when the user accesses another app.

To learn more about the rationale and benefits of redirect-based sign-in, see Logto sign-in experience explained.

note:

In the following code snippets, we assume your app is running on http://localhost:3000/.

Configure redirect URIs

Switch to the application details page of Logto Console. Add a redirect URI http://localhost:3000/callback.

Just like signing in, users should be redirected to Logto for signing out of the shared session. Once finished, it would be great to redirect the user back to your website. For example, add http://localhost:3000/ as the post sign-out redirect URI section.

Then click "Save" to save the changes.

Handle callback

After the user signs in, Logto will redirect the user back to the redirect URI configured above. However, there are still things to do to make your application work properly.

We provide a helper function handleSignIn to handle the sign-in callback:

app/callback/route.ts
import { handleSignIn } from '@logto/next/server-actions';
import { redirect } from 'next/navigation';
import { NextRequest } from 'next/server';
import { logtoConfig } from '../logto';

export async function GET(request: NextRequest) {
  const searchParams = request.nextUrl.searchParams;
  await handleSignIn(logtoConfig, searchParams);

  redirect('/');
}

In Next.js App Router, events are handled in client components, so we need to create two components first: SignIn and SignOut.

app/sign-in.tsx
'use client';

type Props = {
  onSignIn: () => Promise<void>;
};

const SignIn = ({ onSignIn }: Props) => {
  return (
    <button
      onClick={() => {
        onSignIn();
      }}
    >
      Sign In
    </button>
  );
};

export default SignIn;

app/sign-out.tsx
'use client';

type Props = {
  onSignOut: () => Promise<void>;
};

const SignOut = ({ onSignOut }: Props) => {
  return (
    <button
      onClick={() => {
        onSignOut();
      }}
    >
      Sign Out
    </button>
  );
};

export default SignOut;

Remember to add 'use client' to the top of the file to indicate that these components are client components.

Add buttons to home page

note:

It is not allowed to define inline "use server" annotated Server Actions in Client Components. We have to pass it down through props from a Server Component.

Now let's add the sign-in and sign-out buttons in your hoem page. We need to call the server actions in SDK when needed. To help with this, use getLogtoContext to fetch authentication status.

app/page.tsx
import { getLogtoContext, signIn, signOut } from '@logto/next/server-actions';
import SignIn from './sign-in';
import SignOut from './sign-out';
import { logtoConfig } from './logto';

const Home = () => {
  const { isAuthenticated, claims } = await getLogtoContext(logtoConfig);

  return (
    <nav>
      {isAuthenticated ? (
        <p>
          Hello, {claims?.sub},
          <SignOut
            onSignOut={async () => {
              'use server';

              await signOut(logtoConfig);
            }}
          />
        </p>
      ) : (
        <p>
          <SignIn
            onSignIn={async () => {
              'use server';

              await signIn(logtoConfig);
            }}
          />
        </p>
      )}
    </nav>
  );
};

export default Home;

Checkpoint: Test your application

Now, you can test your application:

Run your application, you will see the sign-in button.
Click the sign-in button, the SDK will init the sign-in process and redirect you to the Logto sign-in page.
After you signed in, you will be redirected back to your application and see the sign-out button.
Click the sign-out button to clear local storage and sign out.

Fetch user information

Display user information

When user is signed in, the return value of getLogtoContext() will be an object containing the user's information. You can display this information in your app:

app/page.tsx
import { getLogtoContext } from '@logto/next/server-actions';
import { logtoConfig } from './logto';

export default async function Home() {
  const { claims } = await getLogtoContext(logtoConfig);

  return (
    <main>
      {claims && (
        <div>
          <h2>Claims:</h2>
          <table>
            <thead>
              <tr>
                <th>Name</th>
                <th>Value</th>
              </tr>
            </thead>
            <tbody>
              {Object.entries(claims).map(([key, value]) => (
                <tr key={key}>
                  <td>{key}</td>
                  <td>{String(value)}</td>
                </tr>
              ))}
            </tbody>
          </table>
        </div>
      )}
    </main>
  );
}

Get user information in API route handlers

You can also get user information in API route handlers:

app/api/profile/route.ts
import { getLogtoContext } from '@logto/next/server-actions';
import { logtoConfig } from '../../logto';

export const dynamic = 'force-dynamic';

export async function GET() {
  const { claims } = await getLogtoContext(logtoConfig);

  return Response.json({ claims });
}

Request additional claims

You may find some user information are missing in the returned object from getLogtoContext. This is because OAuth 2.0 and OpenID Connect (OIDC) are designed to follow the principle of least privilege (PoLP), and Logto is built on top of these standards.

By default, limited claims are returned. If you need more information, you can request additional scopes to access more claims.

info:

A "claim" is an assertion made about a subject; a "scope" is a group of claims. In the current case, a claim is a piece of information about the user.

Here's a non-normative example the scope - claim relationship:

tip:

The "sub" claim means "subject", which is the unique identifier of the user (i.e. user ID).

Logto SDK will always request three scopes: openid, profile, and offline_access.

To request additional scopes, you can configure the params when init the Logto client:

app/logto.ts
import { UserScope, LogtoNextConfig } from '@logto/next';

export const logtoConfig: LogtoNextConfig = {
  scopes: [UserScope.Email, UserScope.Phone], // Add more scopes if needed
  // ...other configs
});

Then you can access the additional claims in the context response:

app/page.tsx
export default async function Home() {
  const { claims: { email } = {}, } = await getLogtoContext(logtoConfig);

  return (
    <div>
      {email && <p>Email: {email}</p>}
    </div>
  );
};

export default Home;

Claims that need network requests

To prevent bloating the ID token, some claims require network requests to fetch. For example, the custom_data claim is not included in the user object even if it's requested in the scopes. To access these claims, you can configure the fetchUserInfo option:

app/page.tsx
export default async function Home() {
const { userInfo } = await getLogtoContext(logtoConfig, { fetchUserInfo: true });
return (
  <div>
    {userInfo && <p>Email: {userInfo.email}</p>}
  </div>
);
};

export default Home;

By configuring fetchUserInfo, the SDK will fetch the user information by requesting to the userinfo endpoint after the user is signed in, and userInfo will be available once the request is completed.

Scopes and claims

Logto uses OIDC scopes and claims conventions to define the scopes and claims for retrieving user information from the ID token and OIDC userinfo endpoint. Both of the "scope" and the "claim" are terms from the OAuth 2.0 and OpenID Connect (OIDC) specifications.

Here's the list of supported scopes and the corresponding claims:

openid

Claim name	Type	Description	Needs userinfo?
sub	`string`	The unique identifier of the user	No

profile

Claim name	Type	Description	Needs userinfo?
name	`string`	The full name of the user	No
username	`string`	The username of the user	No
picture	`string`	URL of the End-User's profile picture. This URL MUST refer to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image. Note that this URL SHOULD specifically reference a profile photo of the End-User suitable for displaying when describing the End-User, rather than an arbitrary photo taken by the End-User.	No
created_at	`number`	Time the End-User was created. The time is represented as the number of milliseconds since the Unix epoch (1970-01-01T00:00:00Z).	No
updated_at	`number`	Time the End-User's information was last updated. The time is represented as the number of milliseconds since the Unix epoch (1970-01-01T00:00:00Z).	No

Other standard claims include family_name, given_name, middle_name, nickname, preferred_username, profile, website, gender, birthdate, zoneinfo, and locale will be also included in the profile scope without the need for requesting the userinfo endpoint. A difference compared to the claims above is that these claims will only be returned when their values are not empty, while the claims above will return null if the values are empty.

note:

Unlike the standard claims, the created_at and updated_at claims are using milliseconds instead of seconds.

email

Claim name	Type	Description	Needs userinfo?
email	`string`	The email address of the user	No
email_verified	`boolean`	Whether the email address has been verified	No

phone

Claim name	Type	Description	Needs userinfo?
phone_number	`string`	The phone number of the user	No
phone_number_verified	`boolean`	Whether the phone number has been verified	No

address

Please refer to the OpenID Connect Core 1.0 for the details of the address claim.

custom_data

Claim name	Type	Description	Needs userinfo?
custom_data	`object`	The custom data of the user	Yes

identities

Claim name	Type	Description	Needs userinfo?
identities	`object`	The linked identities of the user	Yes
sso_identities	`array`	The linked SSO identities of the user	Yes

urn:logto:scope:organizations

Claim name	Type	Description	Needs userinfo?
organizations	`string[]`	The organization IDs the user belongs to	No
organization_data	`object[]`	The organization data the user belongs to	Yes

urn:logto:scope:organization_roles

Claim name	Type	Description	Needs userinfo?
organization_roles	`string[]`	The organization roles the user belongs to with the format of `<organization_id>:<role_name>`	No

Considering performance and the data size, if "Needs userinfo?" is "Yes", it means the claim will not show up in the ID token, but will be returned in the userinfo endpoint response.

API resources

We recommend to read 🔐 Role-Based Access Control (RBAC) first to understand the basic concepts of Logto RBAC and how to set up API resources properly.

Configure Logto client

Once you have set up the API resources, you can add them when configuring Logto in your app:

app/logto.ts
export const logtoConfig = {
  // ...other configs
  resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'], // Add API resources
};

Each API resource has its own permissions (scopes).

For example, the https://shopping.your-app.com/api resource has the shopping:read and shopping:write permissions, and the https://store.your-app.com/api resource has the store:read and store:write permissions.

To request these permissions, you can add them when configuring Logto in your app:

app/logto.ts
export const logtoConfig = {
  // ...other configs
  scopes: ['shopping:read', 'shopping:write', 'store:read', 'store:write'],
  resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
};

You may notice that scopes are defined separately from API resources. This is because Resource Indicators for OAuth 2.0 specifies the final scopes for the request will be the cartesian product of all the scopes at all the target services.

Thus, in the above case, scopes can be simplified from the definition in Logto, both of the API resources can have read and write scopes without the prefix. Then, in the Logto config:

app/logto.ts
export const logtoConfig = {
  // ...other configs
  scopes: ['read', 'write'],
  resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
};

For every API resource, it will request for both read and write scopes.

note:

It is fine to request scopes that are not defined in the API resources. For example, you can request the email scope even if the API resources don't have the email scope available. Unavailable scopes will be safely ignored.

After the successful sign-in, Logto will issue proper scopes to API resources according to the user's roles.

Fetch access token for the API resource

To fetch the access token for a specific API resource, you can use the getAccessToken method:

note:

It is not allowed to define inline "use server" annotated Server Actions in Client Components. We have to pass it down through props from a Server Component.

app/page.ts
import { getAccessToken } from '@logto/next/server-actions';
import { logtoConfig } from './logto';
import GetAccessToken from './get-access-token';

export default async function Home() {
  return (
    <main>
      <GetAccessToken
        onGetAccessToken={async () => {
          'use server';

          return getAccessToken(logtoConfig, 'https://shopping.your-app.com/api');
        }}
      />
    </main>
  );
}

app/get-access-token.ts
'use client';

type Props = {
  onGetAccessToken: () => Promise<string>;
};

const GetAccessToken = ({ onGetAccessToken }: Props) => {
  return (
    <button
      onClick={async () => {
        const token = await onGetAccessToken();
        console.log(token);
      }}
    >
      Get access token (see console log)
    </button>
  );
};

export default GetAccessToken;

This method will return a JWT access token that can be used to access the API resource when the user has related permissions. If the current cached access token has expired, this method will automatically try to use a refresh token to get a new access token.

If you need to fetch an access token in the server component, you can use the getAccessTokenRSC function:

app/page.tsx
import { getAccessTokenRSC } from '@logto/next/server-actions';
import { logtoConfig } from './logto';

export default async function Home() {
  const accessToken = await getAccessTokenRSC(logtoConfig, 'https://shopping.your-app.com/api');

  return (
    <main>
      <p>Access token: {accessToken}</p>
    </main>
  );
}

tip:

HTTP does not allow setting cookies after streaming starts, getAccessTokenRSC cannot update the cookie value, so if the access token is refreshed, it won't be persisted in the session. It is recommended to use getAccessToken function in client side or route handlers.

Fetch organization tokens

If organization is new to you, please read 🏢 Organizations (Multi-tenancy) to get started.

You need to add UserScope.Organizations scope when configuring the Logto client:

app/logto.ts
import { UserScope } from '@logto/next';

export const logtoConfig = {
  // ...other configs
  scopes: [UserScope.Organizations],
};

Once the user is signed in, you can fetch the organization token for the user:

note:

It is not allowed to define inline "use server" annotated Server Actions in Client Components. We have to pass it down through props from a Server Component.

app/page.ts
import { getOrganizationToken } from '@logto/next/server-actions';
import { logtoConfig } from './logto';
import GetOrganizationToken from './get-organization-token';

export default async function Home() {
  return (
    <main>
      <GetOrganizationToken
        onGetOrganizationToken={async () => {
          'use server';

          return getOrganizationToken(logtoConfig, 'organization-id');
        }}
      />
    </main>
  );
}

app/get-organization-token.ts
'use client';

type Props = {
  onGetOrganizationToken: () => Promise<string>;
};

const GetOrganizationToken = ({ onGetOrganizationToken }: Props) => {
  return (
    <button
      onClick={async () => {
        const token = await onGetOrganizationToken();
        console.log(token);
      }}
    >
      Get organization token (see console log)
    </button>
  );
};

export default GetOrganizationToken;

If you need to fetch an organization token in the server component, you can use the getOrganizationTokenRSC function:

app/page.tsx
import { getOrganizationTokenRSC } from '@logto/next/server-actions';
import { logtoConfig } from './logto';

export default async function Home() {
  const token = await getOrganizationTokenRSC(logtoConfig, 'organization-id');

  return (
    <main>
      <p>Organization token: {token}</p>
    </main>
  );
}

tip:

HTTP does not allow setting cookies after streaming starts, getOrganizationTokenRSC cannot update the cookie value, so if the access token is refreshed, it won't be persisted in the session. It is recommended to use getOrganizationToken function in client side or route handlers.

Prerequisites​

Installation​

Integration​

Prepare configs​

Configure redirect URIs​

Regarding redirect-based sign-in​

Configure redirect URIs​

Handle callback​

Implement sign-in and sign-out​

Implement sign-in and sign-out button​

Add buttons to home page​

Checkpoint: Test your application​

Fetch user information​

Display user information​

Get user information in API route handlers​

Request additional claims​

Claims that need network requests​

Scopes and claims​

API resources​

Configure Logto client​

Fetch access token for the API resource​

Fetch organization tokens​

Further readings​

Prerequisites

Installation

Integration

Prepare configs

Configure redirect URIs

Regarding redirect-based sign-in

Configure redirect URIs

Handle callback

Implement sign-in and sign-out

Implement sign-in and sign-out button

Add buttons to home page

Checkpoint: Test your application

Fetch user information

Display user information

Get user information in API route handlers

Request additional claims

Claims that need network requests

Scopes and claims

API resources

Configure Logto client

Fetch access token for the API resource

Fetch organization tokens

Further readings