@auth/core

⚠️

實驗性 @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 Tokens 的情況下，因為它們允許您在沒有資料庫的情況下實作存取控制，並與外部資料庫或 API 整合。

jwt()?

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

每當建立 JSON Web Token（例如在登入時）或更新時（例如每當在客戶端存取工作階段時），就會呼叫此回呼。您在此處回傳的任何內容都會儲存在 JWT 中，並轉送到工作階段回呼。您可以在那裡控制應回傳給客戶端的內容。其他任何內容都會保留在您的前端之外。JWT 預設會透過您的 AUTH_SECRET 環境變數加密。

session 回呼

參數

參數	類型	說明
`params`	`Object`	-
`params.account`?	`null` \| `Account`	包含有關用於登入的提供者資訊。也包含 TokenSet 注意當 `trigger` 為 `"signIn"` 或 `"signUp"` 時可用
`params.isNewUser`?	`boolean`	已棄用改用 `trigger === "signUp"`
`params.profile`?	`Profile`	從您的提供者回傳的 OAuth 設定檔。（在 OIDC 的情況下，它會是已解碼的 ID 權杖或 /userinfo 回應）注意當 `trigger` 為 `"signIn"` 時可用。
`params.session`?	`any`	當使用 AuthConfig.session `strategy: "jwt"` 時，這是資料透過 `useSession().update` 方法從用戶端傳送。 ⚠ 請注意，您應在使用此資料之前進行驗證。
`params.token`	`JWT`	當 `trigger` 為 `"signIn"` 或 `"signUp"` 時，它會是 JWT 的子集， `name`、`email` 和 `image` 將會被包含在內。否則，它將是後續呼叫的完整 JWT。
`params.trigger`?	`"signIn"` \| `"signUp"` \| `"update"`	檢查為何調用 jwt 回呼函式。可能的原因有 - 使用者登入：第一次調用回呼函式時，將會提供 `user`、`profile` 和 `account`。 - 使用者註冊：在資料庫中首次建立使用者（當 AuthConfig.session.strategy 設定為 `"database"` 時）。 - 更新事件：由 `useSession().update` 方法觸發。在後者的情況下，`trigger` 將會是 `undefined`。
`params.user`	`User` \| `AdapterUser`	OAuthConfig.profile 或 CredentialsConfig.authorize 回呼函式的結果。注意當 `trigger` 為 `"signIn"` 或 `"signUp"` 時可用。資源 - 憑證提供者 - 使用者資料庫模型

回傳值

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
  }
}

參數

參數	類型	說明
`params`	`Object`	-
`params.baseUrl`	`字串`	網站的預設基礎 URL（可用作回退）。
`params.url`	`字串`	客戶端作為回呼 URL 提供的 URL。

回傳值

Awaitable<string>

session()？

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

每當檢查會話時，就會呼叫此回呼函式。（例如，當調用 /api/session 端點、使用 useSession 或 getSession 時）。回傳值將會暴露給客戶端，所以請小心您在此處回傳的內容！如果您想讓客戶端可以訪問您透過 JWT 回呼函式新增到令牌的任何內容，您也必須在此處明確地回傳它。

⚠ 預設情況下，為了提高安全性，只會回傳令牌的子集（電子郵件、名稱、圖片）。

只有在使用 jwt 會話策略時，才能使用 token 參數，而只有在使用資料庫會話策略時，才能使用 user 參數。

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
  }
}

參數

參數	類型
`params`	{ `session`: { `user`: `AdapterUser`; } & `AdapterSession`; `user`: `AdapterUser`; } & { `session`: `Session`; `token`: `JWT`; } & { `newSession`: `any`; `trigger`: `"update"`; }

回傳值

Awaitable<Session | DefaultSession>

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")
}

參數

參數	類型	說明
`params`	`Object`	-
`params.account`?	`null` \| `Account`	-
`params.credentials`?	`Record`<`string`, `CredentialInput`>	如果使用憑證提供者，則包含使用者憑證。
`params.email`?	`Object`	如果使用電子郵件提供者，在第一次呼叫時，它會包含 `verificationRequest: true` 屬性，表示它正在驗證請求流程中被觸發。當在使用者點擊登入連結後調用回呼函式時，此屬性將不存在。您可以檢查 `verificationRequest` 屬性以避免將電子郵件發送到黑名單上的地址或網域，或僅顯式地產生它們給允許清單中的電子郵件地址。
`params.email.verificationRequest`?	`boolean`	-
`params.profile`?	`Profile`	如果使用 OAuth 提供者，它包含提供者回傳的完整 OAuth 設定檔。
`params.user`	`User` \| `AdapterUser`	-

回傳值

Awaitable<string | boolean>

cookies？

optional cookies: Partial<CookiesOptions>;

您可以覆寫 Auth.js 使用的任何 Cookie 的預設 Cookie 名稱和選項。您可以指定一個或多個具有自訂屬性的 Cookie，遺失的選項將使用 Auth.js 定義的預設值。如果您使用此功能，您可能需要建立條件行為，以支援在開發和生產版本中設定不同的 Cookie 策略，因為您將選擇退出內建的動態策略。

⚠ **這是一個進階選項。** 進階選項的傳遞方式與基本選項相同，但**可能具有複雜的影響**或副作用。您應該**盡量避免使用進階選項**，除非您非常熟悉如何使用它們。

預設值

{}

debug？

optional debug: boolean;

將 debug 設定為 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>;

參數

參數	類型
`message`	`Object`
`message.user`	`使用者`

回傳值

Awaitable<void>

linkAccount()？

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

參數

參數	類型
`message`	`Object`
`message.account`	`帳號`
`message.profile`	`User` \| `AdapterUser`
`message.user`	`User` \| `AdapterUser`

回傳值

Awaitable<void>

session()？

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

訊息物件將包含以下其中一項，具體取決於您使用的是 JWT 還是資料庫持續性會話

token：此會話的 JWT。
session：來自您适配器的會話物件。

參數

參數	類型
`message`	`Object`
`message.session`	`會話`
`message.token`	`JWT`

回傳值

Awaitable<void>

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

如果使用 credentials 類型驗證，則使用者是來自您憑證提供者的原始回應。對於其他提供者，您將從您的适配器取得 User 物件、帳號，以及使用者是否為您适配器的新使用者的指示。

參數

參數	類型
`message`	`Object`
`message.account`?	`null` \| `Account`
`message.isNewUser`?	`boolean`
`message.profile`?	`Profile`
`message.user`	`使用者`

回傳值

Awaitable<void>

signOut()？

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

訊息物件將包含以下其中一項，具體取決於您使用的是 JWT 還是資料庫持續性會話

token：此會話的 JWT。
session：來自您适配器且正在結束的會話物件。

參數

參數	類型
`message`	{ `session`: `undefined` \| `null` \| `void` \| `AdapterSession`; } \| { `token`: `null` \| `JWT`; }

回傳值

Awaitable<void>

updateUser()?

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

參數

參數	類型
`message`	`Object`
`message.user`	`使用者`

回傳值

Awaitable<void>

實驗性功能？

optional experimental: {
  enableWebAuthn: boolean;
};

使用此選項啟用實驗性功能。啟用後，它將在主控台中印出警告訊息。

注意

實驗性功能不保證穩定，可能會在沒有通知的情況下變更或移除。請謹慎使用。

預設值

{}

啟用 WebAuthn？

optional enableWebAuthn: boolean;

啟用 WebAuthn 支援。

預設值

false

jwt？

optional jwt: Partial<JWTOptions>;

如果您沒有指定 AuthConfig.adapter，預設會啟用 JSON Web Tokens。預設情況下，JSON Web Tokens 是加密的 (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）上使用 OAuth，而您事先不知道最終部署 URL 時，這會很有用。

該 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";

選擇您要如何儲存使用者會話。預設值為 "jwt"，即會話 Cookie 中的加密 JWT (JWE)。

但是，如果您使用 adapter，我們會將其預設為 "database"。您仍然可以透過明確定義 "jwt" 來強制使用 JWT 會話。

使用 "database" 時，會話 Cookie 只會包含 sessionToken 值，用於在資料庫中查詢會話。

文件 | Adapter | 關於 JSON Web Tokens

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 標頭。

基於官方 Auth.js 的程式庫將嘗試針對某些已知安全設定 host 標頭的部署平台（例如：Vercel）自動設定此值。

useSecureCookies？

optional useSecureCookies: boolean;

如果設定為 true，則 NextAuth.js 設定的所有 Cookie 都只能從 HTTPS URL 存取。對於以 http:// 開頭的 URL（例如 https://127.0.0.1:3000），為了方便開發人員，此選項預設為 false。您可以手動將此選項設定為 false 以停用此安全性功能，並允許從不安全的 URL 存取 Cookie（不建議這樣做）。

⚠ **這是一個進階選項。** 進階選項的傳遞方式與基本選項相同，但**可能具有複雜的影響**或副作用。您應該**盡量避免使用進階選項**，除非您非常熟悉如何使用它們。

預設值為 HTTP 的 false 和 HTTPS 網站的 true。

customFetch

const customFetch: typeof customFetch;

🚫

此選項允許您覆寫提供者用於直接向提供者的 OAuth 端點發出請求的預設 fetch 函式。使用不當時，可能會產生安全性影響。

它可用於支援企業 Proxy、自訂 fetch 程式庫、快取探索端點、新增測試用的 Mock、記錄、為不符合規範的提供者設定自訂標頭/參數等。

範例

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 })]
})

參見

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。

參數

參數	類型
`request`	`請求`
`config`	`AuthConfig` & { `raw`: typeof `raw`; }

回傳值

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。

參數

參數	類型
`request`	`請求`
`config`	`Omit`<`AuthConfig`, `"raw"`>

回傳值

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

參數

參數	類型
`action`	`AuthAction`
`protocol`	`字串`
`headers`	`Headers`
`envObject`	`any`
`config`	`Pick`<`AuthConfig`, `"logger"` \| `"basePath"`>

回傳值

URL

isAuthAction()

isAuthAction(action): action is AuthAction

參數

參數	類型
`action`	`字串`

回傳值

action is AuthAction

setEnvDefaults()

setEnvDefaults(
   envObject, 
   config, 
   suppressBasePathWarning): void

在 config 物件上設定預設的環境變數

參數

參數	類型	預設值
`envObject`	`any`	`undefined`
`config`	`AuthConfig`	`undefined`
`suppressBasePathWarning`	`boolean`	`false`

回傳值

void

概觀 adapters

@auth/core

安裝

用法

資源

AuthConfig

範例

參見

擴充自

屬性

adapter?

basePath?

預設值

callbacks?

jwt()?

參數

回傳值

redirect()？

範例

參數

回傳值

session()？

範例

參數

回傳值

signIn()？

範例

參數

回傳值

cookies？

預設值

debug？

預設值

events？

預設值

createUser()？

參數

回傳值

linkAccount()？

參數

回傳值

session()？

參數

回傳值

signIn()？

參數

回傳值

signOut()？

參數

回傳值

updateUser()?

參數

回傳值

實驗性功能？

注意

預設值

啟用 WebAuthn？

預設值

jwt？

logger？

範例

預設值

pages？

預設值

範例

providers

預設值

raw？

redirectProxyUrl？

注意

範例

範例

預設值

secret？

注意

session？

generateSessionToken()？

預設值

回傳值

maxAge？

預設值