Skip to content

MongoDB-CE SCRAM-SHA-256 support

Choose a tag to compare

View all tags
@aarora79 aarora79 released this 07 Jan 22:28
· 1202 commits to main since this release
v1.0.9-patch1
5dc2471
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Release v1.0.9-patch1 - MongoDB Authentication Compatibility

January 7, 2026

Overview

This patch release addresses MongoDB authentication compatibility issues between MongoDB Community Edition and AWS DocumentDB. The changes enable the MCP Gateway Registry to work seamlessly with both MongoDB CE 8.2+ (using SCRAM-SHA-256) and AWS DocumentDB v5.0 (using SCRAM-SHA-1).

Related Issues:

  • #334 - Upgrade MongoDB authentication to SCRAM-SHA-256
  • #336 - Upgrade AWS DocumentDB authentication to SCRAM-SHA-256 (parking lot)

Pull Request:

  • #335 - Fix MongoDB authentication compatibility for DocumentDB

What's Fixed

MongoDB Authentication Compatibility

The registry now automatically selects the correct authentication mechanism based on the storage backend:

  • MongoDB CE 8.2+: Uses SCRAM-SHA-256 (stronger, modern authentication)
  • AWS DocumentDB v5.0: Uses SCRAM-SHA-1 (only mechanism we could get to work with Amazon DocumentDB although the documentation claims SCRAM-SHA-256 should work, tracking it via #336)

This is controlled by the new STORAGE_BACKEND environment variable:

# For MongoDB Community Edition
STORAGE_BACKEND=mongodb-ce

# For AWS DocumentDB (default)
STORAGE_BACKEND=documentdb

Pydantic Validation Fix

Fixed test failures in semantic search API models by adding upper bound validation to relevance scores:

# Before:
relevance_score: float = Field(0.0, ge=0.0)

# After:
relevance_score: float = Field(0.0, ge=0.0, le=1.0)

This ensures relevance scores are always bounded between 0.0 and 1.0, as expected.

Federation Command Fix

Fixed populate-registry.sh script federation command syntax:

# Before (incorrect):
federation-rescan --provider anthropic

# After (correct):
federation-sync --source anthropic

Integration Test Improvements

Added skip markers to MongoDB integration tests that require MongoDB to be running, preventing false failures in CI environments where MongoDB is not available.

Changed Files

Core Authentication Changes

  • registry/repositories/documentdb/client.py - Conditional SCRAM authentication based on storage backend
  • scripts/init-documentdb-indexes.py - Added storage_backend parameter
  • scripts/load-scopes.py - Conditional SCRAM mechanism selection
  • scripts/manage-documentdb.py - Conditional SCRAM mechanism selection
  • scripts/debug-scopes.py - Conditional SCRAM mechanism selection
  • registry/scripts/inspect-documentdb.py - Conditional SCRAM mechanism selection

Build and Deployment

  • docker/Dockerfile.registry - Added scripts directory to container
  • terraform/aws-ecs/documentdb.tf - Added STORAGE_BACKEND environment variable
  • terraform/aws-ecs/keycloak-ecr.tf - Version update
  • terraform/aws-ecs/modules/mcp-gateway/ecs-services.tf - Added STORAGE_BACKEND to all services

Scripts and Configuration

  • api/populate-registry.sh - Fixed federation-sync command syntax
  • .env.example - Added STORAGE_BACKEND documentation

API and Test Fixes

  • registry/api/search_routes.py - Added upper bound validation to relevance_score fields
  • tests/integration/test_mongodb_connectivity.py - Added skip decorators to MongoDB tests

Upgrade Instructions

For Docker Compose Deployments

  1. Pull the latest changes:
cd mcp-gateway-registry
git pull origin main
git checkout v1.0.9-patch1
  1. Update environment configuration:
# For MongoDB CE deployments, add:
echo "STORAGE_BACKEND=mongodb-ce" >> .env

# For DocumentDB deployments (default), no changes needed
# STORAGE_BACKEND defaults to "documentdb"
  1. Rebuild and restart:
./build_and_run.sh

For AWS ECS Deployment

  1. Update Terraform configuration:

The STORAGE_BACKEND environment variable is already set to documentdb in the Terraform configuration. No changes are required for DocumentDB deployments.

  1. Pull and deploy new images:
# Build and push updated images
export AWS_REGION=us-east-1
make build-push

# Force ECS service update
aws ecs update-service \
  --cluster mcp-gateway-ecs-cluster \
  --service mcp-gateway-v2-registry \
  --force-new-deployment

# For auth server
aws ecs update-service \
  --cluster mcp-gateway-ecs-cluster \
  --service mcp-gateway-v2-auth \
  --force-new-deployment

Testing the Upgrade

Verify authentication is working correctly:

# Check logs for authentication mechanism
aws logs tail /ecs/mcp-gateway-v2-registry --follow | grep "authentication"

# Expected output:
# Using username/password authentication (SCRAM-SHA-1) for documentdb

# Or for MongoDB CE:
# Using username/password authentication (SCRAM-SHA-256) for mongodb-ce

Technical Details

Authentication Mechanism Selection

The conditional authentication logic in client.py:

if settings.storage_backend == "mongodb-ce":
    # MongoDB CE 8.2+: Use SCRAM-SHA-256 (stronger, modern authentication)
    auth_mechanism = "SCRAM-SHA-256"
else:
    # AWS DocumentDB v5.0: Only supports SCRAM-SHA-1
    auth_mechanism = "SCRAM-SHA-1"

connection_string = (
    f"mongodb://{settings.documentdb_username}:{settings.documentdb_password}@"
    f"{settings.documentdb_host}:{settings.documentdb_port}/"
    f"{settings.documentdb_database}?authMechanism={auth_mechanism}&authSource=admin"
)

Environment Variables

New environment variable:

  • STORAGE_BACKEND - Controls authentication mechanism selection
    • documentdb (default) - Use SCRAM-SHA-1 for AWS DocumentDB
    • mongodb-ce - Use SCRAM-SHA-256 for MongoDB Community Edition

Why This Change?

AWS DocumentDB v5.0 only supports two authentication mechanisms:

  • SCRAM-SHA-1 (username/password)
  • MONGODB-AWS (IAM authentication)

MongoDB Community Edition 8.2+ defaults to SCRAM-SHA-256 for improved security. This patch enables seamless operation with both backends without requiring code changes.

Breaking Changes

None. This is a backward-compatible patch release. Existing deployments will continue to work:

  • DocumentDB deployments: STORAGE_BACKEND defaults to documentdb, using SCRAM-SHA-1
  • MongoDB CE deployments: Can now explicitly set STORAGE_BACKEND=mongodb-ce to use SCRAM-SHA-256

Known Limitations

  • AWS DocumentDB: Still uses SCRAM-SHA-1 authentication. Upgrade to SCRAM-SHA-256 is tracked in #336 and depends on AWS adding SCRAM-SHA-256 support to DocumentDB.

Resources

Documentation

Related Issues and PRs

  • #334 - Original issue: Upgrade MongoDB authentication to SCRAM-SHA-256
  • #335 - Implementation PR
  • #336 - Future work: DocumentDB SCRAM-SHA-256 support

Commits Included

5dc2471 Fix MongoDB authentication compatibility for DocumentDB (#335)
252869c Rewrite roadmap section with milestone-based table format
5761054 Move completed issues #70 and #48 to Completed section

Files Changed: 16 files changed, 461 insertions(+), 106 deletions(-)

Support

Full Changelog: v1.0.9...v1.0.9-patch1

What's Changed

  • Fix MongoDB authentication compatibility for DocumentDB by @aarora79 in #335

Full Changelog: v1.0.9...v1.0.9-patch1

Contributors

aarora79
Assets 2
Loading