Sendgrid 提供商

概述

Sendgrid 提供商使用电子邮件发送“魔法链接”，其中包含带有验证令牌的 URL，可用于登录。

除了一个或多个 OAuth 服务之外，添加对通过电子邮件登录的支持，为用户提供了一种在失去 OAuth 帐户访问权限（例如，帐户被锁定或删除）时登录的方法。

Sendgrid 提供商可以与一个或多个 OAuth 提供商一起使用（或代替它们）。

工作原理

在首次登录时，将向提供的电子邮件地址发送一个**验证令牌**。默认情况下，此令牌有效期为 24 小时。如果验证令牌在此时间范围内使用（即，通过单击电子邮件中的链接），将为用户创建帐户，并将其登录。

如果有人在登录时提供了一个现有帐户的电子邮件地址，系统会发送一封电子邮件，并在他们点击电子邮件中的链接并使用验证令牌后，将其登录到与该电子邮件地址关联的帐户。

⚠️

Sendgrid 提供商可以与 JSON Web Token 和数据库管理的会话一起使用，但**必须配置数据库**才能使用它。没有使用数据库，就不可能启用电子邮件登录。

配置

首先，您需要将您的域名添加到 Sendgrid 帐户中。这是 Sendgrid 所要求的，也是您在 from 提供商选项中使用的地址的域名。
接下来，您必须在Sendgrid 仪表板中生成一个 API 密钥。您可以将此 API 密钥保存为 AUTH_SENDGRID_KEY 环境变量。

AUTH_SENDGRID_KEY=abc

如果您将环境变量命名为 AUTH_SENDGRID_KEY，提供商会自动获取它，您的 Auth.js 配置对象可以更简单。但是，如果您想将其重命名为其他名称，则必须手动将其传递到 Auth.js 配置中的提供商中。

./auth.ts

import NextAuth from "next-auth"
import Sendgrid from "next-auth/providers/sendgrid"
 
export const { handlers, auth, signIn, signOut } = NextAuth({
  adapter: ...,
  providers: [
    Sendgrid({
      // If your environment variable is named differently than default
      apiKey: COMPANY_AUTH_SENDGRID_API_KEY,
      from: "[email protected]"
    }),
  ],
})

/src/routes/[email protected]

import { QwikAuth$ } from "@auth/qwik"
import Sendgrid from "@auth/qwik/providers/sendgrid"
 
export const { onRequest, useSession, useSignIn, useSignOut } = QwikAuth$(
  () => ({
    providers: [
      Sendgrid({
        // If your environment variable is named differently than default
        apiKey: import.meta.env.COMPANY_AUTH_SENDGRID_API_KEY,
        from: "[email protected]",
      }),
    ],
  })
)

./src/auth.ts

import { SvelteKitAuth } from "@auth/sveltekit"
import Sendgrid from "@auth/sveltekit/providers/sendgrid"
import { env } from "$env/dynamic/prviate"
 
export const { handle, signIn, signOut } = SvelteKitAuth({
  adapter: ...,
  providers: [
    Sendgrid({
      // If your environment variable is named differently than default
      apiKey: env.COMPANY_AUTH_SENDGRID_API_KEY,
      from: "[email protected]",
    }),
  ],
})

不要忘记设置一个数据库适配器，用于存储电子邮件验证令牌。
您现在可以使用电子邮件地址在 /api/auth/signin 开始登录过程。

在用户第一次验证其电子邮件地址之前，不会为用户创建用户帐户（即 Users 表中的条目）。如果电子邮件地址已与帐户关联，则当用户点击魔法链接电子邮件中的链接并使用验证令牌时，会将其登录到该帐户。

自定义

电子邮件正文

您可以通过将自定义函数作为 sendVerificationRequest 选项传递到 Sendgrid() 来完全自定义发送的登录电子邮件。

./auth.ts

import NextAuth from "next-auth"
import Sendgrid from "next-auth/providers/sendgrid"
 
export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [
    Sendgrid({
      server: process.env.EMAIL_SERVER,
      from: process.env.EMAIL_FROM,
      sendVerificationRequest({
        identifier: email,
        url,
        provider: { server, from },
      }) {
        // your function
      },
    }),
  ],
})

例如，以下显示了我们内置 sendVerificationRequest() 方法的源代码。请注意，我们在这里在这个方法中渲染了 HTML (html()) 并对 Sendgrid 发起了网络调用 (fetch()) 来实际执行发送。

./lib/authSendRequest.ts

export async function sendVerificationRequest(params) {
  const { identifier: to, provider, url, theme } = params
  const { host } = new URL(url)
  const res = await fetch("https://api.sendgrid.com/v3/mail/send", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${provider.apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      personalizations: [{ to: [{ email: to }] }],
      from: { email: provider.from },
      subject: `Sign in to ${host}`,
      content: [
        { type: "text/plain", value: text({ url, host }) },
        { type: "text/html", value: html({ url, host, theme }) },
      ],
    }),
  })
 
  if (!res.ok) throw new Error("Sendgrid error: " + (await res.text()))
}
 
function html(params: { url: string; host: string; theme: Theme }) {
  const { url, host, theme } = params
 
  const escapedHost = host.replace(/\./g, "&#8203;.")
 
  const brandColor = theme.brandColor || "#346df1"
  const color = {
    background: "#f9f9f9",
    text: "#444",
    mainBackground: "#fff",
    buttonBackground: brandColor,
    buttonBorder: brandColor,
    buttonText: theme.buttonText || "#fff",
  }
 
  return `
<body style="background: ${color.background};">
  <table width="100%" border="0" cellspacing="20" cellpadding="0"
    style="background: ${color.mainBackground}; max-width: 600px; margin: auto; border-radius: 10px;">
    <tr>
      <td align="center"
        style="padding: 10px 0px; font-size: 22px; font-family: Helvetica, Arial, sans-serif; color: ${color.text};">
        Sign in to <strong>${escapedHost}</strong>
      </td>
    </tr>
    <tr>
      <td align="center" style="padding: 20px 0;">
        <table border="0" cellspacing="0" cellpadding="0">
          <tr>
            <td align="center" style="border-radius: 5px;" bgcolor="${color.buttonBackground}"><a href="${url}"
                target="_blank"
                style="font-size: 18px; font-family: Helvetica, Arial, sans-serif; color: ${color.buttonText}; text-decoration: none; border-radius: 5px; padding: 10px 20px; border: 1px solid ${color.buttonBorder}; display: inline-block; font-weight: bold;">Sign
                in</a></td>
          </tr>
        </table>
      </td>
    </tr>
    <tr>
      <td align="center"
        style="padding: 0px 0px 10px 0px; font-size: 16px; line-height: 22px; font-family: Helvetica, Arial, sans-serif; color: ${color.text};">
        If you did not request this email you can safely ignore it.
      </td>
    </tr>
  </table>
</body>
`
}
 
// Email Text body (fallback for email clients that don't render HTML, e.g. feature phones)
function text({ url, host }: { url: string; host: string }) {
  return `Sign in to ${host}\n${url}\n\n`
}

如果您想使用 React 生成外观很棒的电子邮件，这些电子邮件与许多电子邮件客户端兼容，请查看mjml 或 react-email

验证令牌

默认情况下，我们生成一个随机验证令牌。如果您想覆盖它，可以在提供商选项中定义一个 generateVerificationToken 方法

./auth.ts

import NextAuth from "next-auth"
import Sendgrid from "next-auth/providers/sendgrid"
 
export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [
    Sendgrid({
      async generateVerificationToken() {
        return crypto.randomUUID()
      },
    }),
  ],
})

规范化电子邮件地址

默认情况下，Auth.js 将规范化电子邮件地址。它将地址视为不区分大小写（从技术上讲这与RFC 2821 规范不兼容，但在实践中，这会导致比解决问题更大的问题，例如，当从数据库中按电子邮件查找用户时）。它还会删除可能以逗号分隔列表形式传入的任何辅助电子邮件地址。您可以通过 Sendgrid 提供商上的 normalizeIdentifier 方法应用您自己的规范化。以下示例显示了默认行为

./auth.ts

import NextAuth from "next-auth"
import Sendgrid from "next-auth/providers/sendgrid"
 
export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [
    Sendgrid({
      normalizeIdentifier(identifier: string): string {
        // Get the first two elements only,
        // separated by `@` from user input.
        let [local, domain] = identifier.toLowerCase().trim().split("@")
        // The part before "@" can contain a ","
        // but we remove it on the domain part
        domain = domain.split(",")[0]
        return `${local}@${domain}`
 
        // You can also throw an error, which will redirect the user
        // to the sign-in page with error=EmailSignin in the URL
        // if (identifier.split("@").length > 2) {
        //   throw new Error("Only one email allowed")
        // }
      },
    }),
  ],
})

⚠️

始终确保这将返回单个电子邮件地址，即使传入多个电子邮件地址也是如此。

Salesforce Simplelogin

Sendgrid 提供商

概述

工作原理

配置

自定义

电子邮件正文

验证令牌

规范化电子邮件地址

关于 Auth.js

下载

鸣谢