あなたの Next.js (Pages Router) アプリケーションに認証 (Authentication) を追加する
- サンプルプロジェクトは、私たちの SDK リポジトリ で利用可能です。
 - この例は、Next.js の Pages Router に基づいています。
 
前提条件
- Logto Cloud アカウントまたは セルフホスト Logto。
 - 作成された Logto の従来のアプリケーション。
 
インストール
お好みのパッケージマネージャーを使用して Logto SDK をインストールします:
- npm
 - pnpm
 - yarn
 
npm i @logto/nextpnpm add @logto/nextyarn add @logto/next統合
LogtoClient を初期化する
LogtoClient をインポートして初期化します:
import LogtoClient from '@logto/next';
export const logtoClient = new LogtoClient({
  appId: '<your-application-id>',
  appSecret: '<your-app-secret-copied-from-console>',
  endpoint: '<your-logto-endpoint>', // 例: http://localhost:3001
  baseUrl: 'http://localhost:3000',
  cookieSecret: 'complex_password_at_least_32_characters_long',
  cookieSecure: process.env.NODE_ENV === 'production',
});
リダイレクト URI を設定する
詳細に入る前に、エンドユーザー体験の概要を簡単にご紹介します。サインインプロセスは次のようにシンプルにまとめられます:
- アプリがサインインメソッドを呼び出します。
 - ユーザーは Logto のサインインページにリダイレクトされます。ネイティブアプリの場合は、システムブラウザが開かれます。
 - ユーザーがサインインし、アプリ(リダイレクト URI として設定)に戻されます。
 
リダイレクトベースのサインインについて
- この認証 (Authentication) プロセスは OpenID Connect (OIDC) プロトコルに従い、Logto はユーザーのサインインを保護するために厳格なセキュリティ対策を講じています。
 - 複数のアプリがある場合、同じアイデンティティプロバイダー (Logto) を使用できます。ユーザーがあるアプリにサインインすると、Logto は別のアプリにアクセスした際に自動的にサインインプロセスを完了します。
 
リダイレクトベースのサインインの理論と利点について詳しく知るには、Logto サインイン体験の説明を参照してください。
以下のコードスニペットでは、あなたのアプリが http://localhost:3000/ で実行されていると仮定しています。
リダイレクト URI を設定する
Logto Console のアプリケーション詳細ページに移動します。リダイレクト URI http://localhost:3000/api/logto/sign-in-callback を追加します。
サインインと同様に、ユーザーは共有セッションからサインアウトするために Logto にリダイレクトされるべきです。完了したら、ユーザーをあなたのウェブサイトに戻すと良いでしょう。例えば、http://localhost:3000/ をサインアウト後のリダイレクト URI セクションとして追加します。
その後、「保存」をクリックして変更を保存します。
API ルートを準備する
Logto と接続するための API ルート を準備します。
IDE / エディタに戻り、まず次のコードを使用して API ルートを実装します:
import { logtoClient } from '../../../libraries/logto';
export default logtoClient.handleAuthRoutes();
これにより、4 つのルートが自動的に作成されます:
/api/logto/sign-in: Logto でサインインします。/api/logto/sign-in-callback: サインインコールバックを処理します。/api/logto/sign-out: Logto でサインアウトします。/api/logto/user: ユーザーが Logto で認証されているかどうかを確認し、認証されている場合はユーザー情報を返します。
サインインとサインアウトを実装する
API ルートを準備しましたので、次にホームページにサインインとサインアウトボタンを実装しましょう。必要に応じて、ユーザーをサインインまたはサインアウトルートにリダイレクトする必要があります。これを支援するために、useSWR を使用して /api/logto/user から認証 (Authentication) ステータスを取得します。
useSWR について詳しくは このガイド をご覧ください。
import { type LogtoContext } from '@logto/next';
import useSWR from 'swr';
const Home = () => {
  const { data } = useSWR<LogtoContext>('/api/logto/user');
  return (
    <nav>
      {data?.isAuthenticated ? (
        <p>
          こんにちは、{data.claims?.sub} さん、
          <button
            onClick={() => {
              window.location.assign('/api/logto/sign-out');
            }}
          >
            サインアウト
          </button>
        </p>
      ) : (
        <p>
          <button
            onClick={() => {
              window.location.assign('/api/logto/sign-in');
            }}
          >
            サインイン
          </button>
        </p>
      )}
    </nav>
  );
};
export default Home;
チェックポイント: アプリケーションをテストする
これで、アプリケーションをテストできます:
- アプリケーションを実行すると、サインインボタンが表示されます。
 - サインインボタンをクリックすると、SDK がサインインプロセスを初期化し、Logto のサインインページにリダイレクトされます。
 - サインインすると、アプリケーションに戻り、サインアウトボタンが表示されます。
 - サインアウトボタンをクリックして、トークンストレージをクリアし、サインアウトします。
 
ユーザー情報を取得する
ユーザー情報を表示する
ユーザーがサインインしている場合、ユーザー情報を取得する方法は 3 つあります。
フロントエンドでの API リクエストを通じて
import { type LogtoContext } from '@logto/next';
import { useMemo } from 'react';
import useSWR from 'swr';
const Home = () => {
  const { data } = useSWR<LogtoContext>('/api/logto/user');
  const claims = useMemo(() => {
    if (!data?.isAuthenticated || !data.claims) {
      return null;
    }
    return (
      <div>
        <h2>クレーム (Claims):</h2>
        <table>
          <thead>
            <tr>
              <th>名前</th>
              <th>値</th>
            </tr>
          </thead>
          <tbody>
            {Object.entries(data.claims).map(([key, value]) => (
              <tr key={key}>
                <td>{key}</td>
                <td>{String(value)}</td>
              </tr>
            ))}
          </tbody>
        </table>
      </div>
    );
  }, [data]);
  return (
    <div>
      {claims}
    </div>
  );
};
export default Home;
getServerSideProps を通じて
import { LogtoContext } from '@logto/next';
import { logtoClient } from '../../libraries/logto';
type Props = {
  user: LogtoContext;
};
const Home = ({ user }: Props) => {
  const claims = useMemo(() => {
    if (!user.isAuthenticated || !user.claims) {
      return null;
    }
    return (
      <div>
        <h2>クレーム (Claims):</h2>
        <table>
          <thead>
            <tr>
              <th>名前</th>
              <th>値</th>
            </tr>
          </thead>
          <tbody>
            {Object.entries(user.claims).map(([key, value]) => (
              <tr key={key}>
                <td>{key}</td>
                <td>{String(value)}</td>
              </tr>
            ))}
          </tbody>
        </table>
      </div>
    );
  }, [user]);
  return (
    <div>
      {claims}
    </div>
  );
};
export default Home;
export const getServerSideProps = logtoClient.withLogtoSsr(async function ({ request }) {
  const { user } = request;
  return {
    props: { user },
  };
});
API ルートで
import { logtoClient } from '../../libraries/logto';
export default logtoClient.withLogtoApiRoute((request, response) => {
  if (!request.user.isAuthenticated) {
    response.status(401).json({ message: 'Unauthorized' });
    return;
  }
  response.json({
    data: request.user.claims,
  });
});
追加のクレーム (Claims) をリクエストする
/api/logto/user から返されるオブジェクトに一部のユーザー情報が欠けていることがあります。これは、OAuth
2.0 と OpenID Connect (OIDC) が最小特権の原則 (PoLP) に従うように設計されており、Logto
はこれらの標準に基づいて構築されているためです。
デフォルトでは、限られたクレーム (Claims) が返されます。より多くの情報が必要な場合は、追加のスコープ (Scopes) をリクエストして、より多くのクレーム (Claims) にアクセスできます。
「クレーム (Claim)」はサブジェクトについての主張であり、「スコープ (Scope)」はクレーム (Claims) のグループです。現在のケースでは、クレーム (Claim) はユーザーに関する情報の一部です。
スコープ (Scope) とクレーム (Claim) の関係の非規範的な例を示します:
「sub」クレーム (Claim) は「サブジェクト (Subject)」を意味し、ユーザーの一意の識別子(つまり、ユーザー ID)です。
Logto SDK は常に 3 つのスコープ (Scopes) をリクエストします:openid、profile、および offline_access。
追加のスコープをリクエストするには、Logto クライアントを初期化する際にパラメータを設定できます:
import LogtoClient, { UserScope } from '@logto/next';
export const logtoClient = new LogtoClient({
  scopes: [UserScope.Email, UserScope.Phone], // 必要に応じてスコープを追加
  // ...他の設定
});
その後、コンテキストレスポンスで追加のクレーム (Claims) にアクセスできます:
const Home = () => {
  const { data } = useSWR<LogtoContext>('/api/logto/user');
  const email = data?.claims?.email;
  return (
    <div>
      {email && <p>Email: {email}</p>}
    </div>
  );
};
export default Home;
ネットワークリクエストが必要なクレーム (Claims)
ID トークンの肥大化を防ぐために、一部のクレーム (Claims) は取得するためにネットワークリクエストが必要です。例えば、custom_data クレームはスコープで要求されてもユーザーオブジェクトに含まれません。これらのクレームにアクセスするには、 fetchUserInfo オプションを設定できます:
import { logtoClient } from '../../../libraries/logto';
export default logtoClient.handleAuthRoutes({ fetchUserInfo: true });
fetchUserInfo を設定することで、SDK はユーザーがサインインした後に userinfo エンドポイント にリクエストを送信してユーザー情報を取得し、リクエストが完了すると req.user.userInfo が利用可能になります。
ユーザー情報を手動で取得する
API ルートでユーザー情報を手動で取得できます:
import { logtoClient } from '../../libraries/logto';
export default logtoClient.withLogtoApiRoute(
  (request, response) => {
    if (!request.user.isAuthenticated) {
      response.status(401).json({ message: 'Unauthorized' });
      return;
    }
    response.json({
      userInfo: request.user.userInfo,
    });
  },
  { fetchUserInfo: true }
);
スコープとクレーム (Claims)
Logto は OIDC の スコープとクレームの規約 を使用して、ID トークンおよび OIDC userinfo エンドポイント からユーザー情報を取得するためのスコープとクレームを定義します。「スコープ」と「クレーム」は、OAuth 2.0 および OpenID Connect (OIDC) 仕様からの用語です。
サポートされているスコープと対応するクレームのリストはこちらです:
openid
| クレーム名 | タイプ | 説明 | ユーザー情報が必要か? | 
|---|---|---|---|
| sub | string | ユーザーの一意の識別子 | いいえ | 
profile
| クレーム名 | タイプ | 説明 | ユーザー情報が必要か? | 
|---|---|---|---|
| name | string | ユーザーのフルネーム | いいえ | 
| username | string | ユーザーのユーザー名 | いいえ | 
| picture | string | エンドユーザーのプロフィール画像の URL。この URL は画像ファイル(例:PNG、JPEG、または GIF 画像ファイル)を参照する必要があります。画像を含む Web ページを参照してはいけません。この URL は、エンドユーザーを説明する際に表示するのに適したプロフィール写真を特に参照するべきであり、エンドユーザーが撮影した任意の写真を参照するべきではありません。 | いいえ | 
| created_at | number | エンドユーザーが作成された時間。時間は Unix エポック(1970-01-01T00:00:00Z)からのミリ秒数で表されます。 | いいえ | 
| updated_at | number | エンドユーザーの情報が最後に更新された時間。時間は Unix エポック(1970-01-01T00:00:00Z)からのミリ秒数で表されます。 | いいえ | 
その他の 標準クレーム には、family_name、given_name、middle_name、nickname、preferred_username、profile、website、gender、birthdate、zoneinfo、および locale が含まれ、ユーザー情報エンドポイントを要求することなく profile スコープに含まれます。上記のクレームと比較しての違いは、これらのクレームは値が空でない場合にのみ返されることであり、上記のクレームは値が空の場合に null を返します。
標準クレームとは異なり、created_at と updated_at クレームは秒ではなくミリ秒を使用しています。
email
| クレーム名 | タイプ | 説明 | ユーザー情報が必要か? | 
|---|---|---|---|
string | ユーザーのメールアドレス | いいえ | |
| email_verified | boolean | メールアドレスが確認済みかどうか | いいえ | 
phone
| クレーム名 | タイプ | 説明 | ユーザー情報が必要か? | 
|---|---|---|---|
| phone_number | string | ユーザーの電話番号 | いいえ | 
| phone_number_verified | boolean | 電話番号が確認済みかどうか | いいえ | 
address
住所クレームの詳細については、OpenID Connect Core 1.0 を参照してください。
custom_data
| クレーム名 | タイプ | 説明 | ユーザー情報が必要か? | 
|---|---|---|---|
| custom_data | object | ユーザーのカスタムデータ | はい | 
identities
| クレーム名 | タイプ | 説明 | ユーザー情報が必要か? | 
|---|---|---|---|
| identities | object | ユーザーのリンクされたアイデンティティ | はい | 
| sso_identities | array | ユーザーのリンクされた SSO アイデンティティ | はい | 
roles
| クレーム名 | タイプ | 説明 | ユーザー情報が必要か? | 
|---|---|---|---|
| roles | string[] | ユーザーのロール | いいえ | 
urn:logto:scope:organizations
| クレーム名 | タイプ | 説明 | ユーザー情報が必要か? | 
|---|---|---|---|
| organizations | string[] | ユーザーが所属する組織の ID | いいえ | 
| organization_data | object[] | ユーザーが所属する組織のデータ | はい | 
urn:logto:scope:organization_roles
| クレーム名 | タイプ | 説明 | ユーザー情報が必要か? | 
|---|---|---|---|
| organization_roles | string[] | ユーザーが所属する組織のロール(<organization_id>:<role_name> の形式) | いいえ | 
パフォーマンスとデータサイズを考慮して、「ユーザー情報が必要か?」が「はい」の場合、クレームは ID トークンには表示されず、ユーザー情報エンドポイント のレスポンスで返されます。
API リソース
まず 🔐 ロールベースのアクセス制御 (RBAC) を読むことをお勧めします。これにより、Logto の RBAC の基本概念と API リソースを適切に設定する方法を理解できます。
Logto クライアントを設定する
API リソースを設定したら、アプリで Logto を設定する際にそれらを追加できます:
export const logtoClient = new LogtoClient({
  // ...other configs
  resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'], // API リソースを追加
});
各 API リソースには独自の権限 (スコープ) があります。
例えば、https://shopping.your-app.com/api リソースには shopping:read と shopping:write の権限があり、https://store.your-app.com/api リソースには store:read と store:write の権限があります。
これらの権限を要求するには、アプリで Logto を設定する際にそれらを追加できます:
export const logtoClient = new LogtoClient({
  // ...other configs
  scopes: ['shopping:read', 'shopping:write', 'store:read', 'store:write'],
  resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
});
スコープが API リソースとは別に定義されていることに気付くかもしれません。これは、OAuth 2.0 のリソースインジケーター が、リクエストの最終的なスコープはすべてのターゲットサービスでのすべてのスコープの直積になると指定しているためです。
したがって、上記のケースでは、Logto での定義からスコープを簡略化できます。両方の API リソースは、プレフィックスなしで read と write スコープを持つことができます。その後、Logto の設定では:
export const logtoClient = new LogtoClient({
  // ...other configs
  scopes: ['read', 'write'],
  resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
});
各 API リソースは、read と write の両方のスコープを要求します。
API リソースで定義されていないスコープを要求しても問題ありません。例えば、API リソースに email スコープが利用できなくても、email スコープを要求できます。利用できないスコープは安全に無視されます。
サインインが成功すると、Logto はユーザーのロールに応じて適切なスコープを API リソースに発行します。
API リソースのアクセス トークンを取得する
特定の API リソースのアクセス トークンを取得するには、getAccessToken メソッドを使用できます:
import { logtoClient } from '../../../libraries/logto';
export default logtoClient.withLogtoApiRoute(
  (request, response) => {
    if (!request.user.isAuthenticated) {
      response.status(401).json({ message: 'Unauthorized' });
      return;
    }
    // ここでアクセス トークンを取得
    console.log(request.user.accessToken);
    response.json(request.user);
  },
  {
    getAccessToken: true,
    resource: 'https://shopping.your-app.com/api',
  }
);
このメソッドは、ユーザーが関連する権限を持っている場合に API リソースにアクセスするために使用できる JWT アクセス トークンを返します。現在キャッシュされているアクセス トークンが期限切れの場合、このメソッドは自動的にリフレッシュ トークンを使用して新しいアクセス トークンを取得しようとします。
組織トークンを取得する
組織 (Organization) が初めての場合は、🏢 組織 (マルチテナンシー) を読んで始めてください。
Logto クライアントを設定する際に、UserScope.Organizations スコープを追加する必要があります:
import { UserScope } from '@logto/next';
export const logtoClient = new LogtoClient({
  // ...other configs
  scopes: [UserScope.Organizations],
});
ユーザーがサインインしたら、ユーザーのための組織トークンを取得できます:
import { logtoClient } from '../../../libraries/logto';
export default logtoClient.withLogtoApiRoute(async (request, response) => {
  if (!request.user.isAuthenticated) {
    response.status(401).json({ message: 'Unauthorized' });
    return;
  }
  const client = await logtoClient.createNodeClientFromNextApi(request, response);
  // 組織 (Organization) ID はユーザーの ID トークンのクレームに保存されています
  const { organizations = [] } = await client.getIdTokenClaims();
  const organizationTokens = await Promise.all(
    organizations.map(async (organizationId) => client.getOrganizationToken(organizationId))
  );
  const organizationClaims = await Promise.all(
    organizations.map(async (organizationId) => client.getOrganizationTokenClaims(organizationId))
  );
  // 組織トークンおよび / またはクレームを使用して処理を行う
  response.json({
    organizations,
  });
});
エッジランタイム
@logto/[email protected] に追加
エッジランタイム API ルートを使用したい場合は、サブパッケージ @logto/next/edge を使用する必要があります。
import LogtoClient from '@logto/next/edge';
export const logtoClient = new LogtoClient({
  appId: '<your-application-id>',
  appSecret: '<your-app-secret-copied-from-console>',
  endpoint: '<your-logto-endpoint>', // 例: http://localhost:3001
  baseUrl: '<your-nextjs-app-base-url>', // 例: http://localhost:3000
  cookieSecret: 'complex_password_at_least_32_characters_long',
  cookieSecure: process.env.NODE_ENV === 'production',
  resources: ['<your-api-resource>'],
});
その後、API ルートでランタイムを experimental-edge または edge に設定します。
import { logtoClient } from '../../../../libraries/logto';
export default logtoClient.handleSignIn();
export const config = {
  runtime: 'experimental-edge',
};
完全な例を見るには、next-sample を確認してください。
外部セッションストレージを使用する
SDK はデフォルトでクッキーを使用して暗号化されたセッションデータを保存します。このアプローチは安全で、追加のインフラストラクチャを必要とせず、特に Vercel のようなサーバーレス環境でうまく機能します。
しかし、セッションデータを外部に保存する必要がある場合もあります。たとえば、セッションデータがクッキーに収まりきらないほど大きくなった場合や、複数のアクティブな組織セッションを同時に維持する必要がある場合です。このような場合、sessionWrapper オプションを使用して外部セッションストレージを実装できます:
import { MemorySessionWrapper } from './storage';
export const config = {
  // ...
  sessionWrapper: new MemorySessionWrapper(),
};
import { randomUUID } from 'node:crypto';
import { type SessionWrapper, type SessionData } from '@logto/next';
export class MemorySessionWrapper implements SessionWrapper {
  private readonly storage = new Map<string, unknown>();
  async wrap(data: unknown, _key: string): Promise<string> {
    const sessionId = randomUUID();
    this.storage.set(sessionId, data);
    return sessionId;
  }
  async unwrap(value: string, _key: string): Promise<SessionData> {
    if (!value) {
      return {};
    }
    const data = this.storage.get(value);
    return data ?? {};
  }
}
上記の実装は、シンプルなインメモリストレージを使用しています。本番環境では、Redis やデータベースなど、より永続的なストレージソリューションを使用することをお勧めします。