Next Auth guide

This guide will show you how to integrate Logto into your Next.js application with Next Auth.

tip

• In this guide, we assume you have set up Next Auth in your Next.js project. If you haven't, check out the Next Auth documentation to get started.

Prerequisites

• A Logto Cloud account or a self-hosted Logto (Check out the ⚡ Get started guide to create one if you don't have).
• A Logto traditional application created.
• A Next.js project with Next Auth, check out the Next Auth documentation.

Integration

Config Next Auth provider

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:

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

Regarding redirect-based sign-in

1. This authentication process follows the OpenID Connect (OIDC) protocol, and Logto enforces strict security measures to protect user sign-in.
2. 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 sign-in redirect URI

Let's switch to the Application details page of Logto Console. Add a Redirect URI http://localhost:3000/api/auth/callback/logto and click "Save changes".

Set up Next Auth provider

tip

You can find and copy "App Secret" from application details page in Admin Console:

Modify your API route config of Next Auth, if you are using Pages Router, the file is in pages/api/auth/[...nextauth].js, if you are using App Router, the file is in app/api/auth/[...nextauth]/route.ts.

The following is an example of App Router:

Next Auth v5

import NextAuth from 'next-auth';

export const {
  handlers: { GET, POST },
  signIn,
  signOut,
  auth,
} = NextAuth({
  providers: [
    {
      id: 'logto',
      name: 'Logto',
      type: 'oidc',
      // You can get the issuer value from the Logto Application Details page,
      // in the field "Issuer endpoint"
      issuer: 'https://xxxx.logto.app/oidc',
      clientId: '<logto-app-id>',
      clientSecret: '<logto-app-secret>',
      authorization: {
        params: { scope: 'openid offline_access profile email' },
      },
      profile(profile) {
        // You can customize the user profile mapping here
        return {
          id: profile.sub,
          name: profile.name ?? profile.username,
          email: profile.email,
          image: profile.picture,
        };
      },
    },
  ],
});

1. Replace the issuer URL with your Logto application's "Issuer endpoint".
2. Replace the clientId and clientSecret with your Logto application's ID and secret.
3. Customize the profile function to map the user profile to the Next Auth user object, the default mapping is shown in the example.

Next Auth v4

import NextAuth from 'next-auth';

const handler = NextAuth({
  providers: [
    {
      id: 'logto',
      name: 'Logto',
      type: 'oauth',
      // You can get the well-known URL from the Logto Application Details page,
      // in the field "OpenID Provider configuration endpoint"
      wellKnown: 'https://xxxx.logto.app/oidc/.well-known/openid-configuration',
      authorization: { params: { scope: 'openid offline_access profile email' } },
      clientId: '<logto-app-id>',
      clientSecret: '<logto-app-secret>',
      client: {
        id_token_signed_response_alg: 'ES384',
      },
      profile(profile) {
        // You can customize the user profile mapping here
        return {
          id: profile.sub,
          name: profile.name ?? profile.username,
          email: profile.email,
          image: profile.picture,
        };
      },
    },
  ],
});

export { handler as GET, handler as POST };

1. Replace the wellKnown URL with your Logto application's "OpenID Provider configuration endpoint".
2. Replace the clientId and clientSecret with your Logto application's ID and secret.
3. Customize the profile function to map the user profile to the Next Auth user object, the default mapping is shown in the example.
4. Remember to set the id_token_signed_response_alg to ES384.

Checkpoint

Now, you can test your application to see if the authentication works as expected.

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.

In short, when you request a scope, you will get the corresponding claims in the user information. For example, if you request the `email` scope, you will get the `email` and `email_verified` data of the user.

By default, Logto SDK will always request three scopes: `openid`, `profile`. And `offline_access`, and there is no way to remove these default scopes. But you can add more scopes when configuring Logto:

const handler = NextAuth({
  providers: [
    {
      id: 'logto',
      name: 'Logto',
      // ... other options
      authorization: { params: { scope: 'openid offline_access profile email' } },
      // ... other options
    },
  ],
});

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.

Further readings

• Customize sign-in experience
• Configure connectors
• Protect your API