diff --git a/source/atlas-sfp-testing/atlas-sfp-testing.md b/source/atlas-sfp-testing/atlas-sfp-testing.md new file mode 100644 index 0000000000..b687161362 --- /dev/null +++ b/source/atlas-sfp-testing/atlas-sfp-testing.md @@ -0,0 +1,120 @@ +# Atlas Secure Frontend Processor (SFP) Testing + +- Status: Accepted +- Minimum Server Version: 7.0 + +______________________________________________________________________ + +## Abstract + +This specification defines the tests that drivers MUST run to verify connectivity and authentication through an Atlas +Secure Frontend Processor (SFP). The SFP is a proxy that sits in front of Atlas clusters to provide additional security +capabilities. + +## META + +The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and +"OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). + +## Specification + +### Terms + +#### SFP + +Secure Frontend Processor - a proxy service that sits in front of Atlas clusters, providing TLS termination, +authentication forwarding, and additional security features. + +### Test Environment + +SFP clusters are **preconfigured** and do not require provisioning or teardown as part of the test run. Drivers will be +provided with connection URIs and credentials via environment variables. + +The SFP proxy is fully transparent to drivers - all standard MongoDB operations should work exactly as they would +against a normal Atlas cluster. + +### Required Environment Variables + +The following environment variables will be available to run the tests: + +| Variable | Description | +| -------------------- | -------------------------------------------------- | +| `SFP_ATLAS_URI` | MongoDB connection URI for the SFP-proxied cluster | +| `SFP_ATLAS_USER` | Username for SCRAM authentication | +| `SFP_ATLAS_PASSWORD` | Password for SCRAM authentication | + +For X.509 authentication tests, the following additional variables are required: + +| Variable | Description | +| --------------------- | ----------------------------------------------- | +| `SFP_ATLAS_X509_URI` | MongoDB connection URI for X.509 authentication | +| `SFP_ATLAS_X509_CERT` | Path to client certificate (PEM format) | + +### Test Isolation and Cleanup + +To prevent conflicts between concurrent test runs and avoid unbounded collection growth: + +1. Drivers MUST use a unique collection name for each test run, e.g., `sfp_test_` where `` is an + ObjectID string representation +2. Drivers MUST drop the test collection after all tests complete, regardless of test success or failure + +## Required Tests + +Drivers MUST implement and run the following tests against SFP-proxied clusters. + +### Common Assertions + +The following assertions are used across multiple tests: + +#### Assertion: Ping + +1. Execute a `ping` command against the `admin` database +2. Assert that the command succeeds with `ok: 1` + +#### Assertion: Connection Status + +1. Execute a `connectionStatus` command against the `admin` database +2. Assert that the command succeeds with `ok: 1` +3. If authenticated, assert that `authInfo.authenticatedUsers` contains at least one user + +#### Assertion: CRUD Operations + +1. Insert a document into a test collection and assert the insert succeeds +2. Query the collection using `find` and assert the inserted document is returned + +### Unauthenticated Tests + +Create a `MongoClient` configured with `SFP_ATLAS_URI` but without credentials. Run the following assertions: + +- Ping +- Connection Status (assert `authenticatedUsers` is empty) + +### Authenticated Tests + +Each authenticated test MUST be run under each of the following variations: + +1. No additional configuration (baseline) +2. With at least one compressor enabled (e.g., zlib, snappy, or zstd) +3. With [Server API](../versioned-api/versioned-api.md#mongoclient-changes) version 1 + +#### SCRAM-SHA-256 + +Create a `MongoClient` with the connection string and SCRAM-SHA-256 credentials from environment variables. Run the +following assertions: + +- Ping +- Connection Status +- CRUD Operations + +#### X.509 + +Create a `MongoClient` with the connection string and X.509 authentication using the client certificate. Run the +following assertions: + +- Ping +- Connection Status +- CRUD Operations + +## Changelog + +- 2025-02-27: Initial version diff --git a/source/index.md b/source/index.md index c2aa2aefd7..d38053b8b6 100644 --- a/source/index.md +++ b/source/index.md @@ -1,5 +1,6 @@ # MongoDB Specifications +- [Atlas Secure Frontend Processor (SFP) Testing](atlas-sfp-testing/atlas-sfp-testing.md) - [Atlas Serverless Tests](serverless-testing/README.md) - [Authentication](auth/auth.md) - [BSON Binary Encrypted](bson-binary-encrypted/binary-encrypted.md)