单点登录（SSO）

{issuer}/.well-known/openid-configuration

trustedOrigins: ["https://your-org.okta.com"],

trustedOrigins: [
    "https://your-org.okta.com",
    "https://accounts.google.com",
    "https://login.microsoftonline.com",
    "https://auth0.com",
    "https://idp.example.com"
],

trustedOrigins: async (request) => {
    // 初始化和 auth.api 调用时 request 可能为 undefined
    if (!request) {
        return ["https://my-frontend.com"];
    }

    // SSO 注册接口的受信列表
    if (request.url.endsWith("/sso/register")) {
        const trustedOrigins = await fetchOriginList();
        return trustedOrigins;
    }

    // 其它请求使用正常的来源列表
    return [];
}

const response = await auth.api.spMetadata({
    query: {
        providerId: "saml-provider",
        format: "xml" // 可选 "xml" 或 "json"
    }
});

const metadataXML = await response.text();
console.log(metadataXML);

import { authClient } from "@/lib/auth-client"

const res = await authClient.signIn.sso({
    email: "user@example.com",
    callbackURL: "/dashboard",
});

import { authClient } from "@/lib/auth-client"

const res = await authClient.signIn.sso({
    domain: "example.com",
    callbackURL: "/dashboard",
});

import { authClient } from "@/lib/auth-client"

const res = await authClient.signIn.sso({
    organizationSlug: "example-org",
    callbackURL: "/dashboard",
});

import { authClient } from "@/lib/auth-client"

const res = await authClient.signIn.sso({
    providerId: "example-provider-id",
    callbackURL: "/dashboard",
});

import { authClient } from "@/lib/auth-client"

const res = await authClient.signIn.sso({
    providerId: "example-provider-id",
    loginHint: "user@example.com",
    callbackURL: "/dashboard",
});

import { authClient } from "@/lib/auth-client"

const res = await auth.api.signInSSO({
    body: {
        organizationSlug: "example-org",
        callbackURL: "/dashboard",
    }
});

import { betterAuth } from "better-auth";
import { sso } from "@better-auth/sso";

const auth = betterAuth({
    plugins: [
        sso({
            provisionUser: async (user) => {
                // 用户预置逻辑
            },
            organizationProvisioning: {
                disabled: false,
                defaultRole: "member",
                getRole: async (user) => {
                    // 需要时获取角色
                },
            },
        }),
    ],
});

import { betterAuth } from "better-auth";
import { sso } from "@better-auth/sso";

const auth = betterAuth({
    plugins: [
        sso({
            provisionUser: async ({ user, userInfo, token, provider }) => {
                // 用 SSO 数据更新用户资料
                await updateUserProfile(user.id, {
                    department: userInfo.attributes?.department,
                    jobTitle: userInfo.attributes?.jobTitle,
                    manager: userInfo.attributes?.manager,
                    lastSSOLogin: new Date(),
                });

                // 创建用户专属工作区
                await createUserWorkspace(user.id);

                // 与 CRM 同步用户
                await syncUserWithCRM(user.id, userInfo);

                // 记录 SSO 登录事件
                await auditLog.create({
                    userId: user.id,
                    action: 'sso_signin',
                    provider: provider.providerId,
                    metadata: {
                        email: userInfo.email,
                        ssoProvider: provider.issuer,
                    },
                });
            },
        }),
    ],
});

import { betterAuth } from "better-auth";
import { sso } from "@better-auth/sso";

const auth = betterAuth({
    plugins: [
        sso({
            organizationProvisioning: {
                disabled: false,           // 开启组织预置
                defaultRole: "member",     // 新成员默认角色
            },
        }),
    ],
});

import { betterAuth } from "better-auth";
import { sso } from "@better-auth/sso";

const auth = betterAuth({
    plugins: [
        sso({
            organizationProvisioning: {
                disabled: false,
                defaultRole: "member",
                getRole: async ({ user, userInfo, provider }) => {
                    // 根据 SSO 属性分配角色
                    const department = userInfo.attributes?.department;
                    const jobTitle = userInfo.attributes?.jobTitle;
                    
                    // 基于职位判断管理员
                    if (jobTitle?.toLowerCase().includes('manager') || 
                        jobTitle?.toLowerCase().includes('director') ||
                        jobTitle?.toLowerCase().includes('vp')) {
                        return "admin";
                    }
                    
                    // IT 部门特殊角色
                    if (department?.toLowerCase() === 'it') {
                        return "admin";
                    }
                    
                    // 其它默认成员权限
                    return "member";
                },
            },
        }),
    ],
});

import { auth } from "@/lib/auth"

await auth.api.registerSSOProvider({
    body: {
        providerId: "acme-corp-saml",
        issuer: "https://acme-corp.okta.com",
        domain: "acmecorp.com",
        organizationId: "org_acme_corp_id", // 关联组织
        samlConfig: {
            // SAML 配置...
        },
    },
    headers: await headers() // 包含用户会话令牌的头
});

https://dash.better-auth.com/[project]/organization/[orgId]/enterprise

import { auth } from "@/lib/auth"

// Acme Corp SAML 提供者
await auth.api.registerSSOProvider({
    body: {
        providerId: "acme-corp",
        issuer: "https://acme.okta.com",
        domain: "acmecorp.com",
        organizationId: "org_acme_id",
        samlConfig: { /* ... */ },
    },
    headers,
});

// TechStart OIDC 提供者
await auth.api.registerSSOProvider({
    body: {
        providerId: "techstart-google",
        issuer: "https://accounts.google.com",
        domain: "techstart.io",
        organizationId: "org_techstart_id",
        oidcConfig: { /* ... */ },
    },
    headers,
});

provisionUser: async ({ user, userInfo }) => {
    // 判断是否已预置
    const existingProfile = await getUserProfile(user.id);
    if (!existingProfile.ssoProvisioned) {
        await createUserResources(user.id);
        await markAsProvisioned(user.id);
    }
    
    // 总是更新属性（可能发生变更）
    await updateUserAttributes(user.id, userInfo.attributes);
},

provisionUser: async ({ user, userInfo }) => {
    try {
        await syncWithExternalSystem(user, userInfo);
    } catch (error) {
        // 记录错误但不抛出 — 用户仍能登录
        console.error('同步外部系统失败:', error);
        await logProvisioningError(user.id, error);
    }
},

organizationProvisioning: {
    disabled: false,
    getRole: async ({ user, userInfo, provider }) => {
        // 仅为特定提供者处理角色分配
        if (provider.providerId.includes('enterprise')) {
            return determineEnterpriseRole(userInfo);
        }
        return "member";
    },
},

import { betterAuth } from "better-auth";
import { sso } from "@better-auth/sso";

const auth = betterAuth({
    plugins: [
        sso({
            defaultSSO: [
                {
                    providerId: "default-saml", // 默认提供者 ID
                    domain: "http://your-app.com",
                    samlConfig: {
                        issuer: "https://your-app.com",
                        entryPoint: "https://idp.example.com/sso",
                        cert: "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
                        callbackUrl: "http://localhost:3000/api/auth/sso/saml2/sp/acs",
                        spMetadata: {
                            entityID: "http://localhost:3000/api/auth/sso/saml2/sp/metadata",
                            metadata: "<!-- Your SP Metadata XML -->",
                        }
                    }
                }
            ]
        })
    ]
});

samlConfig: {
    // ... 其他配置
    authnRequestsSigned: true,
    spMetadata: {
        privateKey: "-----BEGIN RSA PRIVATE KEY-----\n...",
    }
}

mapping: {
    id: "nameID",           // 默认: "nameID"
    email: "email",         // 默认: "email" 或 "nameID"
    name: "displayName",    // 默认: "displayName"
    firstName: "givenName", // 默认: "givenName"
    lastName: "surname",    // 默认: "surname"
    extraFields: {
        department: "department",
        role: "jobTitle",
        phone: "telephoneNumber"
    }
}

import { betterAuth } from "better-auth";
import { sso } from "@better-auth/sso";

const auth = betterAuth({
    plugins: [
        sso({
            saml: {
                // 启用 InResponseTo 校验
                enableInResponseToValidation: true,
                // 可选：禁止 IdP 发起的 SSO（更严安全）
                allowIdpInitiated: false,
                // AuthnRequest 有效期（默认 5 分钟）
                requestTTL: 10 * 60 * 1000, // 10 分钟
            },
        }),
    ],
});

import { betterAuth } from "better-auth";
import { sso } from "@better-auth/sso";

const auth = betterAuth({
    plugins: [
        sso({
            saml: {
                // 时钟偏差容忍（默认 5 分钟）
                clockSkew: 5 * 60 * 1000,
                // 是否强制要求断言必须有时间戳（默认 false）
                requireTimestamps: false,
            },
        }),
    ],
});

sso({
    saml: {
        clockSkew: 60 * 1000,      // 1 分钟容忍
        requireTimestamps: true,   // 严格拒绝无时间戳断言（SAML2Int）
    },
})

sso({
    saml: {
        algorithms: {
            // "warn"（默认） | "reject" | "allow"
            onDeprecated: "warn",
        },
    },
})

sso({
    saml: {
        algorithms: {
            onDeprecated: "reject",
        },
    },
})

sso({
    saml: {
        // 企业级 IdP 可能需要更大响应限制
        maxResponseSize: 512 * 1024, // 512KB
        maxMetadataSize: 100 * 1024, // 100KB
    },
})

// 相对路径（追加到 baseURL）
sso({ redirectURI: "/sso/callback" })

// 完整 URL
sso({ redirectURI: "https://login.example.com/callback" })

samlConfig: {
  callbackUrl: "/dashboard", // 正确：指向应用终点
  // callbackUrl: "/api/auth/sso/saml2/callback/my-provider" // 错误：不要指向回调接口
}