From 3094615e387e927e7c49d583bf471906ec329801 Mon Sep 17 00:00:00 2001 From: Harshavardhana Date: Thu, 26 Sep 2019 11:18:26 -0700 Subject: [PATCH] Update LDAP document to reflect work user/group sub-commands (#8313) This PR also fixes markdown formatting --- docs/sts/ldap.md | 105 ++++++++++++----------------------------------- 1 file changed, 26 insertions(+), 79 deletions(-) diff --git a/docs/sts/ldap.md b/docs/sts/ldap.md index f0ab9bde3..8d0032706 100644 --- a/docs/sts/ldap.md +++ b/docs/sts/ldap.md @@ -1,48 +1,21 @@ # 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: +MinIO provides a custom STS API that allows integration with LDAP based corporate environments. The flow is as follows: 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 AD/LDAP server for a list of groups that the - user is a member of. +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 AD/LDAP server for a list of groups that the user is a member of. - 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 - the user. -5. The user can now use these credentials to make requests to the - MinIO server. - -The administrator will associate IAM access policies with each group -and if required with the user too. The MinIO server then evaluates -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. +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 the user. +5. The user can now use these credentials to make requests to the MinIO server. + +The administrator will associate IAM access policies with each group and if required with the user too. The MinIO server then evaluates 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 AD/LDAP on MinIO -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 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 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 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 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 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 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 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: @@ -56,9 +29,7 @@ LDAP is configured via the following environment variables: | **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 AD/LDAP server over TLS. - -An example setup for development or experimentation: +Please note that MinIO will only access the AD/LDAP server over TLS. An example setup for development or experimentation: ``` shell export MINIO_IDENTITY_LDAP_SERVER_ADDR=myldapserver.com:636 @@ -72,33 +43,22 @@ export MINIO_IDENTITY_LDAP_TLS_SKIP_VERIFY=true ### Variable substitution in AD/LDAP configuration strings -In the configuration values described above, some values support -runtime substitutions. The substitution syntax is simply -`${variable}` - this substring is replaced with the (string) value of -`variable`. The following substitutions will be available: +In the configuration values described above, some values support runtime substitutions. The substitution syntax is simply `${variable}` - this substring is replaced with the (string) value of `variable`. The following substitutions will be available: | Variable | Example Runtime Value | Description | |--------------|------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------| | *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. +The **MINIO_IDENTITY_LDAP_USERNAME_FORMAT** environment variable supports substitution of the *username* variable only. -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. +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. +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/): +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" @@ -118,14 +78,9 @@ 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 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`. +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: @@ -234,32 +189,24 @@ $ go run ldap.go -u foouser -p foopassword ## Managing User/Group Access Policy -Access policies may be configured on a group or on a user directly. Access -policies are first defined on the MinIO server using IAM policy JSON syntax. The -`mc` tool is used to issue the necessary commands. +Access policies may be configured on a group or on a user directly. Access policies are first defined on the MinIO server using IAM policy JSON syntax. The `mc` tool is used to issue the necessary commands. -**Note that by default no policy is set on a user**. Thus even if they -successfully authenticate with AD/LDAP credentials, they have no access to -object storage as the default access policy is to deny all access. +**Note that by default no policy is set on a user**. Thus even if they successfully authenticate with AD/LDAP credentials, they have no access to object storage as the default access policy is to deny all access. -To define a new policy, you can use the [AWS policy -generator](https://awspolicygen.s3.amazonaws.com/policygen.html). Copy the -policy into a text file `mypolicy.json` and issue the command like so: +To define a new policy, you can use the [AWS policy generator](https://awspolicygen.s3.amazonaws.com/policygen.html). Copy the policy into a text file `mypolicy.json` and issue the command like so: -```shell +```sh mc admin policy add myminio mypolicy mypolicy.json ``` To assign the policy to a user or group, use: -```shell +```sh mc admin policy set myminio mypolicy user=james +``` +```sh mc admin policy set myminio mypolicy group=bigdatausers ``` -**Please note that when AD/LDAP is configured, MinIO will not support long term -users defined internally.** Only AD/LDAP users are allowed. In addition to this, -the server will not support operations on users or groups using `mc admin user` -or `mc admin group` commands. This is because users and groups are defined -externally in AD/LDAP. +**Please note that when AD/LDAP is configured, MinIO will not support long term users defined internally.** Only AD/LDAP users are allowed. In addition to this, the server will not support operations on users or groups using `mc admin user` or `mc admin group` commands except `mc admin user info` and `mc admin group info` to list set policies for users and groups. This is because users and groups are defined externally in AD/LDAP.