Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🔐 feat: Support Cognito Access Tokens for Agent Management (#16224)
Dustin Healy418d62d52d25
diff --git a/librechat.example.yaml b/librechat.example.yamlindex 6c1cba99c0..4a628517b9 100644--- a/librechat.example.yaml+++ b/librechat.example.yaml@@ -768,6 +768,10 @@ endpoints:# issuer: 'https://identity.example.com/'# audience: 'https://librechat.example.com/agents'# # jwksUri: 'https://identity.example.com/.well-known/jwks.json'+ # # Cognito M2M access tokens use client_id instead of aud. For that+ # # profile, omit audience and require the access-token type and scope:+ # # tokenUse: access+ # # requiredScopes: ['agents-api/manage']# clients:# - clientId: 'machine-client-id'# # subject: 'provider-specific-service-principal-subject'diff --git a/packages/api/src/auth/oidc.cognito.spec.ts b/packages/api/src/auth/oidc.cognito.spec.tsnew file mode 100644index 0000000000..6a62f2f759--- /dev/null+++ b/packages/api/src/auth/oidc.cognito.spec.ts@@ -0,0 +1,205 @@+import jwt from 'jsonwebtoken';+import { Types } from 'mongoose';+import { createServer } from 'http';+import { generateKeyPairSync } from 'crypto';+import { getTenantId } from '@librechat/data-schemas';+import type { AppConfig, IUser } from '@librechat/data-schemas';+import type { Server, ServerResponse } from 'http';+import type { Request, Response } from 'express';+import type { JwtPayload } from 'jsonwebtoken';+import type { AddressInfo } from 'net';+import { clearOidcAccessTokenCache, verifyOidcAccessToken } from './oidc';+import { createAgentManagementAuth } from '../middleware/management';++const CLIENT_ID = 'cognito-machine-client';+const USER_ID = '507f1f77bcf86cd799439011';+const TENANT_ID = 'tenant-a';+const REQUIRED_SCOPE = 'agents-api/manage';+const KEY_ID = 'cognito-access-key';++const keyPair = generateKeyPairSync('rsa', { modulusLength: 2048 });+const publicJwk = {+ ...keyPair.publicKey.export({ format: 'jwk' }),+ alg: 'RS256',+ kid: KEY_ID,+ use: 'sig',+};++let issuer: string;+let server: Server;++function sendJson(res: ServerResponse, body: unknown): void {+ res.writeHead(200, { 'Content-Type': 'application/json' });+ res.end(JSON.stringify(body));+}++function signAccessToken(overrides: JwtPayload = {}): string {+ const now = Math.floor(Date.now() / 1000);+ return jwt.sign(+ {+ sub: CLIENT_ID,+ iss: issuer,+ client_id: CLIENT_ID,+ token_use: 'access',+ scope: `${REQUIRED_SCOPE} another-scope`,+ iat: now,+ exp: now + 300,+ ...overrides,+ },+ keyPair.privateKey,+ { algorithm: 'RS256', keyid: KEY_ID },+ );+}++function createConfig(): AppConfig {+ return {+ endpoints: {+ agents: {+ managementApi: {+ auth: {+ oidc: {+ enabled: true,+ issuer,+ tokenUse: 'access',+ requiredScopes: [REQUIRED_SCOPE],+ },+ clients: [+ {+ clientId: CLIENT_ID,+ userId: USER_ID,+ tenantId: TENANT_ID,+ enabled: true,+ },+ ],+ },+ },+ },+ },+ } as AppConfig;+}++function createUser(): IUser {+ return {+ _id: new Types.ObjectId(USER_ID),+ email: '[email protected]',+ name: 'Integration',+ username: 'integration',+ provider: 'local',+ role: 'USER',+ tenantId: TENANT_ID,+ } as IUser;+}++function createResponse(): Response {+ const res = { status: jest.fn(), json: jest.fn() };+ res.status.mockReturnValue(res);+ res.json.mockReturnValue(res);+ return res as unknown as Response;+}++beforeAll(async () => {+ server = createServer((req, res) => {+ if (req.url === '/.well-known/openid-configuration') {+ sendJson(res, { issuer, jwks_uri: `${issuer}/.well-known/jwks.json` });+ return;+ }+ if (req.url === '/.well-known/jwks.json') {+ sendJson(res, { keys: [publicJwk] });+ return;+ }+ res.writeHead(404).end();+ });+ await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));+ const address = server.address() as AddressInfo;+ issuer = `http://127.0.0.1:${address.port}`;+});++afterEach(() => {+ clearOidcAccessTokenCache();+});++afterAll(async () => {+ await new Promise<void>((resolve, reject) =>+ server.close((error) => (error ? reject(error) : resolve())),+ );+});++it('verifies a Cognito-shaped access token through discovery and JWKS', async () => {+ await expect(+ verifyOidcAccessToken(signAccessToken(), {+ issuer,+ tokenUse: 'access',+ requiredScopes: [REQUIRED_SCOPE],+ }),+ ).resolves.toMatchObject({+ sub: CLIENT_ID,+ client_id: CLIENT_ID,+ token_use: 'access',+ scope: `${REQUIRED_SCOPE} another-scope`,+ });+});++it.each([+ ['an ID token', { token_use: 'id' }],+ ['a missing required scope', { scope: 'another-scope' }],+ ['a different issuer', { iss: 'https://other-issuer.example.com' }],+ ['an expired token', { exp: Math.floor(Date.now() / 1000) - 1 }],+])('rejects %s after real signature verification', async (_case, overrides) => {+ await expect(+ verifyOidcAccessToken(signAccessToken(overrides), {+ issuer,+ tokenUse: 'access',+ requiredScopes: [REQUIRED_SCOPE],+ }),+ ).rejects.toThrow();+});++it('authenticates and binds a Cognito machine client to its configured tenant user', async () => {+ const findUser = jest.fn().mockImplementation(async () => {+ expect(getTenantId()).toBe(TENANT_ID);+ return createUser();+ });+ const middleware = createAgentManagementAuth({+ getAppConfig: jest.fn().mockResolvedValue(createConfig()),+ findUser,+ isPrincipalActive: jest.fn().mockResolvedValue(true),+ });+ const req = {+ headers: { authorization: `Bearer ${signAccessToken()}` },+ } as Request;+ const res = createResponse();+ const next = jest.fn();++ await middleware(req, res, next);++ expect(findUser).toHaveBeenCalledWith({ _id: USER_ID, tenantId: TENANT_ID });+ expect(req.user).toMatchObject({ id: USER_ID, tenantId: TENANT_ID, role: 'USER' });+ expect((req as Request & { authStrategy?: string }).authStrategy).toBe('agentManagementM2M');+ expect(next).toHaveBeenCalledTimes(1);+ expect(res.status).not.toHaveBeenCalled();+});++it('rejects a valid token whose signed client ID has no configured binding', async () => {+ const findUser = jest.fn();+ const middleware = createAgentManagementAuth({+ getAppConfig: jest.fn().mockResolvedValue(createConfig()),+ findUser,+ isPrincipalActive: jest.fn(),+ });+ const req = {+ headers: {+ authorization: `Bearer ${signAccessToken({+ sub: 'other-client',+ client_id: 'other-client',+ })}`,+ },+ } as Request;+ const res = createResponse();+ const next = jest.fn();++ await middleware(req, res, next);++ expect(findUser).not.toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(401);+ expect(next).not.toHaveBeenCalled();+});diff --git a/packages/api/src/auth/oidc.spec.ts b/packages/api/src/auth/oidc.spec.tsindex 7153f491f0..be3f35242e 100644--- a/packages/api/src/auth/oidc.spec.ts+++ b/packages/api/src/auth/oidc.spec.ts@@ -1,7 +1,7 @@import jwt from 'jsonwebtoken';import jwksRsa from 'jwks-rsa';import { fetch as undiciFetch } from 'undici';-import type { JwtPayload } from 'jsonwebtoken';+import type { JwtPayload, VerifyOptions } from 'jsonwebtoken';import { clearOidcAccessTokenCache, verifyOidcAccessToken } from './oidc';const mockGetSigningKey = jest.fn();@@ -62,6 +62,12 @@ it('does not use the interactive OpenID JWKS override unless explicitly enabled'jwksRequestsPerMinute: 10,}),);+ expect(mockVerify).toHaveBeenCalledWith(+ 'access-token',+ 'public-key',+ expect.objectContaining({ audience: 'agent-management' }),+ expect.any(Function),+ );});it('does not reuse an interactive OpenID JWKS override for a machine-token caller', async () => {@@ -93,3 +99,56 @@ it('does not reuse an interactive OpenID JWKS override for a machine-token calleexpect.objectContaining({ jwksUri: discoveredJwksUri }),);});++it('validates a Cognito access token without requiring an aud claim', async () => {+ const issuer = 'https://cognito-idp.us-west-2.amazonaws.com/us-west-2_example';+ mockFetch.mockResolvedValue({+ ok: true,+ json: async () => ({ jwks_uri: `${issuer}/.well-known/jwks.json` }),+ });+ mockDecode.mockReturnValue({ header: { kid: 'cognito-key' } });+ mockGetSigningKey.mockResolvedValue({ getPublicKey: () => 'public-key' });+ mockVerify.mockImplementation(+ (_token: string, _key: string, options: VerifyOptions, callback: JwtVerifyCallback) => {+ expect(options).not.toHaveProperty('audience');+ callback(null, {+ client_id: 'machine-client',+ token_use: 'access',+ scope: 'agents-api/manage another-scope',+ } satisfies JwtPayload);+ },+ );++ await expect(+ verifyOidcAccessToken('cognito-access-token', {+ issuer,+ tokenUse: 'access',+ requiredScopes: ['agents-api/manage'],+ }),+ ).resolves.toMatchObject({ client_id: 'machine-client' });+});++it.each([+ ['the token type is wrong', { token_use: 'id', scope: 'agents-api/manage' }],+ ['a required scope is missing', { token_use: 'access', scope: 'another-scope' }],+])('rejects a Cognito token when %s', async (_case, claims) => {+ const issuer = 'https://cognito-idp.us-west-2.amazonaws.com/us-west-2_example';+ mockFetch.mockResolvedValue({+ ok: true,+ json: async () => ({ jwks_uri: `${issuer}/.well-known/jwks.json` }),+ });+ mockDecode.mockReturnValue({ header: { kid: 'cognito-key' } });+ mockGetSigningKey.mockResolvedValue({ getPublicKey: () => 'public-key' });+ mockVerify.mockImplementation(+ (_token: string, _key: string, _options: VerifyOptions, callback: JwtVerifyCallback) =>+ callback(null, claims satisfies JwtPayload),+ );++ await expect(+ verifyOidcAccessToken('cognito-access-token', {+ issuer,+ tokenUse: 'access',+ requiredScopes: ['agents-api/manage'],+ }),+ ).rejects.toThrow();+});diff --git a/packages/api/src/auth/oidc.ts b/packages/api/src/auth/oidc.tsindex 8f6444476b..a8850de44a 100644--- a/packages/api/src/auth/oidc.ts+++ b/packages/api/src/auth/oidc.ts@@ -9,9 +9,11 @@ import { normalizeOpenIdIssuer } from './openid';import { isEnabled, math } from '~/utils';export interface OidcAccessTokenConfig {- audience: string;+ audience?: string;issuer: string;jwksUri?: string;+ requiredScopes?: string[];+ tokenUse?: 'access';}export interface OidcAccessTokenOptions {@@ -208,11 +210,31 @@ function getVerifyOptions(oidcConfig: OidcAccessTokenConfig): VerifyOptions {? [oidcConfig.issuer, normalizedIssuer]: oidcConfig.issuer;- return {+ const options: VerifyOptions = {algorithms: JWT_ALGORITHMS,- audience: oidcConfig.audience,issuer,};+ if (oidcConfig.audience) options.audience = oidcConfig.audience;+ return options;+}++function verifyAccessTokenClaims(+ payload: JwtPayload,+ oidcConfig: OidcAccessTokenConfig,+): JwtPayload {+ if (oidcConfig.tokenUse && payload.token_use !== oidcConfig.tokenUse) {+ throw new Error('Invalid JWT token use');+ }++ if (oidcConfig.requiredScopes?.length) {+ const scope = typeof payload.scope === 'string' ? payload.scope.trim().split(/\s+/) : [];+ const grantedScopes = new Set(scope.filter(Boolean));+ if (!oidcConfig.requiredScopes.every((requiredScope) => grantedScopes.has(requiredScope))) {+ throw new Error('Invalid JWT scope');+ }+ }++ return payload;}function verifyJwt(@@ -224,7 +246,11 @@ function verifyJwt(jwt.verify(token, signingKey.getPublicKey(), getVerifyOptions(oidcConfig), (err, payload) => {if (err != null || payload == null) return reject(err ?? new Error('Empty payload'));if (typeof payload === 'string') return reject(new Error('Invalid JWT payload'));- resolve(payload);+ try {+ resolve(verifyAccessTokenClaims(payload, oidcConfig));+ } catch (claimError) {+ reject(claimError);+ }});});}diff --git a/packages/api/src/middleware/management.spec.ts b/packages/api/src/middleware/management.spec.tsindex 1423ad8db2..c0fed4c4fa 100644--- a/packages/api/src/middleware/management.spec.ts+++ b/packages/api/src/middleware/management.spec.ts@@ -134,6 +134,39 @@ describe('getMachineClientId', () => {expect(next).toHaveBeenCalledTimes(1);});+ it('passes Cognito access-token requirements to the verifier', async () => {+ const config = createConfig();+ const oidc = config.endpoints?.agents?.managementApi?.auth?.oidc;+ if (oidc) {+ delete oidc.audience;+ oidc.tokenUse = 'access';+ oidc.requiredScopes = ['agents-api/manage'];+ }+ const deps = createDeps({+ getAppConfig: jest.fn().mockResolvedValue(config),+ verifyAccessToken: jest.fn().mockResolvedValue(+ createPayload({+ azp: undefined,+ client_id: CLIENT_ID,+ sub: CLIENT_ID,+ token_use: 'access',+ scope: 'agents-api/manage',+ }),+ ),+ });+ const next = jest.fn();++ await runMiddleware(deps, createRequest(), createResponse(), next);++ expect(deps.verifyAccessToken).toHaveBeenCalledWith(TOKEN, {+ enabled: true,+ issuer: 'https://issuer.example.com',+ tokenUse: 'access',+ requiredScopes: ['agents-api/manage'],+ });+ expect(next).toHaveBeenCalledTimes(1);+ });+it.each([['the default subject rule', createConfig(), createPayload({ sub: 'auth0|human-user' })],[@@ -241,6 +274,26 @@ describe('createAgentManagementAuth', () => {expect(res.status).toHaveBeenCalledWith(401);});+ it('rejects audience-less access-token auth without required scopes before verification', async () => {+ const config = createConfig();+ const oidc = config.endpoints?.agents?.managementApi?.auth?.oidc;+ if (oidc) {+ delete oidc.audience;+ oidc.tokenUse = 'access';+ delete oidc.requiredScopes;+ }+ const deps = createDeps({ getAppConfig: jest.fn().mockResolvedValue(config) });+ const res = createResponse();+ const next = jest.fn();++ await runMiddleware(deps, createRequest(), res, next);++ expect(deps.verifyAccessToken).not.toHaveBeenCalled();+ expect(deps.findUser).not.toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(401);+ expect(next).not.toHaveBeenCalled();+ });+it.each([['unknown', createPayload({ azp: 'unknown', sub: 'unknown@clients' }), createConfig()],[diff --git a/packages/api/src/middleware/management.ts b/packages/api/src/middleware/management.tsindex ce42e1b73b..ce89599744 100644--- a/packages/api/src/middleware/management.ts+++ b/packages/api/src/middleware/management.ts@@ -21,7 +21,7 @@ type ManagementApi = NonNullable<TAgentsEndpoint['managementApi']>;type ManagementAuth = NonNullable<ManagementApi['auth']>;type ManagementOidc = NonNullable<ManagementAuth['oidc']>;type ManagementClient = ManagementAuth['clients'][number];-type EnabledManagementOidc = ManagementOidc & { audience: string; issuer: string };+type EnabledManagementOidc = ManagementOidc & { issuer: string };type PrincipalResolution =| { status: 'resolved'; user: IUser }@@ -47,15 +47,17 @@ function getEnabledAuth(config: AppConfig,): { auth: ManagementAuth; oidc: EnabledManagementOidc } | undefined {const auth = config.endpoints?.agents?.managementApi?.auth;- if (auth?.oidc?.enabled !== true || !auth.oidc.issuer || !auth.oidc.audience) {+ const oidc = auth?.oidc;+ const hasAudience = Boolean(oidc?.audience);+ const hasScopedAccessToken = oidc?.tokenUse === 'access' && Boolean(oidc.requiredScopes?.length);+ if (!auth || oidc?.enabled !== true || !oidc.issuer || (!hasAudience && !hasScopedAccessToken)) {return;}return {auth,oidc: {- ...auth.oidc,- audience: auth.oidc.audience,- issuer: auth.oidc.issuer,+ ...oidc,+ issuer: oidc.issuer,},};}diff --git a/packages/data-provider/src/config.spec.ts b/packages/data-provider/src/config.spec.tsindex c33514fd2c..d41e03d260 100644--- a/packages/data-provider/src/config.spec.ts+++ b/packages/data-provider/src/config.spec.ts@@ -334,6 +334,121 @@ describe('Agent Management authentication config', () => {expect(result.data.endpoints?.agents?.managementApi?.auth?.clients[0].subject).toBe(subject);});+ it('accepts Cognito access-token validation', () => {+ const result = configSchema.safeParse({+ version: '1.0',+ endpoints: {+ agents: {+ managementApi: {+ auth: {+ oidc: {+ enabled: true,+ issuer: 'https://cognito-idp.us-west-2.amazonaws.com/us-west-2_example',+ tokenUse: 'access',+ requiredScopes: ['agents-api/manage'],+ },+ clients: [binding],+ },+ },+ },+ },+ });++ expect(result.success).toBe(true);+ });++ it('accepts audience-bound access-token validation without required scopes', () => {+ const result = configSchema.safeParse({+ version: '1.0',+ endpoints: {+ agents: {+ managementApi: {+ auth: {+ oidc: {+ enabled: true,+ issuer: 'https://issuer.example.com',+ audience: 'https://agents.example.com',+ tokenUse: 'access',+ },+ clients: [binding],+ },+ },+ },+ },+ });++ expect(result.success).toBe(true);+ });++ it('rejects audience-less access-token validation without required scopes', () => {+ const result = configSchema.safeParse({+ version: '1.0',+ endpoints: {+ agents: {+ managementApi: {+ auth: {+ oidc: {+ enabled: true,+ issuer: 'https://issuer.example.com',+ tokenUse: 'access',+ },+ clients: [binding],+ },+ },+ },+ },+ });++ expect(result.success).toBe(false);+ });++ it.each(['agents-api/manage another-scope', 'agents-api/manage\tanother-scope'])(+ 'rejects a required scope containing whitespace: %j',+ (requiredScope) => {+ const result = configSchema.safeParse({+ version: '1.0',+ endpoints: {+ agents: {+ managementApi: {+ auth: {+ oidc: {+ enabled: true,+ issuer: 'https://issuer.example.com',+ tokenUse: 'access',+ requiredScopes: [requiredScope],+ },+ clients: [binding],+ },+ },+ },+ },+ });++ expect(result.success).toBe(false);+ },+ );++ it('rejects enabled management auth without an audience or access-token validation', () => {+ const result = configSchema.safeParse({+ version: '1.0',+ endpoints: {+ agents: {+ managementApi: {+ auth: {+ oidc: {+ enabled: true,+ issuer: 'https://issuer.example.com',+ },+ clients: [binding],+ },+ },+ },+ },+ });++ expect(result.success).toBe(false);+ });+it('normalizes binding User ObjectIds', () => {const result = configSchema.safeParse({version: '1.0',diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.tsindex 4eae516f8b..18747628d1 100644--- a/packages/data-provider/src/config.ts+++ b/packages/data-provider/src/config.ts@@ -928,7 +928,37 @@ const managementClientBindingSchema = z}).strict();-const managementApiOidcSchema = oidcAccessTokenSchema.strict().superRefine(validateEnabledOidc);+const managementApiOidcSchema = oidcAccessTokenSchema+ .extend({+ tokenUse: z.literal('access').optional(),+ requiredScopes: z+ .array(z.string().trim().min(1).max(256).regex(/^\S+$/, 'must be a single scope token'))+ .min(1)+ .max(20)+ .optional(),+ })+ .strict()+ .superRefine((oidc, ctx) => {+ if (oidc.enabled === true && !oidc.issuer) {+ ctx.addIssue({+ code: z.ZodIssueCode.custom,+ path: ['issuer'],+ message: 'issuer is required when OIDC auth is enabled',+ });+ }+ if (+ oidc.enabled === true &&+ !oidc.audience &&+ (oidc.tokenUse !== 'access' || !oidc.requiredScopes?.length)+ ) {+ ctx.addIssue({+ code: z.ZodIssueCode.custom,+ path: ['requiredScopes'],+ message:+ 'audience or access-token validation with required scopes is required when OIDC auth is enabled',+ });+ }+ });const managementApiAuthSchema = z.object({