Skip to content

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

🔐 feat: Support Cognito Access Tokens for Agent Management (#16224)

Dustin Healy418d62d52d25
diff --git a/librechat.example.yaml b/librechat.example.yaml
index 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.ts
new file mode 100644
index 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.ts
index 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 calle
expect.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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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({