From 8f598693f08ffcf080fd24253119127fc9002e1c Mon Sep 17 00:00:00 2001 From: Andrea Longo Date: Thu, 10 Aug 2023 09:44:12 -0600 Subject: [PATCH] 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 Co-authored-by: Daryl White <53910321+djwfyi@users.noreply.github.com> --- .../console/security-and-access.rst | 5 +- .../ad-ldap-access-management.rst | 7 +- .../includes/common-minio-external-auth.rst | 22 +- ...e-ad-ldap-external-identity-management.rst | 193 +++++++++--------- .../minio-mc-admin/mc-admin-config.rst | 19 +- source/reference/minio-mc/mc-idp-ldap.rst | 8 +- 6 files changed, 148 insertions(+), 106 deletions(-) diff --git a/source/administration/console/security-and-access.rst b/source/administration/console/security-and-access.rst index 14fa9201..4ae5fdff 100644 --- a/source/administration/console/security-and-access.rst +++ b/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. \ No newline at end of file +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. diff --git a/source/administration/identity-access-management/ad-ldap-access-management.rst b/source/administration/identity-access-management/ad-ldap-access-management.rst index 7cd5081d..a5634fed 100644 --- a/source/administration/identity-access-management/ad-ldap-access-management.rst +++ b/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 ` 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 ` 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 ` 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. \ No newline at end of file + operations. diff --git a/source/includes/common-minio-external-auth.rst b/source/includes/common-minio-external-auth.rst index 2232301b..bce6464a 100644 --- a/source/includes/common-minio-external-auth.rst +++ b/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 ` 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 `. + +.. 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 \ No newline at end of file +.. end-minio-identity-management-comment + diff --git a/source/operations/external-iam/configure-ad-ldap-external-identity-management.rst b/source/operations/external-iam/configure-ad-ldap-external-identity-management.rst index c938d0d6..b2ff9684 100644 --- a/source/operations/external-iam/configure-ad-ldap-external-identity-management.rst +++ b/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 ` to perform authenticated user and group queries. - Ensure each AD/LDAP user and group intended for use with MinIO has a corresponding :ref:`policy ` 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 ` 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 - environment variables *or* server runtime configuration settings. Both - methods require starting/restarting the MinIO deployment to apply changes. The - following tabs provide a quick reference of all required and optional - environment variables and configuration settings respectively: + Configure the AD/LDAP provider using one of the following: + + * MinIO Client + * Environment variables + * 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 ` + - :mc-conf:`lookup_bind_dn ` + - :mc-conf:`lookup_bind_password ` + - :mc-conf:`user_dn_search_base_dn ` + - :mc-conf:`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 - settings using :ref:`environment variables - `. The - :mc:`minio server` process applies the specified settings on its next - startup. For distributed deployments, specify these settings across all - nodes in the deployment using the *same* values consistently. + MinIO supports specifying the AD/LDAP provider settings using :ref:`environment variables `. + The :mc:`minio server` process applies the specified settings on its next startup. + For distributed deployments, specify these settings across all nodes in the deployment using the *same* values. + Any differences in server configurations between nodes will result in startup or configuration failures. + + 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 - :ref:`minio-server-envvar-external-identity-management-ad-ldap` + export MINIO_IDENTITY_LDAP_STS_EXPIRY="1h" + 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 - settings using :mc-conf:`configuration settings `. 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. + .. tab-item:: MinIO Console - The following example code sets *all* configuration settings related to - configuring an AD/LDAP provider for external - identity management. The minimum *required* setting are: - - - :mc-conf:`identity_ldap server_addr ` - - - :mc-conf:`identity_ldap lookup_bind_dn ` - - - :mc-conf:`identity_ldap lookup_bind_password ` - - - :mc-conf:`identity_ldap user_dn_search_base_dn ` - - - :mc-conf:`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`. + MinIO supports specifying the AD/LDAP provider settings using the :ref:`MinIO Console `. + For distributed deployments, configuring AD/LDAP from the Console applies the configuration to all nodes in the deployment. + .. 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. - Use the :mc-cmd:`mc admin service restart` command to restart the deployment. + You must restart the MinIO deployment to apply the configuration changes. + + 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 ` of the deployment to - restart. + Replace ``ALIAS`` with the :ref:`alias ` of the deployment to restart. 3) Use the MinIO Console to Log In with AD/LDAP Credentials ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - 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. + 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. - Starting in :minio-release:`RELEASE.2021-07-08T01-15-01Z`, the MinIO Console is - 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``. + 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 - authentication flow. + Once logged in, you can perform any action for which the authenticated user is :ref:`authorized `. - Once logged in, you can perform any action for which the authenticated - user is :ref:`authorized - `. - - You can also create :ref:`access keys ` 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. + You can also create :ref:`access keys ` 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 - protocol ` with support for the deprecated - 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. + MinIO requires clients to authenticate using :s3-api:`AWS Signature Version 4 protocol ` with support for the deprecated 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 - :ref:`minio-sts-assumerolewithldapidentity` Security Token Service (STS) API - endpoint and AD/LDAP user credentials. MinIO provides an example Go application - :minio-git:`ldap.go ` with an example of - managing this workflow. + 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. + MinIO provides an example Go application :minio-git:`ldap.go ` that manages 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 ` that further restricts the permissions associated to the temporary credentials. - + Omit to use the :ref:`policy whose name matches ` the Distinguished Name (DN) of the AD/LDAP user. - The API response consists of an XML document containing the - access key, secret key, session token, and expiration date. Applications - can use the access key and secret key to access and perform operations on - MinIO. + The API response consists of an XML document containing the access key, secret key, session token, and expiration date. + Applications 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 `. diff --git a/source/reference/minio-mc-admin/mc-admin-config.rst b/source/reference/minio-mc-admin/mc-admin-config.rst index f43e1463..aa8fbfca 100644 --- a/source/reference/minio-mc-admin/mc-admin-config.rst +++ b/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 -:ref:`minio-external-identity-management-ad-ldap` for a tutorial on using these -configuration settings. +management using an Active Directory or LDAP service. + +.. 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 `. - 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" \ diff --git a/source/reference/minio-mc/mc-idp-ldap.rst b/source/reference/minio-mc/mc-idp-ldap.rst index 29326460..1779ce81 100644 --- a/source/reference/minio-mc/mc-idp-ldap.rst +++ b/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 `. 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 `. 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 parameters define the server's interaction with the Active Directory or LDAP IAM provider. +The :mc-cmd:`mc idp ldap` subcommands support the same configuration parameters as the :mc-conf:`identity_ldap` configuration key. +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 `.