Add notes on configuring LDAP STS with Microsoft Active Directory (#8260)

2024-12-24 06:05:55 -05:00 · 2019-09-17 17:21:37 -07:00 · 2019-09-17 17:21:37 -07:00 · 696f4ceee2
commit 696f4ceee2
parent dac1cf5a9a
2 changed files with 77 additions and 28 deletions
--- a/docs/sts/README.md
+++ b/docs/sts/README.md
@ -11,12 +11,15 @@ Following are advantages for using temporary credentials:
 - Temporary credentials have a limited lifetime, there is no need to rotate them or explicitly revoke them. Expired temporary credentials cannot be reused.

 ## Identity Federation
- [**Client grants**](https://github.com/minio/minio/blob/master/docs/sts/client-grants.md) - Let applications request `client_grants` using any well-known third party identity provider such as KeyCloak, WSO2. This is known as the client grants approach to temporary access. Using this approach helps clients keep MinIO credentials to be secured. MinIO STS supports client grants, tested against identity providers such as WSO2, KeyCloak.
- [**WebIdentity**](https://github.com/minio/minio/blob/master/docs/sts/web-identity.md) - Let users request temporary credentials using any OpenID(OIDC) compatible web identity providers such as Facebook, Google etc.
- [**AssumeRole**](https://github.com/minio/minio/blob/master/docs/sts/assume-role.md) - Let MinIO users request temporary credentials using user access and secret keys.
+|AuthN | Description |
+| :---------------------- | ------------------------------------------ |
+| [**Client grants**](https://github.com/minio/minio/blob/master/docs/sts/client-grants.md) | Let applications request `client_grants` using any well-known third party identity provider such as KeyCloak, WSO2. This is known as the client grants approach to temporary access. Using this approach helps clients keep MinIO credentials to be secured. MinIO STS supports client grants, tested against identity providers such as WSO2, KeyCloak. |
+| [**WebIdentity**](https://github.com/minio/minio/blob/master/docs/sts/web-identity.md) | Let users request temporary credentials using any OpenID(OIDC) compatible web identity providers such as Facebook, Google etc. |
+| [**AssumeRole**](https://github.com/minio/minio/blob/master/docs/sts/assume-role.md) | Let MinIO users request temporary credentials using user access and secret keys. |
+| [**AD/LDAP**](https://github.com/minio/minio/blob/master/docs/sts/ldap.md) | Let AD/LDAP users request temporary credentials using AD/LDAP username and password. |

 ## Get started
-In this document we will explain in detail on how to configure all the prerequisites, primarily WSO2, OPA (open policy agent).
+In this document we will explain in detail on how to configure all the prerequisites.

 > NOTE: If you are interested in AssumeRole API only, skip to [here](https://github.com/minio/minio/blob/master/docs/sts/assume-role.md)

--- a/docs/sts/ldap.md
+++ b/docs/sts/ldap.md
@ -1,14 +1,14 @@
-# MinIO LDAP Integration
+# MinIO AD/LDAP Integration [![Slack](https://slack.min.io/slack?type=svg)](https://slack.min.io)

 MinIO provides a custom STS API that allows integration with LDAP
 based corporate environments. The flow is as follows:

-1. User provides their LDAP username and password to the STS API.
-2. MinIO logs-in to the LDAP server as the user - if the login
+1. User provides their AD/LDAP username and password to the STS API.
+2. MinIO logs-in to the AD/LDAP server as the user - if the login
   succeeds the user is authenticated.
-3. MinIO then queries the LDAP server for a list of groups that the
+3. MinIO then queries the AD/LDAP server for a list of groups that the
   user is a member of.
-   - This is done via a customizable LDAP search query.
+   - This is done via a customizable AD/LDAP search query.
 4. MinIO then generates temporary credentials for the user storing the
   list of groups in a cryptographically secure session token. The
   temporary access key, secret key and session token are returned to
@ -22,42 +22,41 @@ applicable policies on a user (these are the policies associated with
 the groups along with the policy on the user if any) to check if the
 request should be allowed or denied.

-## Configuring LDAP on MinIO
+## Configuring AD/LDAP on MinIO

-LDAP configuration is designed to be simple for the MinIO
-administrator.
+LDAP configuration is designed to be simple for the MinIO administrator.

 The full path of a user DN (Distinguished Name)
 (e.g. `uid=johnwick,cn=users,cn=accounts,dc=minio,dc=io`) is
 configured as a format string in the
 **MINIO_IDENTITY_LDAP_USERNAME_FORMAT** environment variable. This
-allows an LDAP user to not specify this whole string in the LDAP STS
+allows an AD/LDAP user to not specify this whole string in the AD/LDAP STS
 API. Instead the user only needs to specify the username portion
 (i.e. `johnwick` in this example) that will be substituted into the
 format string configured on the server.

-MinIO can be configured to find the groups of a user from LDAP by
+MinIO can be configured to find the groups of a user from AD/LDAP by
 specifying the **MINIO_IDENTITY_LDAP_GROUP_SEARCH_FILTER** and
 **MINIO_IDENTITY_LDAP_GROUP_NAME_ATTRIBUTE** environment
 variables. When a user logs in via the STS API, the MinIO server
-queries the LDAP server with the given search filter and extracts the
+queries the AD/LDAP server with the given search filter and extracts the
 given attribute from the search results. These values represent the
 groups that the user is a member of. On each access MinIO applies the
 IAM policies attached to these groups in MinIO.

 LDAP is configured via the following environment variables:

-| Variable                                     | Required?                 | Purpose                                             |
-|----------------------------------------------|---------------------------|-----------------------------------------------------|
-| **MINIO_IDENTITY_LDAP_SERVER_ADDR**               | **YES**                   | LDAP server address                                 |
-| **MINIO_IDENTITY_LDAP_USERNAME_FORMAT**      | **YES**                   | Format of full username DN                          |
-| **MINIO_IDENTITY_LDAP_GROUP_SEARCH_BASE_DN** | **NO**                    | Base DN in LDAP hierarchy to use in search requests |
-| **MINIO_IDENTITY_LDAP_GROUP_SEARCH_FILTER**  | **NO**                    | Search filter to find groups of a user              |
-| **MINIO_IDENTITY_LDAP_GROUP_NAME_ATTRIBUTE** | **NO**                    | Attribute of search results to use as group name    |
-| **MINIO_IDENTITY_LDAP_STS_EXPIRY_DURATION**  | **NO** (default: "1h")    | STS credentials validity duration                   |
-| **MINIO_IDENTITY_LDAP_TLS_SKIP_VERIFY**      | **NO** (default: "false") | Disable TLS certificate verification                |
+| Variable                                     | Required?                 | Purpose                                                |
+|----------------------------------------------|---------------------------|--------------------------------------------------------|
+| **MINIO_IDENTITY_LDAP_SERVER_ADDR**          | **YES**                   | AD/LDAP server address                                 |
+| **MINIO_IDENTITY_LDAP_USERNAME_FORMAT**      | **YES**                   | Format of full username DN                             |
+| **MINIO_IDENTITY_LDAP_GROUP_SEARCH_BASE_DN** | **NO**                    | Base DN in AD/LDAP hierarchy to use in search requests |
+| **MINIO_IDENTITY_LDAP_GROUP_SEARCH_FILTER**  | **NO**                    | Search filter to find groups of a user                 |
+| **MINIO_IDENTITY_LDAP_GROUP_NAME_ATTRIBUTE** | **NO**                    | Attribute of search results to use as group name       |
+| **MINIO_IDENTITY_LDAP_STS_EXPIRY_DURATION**  | **NO** (default: "1h")    | STS credentials validity duration                      |
+| **MINIO_IDENTITY_LDAP_TLS_SKIP_VERIFY**      | **NO** (default: "false") | Disable TLS certificate verification                   |

-Please note that MinIO will only access the LDAP server over TLS.
+Please note that MinIO will only access the AD/LDAP server over TLS.

 An example setup for development or experimentation:

@ -71,7 +70,7 @@ export MINIO_IDENTITY_LDAP_STS_EXPIRY_DURATION=60
 export MINIO_IDENTITY_LDAP_TLS_SKIP_VERIFY=true
 ```

-### Variable substitution in LDAP configuration strings
+### Variable substitution in AD/LDAP configuration strings

 In the configuration values described above, some values support
 runtime substitutions. The substitution syntax is simply
@ -80,8 +79,8 @@ runtime substitutions. The substitution syntax is simply

 | Variable     | Example Runtime Value                          | Description                                                                                                                                  |
 |--------------|------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|
-| *username*   | "james"                                        | The LDAP username of a user.                                                                                                                 |
-| *usernamedn* | "uid=james,cn=accounts,dc=myldapserver,dc=com" | The LDAP username DN of a user. This is constructed from the LDAP user DN format string provided to the server and the actual LDAP username. |
+| *username*   | "james"                                        | The AD/LDAP username of a user.                                                                                                                 |
+| *usernamedn* | "uid=james,cn=accounts,dc=myldapserver,dc=com" | The AD/LDAP username DN of a user. This is constructed from the AD/LDAP user DN format string provided to the server and the actual AD/LDAP username. |

 The **MINIO_IDENTITY_LDAP_USERNAME_FORMAT** environment variable
 supports substitution of the *username* variable only.
@ -90,3 +89,50 @@ The **MINIO_IDENTITY_LDAP_GROUP_SEARCH_FILTER** and
 **MINIO_IDENTITY_LDAP_GROUP_SEARCH_BASE_DN** environment variables
 support substitution of the *username* and *usernamedn* variables
 only.
+
+## Notes on configuring with Microsoft Active Directory (AD)
+
+The LDAP STS API also works with Microsoft AD and can be configured
+as above. The following are some notes on determining the values of
+the configuration parameters described above.
+
+Once LDAP over TLS is enabled on AD, test access to LDAP works by running a
+sample search query with the `ldapsearch` utility from
+[OpenLDAP](https://openldap.org/):
+
+```shell
+$ ldapsearch -H ldaps://my.ldap-active-dir-server.com -D "username@minioad.local" -x -w 'secretpassword' -b "dc=minioad,dc=local"
+...
+
+# John, Users, minioad.local
+dn: CN=John,CN=Users,DC=minioad,DC=local
+...
+
+# hpc, Users, minioad.local
+dn: CN=hpc,CN=Users,DC=minioad,DC=local
+objectClass: top
+objectClass: group
+cn: hpc
+...
+member: CN=John,CN=Users,DC=minioad,DC=local
+...
+```
+
+The lines with "..." represent skipped content not shown here from brevity.
+
+Based on the output above, we see that the username format variable looks like
+`cn=${username},cn=users,dc=minioad,dc=local`.
+
+The group search filter looks like
+`(&(objectclass=group)(member=${usernamedn}))` and the group name attribute is
+clearly `cn`.
+
+Thus the key configuration parameters look like:
+
+```
+MINIO_IDENTITY_LDAP_SERVER_ADDR='ldaps://my.ldap-active-dir-server.com:636'
+MINIO_IDENTITY_LDAP_USERNAME_FORMAT='cn=${username},cn=users,dc=minioad,dc=local'
+MINIO_IDENTITY_LDAP_GROUP_SEARCH_BASE_DN='dc=minioad,dc=local'
+MINIO_IDENTITY_LDAP_GROUP_SEARCH_FILTER='(&(objectclass=group)(member=${usernamedn}))'
+MINIO_IDENTITY_LDAP_GROUP_NAME_ATTRIBUTE='cn'
+```