其后执行 奥奥特2.1 及相关的OAuth/OIDC规格:

支持的赠款类型

• ✅ 带有 PKCE 的授权代码 (公共和保密客户)
• ✅ 刷新托肯 (带有符号旋转)

不支持的地物( OAuth 2. 0 遗产)

• ❌ 间接赠款 (因安全原因在OAuth 2.1被拆除)
• ❌ 资源所有人密码证书赠款 (在OAuth 2.1中删除)
• ❌ PKCE 平原方法 (每个OAuth2.1最佳做法只支持S256)

关键安全要求

• PKCE 执行: 所有授权代码流量需要使用 S256 方法的 PKCE
• 重定向 URI 验证: 精确字符串匹配(仅限RFC 8252回转可变端口例外)
• 资源约束数字 : resource 值与授权授予和刷新令牌绑定
• 访问托肯观众: 访问令牌 aud 是授权的 resource,或配置的默认受众
• 授权代码: 单用,10分钟后到期
• 托肯·哈兴: 所有以 SHA-256 散列存储的令牌
• 刷新托肯旋转: 每次使用时发布新的刷新令牌,旧令牌作废

内设安全控制

• PKCE 执行: 所有授权代码流量都需要PKCE(代码 质疑/代码 验证)
• 重定向 URI 验证: 严格核对已注册的 URI
• 范围验证:每个客户只允许注册范围
• 托肯·哈兴: 访问和刷新令牌作为SHA-256散列存储
• 客户端秘密搜索: 使用 bcrypt 的客户机密
• 客户端机密兼容性:新发布的符合bcrypt72字节输入限制的客户机密;现有的更长的秘密对于补丁放出兼容性仍然有效,在实用时应当被旋转
• 内部变异:关键业务,如 issueAuthorizationCode 无法直接访问
• 默认禁用 DCR: 必须明确启用动态客户端注册

授权流量安全

这个 /oauth/authorize 端点进行全面的验证 :

1. 客户身份验证
2. 根据注册的 URI 重定向 URI 匹配
3. 对照客户端允许的范围进行范围验证
4. PKCE 要求(使用 S256 方法的代码-挑战)
5. 用户认证通过 getUserId 钩子

支持的范围

• openid: OpenID 连接认证和ID 令牌需要
• profile: 授权访问用户配置信息(名称、图片)
• email: 授权访问用户电子邮件地址
• offline_access: 为长期访问启用刷新令牌发行

刷新托肯要求

刷新符号是 仅印发 当 offline_access 在最初授权期间,请求并授予范围。 对于 OpenID 连接请求, offline_access 需求 prompt=consent (或包含 consent:

• ✅ 与 offline_access:客户端同时收到访问令牌和刷新令牌
• ❌ 无 offline_access:客户端仅接收访问令牌(无刷新令牌)

刷新托肯赠款流程 :

• 使用 refresh_token 获取新访问符的赠款类型
• 原始授权必须包括: offline_access 范围
• 刷新令牌在每次使用时自动旋转(旧令牌无效)
• 新的刷新令牌保持与原值相同的范围
• 重用旋转的刷新令牌将活动刷新的家族及其授权记录取消

这遵循了OAuth 2.1和OpenID Connect的规格,确保了长寿的刷新令牌只有在得到用户明确同意的情况下才发布.

这个提供者支持 RFC 8707 resource mCP和其他资源服务器流量的指标.

• resource 可在授权请求中选择.
• 如果存在,它必须是绝对的无碎片URI.
• 授权代码存储批准 resource。 。 。 .
• 令牌请求可能重复同样内容 resource,但不能添加未经批准的新的.
• 刷新令牌在旋转时保留相同的资源/听众绑定 .
• 访问符使用授权 resource 作为 aud; 否则使用 applicationID 默认 convex 观众.

对于自定义同意的 UI , 保存收到的 resource 参数并传递给 issueAuthorizationCode。 。 。 .

手动生成 RSA 密钥 :

# Generate private key
openssl genrsa -out private.pem 2048

# Generate JWKS (use https://mkjwk.org or this script)
node -e "
const jose = require('jose');
const fs = require('fs');
const privateKey = fs.readFileSync('private.pem', 'utf8');
(async () => {
  const key = await jose.importPKCS8(privateKey, 'RS256');
  const jwk = await jose.exportJWK(key);
  console.log(JSON.stringify({ keys: [{ ...jwk, use: 'sig', alg: 'RS256', kid: 'default-key' }] }));
})();
"

设置环境变量 :

bunx convex env set JWT_PRIVATE_KEY "-----BEGIN RSA PRIVATE KEY-----\n..."
bunx convex env set JWKS '{"keys":[...]}'
bunx convex env set SITE_URL "https://your-app.example.com"

// convex/http.ts
import { httpAction } from "./_generated/server";
import { httpRouter } from "convex/server";
import { OAuthProvider } from "@codefox-inc/oauth-provider";
import { components } from "./_generated/api";

const http = httpRouter();

const oauthProvider = new OAuthProvider(components.oauthProvider, {
    privateKey: process.env.JWT_PRIVATE_KEY!,
    jwks: process.env.JWKS!,
    siteUrl: process.env.SITE_URL!,

    // REQUIRED: Authenticate user for authorization endpoint
    getUserId: async (ctx, request) => {
        const identity = await ctx.auth.getUserIdentity();
        return identity?.subject ?? null;
    },
});

// OpenID Connect Discovery
http.route({
    path: "/oauth/.well-known/openid-configuration",
    method: "GET",
    handler: httpAction((ctx, req) =>
        oauthProvider.handlers.openIdConfiguration(ctx, req)
    ),
});

// JWKS endpoint
http.route({
    path: "/oauth/.well-known/jwks.json",
    method: "GET",
    handler: httpAction((ctx, req) =>
        oauthProvider.handlers.jwks(ctx, req)
    ),
});

// Authorization endpoint (validates and issues auth codes)
http.route({
    path: "/oauth/authorize",
    method: "GET",
    handler: httpAction((ctx, req) =>
        oauthProvider.handlers.authorize(ctx, req)
    ),
});

// Token endpoint
http.route({
    path: "/oauth/token",
    method: "POST",
    handler: httpAction((ctx, req) =>
        oauthProvider.handlers.token(ctx, req)
    ),
});

// UserInfo endpoint
http.route({
    path: "/oauth/userinfo",
    method: "GET",
    handler: httpAction((ctx, req) =>
        oauthProvider.handlers.userInfo(ctx, req, async (userId) => {
            const user = await ctx.runQuery(api.users.get, { userId });
            return user ? { sub: userId, name: user.name, email: user.email } : null;
        })
    ),
});

// Dynamic Client Registration (optional)
http.route({
    path: "/oauth/register",
    method: "POST",
    handler: httpAction((ctx, req) =>
        oauthProvider.handlers.register(ctx, req)
    ),
});

export default http;

注册 OAuth 客户端( Admin)

// convex/oauthAdmin.ts
import { mutation } from "./_generated/server";
import { OAuthProvider } from "@codefox-inc/oauth-provider";
import { components } from "./_generated/api";

export const registerOAuthClient = mutation({
    handler: async (ctx, args: {
        name: string;
        redirectUris: string[];
        scopes: string[];
        type: "confidential" | "public";
    }) => {
        // Check admin permissions
        const identity = await ctx.auth.getUserIdentity();
        if (!identity) throw new Error("Unauthorized");

        const oauthProvider = new OAuthProvider(components.oauthProvider, {
            privateKey: process.env.JWT_PRIVATE_KEY!,
            jwks: process.env.JWKS!,
            siteUrl: process.env.SITE_URL!,
        });

        const result = await oauthProvider.registerClient(ctx, {
            name: args.name,
            redirectUris: args.redirectUris,
            scopes: args.scopes,
            type: args.type,
        });

        // IMPORTANT: Save clientSecret securely - it's only returned once!
        return result;
    },
});

如果您需要自定义同意, 您可以直接使用 SDK 方法 :

// convex/oauth.ts
import { mutation } from "./_generated/server";
import { OAuthProvider } from "@codefox-inc/oauth-provider";
import { components } from "./_generated/api";

export const approveAuthorization = mutation({
    handler: async (ctx, args: {
        clientId: string;
        scopes: string[];
        redirectUri: string;
        codeChallenge: string;
        codeChallengeMethod: string;
        nonce?: string;
        resource?: string;
    }) => {
        // Verify user is authenticated
        const identity = await ctx.auth.getUserIdentity();
        if (!identity) throw new Error("Not authenticated");

        const oauthProvider = new OAuthProvider(components.oauthProvider, {
            privateKey: process.env.JWT_PRIVATE_KEY!,
            jwks: process.env.JWKS!,
            siteUrl: process.env.SITE_URL!,
        });

        // Issue authorization code (automatically creates authorization record)
        const authCode = await oauthProvider.issueAuthorizationCode(ctx, {
            userId: identity.subject,
            clientId: args.clientId,
            scopes: args.scopes,
            redirectUri: args.redirectUri,
            codeChallenge: args.codeChallenge,
            codeChallengeMethod: args.codeChallengeMethod,
            nonce: args.nonce,
            resource: args.resource,
        });

        return authCode;
    },
});

当授权请求包含 resource把它显示在同意书上 并且通过它没有改变。 如果象征性请求要求 resource 未存储在授权代码中, 符号端点返回 invalid_target。 。 。 .

列表用户授权的应用程序

import { query } from "./_generated/server";
import { OAuthProvider } from "@codefox-inc/oauth-provider";
import { components } from "./_generated/api";

export const listAuthorizedApps = query({
    handler: async (ctx) => {
        const identity = await ctx.auth.getUserIdentity();
        if (!identity) return [];

        const oauthProvider = new OAuthProvider(components.oauthProvider, {
            privateKey: process.env.JWT_PRIVATE_KEY!,
            jwks: process.env.JWKS!,
            siteUrl: process.env.SITE_URL!,
        });

        return await oauthProvider.listUserAuthorizations(ctx, identity.subject);
    },
});

撤销授权

import { mutation } from "./_generated/server";
import { OAuthProvider } from "@codefox-inc/oauth-provider";
import { components } from "./_generated/api";

export const revokeApp = mutation({
    handler: async (ctx, args: { clientId: string }) => {
        const identity = await ctx.auth.getUserIdentity();
        if (!identity) throw new Error("Not authenticated");

        const oauthProvider = new OAuthProvider(components.oauthProvider, {
            privateKey: process.env.JWT_PRIVATE_KEY!,
            jwks: process.env.JWKS!,
            siteUrl: process.env.SITE_URL!,
        });

        // Deletes authorization and all associated tokens
        await oauthProvider.revokeAuthorization(ctx, identity.subject, args.clientId);
    },
});

interface OAuthConfig {
    // REQUIRED: RSA private key in PEM format
    privateKey: string;

    // REQUIRED: JWKS for token verification (public keys only)
    jwks: string;

    // REQUIRED: Your application URL
    siteUrl: string;

    // OPTIONAL: Convex deployment URL (if different from siteUrl)
    convexSiteUrl?: string;

    // OPTIONAL: OAuth endpoint prefix (default: "/oauth")
    // Normalized to a leading slash, trailing slash removed; "/" means root.
    // Must match the route prefix you register in http.ts.
    prefix?: string;

    // OPTIONAL: Comma-separated list of allowed CORS origins
    allowedOrigins?: string;

    // OPTIONAL: Allowed scopes for dynamic client registration
    allowedScopes?: string[];

    // OPTIONAL: JWT audience claim (default: "convex")
    // Set to "oauth-provider" when using Better Auth to distinguish tokens
    applicationID?: string;

    // REQUIRED: Function to get authenticated user ID
    // Must return a Convex users table Id (string)
    // Returns null if user is not authenticated
    getUserId?: (ctx: ActionCtx, request: Request) => Promise<string | null> | string | null;

    // OPTIONAL: Enable dynamic client registration (default: false)
    allowDynamicClientRegistration?: boolean;
}

import { verifyAccessToken } from "@codefox-inc/oauth-provider";

const payload = await verifyAccessToken(
    token,
    {
        jwks: process.env.JWKS!,
        siteUrl: process.env.SITE_URL!,
        // If using Better Auth, specify the applicationID
        // applicationID: "oauth-provider",
    },
    issuerUrl
);

console.log("User ID:", payload.sub);
console.log("Scopes:", payload.scp);
console.log("Client ID:", payload.cid);

当使用多个认证系统(例如:Better Auth + OAuth Profer)时,您可以通过检查发件人来区分符:

import { isOAuthToken, getOAuthClientId } from "@codefox-inc/oauth-provider";

// Option 1: Using helper functions
const identity = await ctx.auth.getUserIdentity();
if (isOAuthToken(identity)) {
    const clientId = getOAuthClientId(identity);
    // Handle OAuth token (MCP clients, third-party apps)
} else {
    // Handle session token (first-party users)
}

// Option 2: Check issuer directly
if (identity?.issuer?.includes("/oauth")) {
    // This is an OAuth token
}