Updated LDAP docs (#939)

Update the AD/LDAP configuration instructions, including adding details
about configuring with Console.

Includes reformatting some existing content.

Questions:
- What, exactly, is the status of the `mc admin config identity_ldap`
settings? Deprecated? There, but not recommended for new configurations?
- Are the "all settings" examples correct and appropriate? I'm not clear
if `mc idp ldap` supports the same settings with the same names as
`identity_ldap`.

Staged:

http://192.241.195.202:9000/staging/DOCS-919/linux/html/operations/external-iam/configure-ad-ldap-external-identity-management.html

Fixes https://github.com/minio/docs/issues/919

---------

Co-authored-by: Ravind Kumar <ravind@min.io>
Co-authored-by: Daryl White <53910321+djwfyi@users.noreply.github.com>

source/administration/console/security-and-access.rst

@@ -145,6 +145,8 @@ Configuring an external IDP enables Single-Sign On workflows, where applications
 Use the the screens in this section to view, add, or edit OIDC configurations for the deployment.
 MinIO supports any number of active OIDC configurations.
 
+.. _minio-console-admin-identity-ldap:
+
 LDAP
 ~~~~
 
@@ -154,4 +156,5 @@ Configuring an external IDentity Provider (IDP) enables Single-Sign On (SSO) wor
 Use the the screens in this section to view, add, or edit an LDAP configuration for the deployment.
 MinIO only supports one active LDAP configuration.
 
-MinIO queries the active 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. 
+MinIO queries the Active Directory / LDAP server to verify the client-specified credentials. 
+MinIO also performs a group lookup on the AD/LDAP server if configured to do so.

source/administration/identity-access-management/ad-ldap-access-management.rst

@@ -55,9 +55,10 @@ full login flow.
 AD/LDAP users can alternatively create :ref:`access keys <minio-idp-service-account>` associated to their AD/LDAP user Distinguished Name. 
 Access Keys are long-lived credentials which inherit their privileges from the parent user. 
 The parent user can further restrict those privileges while creating the access keys. 
-Use either of the following methods to create a new access keys:
+Use either of the following methods to create a new access key:
 
-- Log into the :ref:`MinIO Console <minio-console>` using the AD/LDAP-managed user credentials. From the :guilabel:`Identity` section of the left navigation, select :guilabel:`Access Keys` followed by the :guilabel:`Create access keys +` button.
+- Log into the :ref:`MinIO Console <minio-console>` using the AD/LDAP-managed user credentials. 
+   In the :guilabel:`User` section, select :guilabel:`Access Keys` followed by :guilabel:`Create access keys +`.
 
 - Use the :mc:`mc admin user svcacct add` command to create the access keys. Specify the user Distinguished Name as the username to which to associate the access keys.
 
@@ -102,4 +103,4 @@ Consider the following policy assignments:
 - MinIO would assign any authenticating user with membership in the
   ``cn=engineering,cn=groups,dc=example,dc=com`` AD/LDAP group the
   :userpolicy:`diagnostics` policy, granting access to diagnostic administrative
-  operations.
+  operations.

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

@@ -163,7 +163,7 @@ provider configuration.
 
 Specify the hostname for the Active Directory / LDAP server. For example:
 
-``https://ldapserver.com:636``
+``ldapserver.com:636``
 
 .. end-minio-ad-ldap-server-addr
 
@@ -317,6 +317,23 @@ Specify a comment to associate to the AD/LDAP configuration.
 
 .. end-minio-ad-ldap-comment
 
+.. start-minio-ad-ldap-console-enable
+
+#. Log in to the MinIO Console as either the :ref:`root <minio-users-root>` user or a MinIO user with the  :userpolicy:`consoleAdmin` policy.
+#. In the :guilabel:`Identity` section, select :guilabel:`LDAP` and then :guilabel:`Edit Configuration` to configure an Active Directory or LDAP server.
+   The minimum required settings are:
+
+   - Server Address
+   - Lookup Bind DN
+   - Lookup Bind Password
+   - User DN Search Base
+   - User DN Search Filter
+
+   Not all configuration options are available in the MinIO Console.
+   For additional settings, use :mc:`mc idp ldap` or :ref:`environment variables <minio-server-envvar-external-identity-management-ad-ldap>`.
+ 
+.. end-minio-ad-ldap-console-enable
+
 .. start-minio-identity-management-plugin-url
 
 The webhook endpoint for the external identity management service (``https://authservice.example.net:8080/auth``).
@@ -350,4 +367,5 @@ If omitted, MinIO automatically generates the ID and prints the full ARN to the
 
 Specify a comment to associate to the identity configuration.
 
-.. end-minio-identity-management-comment
+.. end-minio-identity-management-comment
+

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

@@ -10,6 +10,7 @@ Configure MinIO for Authentication using Active Directory / LDAP
    :local:
    :depth: 2
 
+
 Overview
 --------
 
@@ -29,7 +30,9 @@ The procedure on this page provides instructions for:
    - Accessing the MinIO Console using AD/LDAP credentials.
    - Using the MinIO ``AssumeRoleWithLDAPIdentity`` Security Token Service (STS) API to generate temporary credentials for use by applications.
 
-This procedure is generic for AD/LDAP services. Defer to the documentation for the AD/LDAP provider of your choice for specific instructions or procedures on configuration of user identities.
+This procedure is generic for AD/LDAP services.
+See the documentation for the AD/LDAP provider of your choice for specific instructions or procedures on configuration of user identities.
+
 
 Prerequisites
 -------------
@@ -57,7 +60,6 @@ Instructions on configuring AD/LDAP are out of scope for this procedure.
      This may require configuration or deployment of additional Kubernetes network components and/or enabling access to the public internet.
 
 MinIO requires a read-only access keys with which it :ref:`binds <minio-external-identity-management-ad-ldap-lookup-bind>` to perform authenticated user and group queries.
-
 Ensure each AD/LDAP user and group intended for use with MinIO has a corresponding :ref:`policy <minio-external-identity-management-ad-ldap-access-control>` on the MinIO deployment. 
 An AD/LDAP user with no assigned policy *and* with membership in groups with no assigned policy has no permission to access any action or resource on the MinIO cluster.
 
@@ -85,7 +87,7 @@ An AD/LDAP user with no assigned policy *and* with membership in groups with no
    Install and Configure ``mc`` with Access to the MinIO Cluster
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-   This procedure uses :mc:`mc` for performing operations on the MinIO cluster. 
+   This procedure uses :mc:`mc` for performing operations on the MinIO cluster.
    Install ``mc`` on a machine with network access to the cluster.
    See the ``mc`` :ref:`Installation Quickstart <mc-install>` for instructions on downloading and installing ``mc``.
 
@@ -99,40 +101,84 @@ An AD/LDAP user with no assigned policy *and* with membership in groups with no
 
    .. include:: /includes/k8s/steps-configure-ad-ldap-external-identity-management.rst
 
-
 .. Doing this the quick and dirty way. Need to revise later to be proper full includes via stepfiles
 
 .. cond:: linux or container or macos or windows
 
    .. _minio-external-identity-management-ad-ldap-configure:
 
+
    Procedure
    ---------
 
    1) Set the Active Directory / LDAP Configuration Settings
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-   You can configure the AD/LDAP provider using either
+   Configure the AD/LDAP provider using one of the following:
-   environment variables *or* server runtime configuration settings. Both
+
-   methods require starting/restarting the MinIO deployment to apply changes. The
+   * MinIO Client
-   following tabs provide a quick reference of all required and optional
+   * Environment variables
-   environment variables and configuration settings respectively:
+   * MinIO Console
+
+   All methods require starting/restarting the MinIO deployment to apply changes.
+
+   The following tabs provide a quick reference for the available configuration methods:
 
    .. tab-set::
 
+      .. tab-item:: MinIO Client
+
+         MinIO supports specifying the AD/LDAP provider settings using :mc:`mc idp ldap` commands.
+
+         For distributed deployments, the :mc:`mc idp ldap` command applies the configuration to all nodes in the deployment. 
+
+         The following example code sets *all* configuration settings related to configuring an AD/LDAP provider for external identity management.
+	 The minimum *required* settings are:
+
+         - :mc-conf:`server_addr <identity_ldap.server_addr>`
+         - :mc-conf:`lookup_bind_dn <identity_ldap.lookup_bind_dn>`
+         - :mc-conf:`lookup_bind_password <identity_ldap.lookup_bind_password>`
+         - :mc-conf:`user_dn_search_base_dn <identity_ldap.user_dn_search_base_dn>`
+         - :mc-conf:`user_dn_search_filter <identity_ldap.user_dn_search_filter>`
+
+        .. code-block:: shell
+           :class: copyable
+
+	   mc idp ldap add ALIAS                                                   \
+	      server_addr="ldaps.example.net:636"                                  \
+              lookup_bind_dn="CN=xxxxx,OU=xxxxx,OU=xxxxx,DC=example,DC=net"        \
+	      lookup_bind_password="xxxxxxxx"                                      \
+	      user_dn_search_base_dn="DC=example,DC=net"                           \
+	      user_dn_search_filter="(&(objectCategory=user)(sAMAccountName=%s))"  \
+	      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"
+
+        For more complete documentation on these settings, see :mc:`mc idp ldap`.
+
+	.. admonition:: :mc:`mc idp ldap` recommended
+           :class: note
+
+           :mc:`mc idp ldap` offers additional features and improved validation over :mc-cmd:`mc admin config set` runtime configuration settings.
+           :mc:`mc idp ldap` supports the same settings as :mc:`mc admin config` and the :mc-conf:`identity_ldap` configuration key.
+
+           The :mc-conf:`identity_ldap` configuration key remains available for existing scripts and tools.
+
       .. tab-item:: Environment Variables
 
-         MinIO supports specifying the AD/LDAP provider
+         MinIO supports specifying the AD/LDAP provider settings using :ref:`environment variables <minio-server-envvar-external-identity-management-ad-ldap>`.
-         settings using :ref:`environment variables
+	 The :mc:`minio server` process applies the specified settings on its next startup.
-         <minio-server-envvar-external-identity-management-ad-ldap>`. The 
+	 For distributed deployments, specify these settings across all nodes in the deployment using the *same* values.
-         :mc:`minio server` process applies the specified settings on its next
+	 Any differences in server configurations between nodes will result in startup or configuration failures.
-         startup. For distributed deployments, specify these settings across all
+
-         nodes in the deployment using the *same* values consistently.
+         The following example code sets *all* environment variables related to configuring an AD/LDAP provider for external identity management. The minimum *required* variable are:
 
-         The following example code sets *all* environment variables related to
-         configuring an AD/LDAP provider for external
-         identity management. The minimum *required* variable are:
-         
          - :envvar:`MINIO_IDENTITY_LDAP_SERVER_ADDR`
          - :envvar:`MINIO_IDENTITY_LDAP_LOOKUP_BIND_DN`
          - :envvar:`MINIO_IDENTITY_LDAP_LOOKUP_BIND_PASSWORD`
@@ -150,99 +196,62 @@ An AD/LDAP user with no assigned policy *and* with membership in groups with no
             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"
 
-         For complete documentation on these variables, see
+            export MINIO_IDENTITY_LDAP_STS_EXPIRY="1h"
-         :ref:`minio-server-envvar-external-identity-management-ad-ldap`
+            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_TLS_SKIP_VERIFY="off"
+	    export MINIO_IDENTITY_LDAP_SERVER_INSECURE="off"
+	    export MINIO_IDENTITY_LDAP_SERVER_STARTTLS="off"
+	    export MINIO_IDENTITY_LDAP_COMMENT="LDAP test server"
 
-      .. tab-item:: Configuration Settings
+         For complete documentation on these variables, see :ref:`minio-server-envvar-external-identity-management-ad-ldap`
 
-         MinIO supports specifying the AD/LDAP provider
+      .. tab-item:: MinIO Console
-         settings using :mc-conf:`configuration settings <identity_ldap>`. The 
-         :mc:`minio server` process applies the specified settings on its next
-         startup. For distributed deployments, the :mc:`mc admin config`
-         command applies the configuration to all nodes in the deployment.
 
-         The following example code sets *all* configuration settings related to
+         MinIO supports specifying the AD/LDAP provider settings using the :ref:`MinIO Console <minio-console>`.
-         configuring an AD/LDAP provider for external
+         For distributed deployments, configuring AD/LDAP from the Console applies the configuration to all nodes in the deployment.
-         identity management. The minimum *required* setting are:
-         
-         - :mc-conf:`identity_ldap server_addr <identity_ldap.server_addr>`
-
-         - :mc-conf:`identity_ldap lookup_bind_dn <identity_ldap.lookup_bind_dn>`
-
-         - :mc-conf:`identity_ldap lookup_bind_password <identity_ldap.lookup_bind_password>`
-         
-         - :mc-conf:`identity_ldap user_dn_search_base_dn <identity_ldap.user_dn_search_base_dn>`
-         
-         - :mc-conf:`identity_ldap user_dn_search_filter <identity_ldap.user_dn_search_filter>`
-
-         .. code-block:: shell
-            :class: copyable
-
-            mc admin config set ALIAS/ identity_ldap \
-               server_addr="ldaps.example.net:636" \
-               lookup_bind_dn="CN=xxxxx,OU=xxxxx,OU=xxxxx,DC=example,DC=net" \
-               lookup_bind_password="xxxxxxxx" \
-               user_dn_search_base_dn="DC=example,DC=net" \
-               user_dn_search_filter="(&(objectCategory=user)(sAMAccountName=%s))" \
-               group_search_filter= "(&(objectClass=group)(member=%d))" \
-               group_search_base_dn="ou=MinIO Users,dc=example,dc=net" 
-
-         For more complete documentation on these settings, see
-         :mc-conf:`identity_ldap`.
 
+	 .. include:: /includes/common-minio-external-auth.rst
+            :start-after: start-minio-ad-ldap-console-enable
+            :end-before: end-minio-ad-ldap-console-enable
+			 
    2) Restart the MinIO Deployment
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-   You must restart the MinIO deployment to apply the configuration changes. 
+   You must restart the MinIO deployment to apply the configuration changes.
-   Use the :mc-cmd:`mc admin service restart` command to restart the deployment.
+
+   If you configured AD/LDAP from the MinIO Console, no additional action is required.
+   The MinIO Console automatically restarts the deployment after saving the new AD/LDAP configuration.
+
+   For MinIO Client and environment variable configuration, use the :mc-cmd:`mc admin service restart` command to restart the deployment:
 
    .. code-block:: shell
       :class: copyable
 
       mc admin service restart ALIAS
 
-   Replace ``ALIAS`` with the :ref:`alias <alias>` of the deployment to 
+   Replace ``ALIAS`` with the :ref:`alias <alias>` of the deployment to restart.
-   restart.
 
    3) Use the MinIO Console to Log In with AD/LDAP Credentials
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-   The MinIO Console supports the full workflow of authenticating to the
+   The MinIO Console supports the full workflow of authenticating to the AD/LDAP provider, generating temporary credentials using the MinIO :ref:`minio-sts-assumerolewithldapidentity` Security Token Service (STS) endpoint, and logging the user into the MinIO deployment.
-   AD/LDAP provider, generating temporary credentials using
-   the MinIO :ref:`minio-sts-assumerolewithldapidentity` Security Token Service
-   (STS) endpoint, and logging the user into the MinIO deployment.
 
-   Starting in :minio-release:`RELEASE.2021-07-08T01-15-01Z`, the MinIO Console is
+   You can access the Console by opening the root URL for the MinIO cluster. For example, ``https://minio.example.net:9000``.
-   embedded in the MinIO server. You can access the Console by opening the root URL
-   for the MinIO cluster. For example, ``https://minio.example.net:9000``.
 
-   From the Console, click :guilabel:`BUTTON` to begin the Active Directory / LDAP
+   Once logged in, you can perform any action for which the authenticated user is :ref:`authorized <minio-external-identity-management-ad-ldap-access-control>`.
-   authentication flow.
 
-   Once logged in, you can perform any action for which the authenticated
+   You can also create :ref:`access keys <minio-idp-service-account>` for supporting applications which must perform operations on MinIO.
-   user is :ref:`authorized 
+   Access Keys are long-lived credentials which inherit their privileges from the parent user.
-   <minio-external-identity-management-ad-ldap-access-control>`. 
+   The parent user can further restrict those privileges while creating the service account.
-
-   You can also create :ref:`access keys <minio-idp-service-account>` for
-   supporting applications which must perform operations on MinIO. Access Keys
-   are long-lived credentials which inherit their privileges from the parent user.
-   The parent user can further restrict those privileges while creating the service
-   account. 
 
    4) Generate S3-Compatible Temporary Credentials using AD/LDAP Credentials
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-   MinIO requires clients authenticate using :s3-api:`AWS Signature Version 4
+   MinIO requires clients to authenticate using :s3-api:`AWS Signature Version 4 protocol <sig-v4-authenticating-requests.html>` with support for the deprecated Signature Version 2 protocol.
-   protocol <sig-v4-authenticating-requests.html>` with support for the deprecated
+   Specifically, clients must present a valid access key and secret key to access any S3 or MinIO administrative API, such as ``PUT``, ``GET``, and ``DELETE`` operations.
-   Signature Version 2 protocol. Specifically, clients must present a valid access
-   key and secret key to access any S3 or MinIO administrative API, such as
-   ``PUT``, ``GET``, and ``DELETE`` operations.
 
-   Applications can generate temporary access credentials as-needed using the
+   Applications can generate temporary access credentials as-needed using the :ref:`minio-sts-assumerolewithldapidentity` Security Token Service (STS) API endpoint and AD/LDAP user credentials. 
-   :ref:`minio-sts-assumerolewithldapidentity` Security Token Service (STS) API
+   MinIO provides an example Go application :minio-git:`ldap.go <minio/blob/master/docs/sts/ldap.go>` that manages this workflow.
-   endpoint and AD/LDAP user credentials. MinIO provides an example Go application
-   :minio-git:`ldap.go <minio/blob/master/docs/sts/ldap.go>` with an example of
-   managing this workflow.
 
    .. code-block:: shell
 
@@ -257,13 +266,11 @@ An AD/LDAP user with no assigned policy *and* with membership in groups with no
    - Replace the ``LDAPPassword`` with the password of the AD/LDAP user.
 
    - Replace the ``Policy`` with an inline URL-encoded JSON :ref:`policy <minio-policy>` that further restricts the permissions associated to the temporary credentials. 
-   
+
      Omit to use the  :ref:`policy whose name matches <minio-external-identity-management-ad-ldap-access-control>` the Distinguished Name (DN) of the AD/LDAP user. 
 
-   The API response consists of an XML document containing the
+   The API response consists of an XML document containing the access key, secret key, session token, and expiration date.
-   access key, secret key, session token, and expiration date. Applications
+   Applications can use the access key and secret key to access and perform operations on MinIO.
-   can use the access key and secret key to access and perform operations on
-   MinIO.
 
    See the :ref:`minio-sts-assumerolewithldapidentity` for reference documentation.
 
@@ -277,3 +284,5 @@ You can enable and disable the configured AD/LDAP connection as needed.
 
 Use :mc-cmd:`mc idp ldap disable` to deactivate a configured connection.
 Use :mc-cmd:`mc idp ldap enable` to activate a previously configured connection.
+
+You may also enable or disable AD/LDAP from the :ref:`MinIO Console <minio-console>`.

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

@@ -2299,9 +2299,18 @@ Active Directory / LDAP Identity Management
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following section documents settings for enabling external identity 
-management using an Active Directory or LDAP service. See 
+management using an Active Directory or LDAP service.
-:ref:`minio-external-identity-management-ad-ldap` for a tutorial on using these 
+
-configuration settings.
+.. admonition:: :mc:`mc idp ldap` commands are preferred
+   :class: note
+
+   .. versionadded:: RELEASE.2023-05-26T23-31-54Z
+
+      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`.
+
+      The :mc-conf:`identity_ldap` configuration key remains available for existing scripts and other tools.
 
 .. mc-conf:: identity_ldap
 
@@ -2309,7 +2318,7 @@ configuration settings.
    :ref:`external identity management using Active Directory or LDAP 
    <minio-external-identity-management-ad-ldap>`.
 
-   Use the :mc-cmd:`mc admin config set` to set or update the 
+   Use the :mc-cmd:`mc admin config set` command to set or update the 
    AD/LDAP configuration. The following arguments are *required*:
 
    - :mc-conf:`~identity_ldap.server_addr`
@@ -2323,7 +2332,7 @@ configuration settings.
 
       mc admin config set identity_ldap \
          enabled="true" \
-         server_addr="https://ad-ldap.example.net/" \
+         server_addr="ad-ldap.example.net/" \
          lookup_bind_dn="cn=miniolookupuser,dc=example,dc=net" \
          lookup_bind_dn_password="userpassword" \
          user_dn_search_base_dn="dc=example,dc=net" \

source/reference/minio-mc/mc-idp-ldap.rst

@@ -25,7 +25,9 @@ The :mc-cmd:`mc idp ldap` commands allow you to manage configurations to 3rd par
 
 .. end-mc-idp-ldap-desc
 
-Define configuration settings as an alternative to using environment variables when :ref:`setting up an AD/LDAP connection <minio-authenticate-using-ad-ldap-generic>`. The :mc-cmd:`mc idp ldap` commands are only supported against MinIO deployments.
+The :mc-cmd:`mc idp ldap` commands are an alternative to using environment variables when :ref:`setting up an AD/LDAP connection <minio-authenticate-using-ad-ldap-generic>`. They are only supported against MinIO deployments.
+
+See :ref:`minio-external-identity-management-ad-ldap` for a tutorial on using these commands.
 
 .. note::
 
@@ -67,8 +69,8 @@ The :mc-cmd:`mc idp ldap` command has the following subcommands:
 Configuration Parameters
 ------------------------
 
-The :mc-cmd:`mc idp ldap` subcommands support configuration parameters.
+The :mc-cmd:`mc idp ldap` subcommands support the same configuration parameters as the :mc-conf:`identity_ldap` configuration key.
-The parameters define the server's interaction with the Active Directory or LDAP IAM provider.
+These parameters define the server's interaction with the Active Directory or LDAP IAM provider.
 
 For a more detailed explanation of the configuration parameters, refer to the :ref:`config setting documentation <minio-ldap-config-settings>`.