Remove sts_expiry, username_format; add srv_record_name (#947)

Remove long-gone LDAP settings and add docs for a recent one.

Gone:
- `sts_expiry`, `MINIO_IDENTITY_LDAP_STS_EXPIRY`
- `username_format`, `MINIO_IDENTITY_LDAP_USERNAME_FORMAT`
- Username-Bind mode

Related code change: https://github.com/minio/minio/pull/13165

Recent:
- `srv_record_name` for lookup via DNS SVR records

Added in https://github.com/minio/minio/pull/16201
RELEASE.2022-12-12T19-27-27Z

Staged:

http://192.241.195.202:9000/staging/DOCS-919-2-svc-record/linux/html/reference/minio-server/minio-server.html#envvar.MINIO_IDENTITY_LDAP_SRV_RECORD_NAME

http://192.241.195.202:9000/staging/DOCS-919-2-svc-record/linux/html/reference/minio-mc-admin/mc-admin-config.html#mc-conf.identity_ldap.srv_record_name

source/includes/common-minio-external-auth.rst

@@ -167,20 +167,6 @@ Specify the hostname for the Active Directory / LDAP server. For example:
 
 .. end-minio-ad-ldap-server-addr
 
-.. start-minio-ad-ldap-sts-expiry
-
-Specify the duration for which the credentials are valid as ``<int><unit>``.
-Valid time units are as follows:
-
-- ``s`` - seconds.
-- ``m`` - minutes.
-- ``h`` - hours.
-- ``d`` - days
-
-The default is ``1h`` or 1 hour.
-
-.. end-minio-ad-ldap-sts-expiry
-
 .. start-minio-ad-ldap-lookup-bind-dn
 
 Specify the Distinguished Name (DN) for an AD/LDAP account MinIO uses when
@@ -226,26 +212,6 @@ username into the search string. For example:
 
 .. end-minio-ad-ldap-user-dn-search-filter
 
-.. start-minio-ad-ldap-username-format
-
-Specify a comma-separated list of Distinguished Name templates used for
-querying the AD/LDAP server. MinIO attempts to login to the AD/LDAP server
-by applying the user credentials specified by the authenticating client to
-each DN template. 
-
-Use the ``%s`` substitution character to insert the client-specified username
-into the search string. For example:
-
-.. code-block:: shell
-   :class: copyable
-
-   uid=%s,cn=miniousers,dc=myldapserver,dc=net,userPrincipalName=%s,cn=miniousers,dc=myldapserver,dc=net
-
-MinIO uses the *first* DN template that results in successful login to
-perform a group lookup for that user. 
-
-.. end-minio-ad-ldap-username-format
-
 .. start-minio-ad-ldap-group-search-filter
 
 Specify an AD/LDAP search filter for performing group lookups for the
@@ -311,6 +277,47 @@ Defaults to ``off``
 
 .. end-minio-ad-ldap-server-starttls
 
+.. start-minio-ad-ldap-srv_record_name
+
+Specify the appropriate value to enable MinIO to select an AD/LDAP server using a `DNS SRV record <https://ldap.com/dns-srv-records-for-ldap>`__ request.
+
+When enabled, MinIO selects an AD/LDAP server by:
+
+- Constructing the target SRV record name following standard naming conventions.
+- Requesting a list of available AD/LDAP servers.
+- Choosing an appropriate target based on priority and weight.
+
+The configuration examples below presume the AD/LDAP server address is set to ``example.com`` and the SRV record protocol is ``_tcp``.
+
+For SRV record names beginning with ``_ldap``, specify ``ldap``.
+The constructed DNS SRV record name resembles the following:
+
+.. code-block:: shell
+
+   _ldap._tcp.example.com
+
+For SRV record names with beginning with ``_ldaps``, specify ``ldaps``.
+The constructed	DNS SRV	record name resembles the following:
+
+.. code-block:: shell
+
+   _ldaps._tcp.example.com
+
+If your DNS SRV record name uses alternate service or protocol names, specify ``on`` and provide the full record name as your LDAP server address.
+Example: ``_ldapserver._specialtcp.example.com``
+
+For more about DNS SRV records, see `DNS SRV Records for LDAP <https://ldap.com/dns-srv-records-for-ldap>`__.
+ 
+.. admonition:: Server address for DNS SRV record configurations
+   :class: important
+
+   The specified server name **must not** include a port number.
+   This is different from a standard AD/LDAP configuration, where the port number is required.
+
+   See :mc-conf:`~identity_ldap.server_addr` or :envvar:`MINIO_IDENTITY_LDAP_SERVER_ADDR` for more about configuring an AD/LDAP server address.
+
+.. end-minio-ad-ldap-srv_record_name
+
 .. start-minio-ad-ldap-comment
 
 Specify a comment to associate to the AD/LDAP configuration.

source/operations/external-iam.rst

@@ -69,30 +69,13 @@ management of user identities. Configuring an external IDentity Provider (IDP)
 enables Single-Sign On (SSO) workflows, where applications authenticate against
 the external IDP before accessing MinIO.
 
+.. _minio-external-identity-management-ad-ldap-lookup-bind:
+
 Querying the Active Directory / LDAP Service
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-MinIO queries the configured Active Directory / LDAP server to verify the
+MinIO queries the configured Active Directory / LDAP server to verify the credentials specified by the application and optionally return a list of groups in which the user has membership.
-credentials specified by the application and optionally return a list of groups
+This process, called Lookup-Bind mode, uses an AD/LDAP user with minimal permissions, only sufficient to authenticate with the AD/LDAP server for user and group lookups.
-in which the user has membership. MinIO supports two modes for performing
-these queries:
-
-- :ref:`minio-external-identity-management-ad-ldap-lookup-bind` - Use a special
-  read-only account for querying the LDAP server.
-
-- :ref:`minio-external-identity-management-ad-ldap-username-bind` - Use the 
-  credentials specified by the application to login to the LDAP server. 
-
-MinIO recommends using Lookup-Bind mode as the preferred method for verifying
-AD/LDAP credentials. Username-Bind mode is a legacy method retained
-for backwards compatibility only.
-
-.. _minio-external-identity-management-ad-ldap-lookup-bind:
-
-Lookup-Bind Mode
-++++++++++++++++
-
-In Lookup-Bind mode, MinIO uses a read-only AD/LDAP account with the minimum privileges required to authenticate to the AD/LDAP server and perform user and group lookups.
 
 .. cond:: linux or container or macos or windows
 
@@ -110,7 +93,7 @@ In Lookup-Bind mode, MinIO uses a read-only AD/LDAP account with the minimum pri
 
          See the :ref:`minio-server-envvar-external-identity-management-ad-ldap`
          reference documentation for more information on these variables. The
-         :ref:`minio-authenticate-using-openid-generic` tutorial includes complete
+         :ref:`minio-authenticate-using-ad-ldap-generic` tutorial includes complete
          instructions on setting these values.
 
       .. tab-item:: Configuration Setting
@@ -122,51 +105,9 @@ In Lookup-Bind mode, MinIO uses a read-only AD/LDAP account with the minimum pri
 
          See the :mc-conf:`identity_ldap` reference documentation for more
          information on these settings. The
-         :ref:`minio-authenticate-using-openid-generic` tutorial includes complete
+         :ref:`minio-authenticate-using-ad-ldap-generic` tutorial includes complete
          instructions on setting these variables.
 
-Lookup-Bind is incompatible and mutually exclusive with
-:ref:`minio-external-identity-management-ad-ldap-username-bind`.
-
-.. _minio-external-identity-management-ad-ldap-username-bind:
-
-Username-Bind Mode
-++++++++++++++++++
-
-In Username-Bind mode, MinIO uses the AD/LDAP credentials provided by the client attempting authentication to login to the AD/LDAP server and perform and group lookups.
-
-.. cond:: k8s
-
-   The MinIO Operator Console does not support enabling Username-Bind mode.
-   MinIO generally discourages using Username-Bind over :ref:`minio-external-identity-management-ad-ldap-lookup-bind`.
-
-.. cond:: linux or container or macos or windows
-
-   Username-Bind mode is preserved for compatibility only. 
-   MinIO recommends using :ref:`minio-external-identity-management-ad-ldap-lookup-bind` wherever possible.
-
-   The following tabs provide a reference of the environment variables and
-   configuration settings required for enabling Username-Bind mode.
-
-   .. tab-set::
-      
-      .. tab-item:: Environment Variable
-
-         - :envvar:`MINIO_IDENTITY_LDAP_USERNAME_FORMAT`
-
-         See the :ref:`minio-server-envvar-external-identity-management-ad-ldap`
-         reference documentation for more information on this variable.
-
-      .. tab-item:: Configuration Setting
-
-         - :mc-conf:`identity_ldap username_format <identity_ldap.username_format>`
-
-         See the :mc-conf:`identity_ldap` reference documentation for more
-         information on this setting.
-
-Username-bind is incompatible and mutually exclusive with
-:ref:`minio-external-identity-management-ad-ldap-lookup-bind`.
-
 .. _minio-external-identity-management-ad-ldap-access-control:
 
 Access Control for AD/LDAP-Managed Identities

source/operations/external-iam/configure-ad-ldap-external-identity-management.rst

@@ -153,12 +153,11 @@ An AD/LDAP user with no assigned policy *and* with membership in groups with no
 	      group_search_filter= "(&(objectClass=group)(member=%d))"             \
 	      group_search_base_dn="ou=MinIO Users,dc=example,dc=net"              \
               enabled="true"                                                       \
-              sts_expiry="1h"                                                      \
-              username_format="uid=%s,cn=miniousers,dc=myldapserver,dc=net,userPrincipalName=%s,cn=miniousers,dc=myldapserver,dc=net"                                            \
               tls_skip_verify="off"                                                \
               server_insecure=off                                                  \
               server_starttls="off"                                                \
-	      comment="Test LDAP server"
+              srv_record_name=""                                                   \
+              comment="Test LDAP server"
 
         For more complete documentation on these settings, see :mc:`mc idp ldap`.
 
@@ -195,13 +194,11 @@ An AD/LDAP user with no assigned policy *and* with membership in groups with no
             export MINIO_IDENTITY_LDAP_LOOKUP_BIND_PASSWORD="xxxxxxxxx"
             export MINIO_IDENTITY_LDAP_GROUP_SEARCH_FILTER="(&(objectClass=group)(member=%d))"
             export MINIO_IDENTITY_LDAP_GROUP_SEARCH_BASE_DN="ou=MinIO Users,dc=example,dc=net"
-
+            export MINIO_IDENTITY_LDAP_TLS_SKIP_VERIFY="off"
-            export MINIO_IDENTITY_LDAP_STS_EXPIRY="1h"
+            export MINIO_IDENTITY_LDAP_SERVER_INSECURE="off"
-            export MINIO_IDENTITY_LDAP_USERNAME_FORMAT="uid=%s,cn=miniousers,dc=myldapserver,dc=net,userPrincipalName=%s,cn=miniousers,dc=myldapserver,dc=net"
+            export MINIO_IDENTITY_LDAP_SERVER_STARTTLS="off"
-	    export MINIO_IDENTITY_LDAP_TLS_SKIP_VERIFY="off"
+            export MINIO_IDENTITY_LDAP_SRV_RECORD_NAME=""
-	    export MINIO_IDENTITY_LDAP_SERVER_INSECURE="off"
+            export MINIO_IDENTITY_LDAP_COMMENT="LDAP test server"
-	    export MINIO_IDENTITY_LDAP_SERVER_STARTTLS="off"
-	    export MINIO_IDENTITY_LDAP_COMMENT="LDAP test server"
 
          For complete documentation on these variables, see :ref:`minio-server-envvar-external-identity-management-ad-ldap`
 

source/reference/minio-mc-admin/mc-admin-config.rst

@@ -2308,7 +2308,7 @@ management using an Active Directory or LDAP service.
 
       MinIO recommends using the :mc:`mc idp ldap` commands for LDAP management operations.
       These commands offer better validation and additional features, while providing the same settings as the :mc-conf:`identity_ldap` configuration key.
-      See :ref:`minio-external-identity-management-ad-ldap` for a tutorial on using :mc:`mc idp ldap`.
+      See :ref:`minio-authenticate-using-ad-ldap-generic` for a tutorial on using :mc:`mc idp ldap`.
 
       The :mc-conf:`identity_ldap` configuration key remains available for existing scripts and other tools.
 
@@ -2412,30 +2412,6 @@ management using an Active Directory or LDAP service.
 
       Defaults to ``true`` or "enabled".
 
-   .. mc-conf:: sts_expiry
-      :delimiter: " "
-
-      *Optional*
-
-      .. include:: /includes/common-minio-external-auth.rst
-         :start-after: start-minio-ad-ldap-sts-expiry
-         :end-before: end-minio-ad-ldap-sts-expiry
-
-      This configuration setting corresponds with the 
-      :envvar:`MINIO_IDENTITY_LDAP_STS_EXPIRY` environment variable.
-
-   .. mc-conf:: username_format
-      :delimiter: " "
-
-      *Optional*
-
-      .. include:: /includes/common-minio-external-auth.rst
-         :start-after: start-minio-ad-ldap-username-format
-         :end-before: end-minio-ad-ldap-username-format
-
-      This configuration setting corresponds with the 
-      :envvar:`MINIO_IDENTITY_LDAP_USERNAME_FORMAT` environment variable.
-
    .. mc-conf:: group_search_filter
       :delimiter: " "
 
@@ -2496,6 +2472,20 @@ management using an Active Directory or LDAP service.
       This configuration setting corresponds with the 
       :envvar:`MINIO_IDENTITY_LDAP_SERVER_STARTTLS` environment variable.
 
+   .. mc-conf:: srv_record_name
+      :delimiter: " "
+
+      .. versionadded:: RELEASE.2022-12-12T19-27-27Z
+
+      *Optional*
+
+      .. include:: /includes/common-minio-external-auth.rst
+         :start-after: start-minio-ad-ldap-srv_record_name
+         :end-before: end-minio-ad-ldap-srv_record_name
+
+      This configuration setting corresponds with the
+      :envvar:`MINIO_IDENTITY_LDAP_SRV_RECORD_NAME` environment variable.
+
    .. mc-conf:: comment
       :delimiter: " "
 

source/reference/minio-server/minio-server.rst

@@ -2638,7 +2638,7 @@ Active Directory / LDAP Identity Management
 
 The following section documents environment variables for enabling
 external identity management using an Active Directory or LDAP service.
-See :ref:`minio-external-identity-management-ad-ldap` for a tutorial on using these
+See :ref:`minio-authenticate-using-ad-ldap-generic` for a tutorial on using these
 variables.
 
 .. envvar:: MINIO_IDENTITY_LDAP_SERVER_ADDR
@@ -2653,18 +2653,6 @@ variables.
    :mc-conf:`identity_ldap server_addr 
    <identity_ldap.server_addr>` configuration setting.
 
-.. envvar:: MINIO_IDENTITY_LDAP_STS_EXPIRY
-
-   *Optional*
-
-   .. include:: /includes/common-minio-external-auth.rst
-      :start-after: start-minio-ad-ldap-sts-expiry
-      :end-before: end-minio-ad-ldap-sts-expiry
-
-   This environment variable corresponds with the 
-   :mc-conf:`identity_ldap sts_expiry 
-   <identity_ldap.sts_expiry>` configuration setting.
-
 .. envvar:: MINIO_IDENTITY_LDAP_LOOKUP_BIND_DN
 
    *Required*
@@ -2713,18 +2701,6 @@ variables.
    :mc-conf:`identity_ldap user_dn_search_filter 
    <identity_ldap.user_dn_search_filter>` configuration setting.
 
-.. envvar:: MINIO_IDENTITY_LDAP_USERNAME_FORMAT
-
-   *Optional*
-
-   .. include:: /includes/common-minio-external-auth.rst
-      :start-after: start-minio-ad-ldap-username-format
-      :end-before: end-minio-ad-ldap-username-format
-
-   This environment variable corresponds with the 
-   :mc-conf:`identity_ldap username_format 
-   <identity_ldap.username_format>` configuration setting.
-
 .. envvar:: MINIO_IDENTITY_LDAP_GROUP_SEARCH_FILTER
 
    *Optional*
@@ -2785,6 +2761,19 @@ variables.
    :mc-conf:`identity_ldap server_starttls 
    <identity_ldap.server_starttls>` configuration setting.
 
+.. envvar:: MINIO_IDENTITY_LDAP_SRV_RECORD_NAME
+
+   .. versionadded:: RELEASE.2022-12-12T19-27-27Z
+
+   *Optional*
+
+   .. include:: /includes/common-minio-external-auth.rst
+      :start-after: start-minio-ad-ldap-srv_record_name
+      :end-before: end-minio-ad-ldap-srv_record_name
+
+   This environment variable corresponds with the
+   :mc-conf:`identity_ldap srv_record_name <identity_ldap.srv_record_name>` configuration setting.
+
 .. envvar:: MINIO_IDENTITY_LDAP_COMMENT
 
    *Optional*