@codefox-inc/oauth-provider
OAuth 2.1 / OpenID Connect Provider implemented as a Convex component.
⚠️ Beta Software - Production use at your own risk.
Tested with Convex Auth and @convex-dev/better-auth.
接入你的智能体
從發布者安裝。不是 PlugMCP 端點。
遠端 URL 還是本機指令? 兩種安裝方式的差異
來自發布者
OAuth 2.1 / OpenID Connect Provider implemented as a Convex component.
⚠️ Beta Software - Production use at your own risk.
Tested with Convex Auth and @convex-dev/better-auth.
Turn your Convex Auth app into an OAuth 2.1 Provider — perfect for MCP servers
Most MCP clients (like Claude Code or ChatGPT) require your app to be an OAuth provider. If you want to connect your Convex app to MCP clients, you need to implement OAuth 2.1.
This component turns your Convex app into a fully compliant OAuth 2.1 provider, so you can:
bun add @codefox-inc/oauth-provider
typ: at+jwt, client_id, scope, jti)This implementation follows OAuth 2.1 and related OAuth/OIDC specifications:
resource values are bound to the authorization grant and refresh tokenaud is the authorized resource, or the configured default audienceissueAuthorizationCode are not directly accessibleThe /oauth/authorize endpoint performs comprehensive validation:
getUserId hookopenid: Required for OpenID Connect authentication and ID tokensprofile: Grants access to user profile information (name, picture)email: Grants access to user email addressoffline_access: Enables refresh token issuance for long-lived accessRefresh tokens are only issued when the offline_access scope is requested and granted during the initial authorization. For OpenID Connect requests, offline_access requires prompt=consent (or a space-delimited prompt value that includes consent):
offline_access: Client receives both access token and refresh tokenoffline_access: Client receives only access token (no refresh token)Refresh Token Grant Flow:
refresh_token grant type to obtain new access tokensoffline_access scopeThis follows OAuth 2.1 and OpenID Connect specifications, ensuring that long-lived refresh tokens are only issued with explicit user consent.
This provider supports RFC 8707 resource indicators for MCP and other resource-server flows.
resource is optional on the authorization request.resource.resource, but cannot add a new one that was not approved.resource as aud; otherwise they use applicationID or the default convex audience.For custom consent UIs, preserve the incoming resource parameter and pass it to issueAuthorizationCode.
Provides helper functions to distinguish between OAuth tokens and session tokens:
import { isOAuthToken, getOAuthClientId } from "@codefox-inc/oauth-provider";
const identity = await ctx.auth.getUserIdentity();
if (isOAuthToken(identity)) {
// Handle OAuth token (MCP client, third-party apps, etc.)
const clientId = getOAuthClientId(identity);
console.log("OAuth client:", clientId);
} else {
// Handle Convex Auth session (first-party user)
}
This component works with any authentication system. Choose the setup that matches your stack:
If you're using Convex Auth, you already have the required environment variables configured (JWT_PRIVATE_KEY, JWKS, SITE_URL).
If you're using @convex-dev/better-auth, you can share the same keys:
bunx convex env set OAUTH_PRIVATE_KEY "$(cat private.pem)" # Or use JWT_PRIVATE_KEY
bunx convex env set OAUTH_JWKS '{"keys":[...]}' # Or use JWKS
bunx convex env set SITE_URL "https://your-app.example.com"
Important: When using Better Auth, set applicationID: "oauth-provider" in your OAuthProvider config to distinguish OAuth tokens from Better Auth session tokens.
Generate RSA keys manually:
# 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' }] }));
})();
"
Set environment variables:
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/convex.config.ts
import { defineApp } from "convex/server";
import oauthProvider from "@codefox-inc/oauth-provider/convex.config";
const app = defineApp();
app.use(oauthProvider, { name: "oauthProvider" });
export default app;
// convex/http.ts
import { httpAction } from "./_generated/server";
import { httpRouter } from "convex/server";
import { OAuthProvider, registerOAuthRoutes } from "@codefox-inc/oauth-provider";
import { components } from "./_generated/api";
import { api } 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;
},
});
// Register all OAuth routes automatically
registerOAuthRoutes(http, httpAction, oauthProvider, {
siteUrl: process.env.SITE_URL!,
// OPTIONAL: Override the prefix used for route registration.
// By default, this uses oauthProvider's config prefix.
// prefix: "/oauth",
getUserProfile: async (ctx, userId) => {
// Return user profile for /oauth/userinfo endpoint
const user = await ctx.runQuery(api.users.get, { userId });
return user ? {
sub: userId,
name: user.name,
email: user.email,
picture: user.pictureUrl
} : null;
},
});
export default http;
// convex/http.ts
import { httpAction } from "./_generated/server";
import { httpRouter } from "convex/server";
import { OAuthProvider, registerOAuthRoutes } from "@codefox-inc/oauth-provider";
import { components } from "./_generated/api";
import { api } from "./_generated/api";
const http = httpRouter();
const oauthProvider = new OAuthProvider(components.oauthProvider, {
privateKey: process.env.OAUTH_PRIVATE_KEY ?? process.env.JWT_PRIVATE_KEY!,
jwks: process.env.OAUTH_JWKS ?? process.env.JWKS!,
siteUrl: process.env.SITE_URL!,
// IMPORTANT: Set applicationID to distinguish from Better Auth tokens
applicationID: "oauth-provider",
getUserId: async (ctx, request) => {
const identity = await ctx.auth.getUserIdentity();
return identity?.subject ?? null;
},
});
// Register Better Auth routes first (if using @convex-dev/better-auth)
// authComponent.registerRoutes(http, createAuth, { cors: true });
// Then register OAuth routes
registerOAuthRoutes(http, httpAction, oauthProvider, {
siteUrl: process.env.SITE_URL!,
getUserProfile: async (ctx, userId) => {
const user = await ctx.runQuery(api.users.get, { userId });
return user ? {
sub: userId,
name: user.name,
email: user.email,
picture: user.pictureUrl
} : null;
},
});
export default http;
// 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;
Requires openid scope. Returns claims based on scopes:
openid: Always returns subprofile: Adds name, pictureemail: Adds email (and email_verified if available)// 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;
},
});
The /oauth/authorize endpoint handles the complete authorization flow automatically:
GET /oauth/authorize?
response_type=code
&client_id=CLIENT_ID
&redirect_uri=REDIRECT_URI
&scope=openid+profile+email
&resource=https://api.example.com/mcp
&state=STATE
&code_challenge=CHALLENGE
&code_challenge_method=S256
&nonce=NONCE
The handler:
resource when providedgetUserIdIf you need custom consent UI, you can use the SDK methods directly:
// 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;
},
});
When the authorization request contains resource, show it in the consent UI and pass it through unchanged. If the token request asks for a resource that was not stored on the authorization code, the token endpoint returns 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;
}
Access tokens are JWTs and can be verified statelessly with the JWKS. Stateless verification alone cannot observe authorization revocation, authorization-code replay detection, or refresh-token family revocation until the access token expires.
For Convex resource servers, wire createAuthorizationChecker() into createAuthHelper() so bearer-token requests check the current authorization record:
import { createAuthHelper, OAuthProvider } from "@codefox-inc/oauth-provider";
import { components } from "./_generated/api";
const oauthProvider = new OAuthProvider(components.oauthProvider, {
privateKey: process.env.JWT_PRIVATE_KEY!,
jwks: process.env.JWKS!,
siteUrl: process.env.SITE_URL!,
});
export const authHelper = createAuthHelper({
providers: ["anonymous"],
checkAuthorization: oauthProvider.createAuthorizationChecker(),
});
If you verify access tokens outside Convex with verifyAccessToken() only, revoked access tokens remain valid until their exp time. Use short access-token lifetimes and a resource-server authorization check if immediate revocation is required.
After upgrading this component, rerun Convex code generation (for example convex dev --once or your repository's codegen script). The generated component references and schema must match the package version; prompt=none silent authorization also relies on the latest generated getAuthorization query reference.
import { query } from "./_generated/server";
export const protectedQuery = query({
handler: async (ctx) => {
const identity = await ctx.auth.getUserIdentity();
if (!identity) throw new Error("Not authenticated");
// Token is already verified by Convex Auth
// Use identity.subject for user ID
return { userId: identity.subject };
},
});
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);
When using multiple auth systems (e.g., Better Auth + OAuth Provider), you can distinguish tokens by checking the issuer:
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
}
bun run test
Apache-2.0
Turn your Convex Auth app into an OAuth 2.1 Provider — perfect for MCP servers
工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
Convex Oauth Provider 透過 stdio 在本機執行。
上次檢查時間:2026-10-27。 Turn your Convex Auth app into an OAuth 2.1 Provider — perfect for MCP servers