storj.io/minio@v0.0.0-20230509071714-0cbc90f649b1/docs/sts/ldap.md (about) 1 # AssumeRoleWithLDAPIdentity [](https://slack.min.io) 2 3 **Table of Contents** 4 5 - [AssumeRoleWithLDAPIdentity [](https://slack.min.io)](#assumerolewithldapidentity-slackhttpsslackminioslacktypesvghttpsslackminio) 6 - [Introduction](#introduction) 7 - [Configuring AD/LDAP on MinIO](#configuring-adldap-on-minio) 8 - [Supported modes of operation](#supported-modes-of-operation) 9 - [Lookup-Bind Mode](#lookup-bind-mode) 10 - [Username-Format Mode](#username-format-mode) 11 - [Group membership search](#group-membership-search) 12 - [Variable substitution in AD/LDAP configuration strings](#variable-substitution-in-adldap-configuration-strings) 13 - [Managing User/Group Access Policy](#managing-usergroup-access-policy) 14 - [API Request Parameters](#api-request-parameters) 15 - [LDAPUsername](#ldapusername) 16 - [LDAPPassword](#ldappassword) 17 - [Version](#version) 18 - [Policy](#policy) 19 - [Response Elements](#response-elements) 20 - [Errors](#errors) 21 - [Sample `POST` Request](#sample-post-request) 22 - [Sample Response](#sample-response) 23 - [Using LDAP STS API](#using-ldap-sts-api) 24 - [Caveats](#caveats) 25 - [Explore Further](#explore-further) 26 27 ## Introduction 28 29 MinIO provides a custom STS API that allows integration with LDAP based corporate environments including Microsoft Active Directory. The MinIO server can be configured in two possible modes: either using a LDAP separate service account, called lookup-bind mode or in username-format mode. In either case the login flow for a user is the same as the STS flow: 30 31 1. User provides their AD/LDAP username and password to the STS API. 32 2. MinIO verifies the login credentials with the AD/LDAP server. 33 3. On success, MinIO queries the AD/LDAP server for a list of groups that the user is a member of. 34 - This is done via a customizable AD/LDAP search query. 35 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. 36 5. The user can now use these credentials to make requests to the MinIO server. 37 38 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. 39 40 ## Configuring AD/LDAP on MinIO 41 42 LDAP STS configuration can be performed via MinIO's standard configuration API (i.e. using `mc admin config set/get` commands) or equivalently via environment variables. For brevity we refer to environment variables here. 43 44 LDAP is configured via the following environment variables: 45 46 ``` 47 $ mc admin config set myminio identity_ldap --env 48 KEY: 49 identity_ldap enable LDAP SSO support 50 51 ARGS: 52 MINIO_IDENTITY_LDAP_SERVER_ADDR* (address) AD/LDAP server address e.g. "myldapserver.com:636" 53 MINIO_IDENTITY_LDAP_STS_EXPIRY (duration) temporary credentials validity duration in s,m,h,d. Default is "1h" 54 MINIO_IDENTITY_LDAP_LOOKUP_BIND_DN (string) DN for LDAP read-only service account used to perform DN and group lookups 55 MINIO_IDENTITY_LDAP_LOOKUP_BIND_PASSWORD (string) Password for LDAP read-only service account used to perform DN and group lookups 56 MINIO_IDENTITY_LDAP_USER_DN_SEARCH_BASE_DN (string) Base LDAP DN to search for user DN 57 MINIO_IDENTITY_LDAP_USER_DN_SEARCH_FILTER (string) Search filter to lookup user DN 58 MINIO_IDENTITY_LDAP_USERNAME_FORMAT (list) ";" separated list of username bind DNs e.g. "uid=%s,cn=accounts,dc=myldapserver,dc=com" 59 MINIO_IDENTITY_LDAP_GROUP_SEARCH_FILTER (string) search filter for groups e.g. "(&(objectclass=groupOfNames)(memberUid=%s))" 60 MINIO_IDENTITY_LDAP_GROUP_SEARCH_BASE_DN (list) ";" separated list of group search base DNs e.g. "dc=myldapserver,dc=com" 61 MINIO_IDENTITY_LDAP_TLS_SKIP_VERIFY (on|off) trust server TLS without verification, defaults to "off" (verify) 62 MINIO_IDENTITY_LDAP_SERVER_INSECURE (on|off) allow plain text connection to AD/LDAP server, defaults to "off" 63 MINIO_IDENTITY_LDAP_SERVER_STARTTLS (on|off) use StartTLS connection to AD/LDAP server, defaults to "off" 64 MINIO_IDENTITY_LDAP_COMMENT (sentence) optionally add a comment to this setting 65 ``` 66 67 ### Supported modes of operation ### 68 69 The two supported modes of LDAP configuration differ in how the MinIO server derives the Distinguished Name (DN) of the user from their username provided in the STS API. _Exactly one must be used in a valid configuration_. 70 71 Once a unique DN for the user is derived, the server verifies the user's credentials with the LDAP server and on success, looks up the user's groups via a configured group search query and finally temporary object storage credentials are generated and returned. 72 73 #### Lookup-Bind Mode #### 74 75 In this mode, the a low-privilege read-only LDAP service account is configured in the MinIO server by providing the account's Distinguished Name (DN) and password. It is the new and preferred mode for LDAP integration. 76 77 This service account is used by the MinIO server to lookup a user's DN given their username. The lookup is performed via an LDAP search filter query that is also configured by the administrator. 78 79 This mode is enabled by setting the following variables: 80 81 ``` 82 MINIO_IDENTITY_LDAP_LOOKUP_BIND_DN (string) DN for LDAP read-only service account used to perform DN and group lookups 83 MINIO_IDENTITY_LDAP_LOOKUP_BIND_PASSWORD (string) Password for LDAP read-only service account used to perform DN and group lookups 84 MINIO_IDENTITY_LDAP_USER_DN_SEARCH_BASE_DN (string) Base LDAP DN to search for user DN 85 MINIO_IDENTITY_LDAP_USER_DN_SEARCH_FILTER (string) Search filter to lookup user DN 86 ``` 87 88 If you set an empty lookup bind password, the lookup bind will use the unauthenticated authentication mechanism, as described in [RFC 4513 Section 5.1.2](https://tools.ietf.org/html/rfc4513#section-5.1.2). 89 90 #### Username-Format Mode #### 91 92 In this mode, the server does not use a separate LDAP service account. Instead, the username and password provided in the STS API call are used to login to the LDAP server and also to lookup the user's groups. This mode preserves older behavior for compatibility, but users are encouraged to use the Lookup-Bind mode. 93 94 The DN to use to login to LDAP is computed from a username format configuration parameter. This is a list of possible DN templates to be used. For each such template, the username is substituted and the DN is generated. Each generated DN is tried by the MinIO server to login to LDAP. If exactly one successful DN is found, it is used to perform the groups lookup as well. 95 96 This mode is enabled by setting the following variables: 97 98 ``` 99 MINIO_IDENTITY_LDAP_USERNAME_FORMAT (list) ";" separated list of username bind DNs e.g. "uid=%s,cn=accounts,dc=myldapserver,dc=com" 100 ``` 101 102 ### Group membership search 103 104 MinIO can be configured to find the groups of a user from AD/LDAP by specifying the folllowing variables: 105 106 ``` 107 MINIO_IDENTITY_LDAP_GROUP_SEARCH_FILTER (string) search filter for groups e.g. "(&(objectclass=groupOfNames)(memberUid=%s))" 108 MINIO_IDENTITY_LDAP_GROUP_SEARCH_BASE_DN (list) ";" separated list of group search base DNs e.g. "dc=myldapserver,dc=com" 109 ``` 110 111 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 DN 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. 112 113 **MinIO sends LDAP credentials to LDAP server for validation. So we _strongly recommend_ to use MinIO with AD/LDAP server over TLS or StartTLS _only_. Using plain-text connection between MinIO and LDAP server means _credentials can be compromised_ by anyone listening to network traffic.** 114 115 If a self-signed certificate is being used, the certificate can be added to MinIO's certificates directory, so it can be trusted by the server. An example setup for development or experimentation: 116 117 ```shell 118 export MINIO_IDENTITY_LDAP_SERVER_ADDR=myldapserver.com:636 119 export MINIO_IDENTITY_LDAP_USERNAME_FORMAT="uid=%s,cn=accounts,dc=myldapserver,dc=com" 120 export MINIO_IDENTITY_LDAP_GROUP_SEARCH_BASE_DN="dc=myldapserver,dc=com" 121 export MINIO_IDENTITY_LDAP_GROUP_SEARCH_FILTER="(&(objectclass=groupOfNames)(memberUid=%s)$)" 122 export MINIO_IDENTITY_LDAP_STS_EXPIRY=60h 123 export MINIO_IDENTITY_LDAP_TLS_SKIP_VERIFY=on 124 ``` 125 126 ### Variable substitution in AD/LDAP configuration strings ### 127 128 In the configuration variables, `%s` is substituted with the *username* from the STS request and `%d` is substituted with the *distinguished username (user DN)* of the LDAP user. Please see the following table for which configuration variables support these substitution variables: 129 130 | Variable | Supported substitutions | 131 |---------------------------------------------|-------------------------| 132 | `MINIO_IDENTITY_LDAP_USERNAME_FORMAT` | `%s` | 133 | `MINIO_IDENTITY_LDAP_USER_DN_SEARCH_FILTER` | `%s` | 134 | `MINIO_IDENTITY_LDAP_GROUP_SEARCH_FILTER` | `%s` and `%d` | 135 136 ## Managing User/Group Access Policy 137 138 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. 139 140 **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. 141 142 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: 143 144 ```sh 145 mc admin policy add myminio mypolicy mypolicy.json 146 ``` 147 148 To assign the policy to a user or group, use the full DN of the user or group: 149 150 ```sh 151 mc admin policy set myminio mypolicy user='uid=james,cn=accounts,dc=myldapserver,dc=com' 152 ``` 153 154 ```sh 155 mc admin policy set myminio mypolicy group='cn=projectx,ou=groups,ou=hwengg,dc=min,dc=io' 156 ``` 157 158 **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. 159 160 161 ## API Request Parameters 162 163 ### LDAPUsername 164 Is AD/LDAP username to login. Application must ask user for this value to successfully obtain rotating access credentials from AssumeRoleWithLDAPIdentity. 165 166 | Params | Value | 167 | :-- | :-- | 168 | *Type* | *String* | 169 | *Length Constraints* | *Minimum length of 2. Maximum length of 2048.* | 170 | *Required* | *Yes* | 171 172 173 ### LDAPPassword 174 Is AD/LDAP username password to login. Application must ask user for this value to successfully obtain rotating access credentials from AssumeRoleWithLDAPIdentity. 175 176 | Params | Value | 177 | :-- | :-- | 178 | *Type* | *String* | 179 | *Length Constraints* | *Minimum length of 4. Maximum length of 2048.* | 180 | *Required* | *Yes* | 181 182 ### Version 183 Indicates STS API version information, the only supported value is '2011-06-15'. This value is borrowed from AWS STS API documentation for compatibility reasons. 184 185 | Params | Value | 186 | :-- | :-- | 187 | *Type* | *String* | 188 | *Required* | *Yes* | 189 190 ### Policy 191 An IAM policy in JSON format that you want to use as an inline session policy. This parameter is optional. Passing policies to this operation returns new temporary credentials. The resulting session's permissions are the intersection of the canned policy name and the policy set here. You cannot use this policy to grant more permissions than those allowed by the canned policy name being assumed. 192 193 | Params | Value | 194 | :-- | :-- | 195 | *Type* | *String* | 196 | *Valid Range* | *Minimum length of 1. Maximum length of 2048.* | 197 | *Required* | *No* | 198 199 ### Response Elements 200 XML response for this API is similar to [AWS STS AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html#API_AssumeRoleWithWebIdentity_ResponseElements) 201 202 ### Errors 203 XML error response for this API is similar to [AWS STS AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html#API_AssumeRoleWithWebIdentity_Errors) 204 205 ## Sample `POST` Request 206 ``` 207 http://minio.cluster:9000?Action=AssumeRoleWithLDAPIdentity&LDAPUsername=foouser&LDAPPassword=foouserpassword&Version=2011-06-15 208 ``` 209 210 ## Sample Response 211 ``` 212 <?xml version="1.0" encoding="UTF-8"?> 213 <AssumeRoleWithLDAPIdentityResponse xmlns="https://sts.amazonaws.com/doc/2011-06-15/"> 214 <AssumeRoleWithLDAPIdentityResult> 215 <AssumedRoleUser> 216 <Arn/> 217 <AssumeRoleId/> 218 </AssumedRoleUser> 219 <Credentials> 220 <AccessKeyId>Y4RJU1RNFGK48LGO9I2S</AccessKeyId> 221 <SecretAccessKey>sYLRKS1Z7hSjluf6gEbb9066hnx315wHTiACPAjg</SecretAccessKey> 222 <Expiration>2019-08-08T20:26:12Z</Expiration> 223 <SessionToken>eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3NLZXkiOiJZNFJKVTFSTkZHSzQ4TEdPOUkyUyIsImF1ZCI6IlBvRWdYUDZ1Vk80NUlzRU5SbmdEWGo1QXU1WWEiLCJhenAiOiJQb0VnWFA2dVZPNDVJc0VOUm5nRFhqNUF1NVlhIiwiZXhwIjoxNTQxODExMDcxLCJpYXQiOjE1NDE4MDc0NzEsImlzcyI6Imh0dHBzOi8vbG9jYWxob3N0Ojk0NDMvb2F1dGgyL3Rva2VuIiwianRpIjoiYTBiMjc2MjktZWUxYS00M2JmLTg3MzktZjMzNzRhNGNkYmMwIn0.ewHqKVFTaP-j_kgZrcOEKroNUjk10GEp8bqQjxBbYVovV0nHO985VnRESFbcT6XMDDKHZiWqN2vi_ETX_u3Q-w</SessionToken> 224 </Credentials> 225 </AssumeRoleWithLDAPIdentity> 226 <ResponseMetadata/> 227 </AssumeRoleWithLDAPIdentityResponse> 228 ``` 229 230 ## Using LDAP STS API 231 232 With multiple OU hierarchies for users, and multiple group search base DN's. 233 ``` 234 $ export MINIO_ROOT_USER=minio 235 $ export MINIO_ROOT_PASSWORD=minio123 236 $ export MINIO_IDENTITY_LDAP_SERVER_ADDR='my.ldap-active-dir-server.com:636' 237 $ export MINIO_IDENTITY_LDAP_USERNAME_FORMAT='cn=%s,ou=Users,ou=BUS1,ou=LOB,dc=somedomain,dc=com;cn=%s,ou=Users,ou=BUS2,ou=LOB,dc=somedomain,dc=com' 238 $ export MINIO_IDENTITY_LDAP_GROUP_SEARCH_BASE_DN='dc=minioad,dc=local;dc=somedomain,dc=com' 239 $ export MINIO_IDENTITY_LDAP_GROUP_SEARCH_FILTER='(&(objectclass=group)(member=%s))' 240 $ minio server ~/test 241 ``` 242 You can make sure it works appropriately using our [example program](https://raw.githubusercontent.com/minio/minio/master/docs/sts/ldap.go): 243 ``` 244 $ go run ldap.go -u foouser -p foopassword 245 246 ##### Credentials 247 { 248 "accessKey": "NUIBORZYTV2HG2BMRSXR", 249 "secretKey": "qQlP5O7CFPc5m5IXf1vYhuVTFj7BRVJqh0FqZ86S", 250 "expiration": "2018-08-21T17:10:29-07:00", 251 "sessionToken": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3NLZXkiOiJOVUlCT1JaWVRWMkhHMkJNUlNYUiIsImF1ZCI6IlBvRWdYUDZ1Vk80NUlzRU5SbmdEWGo1QXU1WWEiLCJhenAiOiJQb0VnWFA2dVZPNDVJc0VOUm5nRFhqNUF1NVlhIiwiZXhwIjoxNTM0ODk2NjI5LCJpYXQiOjE1MzQ4OTMwMjksImlzcyI6Imh0dHBzOi8vbG9jYWxob3N0Ojk0NDMvb2F1dGgyL3Rva2VuIiwianRpIjoiNjY2OTZjZTctN2U1Ny00ZjU5LWI0MWQtM2E1YTMzZGZiNjA4In0.eJONnVaSVHypiXKEARSMnSKgr-2mlC2Sr4fEGJitLcJF_at3LeNdTHv0_oHsv6ZZA3zueVGgFlVXMlREgr9LXA" 252 } 253 ``` 254 255 ## Caveats 256 **LDAP STS credentials are not yet supported on MinIO Browser UI, we may add this feature in future releases.** 257 258 ## Explore Further 259 - [MinIO Admin Complete Guide](https://docs.min.io/docs/minio-admin-complete-guide.html) 260 - [The MinIO documentation website](https://docs.min.io)