maxmustermann/minio
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
minio/docs/sts/ldap.md

231 lines
12 KiB
Markdown
Raw Normal View History

Add notes on configuring LDAP STS with Microsoft Active Directory (#8260)
2019-09-18 02:21:37 +02:00
# MinIO AD/LDAP Integration [![Slack](https://slack.min.io/slack?type=svg)](https://slack.min.io)
LDAP STS API (#8091) Add LDAP based users-groups system This change adds support to integrate an LDAP server for user authentication. This works via a custom STS API for LDAP. Each user accessing the MinIO who can be authenticated via LDAP receives temporary credentials to access the MinIO server. LDAP is enabled only over TLS. User groups are also supported via LDAP. The administrator may configure an LDAP search query to find the group attribute of a user - this may correspond to any attribute in the LDAP tree (that the user has access to view). One or more groups may be returned by such a query. A group is mapped to an IAM policy in the usual way, and the server enforces a policy corresponding to all the groups and the user's own mapped policy. When LDAP is configured, the internal MinIO users system is disabled.
2019-09-10 01:12:29 +02:00
MinIO provides a custom STS API that allows integration with LDAP
based corporate environments. The flow is as follows:
Add notes on configuring LDAP STS with Microsoft Active Directory (#8260)
2019-09-18 02:21:37 +02:00
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
LDAP STS API (#8091) Add LDAP based users-groups system This change adds support to integrate an LDAP server for user authentication. This works via a custom STS API for LDAP. Each user accessing the MinIO who can be authenticated via LDAP receives temporary credentials to access the MinIO server. LDAP is enabled only over TLS. User groups are also supported via LDAP. The administrator may configure an LDAP search query to find the group attribute of a user - this may correspond to any attribute in the LDAP tree (that the user has access to view). One or more groups may be returned by such a query. A group is mapped to an IAM policy in the usual way, and the server enforces a policy corresponding to all the groups and the user's own mapped policy. When LDAP is configured, the internal MinIO users system is disabled.
2019-09-10 01:12:29 +02:00
succeeds the user is authenticated.
Add notes on configuring LDAP STS with Microsoft Active Directory (#8260)
2019-09-18 02:21:37 +02:00
3. MinIO then queries the AD/LDAP server for a list of groups that the
LDAP STS API (#8091) Add LDAP based users-groups system This change adds support to integrate an LDAP server for user authentication. This works via a custom STS API for LDAP. Each user accessing the MinIO who can be authenticated via LDAP receives temporary credentials to access the MinIO server. LDAP is enabled only over TLS. User groups are also supported via LDAP. The administrator may configure an LDAP search query to find the group attribute of a user - this may correspond to any attribute in the LDAP tree (that the user has access to view). One or more groups may be returned by such a query. A group is mapped to an IAM policy in the usual way, and the server enforces a policy corresponding to all the groups and the user's own mapped policy. When LDAP is configured, the internal MinIO users system is disabled.
2019-09-10 01:12:29 +02:00
user is a member of.
Add notes on configuring LDAP STS with Microsoft Active Directory (#8260)
2019-09-18 02:21:37 +02:00
- This is done via a customizable AD/LDAP search query.
LDAP STS API (#8091) Add LDAP based users-groups system This change adds support to integrate an LDAP server for user authentication. This works via a custom STS API for LDAP. Each user accessing the MinIO who can be authenticated via LDAP receives temporary credentials to access the MinIO server. LDAP is enabled only over TLS. User groups are also supported via LDAP. The administrator may configure an LDAP search query to find the group attribute of a user - this may correspond to any attribute in the LDAP tree (that the user has access to view). One or more groups may be returned by such a query. A group is mapped to an IAM policy in the usual way, and the server enforces a policy corresponding to all the groups and the user's own mapped policy. When LDAP is configured, the internal MinIO users system is disabled.
2019-09-10 01:12:29 +02:00
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.
Add notes on configuring LDAP STS with Microsoft Active Directory (#8260)
2019-09-18 02:21:37 +02:00
## Configuring AD/LDAP on MinIO
LDAP STS API (#8091) Add LDAP based users-groups system This change adds support to integrate an LDAP server for user authentication. This works via a custom STS API for LDAP. Each user accessing the MinIO who can be authenticated via LDAP receives temporary credentials to access the MinIO server. LDAP is enabled only over TLS. User groups are also supported via LDAP. The administrator may configure an LDAP search query to find the group attribute of a user - this may correspond to any attribute in the LDAP tree (that the user has access to view). One or more groups may be returned by such a query. A group is mapped to an IAM policy in the usual way, and the server enforces a policy corresponding to all the groups and the user's own mapped policy. When LDAP is configured, the internal MinIO users system is disabled.
2019-09-10 01:12:29 +02:00
Add notes on configuring LDAP STS with Microsoft Active Directory (#8260)
2019-09-18 02:21:37 +02:00
LDAP configuration is designed to be simple for the MinIO administrator.
LDAP STS API (#8091) Add LDAP based users-groups system This change adds support to integrate an LDAP server for user authentication. This works via a custom STS API for LDAP. Each user accessing the MinIO who can be authenticated via LDAP receives temporary credentials to access the MinIO server. LDAP is enabled only over TLS. User groups are also supported via LDAP. The administrator may configure an LDAP search query to find the group attribute of a user - this may correspond to any attribute in the LDAP tree (that the user has access to view). One or more groups may be returned by such a query. A group is mapped to an IAM policy in the usual way, and the server enforces a policy corresponding to all the groups and the user's own mapped policy. When LDAP is configured, the internal MinIO users system is disabled.
2019-09-10 01:12:29 +02:00
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
Add notes on configuring LDAP STS with Microsoft Active Directory (#8260)
2019-09-18 02:21:37 +02:00
allows an AD/LDAP user to not specify this whole string in the AD/LDAP STS
LDAP STS API (#8091) Add LDAP based users-groups system This change adds support to integrate an LDAP server for user authentication. This works via a custom STS API for LDAP. Each user accessing the MinIO who can be authenticated via LDAP receives temporary credentials to access the MinIO server. LDAP is enabled only over TLS. User groups are also supported via LDAP. The administrator may configure an LDAP search query to find the group attribute of a user - this may correspond to any attribute in the LDAP tree (that the user has access to view). One or more groups may be returned by such a query. A group is mapped to an IAM policy in the usual way, and the server enforces a policy corresponding to all the groups and the user's own mapped policy. When LDAP is configured, the internal MinIO users system is disabled.
2019-09-10 01:12:29 +02:00
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.
Add notes on configuring LDAP STS with Microsoft Active Directory (#8260)
2019-09-18 02:21:37 +02:00
MinIO can be configured to find the groups of a user from AD/LDAP by
LDAP STS API (#8091) Add LDAP based users-groups system This change adds support to integrate an LDAP server for user authentication. This works via a custom STS API for LDAP. Each user accessing the MinIO who can be authenticated via LDAP receives temporary credentials to access the MinIO server. LDAP is enabled only over TLS. User groups are also supported via LDAP. The administrator may configure an LDAP search query to find the group attribute of a user - this may correspond to any attribute in the LDAP tree (that the user has access to view). One or more groups may be returned by such a query. A group is mapped to an IAM policy in the usual way, and the server enforces a policy corresponding to all the groups and the user's own mapped policy. When LDAP is configured, the internal MinIO users system is disabled.
2019-09-10 01:12:29 +02:00
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
Add notes on configuring LDAP STS with Microsoft Active Directory (#8260)
2019-09-18 02:21:37 +02:00
queries the AD/LDAP server with the given search filter and extracts the
LDAP STS API (#8091) Add LDAP based users-groups system This change adds support to integrate an LDAP server for user authentication. This works via a custom STS API for LDAP. Each user accessing the MinIO who can be authenticated via LDAP receives temporary credentials to access the MinIO server. LDAP is enabled only over TLS. User groups are also supported via LDAP. The administrator may configure an LDAP search query to find the group attribute of a user - this may correspond to any attribute in the LDAP tree (that the user has access to view). One or more groups may be returned by such a query. A group is mapped to an IAM policy in the usual way, and the server enforces a policy corresponding to all the groups and the user's own mapped policy. When LDAP is configured, the internal MinIO users system is disabled.
2019-09-10 01:12:29 +02:00
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:
Add notes on configuring LDAP STS with Microsoft Active Directory (#8260)
2019-09-18 02:21:37 +02:00
| 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 |
LDAP STS API (#8091) Add LDAP based users-groups system This change adds support to integrate an LDAP server for user authentication. This works via a custom STS API for LDAP. Each user accessing the MinIO who can be authenticated via LDAP receives temporary credentials to access the MinIO server. LDAP is enabled only over TLS. User groups are also supported via LDAP. The administrator may configure an LDAP search query to find the group attribute of a user - this may correspond to any attribute in the LDAP tree (that the user has access to view). One or more groups may be returned by such a query. A group is mapped to an IAM policy in the usual way, and the server enforces a policy corresponding to all the groups and the user's own mapped policy. When LDAP is configured, the internal MinIO users system is disabled.
2019-09-10 01:12:29 +02:00
Add notes on configuring LDAP STS with Microsoft Active Directory (#8260)
2019-09-18 02:21:37 +02:00
Please note that MinIO will only access the AD/LDAP server over TLS.
LDAP STS API (#8091) Add LDAP based users-groups system This change adds support to integrate an LDAP server for user authentication. This works via a custom STS API for LDAP. Each user accessing the MinIO who can be authenticated via LDAP receives temporary credentials to access the MinIO server. LDAP is enabled only over TLS. User groups are also supported via LDAP. The administrator may configure an LDAP search query to find the group attribute of a user - this may correspond to any attribute in the LDAP tree (that the user has access to view). One or more groups may be returned by such a query. A group is mapped to an IAM policy in the usual way, and the server enforces a policy corresponding to all the groups and the user's own mapped policy. When LDAP is configured, the internal MinIO users system is disabled.
2019-09-10 01:12:29 +02:00
An example setup for development or experimentation:
``` shell
export MINIO_IDENTITY_LDAP_SERVER_ADDR=myldapserver.com:636
export MINIO_IDENTITY_LDAP_USERNAME_FORMAT="uid=${username},cn=accounts,dc=myldapserver,dc=com"
export MINIO_IDENTITY_LDAP_GROUP_SEARCH_BASE_DN="dc=myldapserver,dc=com"
export MINIO_IDENTITY_LDAP_GROUP_SEARCH_FILTER="(&(objectclass=groupOfNames)(member=${usernamedn}))"
export MINIO_IDENTITY_LDAP_GROUP_NAME_ATTRIBUTE="cn"
export MINIO_IDENTITY_LDAP_STS_EXPIRY_DURATION=60
export MINIO_IDENTITY_LDAP_TLS_SKIP_VERIFY=true
```
Add notes on configuring LDAP STS with Microsoft Active Directory (#8260)
2019-09-18 02:21:37 +02:00
### Variable substitution in AD/LDAP configuration strings
LDAP STS API (#8091) Add LDAP based users-groups system This change adds support to integrate an LDAP server for user authentication. This works via a custom STS API for LDAP. Each user accessing the MinIO who can be authenticated via LDAP receives temporary credentials to access the MinIO server. LDAP is enabled only over TLS. User groups are also supported via LDAP. The administrator may configure an LDAP search query to find the group attribute of a user - this may correspond to any attribute in the LDAP tree (that the user has access to view). One or more groups may be returned by such a query. A group is mapped to an IAM policy in the usual way, and the server enforces a policy corresponding to all the groups and the user's own mapped policy. When LDAP is configured, the internal MinIO users system is disabled.
2019-09-10 01:12:29 +02:00
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 |
|--------------|------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|
Add notes on configuring LDAP STS with Microsoft Active Directory (#8260)
2019-09-18 02:21:37 +02:00
| *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. |
LDAP STS API (#8091) Add LDAP based users-groups system This change adds support to integrate an LDAP server for user authentication. This works via a custom STS API for LDAP. Each user accessing the MinIO who can be authenticated via LDAP receives temporary credentials to access the MinIO server. LDAP is enabled only over TLS. User groups are also supported via LDAP. The administrator may configure an LDAP search query to find the group attribute of a user - this may correspond to any attribute in the LDAP tree (that the user has access to view). One or more groups may be returned by such a query. A group is mapped to an IAM policy in the usual way, and the server enforces a policy corresponding to all the groups and the user's own mapped policy. When LDAP is configured, the internal MinIO users system is disabled.
2019-09-10 01:12:29 +02:00
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.
Add notes on configuring LDAP STS with Microsoft Active Directory (#8260)
2019-09-18 02:21:37 +02:00
## 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'
```
Fix LDAP responseXML to be named appropriately (#8285) This PR additionally also adds support for missing - Session policy support for AD/LDAP - Add API request/response parameters detail - Update example to take ldap username, password input from the command line - Fixes session policy handling for ClientGrants and WebIdentity
2019-09-24 00:21:16 +02:00
### API Request Parameters
#### LDAPUsername
Is AD/LDAP username to login. Application must ask user for this value to successfully obtain rotating access credentials from AssumeRoleWithLDAPIdentity.
| Params | Value |
| :-- | :-- |
| *Type* | *String* |
| *Length Constraints* | *Minimum length of 2. Maximum length of 2048.* |
| *Required* | *Yes* |
#### LDAPPassword
Is AD/LDAP username password to login. Application must ask user for this value to successfully obtain rotating access credentials from AssumeRoleWithLDAPIdentity.
| Params | Value |
| :-- | :-- |
| *Type* | *String* |
| *Length Constraints* | *Minimum length of 4. Maximum length of 2048.* |
| *Required* | *Yes* |
#### Version
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.
| Params | Value |
| :-- | :-- |
| *Type* | *String* |
| *Required* | *Yes* |
#### Policy
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.
| Params | Value |
| :-- | :-- |
| *Type* | *String* |
| *Valid Range* | *Minimum length of 1. Maximum length of 2048.* |
| *Required* | *No* |
#### Response Elements
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)
#### Errors
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)
#### Sample Request
```
http://minio.cluster:9000?Action=AssumeRoleWithLDAPIdentity&LDAPUsername=foouser&LDAPPassword=foouserpassword&Version=2011-06-15
```
#### Sample Response
```
<?xml version="1.0" encoding="UTF-8"?>
<AssumeRoleWithLDAPIdentityResponse xmlns="https://sts.amazonaws.com/doc/2011-06-15/">
<AssumeRoleWithLDAPIdentityResult>
<AssumedRoleUser>
<Arn/>
<AssumeRoleId/>
</AssumedRoleUser>
<Credentials>
<AccessKeyId>Y4RJU1RNFGK48LGO9I2S</AccessKeyId>
<SecretAccessKey>sYLRKS1Z7hSjluf6gEbb9066hnx315wHTiACPAjg</SecretAccessKey>
<Expiration>2019-08-08T20:26:12Z</Expiration>
<SessionToken>eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3NLZXkiOiJZNFJKVTFSTkZHSzQ4TEdPOUkyUyIsImF1ZCI6IlBvRWdYUDZ1Vk80NUlzRU5SbmdEWGo1QXU1WWEiLCJhenAiOiJQb0VnWFA2dVZPNDVJc0VOUm5nRFhqNUF1NVlhIiwiZXhwIjoxNTQxODExMDcxLCJpYXQiOjE1NDE4MDc0NzEsImlzcyI6Imh0dHBzOi8vbG9jYWxob3N0Ojk0NDMvb2F1dGgyL3Rva2VuIiwianRpIjoiYTBiMjc2MjktZWUxYS00M2JmLTg3MzktZjMzNzRhNGNkYmMwIn0.ewHqKVFTaP-j_kgZrcOEKroNUjk10GEp8bqQjxBbYVovV0nHO985VnRESFbcT6XMDDKHZiWqN2vi_ETX_u3Q-w</SessionToken>
</Credentials>
</AssumeRoleWithLDAPIdentity>
<ResponseMetadata/>
</AssumeRoleWithLDAPIdentityResponse>
```
#### Testing
```
$ export MINIO_ACCESS_KEY=minio
$ export MINIO_SECRET_KEY=minio123
$ export MINIO_IDENTITY_LDAP_SERVER_ADDR='ldaps://my.ldap-active-dir-server.com:636'
$ export MINIO_IDENTITY_LDAP_USERNAME_FORMAT='cn=${username},cn=users,dc=minioad,dc=local'
$ export MINIO_IDENTITY_LDAP_GROUP_SEARCH_BASE_DN='dc=minioad,dc=local'
$ export MINIO_IDENTITY_LDAP_GROUP_SEARCH_FILTER='(&(objectclass=group)(member=${usernamedn}))'
$ export MINIO_IDENTITY_LDAP_GROUP_NAME_ATTRIBUTE='cn'
$ minio server ~/test
```
```
$ go run ldap.go -u foouser -p foopassword
##### Credentials
{
"accessKey": "NUIBORZYTV2HG2BMRSXR",
"secretKey": "qQlP5O7CFPc5m5IXf1vYhuVTFj7BRVJqh0FqZ86S",
"expiration": "2018-08-21T17:10:29-07:00",
"sessionToken": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3NLZXkiOiJOVUlCT1JaWVRWMkhHMkJNUlNYUiIsImF1ZCI6IlBvRWdYUDZ1Vk80NUlzRU5SbmdEWGo1QXU1WWEiLCJhenAiOiJQb0VnWFA2dVZPNDVJc0VOUm5nRFhqNUF1NVlhIiwiZXhwIjoxNTM0ODk2NjI5LCJpYXQiOjE1MzQ4OTMwMjksImlzcyI6Imh0dHBzOi8vbG9jYWxob3N0Ojk0NDMvb2F1dGgyL3Rva2VuIiwianRpIjoiNjY2OTZjZTctN2U1Ny00ZjU5LWI0MWQtM2E1YTMzZGZiNjA4In0.eJONnVaSVHypiXKEARSMnSKgr-2mlC2Sr4fEGJitLcJF_at3LeNdTHv0_oHsv6ZZA3zueVGgFlVXMlREgr9LXA"
}
```
Reference in a new issue Copy permalink