Documentation

Configure MinIO for Authentication using Active Directory / LDAP

MinIO supports configuring a single Active Directory / LDAP Connect for external management of user identities.

The procedure on this page provides instructions for:

  • Configuring a MinIO cluster for an external AD/LDAP provider.

  • 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. See the documentation for the AD/LDAP provider of your choice for specific instructions or procedures on configuration of user identities.

This procedure assumes an existing Active Directory or LDAP service. Instructions on configuring AD/LDAP are out of scope for this procedure.

MinIO requires a read-only access keys with which it binds to perform authenticated user and group queries. Ensure each AD/LDAP user and group intended for use with MinIO has a corresponding 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.

This procedure assumes an existing MinIO cluster running the latest stable MinIO version. Defer to the Install and Deploy MinIO for more complete documentation on new MinIO deployments.

This procedure may work as expected for older versions of MinIO.

This procedure uses mc for performing operations on the MinIO cluster. Install mc on a machine with network access to the cluster. See the mc Installation Quickstart for instructions on downloading and installing mc.

This procedure assumes a configured alias for the MinIO cluster.

Configure the AD/LDAP provider using one of the following:

  • MinIO Client

  • Environment variables

All methods require starting/restarting the MinIO deployment to apply changes.

The following tabs provide a quick reference for the available configuration methods:

MinIO supports specifying the AD/LDAP provider settings using mc idp ldap commands.

For distributed deployments, the 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 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"                                                       \
   tls_skip_verify="off"                                                \
   server_insecure=off                                                  \
   server_starttls="off"                                                \
   srv_record_name=""                                                   \
   comment="Test LDAP server"

For more complete documentation on these settings, see mc idp ldap.

MinIO supports specifying the AD/LDAP provider settings using environment variables. The 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:

export MINIO_IDENTITY_LDAP_SERVER_ADDR="ldaps.example.net:636"
export MINIO_IDENTITY_LDAP_LOOKUP_BIND_DN="CN=xxxxx,OU=xxxxx,OU=xxxxx,DC=example,DC=net"
export MINIO_IDENTITY_LDAP_USER_DN_SEARCH_BASE_DN="dc=example,dc=net"
export MINIO_IDENTITY_LDAP_USER_DN_SEARCH_FILTER="(&(objectCategory=user)(sAMAccountName=%s))"
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_SERVER_INSECURE="off"
export MINIO_IDENTITY_LDAP_SERVER_STARTTLS="off"
export MINIO_IDENTITY_LDAP_SRV_RECORD_NAME=""
export MINIO_IDENTITY_LDAP_COMMENT="LDAP test server"

For complete documentation on these variables, see Active Directory / LDAP Settings

You must restart the MinIO deployment to apply the configuration changes.

For MinIO Client and environment variable configuration, use the mc admin service restart command to restart the deployment:

mc admin service restart ALIAS

Replace ALIAS with the alias of the deployment to restart.

MinIO requires clients to authenticate using 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 AssumeRoleWithLDAPIdentity Security Token Service (STS) API endpoint and AD/LDAP user credentials. MinIO provides an example Go application ldap.go that manages this workflow.

POST https://minio.example.net?Action=AssumeRoleWithLDAPIdentity
&LDAPUsername=USERNAME
&LDAPPassword=PASSWORD
&Version=2011-06-15
&Policy={}
  • Replace the LDAPUsername with the username of the AD/LDAP user.

  • Replace the LDAPPassword with the password of the AD/LDAP user.

  • Replace the Policy with an inline URL-encoded JSON policy that further restricts the permissions associated to the temporary credentials.

    Omit to use the 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.

See the AssumeRoleWithLDAPIdentity for reference documentation.

New in version RELEASE.2023-03-20T20-16-18Z.

You can enable and disable the configured AD/LDAP connection as needed.

Use mc idp ldap disable to deactivate a configured connection. Use mc idp ldap enable to activate a previously configured connection.