skip to content

How does a MongoDB client log in with an X.509 certificate, and why must its user live in the `$external` database?

level: middleimportance: should knowfreq 33%

answer

  1. the certificate carries the name
  2. no password to store
  3. RFC2253 subject string
  4. keep clear of member certificates' O, OU, DC

basics

~20 s

The certificate's subject, in RFC2253 form, is the username: you create that user in $external with roles and no password, then connect over TLS with authMechanism=MONGODB-X509. It lives in $external because the certificate, not MongoDB, holds the proof.

solid answer

~50 s

The server runs with TLS and a CA file so it can verify client certificates. You take the certificate's subject in RFC2253 form, for example with `openssl x509 -subject -nameopt RFC2253`, and create a user with exactly that name in `$external`, with roles and no password. The client connects with `tls=true`, its `tlsCertificateKeyFile` and `authMechanism=MONGODB-X509`. It need not send a username, because the server takes the subject from the verified certificate. The user belongs in `$external` because MongoDB stores no credential for it, and the server enforces that: X.509 authentication must always use `$external`. An existing SCRAM user does not convert, because one user cannot mix SCRAM with another type, so you create a new user. One trap is a client certificate sharing the members' `O`, `OU` and `DC`: the server treats it as a cluster member.

code

javascript · 4 lines
javascript
db.getSiblingDB("$external").runCommand({
  createUser: "CN=svc,OU=apps,O=example,L=Oslo,ST=Oslo,C=NO",
  roles: [ { role: "readWrite", db: "orders" } ]
})

go deeper

for a junior

Recall that the certificate's subject is the username, that the user lives in the $external database with no password, and that this needs TLS.

for a middle

Walk through the setup: server TLS and CA, the RFC2253 subject, the createUser call in $external, and the connection options, and predict what a mismatch does.

for a senior

Check issuance rules before rollout, because a client certificate that matches the members' O, OU and DC gets internal permissions in x509 modes, with only a log warning to show for it.

for a principal

Treat certificates as an operated system: who issues them, how renewals keep subjects stable, and how expiry is monitored, since an expired service certificate becomes a production login failure.

## The idea With **X.509 client authentication**, a client proves who it is with a certificate instead of a password. TLS verifies the certificate against a trusted certificate authority (CA), and MongoDB then treats the certificate's **subject** as the username. Community and Enterprise both support it, and `MONGODB-X509` is in the default `authenticationMechanisms` list. The user still has to exist, because that is where its roles come from. It lives in a special database, `$external`, which holds users whose credentials are kept outside MongoDB. The certificate is the proof, so MongoDB stores no password for this user, and the server enforces the location with the check `X.509 authentication must always use the $external database.` ## The steps 1. **Configure the server.** It needs `net.tls.mode` set to `requireTLS`, plus `net.tls.certificateKeyFile` for its own identity and `net.tls.CAFile` to verify what clients present. 2. **Read the subject.** Run `openssl x509 -in client.pem -inform PEM -subject -nameopt RFC2253`. The RFC2253 form matters: the server compares the exact string, and another tool's output can differ in order or spacing. 3. **Create the user.** In `$external`, use that subject as the name and give it roles. There is no `pwd`. 4. **Connect.** Give the client its certificate and name the mechanism. In a connection string, that is `tls=true`, `tlsCertificateKeyFile`, `tlsCAFile`, `authSource=$external` and `authMechanism=MONGODB-X509`. The driver specification says a username should not be provided. If one is sent, it must match the certificate's subject, or the server refuses with `There is no x.509 client certificate matching the user.` ## What the certificate must look like The manual's client certificate requirements are specific: - A **single CA** must issue the certificates for both the client and the server. - It needs `keyUsage = digitalSignature` and `extendedKeyUsage = clientAuth`. - It must not be expired. - At least one of **O**, **OU** or **DC** must differ from those attributes in the server's `net.tls.clusterFile` and `net.tls.certificateKeyFile` certificates. - Its subject must differ from the subjects of member certificates. - Each MongoDB user needs a unique certificate, and one certificate cannot authenticate more than one user. ## The trap: a client certificate that looks like a member MongoDB decides whether a certificate belongs to a cluster member from its attributes, by default `O`, `OU` and `DC`. If a client certificate matches them, the outcome depends on the deployment's `clusterAuthMode`: | `clusterAuthMode` | What happens to that client | |---|---| | `keyFile` | Refused: the certificate can only be used for cluster authentication | | `sendKeyFile`, `sendX509` or `x509` | Accepted as a cluster member with full internal permissions, plus a warning in the log | The second row is why the rule is more than tidiness. A badly issued client certificate quietly gets the permissions of a cluster member, and the visible sign at login is a log warning saying the client is not a mongod or mongos. `enforceUserClusterSeparation` is `true` by default; it also prevents creating users whose names would be read as cluster members. Setting it to `false` is only possible with `keyFile` mode. ## Moving a password login to certificates Suppose an application logs in as SCRAM user `svc` in `orders`. The manual says you cannot use SCRAM and another type of authentication for the same user, so that user does not convert. Instead: - Create a new user in `$external` named after the certificate subject, with the same roles. - Deploy the application with its certificate and the new connection options. - Once nothing logs in as the old user, drop it. The new string needs `authSource=$external` or no value at all, since the driver defaults the source to `$external` for this mechanism. A leftover `authSource=orders` is rejected by the server's check. Renewing a certificate with the same subject changes nothing in MongoDB. A renewal that changes the subject needs a new user first, because the name is the subject. ## LDAP authorization and the 9.0 parameter X.509 only proves who the client is. Where roles come from is a separate matter when a deployment uses LDAP authorization. By default, an X.509-authenticated client then gets its roles from LDAP. MongoDB 9.0 adds the `useInternalAuthzForX509` parameter, `false` by default and settable at startup or runtime. When it is `true`, those clients use internal authorization, based on the user's roles in `$external`, even when LDAP authorization is configured. With no LDAP authorization, internal authorization applies regardless of the setting.

  • A MongoDB X.509 login fails, though the certificate verifies. What do you check first?
    Compare the name in `$external` with the certificate's subject in RFC2253 form, since the match is exact and order or spacing can differ. Then check the login really goes to `$external`, and that the connection string has no stale `authSource`. The client's error is generic, so read the server's failed-login log line.
  • Can one MongoDB X.509 certificate authenticate as several users?
    No. The manual says each unique certificate corresponds to a single MongoDB user, because the subject is the username. If two services need different roles, they should have different certificates with different subjects, and each gets its own user in `$external`.

  • The existing SCRAM user can simply start presenting a certificate as well.
  • The X.509 user can be created in admin as long as authSource points there.
  • A client certificate should share O, OU and DC with the members so that the cluster trusts it.
  • With X.509 you no longer need a user in MongoDB, because the certificate holds the roles.
  • The certificate's Common Name alone is the username.

Assumes MongoDB 9.0; useInternalAuthzForX509 is new in 9.0 per its release notes, so a team on 8.0 cannot rely on it.