Kinde

Kinde：开发者友好身份认证的深度解析

NOTE

本文档最后更新于 2026年4月，深入剖析 Kinde 的设计哲学、Auth 功能、SDK 支持，以及与 Clerk/Auth0 的对比分析。

---

目录

1. 概述与设计哲学
2. 核心功能详解
3. SDK 与集成
4. Organizations 功能
5. Kinde API
6. 与主流方案对比
7. 实战场景
8. 选型建议

---

概述与设计哲学

什么是 Kinde

用户认证是几乎所有 Web 应用的标配功能。从简单的邮箱密码登录到复杂的企业 SSO，认证系统需要处理注册、登录、会话管理、密码找回、多因素认证、社交登录等方方面面。自己实现这些功能不仅耗时耗力，还需要处理安全漏洞、隐私合规等敏感问题。因此，越来越多的开发者选择使用专业的身份认证服务。

Kinde 就是这样一个专注于开发者体验的身份认证平台。与 Auth0 的复杂配置或 Clerk 的精美 UI 不同，Kinde 追求的是配置简单、功能完整、文档清晰的平衡。Kinde 于 2021 年创立，虽然相对年轻，但发展势头非常迅猛，已经成为认证领域的一匹黑马。

Kinde 的目标用户非常明确：不想在认证上花费太多时间的开发者。这个定位让 Kinde 在功能和易用性之间找到了很好的平衡点——既提供了企业级认证需要的所有功能，又保持了足够简单的配置和使用体验。

设计哲学

Kinde 的设计哲学可以概括为四个核心理念。第一个是开发者优先，Kinde 的 API 设计简洁直观，文档清晰易懂，SDK 上手即用，开发者不需要阅读大量文档就能开始工作。第二个是零配置启动，Kinde 提供了合理的默认设置，即使不进行任何配置也能正常运行，这让快速原型开发成为可能。第三个是透明定价，Kinde 的定价模式简单清晰，没有隐藏费用，用户可以准确预测成本。第四个是安全默认，安全性相关的最佳实践在默认配置中就已经启用，开发者不需要专门配置就能获得基本的安全保障。

这种设计哲学的核心理念在于：认证虽然复杂，但不应该成为开发者的负担。Kinde 通过抽象掉认证系统的复杂性，让开发者能够专注于自己应用的核心业务逻辑。

与竞品定位差异

┌─────────────────────────────────────────────────────────┐
│                   认证工具选择光谱                        │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  简单易用                                              复杂强大  │
│     │                                                  │         │
│     ├──────────┬──────────┬──────────┬──────────┤     │
│     │          │          │          │          │     │
│   Kinde      Clerk    Supabase   Auth0      自建     │
│   (开发者    (UI精美)  (免费)    (企业)      (完全    │
│    友好)                                    自主可控)  │
│                                                         │
└─────────────────────────────────────────────────────────┘

这个光谱图展示了认证工具市场的分布情况。Kinde 位于简单易用的一端，但在功能完整性上并不妥协。这让它成为既想快速开发又不想牺牲功能的开发者的理想选择。

支持的认证方式

Kinde 支持当前主流的所有认证方式，从简单的邮箱密码到企业级的 SSO，都能得到支持。

认证方式	Kinde 支持
邮箱/密码	✅
无密码登录	✅ Magic Link
社交登录	✅ 20+ 提供商
企业 SSO	✅ SAML/OIDC
多因素认证	✅ TOTP/Backup Codes
Passkey	✅ WebAuthn

Kinde 的社交登录支持涵盖了主流平台：Google、GitHub、Apple、Microsoft、Facebook、LinkedIn 等都有官方集成。在企业 SSO 方面，Kinde 支持 SAML 和 OIDC 两种协议，可以与 Okta、Azure AD 等企业身份提供商集成。

---

核心功能详解

1. 用户认证

用户认证是 Kinde 的基础功能，包括注册、登录、会话管理等核心流程。Kinde 提供了完整的认证流程处理，开发者只需要几行代码就能集成认证功能。

注册流程

// React/Next.js
import { useKindeAuth } from '@kinde-oss/kinde-auth-nextjs'
 
export default function SignUp() {
  const { register } = useKindeAuth()
  
  return (
    <button onClick={() => register()}>
      Sign Up
    </button>
  )
}
 
// 自定义注册页面
export async function POST(request: Request) {
  const body = await request.json()
  
  const response = await fetch('https://app.kinde.com/api/v1/register', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      email: body.email,
      password: body.password,
      given_name: body.firstName,
      family_name: body.lastName,
    }),
  })
  
  return response.json()
}

Kinde 提供了两种集成方式：使用内置的认证页面（简单快速）或完全自定义的认证界面（完全控制）。对于大多数应用，内置页面已经足够精美和好用。

登录流程

import { useKindeAuth } from '@kinde-oss/kinde-auth-nextjs'
 
export default function Header() {
  const { isAuthenticated, user, login, logout } = useKindeAuth()
  
  return (
    <header>
      <nav>
        {isAuthenticated ? (
          <>
            <span>Welcome, {user?.given_name}</span>
            <button onClick={logout}>Sign Out</button>
          </>
        ) : (
          <>
            <button onClick={login}>Sign In</button>
            <button onClick={() => register()}>Sign Up</button>
          </>
        )}
      </nav>
    </header>
  )
}

useKindeAuth Hook 提供了所有认证相关的状态和操作。isAuthenticated 告诉你用户是否已登录，user 包含用户信息，login/logout/register 用于执行认证操作。这种声明式的 API 设计让认证状态的获取和使用变得非常简单。

2. 社交登录

社交登录是现代应用提升注册转化率的重要手段。Kinde 在 Dashboard 中提供了简单的一键配置来启用社交登录。

提供商	配置难度	说明
Google	⭐ 简单	一键集成
GitHub	⭐ 简单	OAuth App
Apple	⭐⭐ 中等	需要 Apple Developer 账号
Microsoft	⭐ 简单	Azure AD
Facebook	⭐ 简单	Meta App
Twitter/X	⭐⭐ 中等	Developer Portal
LinkedIn	⭐ 简单	OAuth App

每种社交登录的具体配置方法略有不同，但 Kinde 的文档提供了详细的步骤说明。Google 登录是最简单的，只需要几个步骤就能配置完成；Apple 登录相对复杂，因为需要 Apple Developer 账号和额外的配置。

3. 企业 SSO

企业 SSO 让组织内的用户可以使用统一的身份登录多个应用，是企业级应用的标准功能。Kinde 支持 SAML 和 OIDC 两种企业 SSO 协议。

// 配置 SAML 连接
// Kinde Dashboard → Settings → Authentication → Enterprise SSO
 
const ssoConfig = {
  protocol: 'saml',
  domain: 'company.com',
  // Identity Provider 配置
  idp_entity_id: 'https://company.okta.com',
  idp_sso_url: 'https://company.okta.com/app/...',
  idp_certificate: '...',
}
 
// 配置 OIDC 连接
const oidcConfig = {
  protocol: 'oidc',
  client_id: 'your-client-id',
  client_secret: 'your-client-secret',
  issuer: 'https://company.okta.com',
  scopes: ['openid', 'profile', 'email'],
}

SAML 是传统企业 SSO 的标准协议，适合与 Active Directory、Okta 等系统集成。OIDC 是现代化的协议，适合云原生的身份系统。Kinde 对两种协议都有良好支持。

4. 多因素认证（MFA）

多因素认证为用户账户添加了额外的安全层。Kinde 支持 TOTP（基于时间的一次性密码，如 Google Authenticator）和备份码两种 MFA 方式。

// 启用 MFA
// Kinde Dashboard → Settings → Security → Multi-factor authentication
 
// MFA 策略配置
const mfaPolicy = {
  is_active: true,
  // MFA 强制策略
  policy: 'required',  // required | optional | disabled
  // 支持的方式
  allowed_methods: ['totp', 'email_code', 'backup_code'],
  // 信任设备时长
  trust_duration_days: 30,
}

MFA 的配置策略可以根据应用的安全需求灵活调整。对于金融、医疗等高安全要求的应用，可以强制要求 MFA；对于普通应用，可以将 MFA 设置为可选功能。

5. 密码策略

密码策略帮助确保用户密码的强度，减少账户被攻破的风险。Kinde 提供了灵活的密码策略配置。

// 配置密码策略
const passwordPolicy = {
  length: {
    min: 8,
    max: 256,
  },
  lowercase: true,
  uppercase: true,
  numbers: true,
  special_characters: true,
  prevent_reuse: 5,  // 防止重复使用最近 5 个密码
  expiry_days: 90,   // 密码过期天数（0 = 不过期）
}

密码策略的配置需要平衡安全性和用户体验。过于严格的密码要求可能导致用户注册流失，而过于宽松则可能降低账户安全性。Kinde 的默认策略是一个很好的平衡点。

---

SDK 与集成

支持的 SDK

Kinde 提供了丰富的 SDK 覆盖，从 Web 到移动端都有官方支持。

SDK	状态	说明
React/Next.js	✅ 官方	最佳支持
Node.js	✅ 官方	通用 SDK
Python	✅ 官方	Django, Flask 支持
Go	✅ 社区	第三方
Ruby	✅ 社区	Rails 支持
PHP	✅ 社区	Laravel 支持
Java	✅ 社区	Spring 支持
Swift	✅ 官方	iOS/macOS
Kotlin	✅ 官方	Android

React/Next.js 是 Kinde 官方最优先支持的平台，SDK 功能完整，文档详尽。如果你的项目使用 Next.js，那么集成 Kinde 会非常顺畅。

Next.js 集成

Next.js 是当前最流行的 React 框架，Kinde 提供了专门的 SDK 来简化集成过程。

# 安装
npm install @kinde-oss/kinde-auth-nextjs

安装完成后，配置过程分为几个步骤：配置环境变量、设置认证路由、配置中间件、包裹应用。

// kinde.config.ts
import { NextRequest, NextResponse } from 'next/server'
import { handleAuth } from '@kinde-oss/kinde-auth-nextjs'
 
export const GET = handleAuth()

// middleware.ts
import { withAuth } from '@kinde-oss/kinde-auth-nextjs/middleware'
 
export default withAuth({
  isReturnToCurrentLocation: true,
  publishableKey: process.env.KINDE_CLIENT_ID,
})
 
export const config = {
  matcher: ['/dashboard/:path*', '/settings/:path*'],
}

// app/layout.tsx
import { UserProvider } from '@kinde-oss/kinde-auth-nextjs'
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="zh-CN">
      <body>
        <UserProvider>
          {children}
        </UserProvider>
      </body>
    </html>
  )
}

这三个配置步骤完成后，你的应用就具备了完整的认证功能。中间件会自动保护指定的路由，未登录用户会被重定向到登录页面。

---

Organizations 功能

Organizations 是 Kinde 用于处理多租户场景的核心功能。在 SaaS 应用中，每个客户组织通常需要一个独立的空间，Organizations 正是为此设计的。

创建 Organization

// 创建组织
const org = await fetch('https://app.kinde.com/api/v1/organizations', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Acme Corporation',
    slug: 'acme-corp',
  }),
})

每个 Organization 都有唯一的 slug，用于 URL 中标识组织。创建组织后，可以邀请成员加入，并分配不同的角色。

Organization 认证

import { useKindeOrg } from '@kinde-oss/kinde-auth-nextjs'
 
export default function OrgDashboard() {
  const { organization } = useKindeOrg()
  
  return (
    <div>
      <h1>{organization?.org_name}</h1>
      <p>Organization ID: {organization?.org_id}</p>
    </div>
  )
}

useKindeOrg Hook 提供了当前用户所属组织的信息。当用户属于多个组织时，可以通过这个 Hook 获取当前的组织上下文。

角色与权限

// Kinde 中的角色定义
const roles = {
  admin: {
    description: 'Full access',
    permissions: ['read', 'write', 'delete', 'manage'],
  },
  member: {
    description: 'Standard member',
    permissions: ['read', 'write'],
  },
  viewer: {
    description: 'Read-only access',
    permissions: ['read'],
  },
}
 
// 检查权限
export default async function AdminPage({ user }: { user: any }) {
  const hasPermission = user?.permissions?.includes('manage')
  
  if (!hasPermission) {
    return <div>Access denied</div>
  }
  
  return <AdminPanel />
}

Kinde 提供了基于角色的访问控制（RBAC）。可以为组织定义不同的角色，每个角色有不同的权限集。在应用中，可以通过检查用户的权限来决定是否允许访问某些功能。

---

Kinde API

API 端点

Kinde 提供了完整的 REST API，可以用于实现自定义的认证流程或与其他系统集成。

端点	方法	说明
/api/v1/register	POST	用户注册
/api/v1/login	POST	用户登录
/api/v1/logout	POST	用户登出
/api/v1/users	GET	列出用户
/api/v1/users/:id	GET	获取用户详情
/api/v1/organizations	GET/POST	组织管理
/api/v1/oauth2/token	POST	获取 Token

这些 API 覆盖了认证的核心操作。配合 Webhooks，可以实现完整的用户生命周期管理。

API 调用示例

import KindeSDK from '@kinde/js-utils'
 
const kinde = new KindeSDK({
  issuerBaseURL: 'https://app.kinde.com',
  clientId: process.env.KINDE_CLIENT_ID!,
  clientSecret: process.env.KINDE_CLIENT_SECRET!,
  redirectURL: process.env.KINDE_REDIRECT_URL!,
})
 
// 获取 Token
const tokens = await kinde.getTokenByCode(code)
console.log(tokens.access_token)
 
// 刷新 Token
const newTokens = await kinde.refreshToken(refreshToken)
 
// 获取用户信息
const userInfo = await kinde.getUser(token)
console.log(userInfo.email)

Kinde SDK 封装了 OAuth 2.0 的授权码流程，让 API 调用变得简单。

Webhooks

Webhook 让你能够在用户生命周期事件发生时收到通知，从而与外部系统集成。

// 处理 Kinde Webhooks
import crypto from 'crypto'
 
export async function POST(request: Request) {
  const body = await request.text()
  const signature = request.headers.get('x-kinde-signature')
  
  // 验证签名
  const expectedSignature = crypto
    .createHmac('sha256', process.env.KINDE_WEBHOOK_SECRET!)
    .update(body)
    .digest('hex')
  
  if (signature !== expectedSignature) {
    return new Response('Invalid signature', { status: 401 })
  }
  
  const event = JSON.parse(body)
  
  switch (event.type) {
    case 'user.created':
      await handleNewUser(event.data)
      break
    case 'user.updated':
      await handleUserUpdate(event.data)
      break
    case 'organization.created':
      await handleNewOrg(event.data)
      break
  }
  
  return new Response('OK')
}

接收 Webhook 时，必须验证签名以确保请求来自 Kinde 而非恶意攻击者。Kinde 在每个 Webhook 请求中都会包含签名头，你需要在服务端验证这个签名。

---

与主流方案对比

功能矩阵

功能	Kinde	Clerk	Auth0	Supabase
SDK 质量	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐
UI 组件	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐	❌
文档质量	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐
React 集成	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐
Organizations	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	❌
企业 SSO	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	❌
MFA	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐
免费额度	1K MAU	10K MAU	7K MAU	50K MAU
定价	$25/月起	$25/月起	$23/月起	免费+按量

Kinde 在文档质量和 SDK 质量上与 Clerk 相当，但免费额度略少。在 Organizations 和企业 SSO 方面，Kinde 提供了完整的功能，与 Auth0 的差距不大。

定价对比

方案	免费额度	超出部分
Kinde	1K MAU	$0.01/MAU
Clerk	10K MAU	$0.02/MAU
Auth0	7K MAU	$0.016/MAU
Supabase	50K MAU	计量收费

Kinde 的定价策略非常透明，简单明了。虽然免费额度比 Clerk 和 Auth0 少一些，但超出后的单价也相对较低。

选型建议

场景	推荐	理由
文档质量优先	Kinde	文档最清晰
React 项目	Clerk	组件最精美
企业 SSO	Auth0	功能最全面
预算有限	Supabase	免费额度最大

---

实战场景

场景：多租户 SaaS

多租户 SaaS 是 Kinde Organizations 功能的典型应用场景。应用需要为每个客户组织提供独立的认证空间。

// 使用 Kinde Organizations 实现多租户
 
// 1. 用户注册时创建 Organization
async function handleRegister(organizationName: string) {
  // 创建组织
  const org = await kindeClient.createOrganization({
    name: organizationName,
    slug: organizationName.toLowerCase().replace(/\s+/g, '-'),
  })
  
  // 发送邀请
  await kindeClient.inviteUser({
    org_code: org.org_code,
    user_email: 'admin@example.com',
    role: 'admin',
  })
}
 
// 2. Middleware 验证 Organization 访问
import { withOrgAuth } from '@kinde-oss/kinde-auth-nextjs'
 
export default withOrgAuth({
  orgSlugParam: 'orgSlug',
})
 
// 3. 获取 Organization 数据
export default async function OrgDashboard({ params }: { params: { orgSlug: string } }) {
  const { org } = await getOrg(params.orgSlug)
  
  if (!org) {
    notFound()
  }
  
  return (
    <div>
      <h1>{org.name}</h1>
      <OrganizationMembers orgId={org.id} />
    </div>
  )
}

这个场景展示了完整的注册-认证-授权流程。用户注册时自动创建组织，邀请管理员加入，然后通过中间件保护组织的路由。

---

选型建议

选择 Kinde 的条件

• ✅ 追求文档清晰度
• ✅ 开发者体验优先
• ✅ 需要 Organizations
• ✅ React/Next.js 项目
• ✅ 不想被 UI 组件绑定

不选择 Kinde 的场景

• ❌ 需要最精美的 UI（选择 Clerk）
• ❌ 需要离线支持（选择 Clerk）
• ❌ 企业 SSO 需求复杂（选择 Auth0）
• ❌ 预算极其有限（选择 Supabase）

---

参考资料

资源	链接
官方文档	https://kinde.com/docs/
API 参考	https://kinde.com/api/
GitHub	https://github.com/kinde-oss
SDK 仓库	https://github.com/kinde-oss/kinde-auth-nextjs

---

SUCCESS

Kinde 以其清晰的文档、简单的配置和合理的定价，成为认证领域的黑马。对于追求开发者体验和时间效率的团队，Kinde 提供了在功能完整性和易用性之间的最佳平衡。

---

Kinde 高级配置与最佳实践

完整的认证流程实现

// middleware.ts
import { withAuth } from '@kinde-oss/kinde-auth-nextjs/middleware';
 
export default withAuth({
  isReturnToCurrentLocation: true,
  publishableKey: process.env.KINDE_CLIENT_ID,
  secretKey: process.env.KINDE_CLIENT_SECRET,
  issuerBaseURL: process.env.KINDE_ISSUER_URL,
  baseURL: process.env.NEXT_PUBLIC_BASE_URL,
});
 
export const config = {
  matcher: [
    '/dashboard/:path*',
    '/settings/:path*',
    '/api/protected/:path*',
    '/((?!sign-in|sign-up|register|create-account|logout).*)',
  ],
};

多因素认证（MFA）

// components/MFASetup.tsx
'use client';
 
import { useKindeAuth } from '@kinde-oss/kinde-auth-nextjs';
 
export function MFASetup() {
  const { user } = useKindeAuth();
  
  const enableTOTP = async () => {
    const response = await fetch('/api/kinde/totp/setup', {
      method: 'POST',
    });
    const data = await response.json();
    // 显示 QR 码
    return data;
  };
  
  const verifyTOTP = async (code: string) => {
    const response = await fetch('/api/kinde/totp/verify', {
      method: 'POST',
      body: JSON.stringify({ code }),
    });
    return response.json();
  };
  
  return (
    <div>
      <h2>Two-Factor Authentication</h2>
      <button onClick={enableTOTP}>
        Enable Authenticator App
      </button>
    </div>
  );
}

自定义登录页面

// app/sign-in/page.tsx
'use client';
 
import { useState } from 'react';
import { useSignIn } from '@kinde-oss/kinde-auth-nextjs';
 
export default function SignInPage() {
  const { signIn, isLoading } = useSignIn();
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [error, setError] = useState('');
  
  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    
    try {
      await signIn({
        email,
        password,
        redirect_to: '/dashboard',
      });
    } catch (err: any) {
      setError(err.message || 'Sign in failed');
    }
  };
  
  const handleSocialLogin = async (provider: string) => {
    await signIn({
      auth_method: 'oauth',
      provider,
      redirect_to: '/dashboard',
    });
  };
  
  return (
    <div className="min-h-screen flex items-center justify-center">
      <div className="w-full max-w-md p-8">
        <h1 className="text-2xl font-bold mb-6">Sign In</h1>
        
        <form onSubmit={handleSubmit} className="space-y-4">
          <div>
            <label htmlFor="email">Email</label>
            <input
              id="email"
              type="email"
              value={email}
              onChange={(e) => setEmail(e.target.value)}
              required
            />
          </div>
          
          <div>
            <label htmlFor="password">Password</label>
            <input
              id="password"
              type="password"
              value={password}
              onChange={(e) => setPassword(e.target.value)}
              required
            />
          </div>
          
          {error && <p className="text-red-500">{error}</p>}
          
          <button type="submit" disabled={isLoading}>
            {isLoading ? 'Signing in...' : 'Sign In'}
          </button>
        </form>
        
        <div className="mt-6">
          <p>Or continue with:</p>
          <div className="flex gap-4 mt-4">
            <button onClick={() => handleSocialLogin('google')}>
              Google
            </button>
            <button onClick={() => handleSocialLogin('github')}>
              GitHub
            </button>
          </div>
        </div>
      </div>
    </div>
  );
}

Kinde 与数据库同步

// lib/kindeDb.ts
import { db } from './db';
 
export async function syncUserToDatabase(user: any) {
  const existing = await db.user.findUnique({
    where: { kindeId: user.id },
  });
  
  if (existing) {
    return db.user.update({
      where: { kindeId: user.id },
      data: {
        email: user.email,
        name: user.name,
        picture: user.picture,
        updatedAt: new Date(),
      },
    });
  }
  
  return db.user.create({
    data: {
      kindeId: user.id,
      email: user.email,
      name: user.name,
      picture: user.picture,
    },
  });
}
 
// 处理 Webhook
// app/api/webhooks/kinde/route.ts
import { headers } from 'next/headers';
import crypto from 'crypto';
 
export async function POST(req: Request) {
  const body = await req.text();
  const signature = headers().get('x-kinde-signature');
  
  // 验证签名
  const expectedSignature = crypto
    .createHmac('sha256', process.env.KINDE_WEBHOOK_SECRET!)
    .update(body)
    .digest('hex');
  
  if (signature !== expectedSignature) {
    return new Response('Invalid signature', { status: 401 });
  }
  
  const event = JSON.parse(body);
  
  switch (event.type) {
    case 'user.created': {
      await syncUserToDatabase(event.data);
      break;
    }
    case 'user.updated': {
      await syncUserToDatabase(event.data);
      break;
    }
    case 'user.deleted': {
      await db.user.delete({
        where: { kindeId: event.data.id },
      });
      break;
    }
  }
  
  return new Response('OK');
}

Kinde 与 tRPC 集成

// server/router/user.ts
import { router, publicProcedure, protectedProcedure } from '../trpc';
import { z } from 'zod';
import { getKindeServerSession } from '@kinde-oss/kinde-auth-nextjs/server';
 
export const userRouter = router({
  // 获取当前用户
  me: protectedProcedure.query(async ({ ctx }) => {
    const { getUser } = await getKindeServerSession();
    const user = await getUser();
    
    if (!user) {
      throw new TRPCError({ code: 'UNAUTHORIZED' });
    }
    
    // 同步到数据库
    const dbUser = await syncUserToDatabase(user);
    
    return dbUser;
  }),
  
  // 获取用户列表（管理员）
  list: protectedProcedure.query(async ({ ctx }) => {
    const { getUser } = await getKindeServerSession();
    const user = await getUser();
    
    if (!user || user.id !== process.env.ADMIN_ID) {
      throw new TRPCError({ code: 'FORBIDDEN' });
    }
    
    return db.user.findMany();
  }),
});

Kinde 与 Next.js Server Actions

// app/actions/user.ts
'use server';
 
import { getKindeServerSession } from '@kinde-oss/kinde-auth-nextjs/server';
import { db } from '@/lib/db';
import { revalidatePath } from 'next/cache';
 
export async function getAuthState() {
  const { getUser, isAuthenticated } = await getKindeServerSession();
  
  if (!await isAuthenticated()) {
    return { isAuthenticated: false, user: null };
  }
  
  const user = await getUser();
  const dbUser = await db.user.findUnique({
    where: { kindeId: user?.id },
  });
  
  return {
    isAuthenticated: true,
    user: dbUser,
  };
}
 
export async function updateProfile(formData: FormData) {
  const { getUser, isAuthenticated } = await getKindeServerSession();
  
  if (!await isAuthenticated()) {
    throw new Error('Not authenticated');
  }
  
  const user = await getUser();
  const name = formData.get('name') as string;
  
  await db.user.update({
    where: { kindeId: user?.id },
    data: { name },
  });
  
  revalidatePath('/settings');
}

Kinde 权限管理

// 定义权限
export const permissions = {
  READ_POSTS: 'read:posts',
  WRITE_POSTS: 'write:posts',
  DELETE_POSTS: 'delete:posts',
  MANAGE_USERS: 'manage:users',
};
 
// 定义角色
export const roles = {
  ADMIN: {
    id: 'admin',
    name: 'Administrator',
    permissions: [
      permissions.READ_POSTS,
      permissions.WRITE_POSTS,
      permissions.DELETE_POSTS,
      permissions.MANAGE_USERS,
    ],
  },
  EDITOR: {
    id: 'editor',
    name: 'Editor',
    permissions: [
      permissions.READ_POSTS,
      permissions.WRITE_POSTS,
    ],
  },
  VIEWER: {
    id: 'viewer',
    name: 'Viewer',
    permissions: [
      permissions.READ_POSTS,
    ],
  },
};
 
// 检查权限
export async function hasPermission(userId: string, permission: string) {
  const user = await db.user.findUnique({
    where: { kindeId: userId },
    include: { role: true },
  });
  
  if (!user?.role) return false;
 
  return user.role.permissions.includes(permission);
}

Kinde 安全最佳实践

// 1. 验证请求签名
export function verifyKindeSignature(
  payload: string,
  signature: string
): boolean {
  const expectedSignature = crypto
    .createHmac('sha256', process.env.KINDE_WEBHOOK_SECRET!)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}
 
// 2. 安全会话检查
export async function requireAuth() {
  const { isAuthenticated } = await getKindeServerSession();
  
  if (!await isAuthenticated()) {
    throw new Error('Authentication required');
  }
}
 
// 3. 会话超时处理
export async function checkSession() {
  const { getUser, getAccessToken } = await getKindeServerSession();
  const user = await getUser();
  const token = await getAccessToken();
  
  if (!user || !token) {
    return null;
  }
  
  // 验证 token 过期时间
  const decoded = JSON.parse(atob(token.split('.')[1]));
  if (decoded.exp * 1000 < Date.now()) {
    return null;
  }
  
  return user;
}

---

Kinde 与 Clerk 功能对比

详细对比表

功能	Kinde	Clerk
核心定位	开发者友好	UI 美观
文档质量	⭐⭐⭐⭐⭐	⭐⭐⭐⭐
UI 组件	⭐⭐⭐⭐	⭐⭐⭐⭐⭐
React 集成	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
Organizations	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
企业 SSO	⭐⭐⭐⭐	⭐⭐⭐⭐⭐
MFA	⭐⭐⭐⭐	⭐⭐⭐⭐⭐
Webhook 机制	基础	完善
免费额度	1K MAU	10K MAU
定价策略	简单	复杂
SDK 种类	⭐⭐⭐⭐	⭐⭐⭐⭐⭐
迁移工具	无	有
社区活跃度	⭐⭐⭐	⭐⭐⭐⭐⭐

选择建议

选择 Kinde 如果：

• 你是认证新手
• 追求文档清晰度
• 预算中等
• 需要快速启动
• 喜欢简单配置

选择 Clerk 如果：

• 需要精美 UI
• 追求极致 DX
• 企业 SSO 需求
• 需要迁移工具
• 社区支持重要

---

TIP

Kinde 的设计理念是「认证应该简单」，合理利用其内置功能和 API，可以快速构建安全可靠的用户认证系统。

---

NOTE

本文档包含超过 4000 中文字符，涵盖 Kinde 的核心概念、实战代码和最佳实践。如需了解更多高级特性，请参考官方文档。