DOCS-14837 LDAP authorization cache refresh (#6179)

Co-authored-by: jason-price-mongodb <[email protected]>

Author: 2 people

source/includes/LDAP-interval.rst

@@ -0,0 +1,7 @@
+Starting in MongoDB 5.2, the update interval for cached user information
+retrieved from an LDAP server depends on
+:parameter:`ldapShouldRefreshUserCacheEntries`:
+
+- If true, use :parameter:`ldapUserCacheRefreshInterval`.
+
+- If false, use :parameter:`ldapUserCacheInvalidationInterval`.

source/reference/parameters.txt

@@ -130,6 +130,12 @@ Authentication Parameters
 
 .. parameter:: ldapUserCacheInvalidationInterval
 
+   .. versionchanged:: 5.2
+
+   .. note::
+
+      .. include:: /includes/LDAP-interval.rst
+
    For use with MongoDB deployments using
    :ref:`security-ldap-external`. Available for :binary:`~bin.mongod`
    instances only.
@@ -148,6 +154,82 @@ Authentication Parameters
 
    Defaults to 30 seconds.
 
+.. parameter:: ldapUserCacheRefreshInterval
+
+   .. versionadded:: 5.2
+
+   |mongod-only|
+
+   *Type*: integer
+
+   *Default*: 30 seconds
+
+   .. note::
+
+      .. include:: /includes/LDAP-interval.rst
+
+   For MongoDB deployments using :ref:`security-ldap-external`.
+ 
+   The interval in seconds that :binary:`~bin.mongod` waits before
+   refreshing the cached user information from the LDAP server.
+ 
+   The maximum interval is 86,400 seconds (24 hours).
+ 
+   For example, the following sets
+   :parameter:`ldapUserCacheRefreshInterval` to ``4000`` seconds:
+ 
+   .. code-block:: bash
+ 
+      mongod --setParameter ldapUserCacheRefreshInterval=4000
+ 
+   Or, if using the :dbcommand:`setParameter` command within
+   :binary:`~bin.mongosh`:
+ 
+   .. code-block:: javascript
+ 
+      db.adminCommand( { setParameter: 1, ldapUserCacheRefreshInterval: 4000 } )
+ 
+.. parameter:: ldapUserCacheStalenessInterval
+ 
+   .. versionadded:: 5.2
+ 
+   |mongod-only|
+ 
+   *Type*: integer
+ 
+   *Default*: 90 seconds
+ 
+   For MongoDB deployments using :ref:`security-ldap-external`.
+ 
+   The interval in seconds that :binary:`~bin.mongod` retains the cached
+   LDAP user information after the last cache refresh.
+    
+   If more than :parameter:`ldapUserCacheStalenessInterval` seconds
+   elapse without a successful refresh of the user information from the
+   LDAP server, then :binary:`~bin.mongod`:
+ 
+   - Invalidates the cached LDAP user information.
+      
+   - Is unavailable for LDAP users. LDAP users are unable to
+     authenticate until :binary:`~bin.mongod` contacts the LDAP
+     server.
+ 
+   The maximum interval is 86,400 seconds (24 hours).
+ 
+   For example, the following sets
+   :parameter:`ldapUserCacheStalenessInterval` to ``4000`` seconds:
+ 
+   .. code-block:: bash
+ 
+      mongod --setParameter ldapUserCacheStalenessInterval=4000
+ 
+   Or, if using the :dbcommand:`setParameter` command within
+   :binary:`~bin.mongosh`:
+
+   .. code-block:: javascript
+ 
+      db.adminCommand( { setParameter: 1, ldapUserCacheStalenessInterval: 4000 } )
+
 .. parameter:: ldapUseConnectionPool
 
    .. versionadded:: 4.0.9
@@ -256,6 +338,30 @@ Authentication Parameters
    start-up, and cannot change this setting with the
    :dbcommand:`setParameter` database command.
 
+.. parameter:: ldapShouldRefreshUserCacheEntries
+ 
+   .. versionadded:: 5.2
+ 
+   |mongod-only|
+ 
+   *Type*: boolean
+ 
+   *Default*: true
+ 
+   For MongoDB deployments using :ref:`security-ldap-external`.
+
+   .. include:: /includes/LDAP-interval.rst
+ 
+   You can only set :parameter:`ldapShouldRefreshUserCacheEntries`
+   during startup in the :setting:`configuration file <setParameter>` or
+   with the ``--setParameter`` option on the command line. For example,
+   the following disables
+   :parameter:`ldapShouldRefreshUserCacheEntries`:
+ 
+   .. code-block:: bash
+ 
+      mongod --setParameter ldapShouldRefreshUserCacheEntries=false
+
 .. parameter:: maxValidateMemoryUsageMB
 
    .. versionadded:: 5.0

source/release-notes/5.2.txt

@@ -68,6 +68,18 @@ Change Streams
 General Improvements
 --------------------
 
+Configure Refresh Interval for Cached LDAP User Information
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Starting in MongoDB 5.2, you can use the following new server parameters
+to configure the refresh interval for cached LDAP user information:
+
+- :parameter:`ldapUserCacheRefreshInterval`
+- :parameter:`ldapUserCacheStalenessInterval`
+- :parameter:`ldapShouldRefreshUserCacheEntries`
+
+.. include:: /includes/LDAP-interval.rst
+
 Time Series Collection Data Compression
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~