@auth/core

これは Auth.js ライブラリのメインエントリポイントです。

Request および Response Web 標準 API に基づいています。主にフレームワーク固有のパッケージを実装するために使用されますが、直接使用することもできます。

インストール

npm install @auth/core

pnpm add @auth/core

yarn add @auth/core

bun add @auth/core

使い方

import { Auth } from "@auth/core"
 
const request = new Request("https://example.com")
const response = await Auth(request, {...})
 
console.log(response instanceof Response) // true

リソース

• はじめに
• ガイド

AuthConfig

Auth メソッドを構成します。

例

import Auth, { type AuthConfig } from "@auth/core"
 
export const authConfig: AuthConfig = {...}
 
const request = new Request("https://example.com")
const response = await AuthHandler(request, authConfig)

参照

初期化

拡張

プロパティ

adapter?

optional adapter: Adapter;

データベースアダプターを渡すには、adapter オプションを使用できます。

basePath?

optional basePath: string;

Auth.js API エンドポイントのベースパス。

デフォルト

"/api/auth" in "next-auth"; "/auth" with all other frameworks

callbacks?

optional callbacks: {
  jwt: (params) => Awaitable<null | JWT>;
  redirect: (params) => Awaitable<string>;
  session: (params) => Awaitable<Session | DefaultSession>;
  signIn: (params) => Awaitable<string | boolean>;
};

コールバックは、アクションが実行されたときに何が起こるかを制御するために使用できる非同期関数です。コールバックは非常に強力で、特に JSON Web トークンを使用するシナリオでは、データベースなしでアクセス制御を実装したり、外部データベースや API と統合したりできます。

jwt()?

optional jwt: (params) => Awaitable<null | JWT>;

このコールバックは、JSON Web トークンが作成されたとき (つまり、サインイン時) または更新されたとき (つまり、クライアントでセッションにアクセスしたとき) に常に呼び出されます。ここで返すものはすべて JWT に保存され、セッションコールバックに転送されます。そこで、クライアントに返すものを制御できます。それ以外のものは、フロントエンドから保持されます。JWT は、デフォルトで AUTH_SECRET 環境変数によって暗号化されます。

session コールバック

パラメーター

戻り値

Awaitable<null | JWT>

redirect()？

optional redirect: (params) => Awaitable<string>;

このコールバックは、ユーザーがコールバック URL にリダイレクトされるたびに（サインインまたはサインアウト時など）呼び出されます。デフォルトでは、オリジンと同じホスト上の URL のみが許可されます。このコールバックを使用して、その動作をカスタマイズできます。

ドキュメント

例

callbacks: {
  async redirect({ url, baseUrl }) {
    // Allows relative callback URLs
    if (url.startsWith("/")) return `${baseUrl}${url}`
 
    // Allows callback URLs on the same origin
    if (new URL(url).origin === baseUrl) return url
 
    return baseUrl
  }
}

パラメーター

戻り値

Awaitable<string>

session()？

optional session: (params) => Awaitable<Session | DefaultSession>;

このコールバックは、セッションがチェックされるたびに（/api/session エンドポイントを呼び出すとき、useSession または getSession を使用するときなど）呼び出されます。戻り値はクライアントに公開されるため、ここで何を返すかには注意してください！JWT コールバックを通じてトークンに追加したものをクライアントで利用できるようにしたい場合は、ここでも明示的に返す必要があります。

トークン引数は、jwt セッションストラテジーを使用している場合にのみ利用可能であり、ユーザー引数はデータベースセッションストラテジーを使用している場合にのみ利用可能です。

jwt コールバック

例

callbacks: {
  async session({ session, token, user }) {
    // Send properties to the client, like an access_token from a provider.
    session.accessToken = token.accessToken
 
    return session
  }
}

パラメーター

戻り値

Awaitable<Session | DefaultSession>

signIn()？

optional signIn: (params) => Awaitable<string | boolean>;

ユーザーがサインインすることを許可するかどうかを制御します。true を返すと、サインインフローが続行されます。false を返すか、エラーをスローすると、サインインフローが停止し、ユーザーはエラーページにリダイレクトされます。文字列を返すと、ユーザーは指定された URL にリダイレクトされます。

未処理のエラーは、元のエラーに設定されたメッセージとともに AccessDenied をスローします。

AccessDenied

例

callbacks: {
 async signIn({ profile }) {
  // Only allow sign in for users with email addresses ending with "yourdomain.com"
  return profile?.email?.endsWith("@yourdomain.com")
}

パラメーター

戻り値

Awaitable<string | boolean>

cookies？

optional cookies: Partial<CookiesOptions>;

Auth.js で使用される任意のクッキーのデフォルトのクッキー名とオプションをオーバーライドできます。カスタムプロパティを持つ 1 つ以上のクッキーを指定でき、不足しているオプションは Auth.js で定義されたデフォルト値を使用します。この機能を使用する場合は、組み込みの動的ポリシーからオプトアウトするため、開発ビルドと本番ビルドで異なるクッキーポリシーを設定するための条件付き動作を作成する必要がある可能性があります。

• ⚠ これは高度なオプションです。高度なオプションは、基本的なオプションと同じように渡されますが、複雑な影響または副作用がある場合があります。それらの使用に非常に慣れていない限り、高度なオプションの使用は避けるべきです。

デフォルト

{}

debug？

optional debug: boolean;

認証およびデータベース操作のデバッグメッセージを有効にするには、デバッグを true に設定します。

• ⚠ カスタム AuthConfig.logger を追加した場合、この設定は無視されます。

デフォルト

false

events？

optional events: {
  createUser: (message) => Awaitable<void>;
  linkAccount: (message) => Awaitable<void>;
  session: (message) => Awaitable<void>;
  signIn: (message) => Awaitable<void>;
  signOut: (message) => Awaitable<void>;
  updateUser: (message) => Awaitable<void>;
};

イベントは応答を返さない非同期関数であり、監査ロギングに役立ちます。これらのイベントのいずれか（デバッグまたは監査ログの作成など）のハンドラーを指定できます。メッセージオブジェクトの内容は、フロー（OAuth またはメール認証フロー、JWT またはデータベースセッションなど）によって異なりますが、通常はユーザーオブジェクトや JSON Web トークンの内容、およびイベントに関連するその他の情報が含まれます。

デフォルト

{}

createUser()？

optional createUser: (message) => Awaitable<void>;

パラメーター

戻り値

Awaitable<void>

linkAccount()？

optional linkAccount: (message) => Awaitable<void>;

パラメーター

戻り値

Awaitable<void>

session()？

optional session: (message) => Awaitable<void>;

メッセージオブジェクトには、JWT またはデータベース永続化セッションを使用しているかどうかに応じて、次のいずれかが含まれます。

• token：このセッションの JWT。
• session：アダプターからのセッションオブジェクト。

パラメーター

戻り値

Awaitable<void>

signIn()？

optional signIn: (message) => Awaitable<void>;

credentials タイプの認証を使用する場合、ユーザーはクレデンシャルプロバイダーからの生のレスポンスです。その他のプロバイダーの場合、アダプターからUserオブジェクト、アカウント、およびユーザーがアダプターに新規登録したかどうかを示すインジケーターを取得します。

パラメータ

戻り値

Awaitable<void>

signOut()?

optional signOut: (message) => Awaitable<void>;

メッセージオブジェクトには、JWT またはデータベース永続化セッションを使用しているかどうかに応じて、次のいずれかが含まれます。

• token：このセッションの JWT。
• session: 終了されるアダプターからのセッションオブジェクト。

パラメータ

戻り値

Awaitable<void>

updateUser()?

optional updateUser: (message) => Awaitable<void>;

パラメータ

戻り値

Awaitable<void>

experimental?

optional experimental: {
  enableWebAuthn: boolean;
};

このオプションを使用して、実験的な機能を有効にします。有効にすると、コンソールに警告メッセージが出力されます。

注

実験的な機能は安定しているとは限らず、予告なしに変更または削除される可能性があります。慎重に使用してください。

デフォルト

{}

enableWebAuthn?

optional enableWebAuthn: boolean;

WebAuthnのサポートを有効にします。

デフォルト

false

jwt?

optional jwt: Partial<JWTOptions>;

AuthConfig.adapterを指定していない場合、JSON Web Tokenはデフォルトで有効になります。JSON Web Tokenはデフォルトで暗号化（JWE）されます。この動作を維持することをお勧めします。

logger?

optional logger: Partial<LoggerInstance>;

ロガーレベルをオーバーライドし（undefinedレベルは組み込みロガーを使用します）、NextAuthのログをインターセプトします。このオプションを使用して、NextAuthのログをサードパーティのロギングサービスに送信できます。

例

// /auth.ts
import log from "logging-service"
 
export const { handlers, auth, signIn, signOut } = NextAuth({
  logger: {
    error(code, ...message) {
      log.error(code, message)
    },
    warn(code, ...message) {
      log.warn(code, message)
    },
    debug(code, ...message) {
      log.debug(code, message)
    }
  }
})

• ⚠ 設定すると、AuthConfig.debug オプションは無視されます

デフォルト

console

pages?

optional pages: Partial<PagesOptions>;

カスタムのサインイン、サインアウト、およびエラーページを作成する場合は、使用するURLを指定します。指定されたページは、対応する組み込みページをオーバーライドします。

デフォルト

{}

例

  pages: {
    signIn: '/auth/signin',
    signOut: '/auth/signout',
    error: '/auth/error',
    verifyRequest: '/auth/verify-request',
    newUser: '/auth/new-user'
  }

providers

providers: Provider[];

サインイン用の認証プロバイダーのリスト（例：Google、Facebook、Twitter、GitHub、Emailなど）を任意の順序で指定します。これは、組み込みのプロバイダーまたはカスタムプロバイダーのオブジェクトのいずれかになります。

デフォルト

[]

raw?

optional raw: typeof raw;

redirectProxyUrl?

optional redirectProxyUrl: string;

設定した場合、OAuthサインインフロー中に、認証リクエストのredirect_uriはこの値に基づいて設定されます。

これは、OAuthプロバイダーが単一のredirect_uriのみをサポートする場合、または、最終的なデプロイURLを事前に把握できない（Vercelのような）プレビューURLでOAuthを使用する場合に便利です。

URLには、Auth.jsが初期化される場所までのフルパスを含める必要があります。

注

これにより、プロバイダーのstate OAuth2Config.checksが自動的に有効になります。

例

"https://authjs.example.com/api/auth"

また、各プロバイダーに対して個別にこれをオーバーライドすることもできます。

例

GitHub({
  ...
  redirectProxyUrl: "https://github.example.com/api/auth"
})

デフォルト

AUTH_REDIRECT_PROXY_URL 環境変数

参照：ガイド：プレビューデプロイメントの保護

secret?

optional secret: string | string[];

トークンのハッシュ、Cookieの署名、および暗号化キーの生成に使用されるランダムな文字列。

ランダムな文字列を生成するには、Auth.js CLIを使用できます：npx auth secret

注

また、秘密の配列を渡すこともできます。その場合、JWTを正常に復号化した最初の秘密が使用されます。これは、既存のセッションを無効にすることなく秘密をローテーションする場合に便利です。新しい秘密は配列の先頭に追加する必要があり、すべての新しいセッションで使用されます。

session?

optional session: {
  generateSessionToken: () => string;
  maxAge: number;
  strategy: "jwt" | "database";
  updateAge: number;
};

JWTを使用するかデータベースを使用するか、アイドル状態のセッションが期限切れになるまでの時間、またはデータベースを使用している場合に書き込み操作を調整するかなど、セッションを構成します。

generateSessionToken()?

optional generateSessionToken: () => string;

データベースベースのセッション用にカスタムセッショントークンを生成します。デフォルトでは、Node.jsのバージョンに応じて、ランダムなUUIDまたは文字列が生成されます。ただし、使用する独自のカスタム文字列（CUIDなど）を指定できます。

デフォルト

Node.jsのバージョンに応じてrandomUUIDまたはrandomBytes.toHex

戻り値

文字列

maxAge?

optional maxAge: number;

セッションが期限切れになるまでの、現在からの相対時間（秒単位）。

デフォルト

2592000 // 30 days

strategy?

optional strategy: "jwt" | "database";

ユーザーセッションを保存する方法を選択します。デフォルトは、セッションCookie内の暗号化されたJWT（JWE）である"jwt"です。

ただし、adapterを使用する場合は、代わりにデフォルトで"database"になります。"jwt"を明示的に定義することで、JWTセッションを強制的に使用することもできます。

"database"を使用する場合、セッションCookieにはsessionToken値のみが含まれ、これはデータベースでセッションを検索するために使用されます。

ドキュメント | アダプター | JSON Web Tokenについて

updateAge?

optional updateAge: number;

セッションを更新する頻度（秒単位）。0に設定すると、セッションは毎回更新されます。

デフォルト

86400 // 1 day

skipCSRFCheck?

optional skipCSRFCheck: typeof skipCSRFCheck;

theme?

optional theme: Theme;

組み込みのAuthConfig.pagesのテーマを変更します。

trustHost?

optional trustHost: boolean;

Auth.jsは、正しく機能するために、受信リクエストのhostヘッダーに依存しています。このため、このプロパティをtrueに設定する必要があります。

デプロイプラットフォームがhostヘッダーを安全に設定していることを確認してください。

useSecureCookies?

optional useSecureCookies: boolean;

trueに設定すると、NextAuth.jsによって設定されたすべてのCookieは、HTTPS URLからのみアクセス可能になります。このオプションは、開発者の利便性を考慮して、http://で始まるURL（例：http://localhost:3000）ではデフォルトでfalseになります。このセキュリティ機能を無効にし、保護されていないURLからCookieにアクセスできるようにするために、このオプションを手動でfalseに設定できます（これは推奨されません）。

• ⚠ これは高度なオプションです。高度なオプションは、基本的なオプションと同じように渡されますが、複雑な影響または副作用がある場合があります。それらの使用に非常に慣れていない限り、高度なオプションの使用は避けるべきです。

デフォルトは、HTTPではfalse、HTTPSサイトではtrueです。

customFetch

const customFetch: typeof customFetch;

企業のプロキシ、カスタムのフェッチライブラリ、キャッシュ検出エンドポイントのサポート、テスト用のモックの追加、ログ記録、非準拠プロバイダーのカスタムヘッダー/パラメーターの設定などに使用できます。

例

import { Auth, customFetch } from "@auth/core"
import GitHub from "@auth/core/providers/github"
 
const dispatcher = new ProxyAgent("my.proxy.server")
function proxy(...args: Parameters<typeof fetch>): ReturnType<typeof fetch> {
  return undici(args[0], { ...(args[1] ?? {}), dispatcher })
}
 
const response = await Auth(request, {
  providers: [GitHub({ [customFetch]: proxy })]
})

参照

• https://undici.nodejs.org/#/docs/api/ProxyAgent?id=example-basic-proxy-request-with-local-agent-dispatcher
• https://authjs.dokyumento.jp/guides/corporate-proxy

raw

const raw: typeof raw;

Auth.jsはデフォルトでWeb標準のResponseを返しますが、フレームワークを実装している場合、この値をAuthConfig.rawに渡すことで、生の内部レスポンスにアクセスしたい場合があります。

skipCSRFCheck

const skipCSRFCheck: typeof skipCSRFCheck;

Auth.jsにはCSRF保護機能が組み込まれていますが、CSRF攻撃からすでに保護されているフレームワークを実装している場合、この値をAuthConfig.skipCSRFCheckに渡すことで、このチェックをスキップできます。

Auth()

Auth(request, config)

Auth(request, config): Promise<ResponseInternal>

Auth.jsによって提供されるコア機能。

標準のRequestを受け取り、Responseを返します。

パラメータ

戻り値

Promise<ResponseInternal>

例

import { Auth } from "@auth/core"
 
const request = new Request("https://example.com")
const response = await Auth(request, {
  providers: [Google],
  secret: "...",
  trustHost: true,
})

参照

ドキュメント

Auth(request, config)

Auth(request, config): Promise<Response>

Auth.jsによって提供されるコア機能。

標準のRequestを受け取り、Responseを返します。

パラメータ

戻り値

Promise<Response>

例

import { Auth } from "@auth/core"
 
const request = new Request("https://example.com")
const response = await Auth(request, {
  providers: [Google],
  secret: "...",
  trustHost: true,
})

参照

ドキュメント

createActionURL()

createActionURL(
   action, 
   protocol, 
   headers, 
   envObject, 
   config): URL

パラメータ

戻り値

URL

isAuthAction()

isAuthAction(action): action is AuthAction

パラメータ

戻り値

action is AuthAction

setEnvDefaults()

setEnvDefaults(
   envObject, 
   config, 
   suppressBasePathWarning): void

configオブジェクトにデフォルトの環境変数を設定します。

パラメータ

戻り値

void