mirror of
https://github.com/minio/docs.git
synced 2025-08-06 14:42:56 +03:00
282 lines
12 KiB
ReStructuredText
282 lines
12 KiB
ReStructuredText
.. _minio-external-identity-management-ad-ldap:
|
|
|
|
====================================================
|
|
Active Directory / LDAP External Identity Management
|
|
====================================================
|
|
|
|
.. default-domain:: minio
|
|
|
|
.. contents:: Table of Contents
|
|
:local:
|
|
:depth: 2
|
|
|
|
Overview
|
|
--------
|
|
|
|
MinIO supports using an Active Directory or LDAP (AD/LDAP) service for external
|
|
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 by default denies access to all actions or resources not explicitly
|
|
allowed by a user's assigned or inherited :ref:`policies <minio-policy>`. Users
|
|
managed by an AD/LDAP provider must specify the necessary policies as part of
|
|
the user profile data. See :ref:`Access Control for AD/LDAP Managed Identities
|
|
<minio-external-identity-management-ad-ldap-access-control>` for more
|
|
information.
|
|
|
|
See :ref:`minio-authenticate-using-ad-ldap-generic` for instructions on enabling
|
|
external identity management using an AD/LDAP service.
|
|
|
|
.. admonition:: MinIO Supports At Most One Configured IDentity Provider
|
|
:class: important
|
|
|
|
Configuring an external IDP disables the :ref:`MinIO internal IDP
|
|
<minio-internal-idp>` and prevents the configuration of any other
|
|
external IDP.
|
|
|
|
The external :abbr:`IDP (IDentity Provider)` must have *at least* one
|
|
configured user identity with the required :ref:`policy claims
|
|
<minio-external-identity-management-ad-ldap-access-control>`. If no such user
|
|
exists, the MinIO server is effectively inaccessible outside of using the
|
|
:ref:`root <minio-users-root>` user.
|
|
|
|
Authentication and Authorization Flow
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The login flow for an application using Active Directory / LDAP
|
|
credentials is as follows:
|
|
|
|
1. Specify the AD/LDAP credentials to the MinIO Security Token Service (STS)
|
|
:ref:`minio-sts-assumerolewithldapidentity` API endpoint.
|
|
|
|
2. MinIO verifies the provided credentials against the AD/LDAP server.
|
|
|
|
3. MinIO checks for any :ref:`policy <minio-policy>` whose name matches the
|
|
user Distinguished Name (DN) and assigns that policy to the authenticated
|
|
user.
|
|
|
|
If configured to perform group queries, MinIO also queries for a list of
|
|
AD/LDAP groups in which the user has membership. MinIO checks for any policy
|
|
whose name matches a returned group DN and assigns that
|
|
policy to the authenticated user.
|
|
|
|
4. MinIO returns temporary credentials in the STS API response in the form of an
|
|
access key, secret key, and session token. The credentials have permissions
|
|
matching those policies whose name matches either the authenticated user DN
|
|
*or* a group DN.
|
|
|
|
MinIO provides an example Go application
|
|
:minio-git:`ldap.go <minio/blob/master/docs/sts/ldap.go>` that handles the
|
|
full login flow.
|
|
|
|
AD/LDAP users can alternatively create :ref:`service accounts <minio-idp-service-account>` associated to their AD/LDAP user Distinguished Name. Service accounts 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. Use either of the following methods to create a new service account
|
|
|
|
- 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:`Service Accounts` followed by the :guilabel:`Create service account +` button.
|
|
|
|
- Use the :mc-cmd:`mc admin user svcacct add` command to create the service account. Specify the user Distinguished Name as the username to which to associate the service account.
|
|
|
|
Querying the Active Directory / LDAP Service
|
|
--------------------------------------------
|
|
|
|
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. 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.
|
|
|
|
The following tabs provide a reference of the environment variables and
|
|
configuration settings required for enabling Lookup-Bind mode.
|
|
|
|
.. tab-set::
|
|
|
|
.. tab-item:: Environment Variable
|
|
|
|
- :envvar:`MINIO_IDENTITY_LDAP_LOOKUP_BIND_DN`
|
|
- :envvar:`MINIO_IDENTITY_LDAP_LOOKUP_BIND_PASSWORD`
|
|
- :envvar:`MINIO_IDENTITY_LDAP_USER_DN_SEARCH_BASE_DN`
|
|
- :envvar:`MINIO_IDENTITY_LDAP_USER_DN_SEARCH_FILTER`
|
|
|
|
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
|
|
instructions on setting these values.
|
|
|
|
.. tab-item:: Configuration Setting
|
|
|
|
- :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>`
|
|
|
|
See the :mc-conf:`identity_ldap` reference documentation for more
|
|
information on these settings. The
|
|
:ref:`minio-authenticate-using-openid-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.
|
|
|
|
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 Externally Managed Identities
|
|
------------------------------------------------
|
|
|
|
MinIO uses :ref:`Policy Based Access Control (PBAC) <minio-access-management>`
|
|
to define the actions and resources to which an authenticated user has access.
|
|
When using an Active Directory/LDAP server for identity management
|
|
(authentication), MinIO maintains control over access (authorization)
|
|
through PBAC.
|
|
|
|
When a user successfully authenticates to MinIO using their AD/LDAP
|
|
credentials, MinIO searches for all :ref:`policies <minio-policy>` which
|
|
are explicitly associated to that user's Distinguished Name (DN).
|
|
Specifically, the policy must be assigned to a user with a matching DN
|
|
using the :mc-cmd:`mc admin policy set` command.
|
|
|
|
For example, consider the following policy assignments:
|
|
|
|
.. code-block:: shell
|
|
|
|
mc admin policy set --consoleAdmin user='cn=sisko,cn=users,dc=example,dc=com'
|
|
mc admin policy set --readwrite,diagnostics user='cn=dax,cn=users,dc=example,dc=com'
|
|
|
|
- MinIO would assign an authenticated user with DN matching
|
|
``cn=sisko,cn=users,dc=example,dc=com`` the :userpolicy:`consoleAdmin`
|
|
policy, granting complete access to the MinIO server.
|
|
|
|
- MinIO would assign an authenticated user with DN matching
|
|
``cn=dax,cn=users,dc=example,dc=com`` both the :userpolicy:`readwrite` and
|
|
:userpolicy:`diagnostics` policies, granting general read/write access to the
|
|
MinIO server *and* access to diagnostic administrative operations.
|
|
|
|
- MinIO would assign no policies to an authenticated user with DN matching
|
|
``cn=quark,cn=users,dc=example,dc=com`` and deny all access to API operations.
|
|
|
|
MinIO also supports querying for the user's AD/LDAP group membership. MinIO
|
|
attempts to match existing policies to the DN for each of the user's groups. The
|
|
authenticated users complete set of permissions consists of its explicitly
|
|
assigned and group-inherited policies. See
|
|
:ref:`minio-external-identity-management-ad-ldap-access-control-group-lookup`
|
|
for more information.
|
|
|
|
MinIO uses deny-by-default behavior where a user with no explicitly assigned or
|
|
group-inherited policies cannot access any resource on the MinIO deployment.
|
|
|
|
MinIO provides :ref:`built-in policies <minio-policy-built-in>` for basic access
|
|
control. You can create new policies using the :mc:`mc admin policy` command.
|
|
|
|
.. _minio-external-identity-management-ad-ldap-access-control-group-lookup:
|
|
|
|
Group Lookup
|
|
~~~~~~~~~~~~
|
|
|
|
MinIO supports querying the Active Directory / LDAP server for a list of
|
|
groups in which the authenticated user has membership. MinIO
|
|
attempts to match existing :ref:`policies <minio-policy>` to each group
|
|
DN and assigns each matching policy to the authenticated user.
|
|
|
|
For example, consider the following policy assignments:
|
|
|
|
.. code-block:: shell
|
|
|
|
mc admin policy set --consoleAdmin group='cn=ops,cn=groups,dc=example,dc=com'
|
|
mc admin policy set --diagnostics group='cn=engineering,cn=groups,dc=example,dc=com'
|
|
|
|
- MinIO would assign any authenticating user with membership in the
|
|
``cn=ops,cn=groups,dc=example,dc=com`` AD/LDAP group the
|
|
:userpolicy:`consoleAdmin` policy, granting complete access to the MinIO
|
|
server.
|
|
|
|
- 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.
|
|
|
|
The following tabs provide a reference of the environment variables and
|
|
configuration settings required for enabling group lookups:
|
|
|
|
.. tab-set::
|
|
|
|
.. tab-item:: Environment Variable
|
|
|
|
- :envvar:`MINIO_IDENTITY_LDAP_GROUP_SEARCH_BASE_DN`
|
|
- :envvar:`MINIO_IDENTITY_LDAP_GROUP_SEARCH_FILTER`
|
|
|
|
See the :ref:`minio-server-envvar-external-identity-management-ad-ldap`
|
|
reference documentation for more information on these variables. The
|
|
:ref:`minio-authenticate-using-ad-ldap-generic` tutorial includes complete
|
|
instructions on setting these values.
|
|
|
|
.. tab-item:: Configuration Setting
|
|
|
|
|
|
- :mc-conf:`identity_ldap group_search_base_dn <identity_ldap.group_search_base_dn>`
|
|
- :mc-conf:`identity_ldap group_search_filter <identity_ldap.group_search_filter>`
|
|
|
|
See the :mc-conf:`identity_ldap` reference documentation for more
|
|
information on these settings. The
|
|
:ref:`minio-authenticate-using-ad-ldap-generic` tutorial includes complete
|
|
instructions on setting these variables.
|
|
|
|
|
|
.. toctree::
|
|
:titlesonly:
|
|
:hidden:
|
|
|
|
/security/ad-ldap-external-identity-management/configure-ad-ldap-external-identity-management.rst
|
|
/security/ad-ldap-external-identity-management/AssumeRoleWithLDAPIdentity.rst
|
|
|