LibreChat/docs/oidc-token-implementation.md

OpenID Connect Federated Provider Token Implementation

Overview

This implementation adds support for passing federated provider tokens (Cognito, Azure AD, Auth0, etc.) as variables in LibreChat's librechat.yaml configuration for both custom endpoints and MCP servers. These are the actual tokens issued by your federated identity provider, enabling downstream services to validate and authorize users directly.

Features

Supported Variables

• {{LIBRECHAT_OPENID_TOKEN}} - The current user's access token from federated provider (default)
• {{LIBRECHAT_OPENID_ACCESS_TOKEN}} - Access token specifically from federated provider
• {{LIBRECHAT_OPENID_ID_TOKEN}} - ID token with user claims from federated provider
• {{LIBRECHAT_OPENID_USER_ID}} - User ID from federated provider token (subject claim)
• {{LIBRECHAT_OPENID_USER_EMAIL}} - User email from federated provider token
• {{LIBRECHAT_OPENID_USER_NAME}} - User name from federated provider token
• {{LIBRECHAT_OPENID_EXPIRES_AT}} - Token expiration timestamp

Usage Examples

Custom Endpoints with Cognito

endpoints:
  custom:
    - name: 'CognitoProtectedAPI'
      apiKey: '${API_KEY}'
      baseURL: 'https://api.example.com'
      headers:
        Authorization: 'Bearer {{LIBRECHAT_OPENID_TOKEN}}'
        X-Cognito-User-ID: '{{LIBRECHAT_OPENID_USER_ID}}'
        X-User-Email: '{{LIBRECHAT_OPENID_USER_EMAIL}}'
      models:
        default: ['gpt-4']

MCP Servers with AWS Cognito

mcpServers:
  aws-cognito-service:
    command: node
    args:
      - server.js
    env:
      COGNITO_ACCESS_TOKEN: '{{LIBRECHAT_OPENID_ACCESS_TOKEN}}'
      COGNITO_ID_TOKEN: '{{LIBRECHAT_OPENID_ID_TOKEN}}'
      USER_SUB: '{{LIBRECHAT_OPENID_USER_ID}}'
      USER_EMAIL: '{{LIBRECHAT_OPENID_USER_EMAIL}}'

  cognito-http-service:
    type: sse
    url: 'https://mcp.example.com/sse'
    headers:
      Authorization: 'Bearer {{LIBRECHAT_OPENID_TOKEN}}'
      X-Cognito-ID-Token: '{{LIBRECHAT_OPENID_ID_TOKEN}}'
      X-User-Info: '{{LIBRECHAT_OPENID_USER_EMAIL}}'

Azure AD Example

mcpServers:
  azure-ad-service:
    command: node
    args:
      - azure-server.js
    env:
      AZURE_ACCESS_TOKEN: '{{LIBRECHAT_OPENID_ACCESS_TOKEN}}'
      AZURE_ID_TOKEN: '{{LIBRECHAT_OPENID_ID_TOKEN}}'
      AAD_USER_OID: '{{LIBRECHAT_OPENID_USER_ID}}'

Implementation Details

Architecture

The implementation extends LibreChat's existing template variable system:

1. OpenID Connect Module (packages/api/src/utils/oidc.ts)

   • Federated token extraction from user session (Cognito, Azure AD, Auth0, etc.)
   • Token validation and expiration checking
   • JWT claims parsing for ID tokens
   • Placeholder processing for federated provider tokens
   • Security utilities

2. Integration (packages/api/src/utils/env.ts)

   • Extended processSingleValue() function
   • OpenID Connect federated provider placeholder resolution
   • Maintains backward compatibility with existing variables

Security Features

• Federated Token Validation: Checks token expiration before processing
• OpenID Connect Availability: Validates OpenID Connect configuration exists
• Secure Processing: Only processes valid, non-expired federated provider tokens
• JWT Claims Parsing: Safely extracts claims from ID tokens without verification
• Error Handling: Graceful fallbacks for missing or invalid tokens
• Provider Agnostic: Works with Cognito, Azure AD, Auth0, Keycloak, etc.

Token Flow

1. User authenticates via federated OpenID Connect provider (Cognito, Azure AD, etc.)
2. Federated provider tokens stored in user session/object
3. Configuration parsing extracts OpenID Connect placeholders
4. processSingleValue() calls federated token processor
5. Valid federated tokens replace placeholders
6. Raw provider tokens passed to downstream services for validation

Configuration Requirements

Environment Variables

OpenID Connect federated provider must be properly configured with:

For AWS Cognito:

OPENID_CLIENT_ID=your-cognito-client-id
OPENID_CLIENT_SECRET=your-cognito-client-secret
OPENID_ISSUER=https://cognito-idp.region.amazonaws.com/us-east-1_POOL123

For Azure AD:

OPENID_CLIENT_ID=your-azure-app-id
OPENID_CLIENT_SECRET=your-azure-client-secret
OPENID_ISSUER=https://login.microsoftonline.com/tenant-id/v2.0

For Auth0:

OPENID_CLIENT_ID=your-auth0-client-id
OPENID_CLIENT_SECRET=your-auth0-client-secret
OPENID_ISSUER=https://your-domain.auth0.com/

LibreChat Configuration

Enable OIDC in your LibreChat registration:

registration:
  socialLogins: ['openid']

Security Considerations

Federated Token Security

• Server-side Processing: Federated provider tokens are only processed server-side
• Expiration Validation: Expired tokens are automatically rejected
• No Client Exposure: Tokens never stored in client-side configuration
• Pre-validation: Tokens validated before each use
• JWT Claims: ID token claims safely extracted without verification

Best Practices

1. Use HTTPS: Always use HTTPS for downstream services receiving tokens
2. Token Scopes: Ensure federated provider tokens have appropriate scopes
3. Token Validation: Downstream services should validate received federated tokens
4. Expiration Monitoring: Monitor token expiration and refresh cycles
5. Provider-Specific: Configure according to your federated provider (Cognito, Azure AD, etc.)

Federated Provider Considerations

AWS Cognito:

• Use sub claim for user identification
• Validate tokens against Cognito User Pool
• Consider token refresh for long-running sessions

Azure AD:

• Use oid or sub claim for user identification
• Validate tokens against Azure AD tenant
• Configure appropriate scopes (openid, profile, email)

Auth0:

• Use sub claim for user identification
• Validate tokens against Auth0 domain
• Configure custom claims as needed

Risk Mitigation

• No Token Exposure: Tokens never appear in logs or client responses
• Validation Layer: Multi-level validation prevents invalid token usage
• Graceful Degradation: System continues working if OIDC unavailable
• Error Isolation: OIDC failures don't break other functionality

Testing

Comprehensive test suite covers:

• Federated token extraction from multiple storage locations
• JWT claims parsing from ID tokens
• Provider-specific scenarios (Cognito, Azure AD examples)
• Placeholder processing for all variable types
• Integration with existing LibreChat systems
• Security edge cases and error handling
• Token expiration and validation scenarios

Run tests:

npm test -- src/tests/oidc-integration.test.ts

Migration Guide

Existing Deployments

1. Update Code: Apply the implementation changes
2. Configure Federated Provider: Set up OpenID Connect environment variables for your provider (Cognito, Azure AD, etc.)
3. Update Config: Add OpenID Connect variables to librechat.yaml
4. Verify Token Storage: Ensure federated provider tokens are stored in user session
5. Test Integration: Verify downstream services receive and validate federated provider tokens
6. Monitor: Check logs for any integration issues

Backward Compatibility

• Existing configurations continue working unchanged
• New OpenID Connect variables are additive, not replacing existing functionality
• Non-OpenID Connect users see no functional changes
• All existing template variables remain supported
• Works alongside current {{LIBRECHAT_USER_*}} and {{LIBRECHAT_BODY_*}} variables

Troubleshooting

Common Issues

1. Empty Token Values

   • Check OpenID Connect federated provider configuration
   • Verify user authenticated via federated provider (not local auth)
   • Confirm federated tokens stored in user session
   • Check token not expired

2. Authentication Failures

   • Validate downstream service expects federated provider tokens
   • Verify downstream service configured to validate against your provider
   • Check token scopes and permissions from federated provider
   • Verify HTTPS endpoints

3. Variable Not Replaced

   • Confirm user authenticated via OpenID Connect (not Google, Facebook, etc.)
   • Check federated token validity and expiration
   • Verify placeholder syntax uses OPENID not OIDC
   • Ensure tokens stored in federatedTokens or openidTokens

Debug Steps

1. Check LibreChat logs for OpenID Connect errors
2. Verify federated provider environment variables set correctly
3. Test OpenID Connect authentication flow
4. Confirm federated tokens are stored in user session
5. Validate downstream service configuration for your provider
6. Monitor federated token expiration times
7. Test token validation with your federated provider's validation endpoint

Future Enhancements

Potential Improvements

1. Token Refresh: Automatic token refresh handling
2. Scope Validation: Verify token scopes match requirements
3. Multi-Provider: Support multiple OIDC providers
4. Token Claims: Access to specific JWT claims
5. Caching: Token caching for performance optimization

Integration Opportunities

• Integration with existing session management
• Enhanced MCP server authentication
• Custom endpoint security improvements
• Audit logging for token usage
• Advanced claim-based authorization

Support

For issues or questions:

1. Check the troubleshooting section
2. Review LibreChat documentation
3. Submit GitHub issues with relevant logs
4. Include OIDC provider and configuration details (without secrets)

License

This implementation follows LibreChat's existing license terms.