added documentation for mongodb atlas database secrets engine eventua… (

#24152)

* added documentation for mongodb atlas database secrets engine eventual consistency

changelog/24152.txt

@@ -0,0 +1,3 @@
+```release-note:improvement
+website/docs: Add note about eventual consietency with the MongoDB Atlas database secrets engine
+```

website/content/docs/secrets/databases/mongodbatlas.mdx

@@ -73,7 +73,69 @@ the proper permissions, it can generate credentials.
         lease_duration     1h
         lease_renewable    true
         password           FBYwnnh-fwc0quxtKf11
-        username           v-my-role-DKbQEg6uRn
+        username           v-my-password-role-DKbQEg6uRn
+    ```
+
+    Each invocation of the command generates a new credential.
+
+    MongoDB Atlas database credentials eventually become consistent when the
+    [MongoDB Atlas Admin API](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/)
+    coordinates with hosted clusters in your Atlas project. You cannot use the
+    credentials successfully until the consistency process completes.
+
+    If you plan to use MongoDB Atlas credentials in a pipeline, you may need to add
+    a time delay or secondary process to account for the time required to establish consistency.
+
+#### Client certificate credentials
+
+1.  Configure a role that maps a name in Vault to a MongoDB Atlas command that executes and
+    creates the X509 type database user credential:
+
+    ```shell-session
+    $ vault write database/roles/my-dynamic-certificate-role \
+      db_name=my-mongodbatlas-database \
+      creation_statements='{"database_name": "$external", "x509Type": "CUSTOMER", "roles": [{"databaseName":"<db_name>","roleName":"readWrite"}]}' \
+      default_ttl="1h" \
+      max_ttl="24h" \
+      credential_type="client_certificate" \
+      credential_config=ca_cert="$(cat path/to/ca_cert.pem)" \
+      credential_config=ca_private_key="$(cat path/to/private_key.pem)" \
+      credential_config=key_type="rsa" \
+      credential_config=key_bits=2048 \
+      credential_config=signature_bits=256 \
+      credential_config=common_name_template="{{.DisplayName}}_{{.RoleName}}_{{unix_time}}"
+    Success! Data written to: database/roles/my-dynamic-certificate-role
+    ```
+
+1.  Generate a new credential by reading from the `/creds` endpoint with the name
+of the role:
+
+    ```shell-session
+    $ vault read database/creds/my-dynamic-certificate-role
+      Key                 Value
+      ---                 -----
+      request_id          b6556b2d-c379-5a92-465d-6597c506c821
+      lease_id            database/creds/my-dynamic-certificate-role/AZ5tao6NjLJctx7fm1bujKEL
+      lease_duration      1h
+      lease_renewable     true
+      client_certificate  -----BEGIN CERTIFICATE-----
+                          ...
+                          -----END CERTIFICATE-----
+      private_key         -----BEGIN PRIVATE KEY-----
+                          ...
+                          -----END PRIVATE KEY-----
+      private_key_type    rsa
+      username            CN=token_my-dynamic-certificate-role_1677262121
+    ```
+
+## Client certificate authentication
+
+MongoDB Atlas supports [X.509 client certificate based authentication](https://www.mongodb.com/docs/manual/tutorial/configure-x509-client-authentication/)
+for enhanced authentication security as an alternative to username and password authentication.
+The MongoDB Atlas database plugin can be used to manage client certificate credentials for
+MongoDB Atlas users by using `client_certificate` [credential_type](/vault/api-docs/secret/databases#credential_type).
+
+See the [usage](/vault/docs/secrets/databases/mongodbatlas#usage) section for examples using dynamic roles.
 
 ## API