SQL Interface Authentication

The SQL Interface supports multiple authentication mechanisms to connect to your MongoDB deployment. This page includes supported authentication methods, component compatibility, and deployment availability for both Atlas and self-managed MongoDB Enterprise deployments.

Authentication Support Matrix

The following table shows which authentication mechanisms are supported by each SQL Interface component:

Component	SCRAM	X.509	LDAP	GSSAPI	AWS IAM	OIDC
MongoDB SQL Schema Builder	Yes	Yes	Yes	Yes	Yes	Yes
ODBC Driver	Yes	Yes	Yes	Yes	Yes	Yes
JDBC Driver	Yes	Yes	Yes	Yes	Yes	Yes
Power BI Desktop	Yes	Yes	Yes	Yes	Yes	Yes
Power BI Gateway	Yes	No	No	No	No	No
Tableau Desktop	Yes	Yes	Yes	Yes	Yes	Yes
Tableau Server	Yes	Yes	No	No	No	No
Tableau Cloud	Yes	No	No	No	No	No

Note

Not all third-party BI tools support these authentication options even though they are supported in the MongoDB drivers. Test the features you want to use to confirm they work with your specific BI tool.

Deployment Compatibility Matrix

The following table shows which authentication mechanisms are available for each MongoDB deployment type:

Authentication Mechanism	Atlas	MongoDB Enterprise
SCRAM	Yes	Yes
X.509	Yes	Yes
LDAP	No	Yes
Kerberos (GSSAPI)	No	Yes
AWS IAM	Yes	No
OIDC	Yes	Yes

Important

Starting in MongoDB 8.0, LDAP authentication and authorization is deprecated. LDAP remains available and continues to operate without changes throughout MongoDB 8, but a future major release removes it. Consider migrating to OIDC or another supported authentication mechanism. For more information, see LDAP Deprecation.

JDBC Driver Configuration

The MongoDB JDBC driver supports all authentication mechanisms that MongoDB supports. To learn more, see Authentication Mechanisms. If you configure it, the driver also supports TLS/SSL connections. To learn more, see TLS/SSL Configuration.

The following sections describe the connection properties that configure X.509, Kerberos (GSSAPI), and OIDC authentication for the JDBC driver. These properties apply to both Atlas and self-managed MongoDB Enterprise deployments.

X.509 Authentication

The MongoDB JDBC driver supports X.509 client certificate authentication. The following properties control how the driver configures the client certificate and CA trust:

Property	Purpose
`x509pempath`	Path to a PEM file that contains the client certificate and private key. Required for unencrypted or encrypted PKCS #1 and PKCS #8 keys.
`tlscafile`	Optional. Path to a PEM file that contains one or more trusted X.509 certificates. When set, the driver accepts only certificates signed by these CAs.
`password`	Serves a different purpose depending on whether you set `x509pempath`. When you set `x509pempath`, `password` is the passphrase for the encrypted PEM file. When you don't set `x509pempath`, `password` can contain either raw PEM content consisting of an unencrypted certificate and private key, or a JSON object of the form `{"pem": "...", "passphrase": "..."}` for encrypted PEM data.

Consider the following behavior when you configure X.509 authentication:

If you set x509pempath, it takes precedence over any PEM content in the password property.
If you don't set tlscafile, the driver uses the default JVM truststore.
The PEM content must contain both the client certificate and its corresponding private key, whether you provide it through x509pempath or in the password property.

Kerberos (GSSAPI) Authentication

The MongoDB JDBC driver supports GSSAPI for Kerberos-based authentication. This mechanism requires that you configure Kerberos and JAAS settings outside of the driver. The following properties control how the driver uses that configuration:

Property	Description
`jaasconfigpath`	Path to a JAAS configuration file, such as `jaas.config`. If you don't set this property, the driver uses the default JVM JAAS configuration.
`gssapilogincontextname`	Specifies the login context name defined in the JAAS configuration.
`gssapiserverauth`	When set to `true`, enables server authentication during the SASL negotiation.
`gssnativemode`	Controls whether the driver uses native GSSAPI libraries. Accepts `true` or `false`.

OIDC Authentication

The MongoDB JDBC driver distinguishes between human-initiated and machine-automated OIDC flows based on the authentication mechanism properties that you set:

Human flow: The default behavior. Requires user interaction through a browser login.
Machine flow: Used in automated environments such as GCP Workload Identity, Azure Managed Identity, and Kubernetes. To enable the machine flow, set the ENVIRONMENT and TOKEN_RESOURCE parameters.

Security Considerations

When configuring authentication for the SQL Interface, consider the following security best practices:

Use strong authentication mechanisms: Prefer X.509, OIDC, or Kerberos over password-based authentication when possible.
Enable TLS encryption: Always use TLS to protect credentials and data in transit.
Follow the principle of least privilege: Grant users only the minimum permissions required for their tasks.
Secure credential storage: Never hardcode credentials in connection strings. Use environment variables, credential files, or secure credential management systems.
Regular credential rotation: Implement regular rotation of passwords and certificates.
Monitor authentication events: Enable audit logging to track authentication attempts and failures.

Next Steps

Back

Connect and Query

Errors