あなたの Next Auth アプリケーションに認証 (Authentication) を追加する
このガイドでは、Next Auth を使用して Logto を Next.js アプリケーションに統合する方法を紹介します。
- このガイドでは、Next.js プロジェクトに Next Auth を設定していることを前提としています。まだ設定していない場合は、Next Auth ドキュメント を参照して始めてください。
前提条件
- Logto Cloud アカウントまたは セルフホスト Logto。
- 作成された Logto の従来のアプリケーション。
- Next Auth を使用した Next.js プロジェクト。詳細は Next Auth ドキュメント を参照してください。
統合
Next Auth プロバイダーの設定
詳細に入る前に、エンドユーザーの体験について簡単に説明します。サインインプロセスは次のように簡略化できます:
- あなたのアプリがサインインメソッドを呼び出します。
- ユーザーは Logto のサインインページにリダイレクトされます。ネイティブアプリの場合、システムブラウザが開かれます。
- ユーザーがサインインし、あなたのアプリにリダイレクトされます(リダイレクト URI として設定されています)。
リダイレクトベースのサインインについて
- この認証 (Authentication) プロセスは OpenID Connect (OIDC) プロトコルに従い、Logto はユーザーのサインインを保護するために厳格なセキュリティ対策を講じています。
- 複数のアプリがある場合、同じアイデンティティプロバイダー (Logto) を使用できます。ユーザーがあるアプリにサインインすると、Logto は別のアプリにアクセスした際に自動的にサインインプロセスを完了します。
リダイレクトベースのサインインの理論と利点について詳しく知るには、Logto サインイン体験の説明を参照してください。
以下のコードスニペットでは、あなたのアプリが http://localhost:3000/
で実行されていると仮定しています。
サインインリダイレクト URI の設定
Logto コンソールのアプリケーション詳細ページに切り替えましょう。リダイレクト URI http://localhost:3000/api/auth/callback/logto
を追加し、「変更を保存」をクリックします。
Next Auth プロバイダーの設定
「App Secret」は管理コンソールのアプリケーション詳細ページから見つけてコピーできます:
Next Auth の API ルート設定を変更します。Pages Router を使用している場合、ファイルは pages/api/auth/[...nextauth].js
にあります。App Router を使用している場合、ファイルは app/api/auth/[...nextauth]/route.ts
にあります。
以下は App Router の例です:
- Next Auth v5
- Next Auth v4
import NextAuth from 'next-auth';
export const {
handlers: { GET, POST },
signIn,
signOut,
auth,
} = NextAuth({
providers: [
{
id: 'logto',
name: 'Logto',
type: 'oidc',
// Logto アプリケーションの詳細ページから発行者 (Issuer) の値を取得できます。
// フィールド "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) {
// ユーザープロファイルのマッピングをここでカスタマイズできます
return {
id: profile.sub,
name: profile.name ?? profile.username,
email: profile.email,
image: profile.picture,
};
},
},
],
});
issuer
URL を Logto アプリケーションの "Issuer endpoint" に置き換えます。clientId
とclientSecret
を Logto アプリケーションの ID とシークレットに置き換えます。profile
関数をカスタマイズして、ユーザープロファイルを Next Auth ユーザーオブジェクトにマッピングします。デフォルトのマッピングは例に示されています。
import NextAuth from 'next-auth';
const handler = NextAuth({
providers: [
{
id: 'logto',
name: 'Logto',
type: 'oauth',
// Logto アプリケーションの詳細ページから well-known URL を取得できます。
// フィールド "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) {
// ユーザープロファイルのマッピングをここでカスタマイズできます
return {
id: profile.sub,
name: profile.name ?? profile.username,
email: profile.email,
image: profile.picture,
};
},
},
],
});
export { handler as GET, handler as POST };
wellKnown
URL を Logto アプリケーションの "OpenID Provider configuration endpoint" に置き換えます。clientId
とclientSecret
を Logto アプリケーションの ID とシークレットに置き換えます。profile
関数をカスタマイズして、ユーザープロファイルを Next Auth ユーザーオブジェクトにマッピングします。デフォルトのマッピングは例に示されています。id_token_signed_response_alg
をES384
に設定することを忘れないでください。
チェックポイント
これで、アプリケーションをテストして、認証 (Authentication) が期待通りに動作するか確認できます。
スコープとクレーム
Logto は OIDC の スコープとクレームの規約 を使用して、ID トークンおよび OIDC userinfo エンドポイント からユーザー情報を取得するためのスコープとクレームを定義します。「スコープ」と「クレーム」は、OAuth 2.0 および OpenID Connect (OIDC) 仕様からの用語です。
要するに、スコープをリクエストすると、ユーザー情報の対応するクレームを取得できます。例えば、`email` スコープをリクエストすると、ユーザーの `email` と `email_verified` データを取得できます。
デフォルトでは、Logto SDK は常に 3 つのスコープをリクエストします:`openid`、`profile`、および `offline_access` です。 これらのデフォルトスコープを削除する方法はありませんが、Logto を設定する際にさらにスコープを追加することができます:
const handler = NextAuth({
providers: [
{
id: 'logto',
name: 'Logto',
// ... other options
authorization: { params: { scope: 'openid offline_access profile email' } },
// ... other options
},
],
});
サポートされているスコープと対応するクレーム (Claims) のリストはこちらです:
openid
クレーム名 | タイプ | 説明 | ユーザー情報が必要か? |
---|---|---|---|
sub | string | ユーザーの一意の識別子 | いいえ |
profile
クレーム名 | タイプ | 説明 | ユーザー情報が必要か? |
---|---|---|---|
name | string | ユーザーのフルネーム | いいえ |
username | string | ユーザーのユーザー名 | いいえ |
picture | string | エンドユーザーのプロフィール写真の URL。この URL は、画像を含む Web ページではなく、画像ファイル(例えば PNG、JPEG、または GIF 画像ファイル)を指す必要があります。この 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 アイデンティティ | はい |
urn:logto:scope:organizations
クレーム名 | タイプ | 説明 | ユーザー情報が必要か? |
---|---|---|---|
organizations | string[] | ユーザーが所属する組織の ID | いいえ |
organization_data | object[] | ユーザーが所属する組織のデータ | はい |
urn:logto:scope:organization_roles
クレーム名 | タイプ | 説明 | ユーザー情報が必要か? |
---|---|---|---|
organization_roles | string[] | ユーザーが所属する組織のロールで、<organization_id>:<role_name> の形式 | いいえ |
パフォーマンスとデータサイズを考慮して、「ユーザー情報が必要か?」が「はい」の場合、クレームは ID トークンに表示されず、ユーザー情報エンドポイント のレスポンスで返されます。