diff --git a/.circleci/config.yml b/.circleci/config.yml index 615c4f5d6..b29563f0e 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -13,7 +13,7 @@ jobs: - restore_cache: key: v2-dependency-cache-{{ checksum "st2/requirements.txt" }} - run: sudo apt install python-dev - - run: sudo apt install libldap2-dev + - run: sudo apt install libldap2-dev - run: sudo apt install libsasl2-dev - run: make docs - run: diff --git a/README.md b/README.md index 88daa5f29..dd477421f 100644 --- a/README.md +++ b/README.md @@ -28,9 +28,9 @@ Follows these steps to build the docs locally: Install the dependencies: -For Debian/Ubuntu: ``sudo apt-get install libpython-dev libssl-dev`` +For Debian/Ubuntu: ``sudo apt-get install python-dev libssl-dev libldap2-dev libsasl2-dev ldap-utils`` -For RHEL/CentOS: `` sudo yum install python-devel openssl-devel gcc`` +For RHEL/CentOS: `` sudo dnf install python2-devel python3-devel openldap-devel`` ```bash git clone https://github.com/StackStorm/st2docs.git diff --git a/docs/source/authentication.rst b/docs/source/authentication.rst index 0535479f4..036fea2cd 100644 --- a/docs/source/authentication.rst +++ b/docs/source/authentication.rst @@ -134,58 +134,77 @@ The following is a list of auth backends for the community edition to help get t * `Flat File `_ * `OpenStack Keystone `_ -LDAP (Enterprise Edition) -------------------------- -.. note:: +LDAP +---- - Prior to StackStorm 3.3, Extreme Networks provided a commercial version(Extreme Workflow Composer) of the StackStorm automation platform including an LDAP auth backend. +.. note:: -Extreme Workflow Composer was donated to Linux Foundation, but those components are not yet integrated into the StackStorm release. Please visit https://stackstorm.com/2020/05/27/extreme-networks-donates-ewc-to-linux-foundation/ for more details. + Prior to StackStorm 3.3, Extreme Networks provided a commercial version of the StackStorm automation platform which included + LDAP auth backend. As these enterprise features were donated to the Linux Foundation, LDAP auth backend is now available in + StackStorm Open Source since 3.4. - These components are NOT available in the StackStorm 3.3 release, but will be integrated into the community edition of StackStorm in future release(s). +LDAP is now included by default with StackStorm core and needs to be enabled and configured via ``st2.conf``. The source code for the LDAP auth backend can be accessed here: https://github.com/stackstorm/st2-auth-ldap -LDAP -^^^^ The LDAP backend authenticates the user against an LDAP server. The following is a list of configuration options for the backend: -+-----------------+----------+---------+--------------------------------------------------------------------------------------------------------------------------------+ -| option | required | default | description | -+=++==============+==========+=========+=====++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++=======================================================+ -| bind_dn | yes | | DN of the service account to bind with the LDAP server | -+-----------------+----------+---------+--------------------------------------------------------------------------------------------------------------------------------+ -| bind_password | yes | | Password of the service account | -+-----------------+----------+---------+--------------------------------------------------------------------------------------------------------------------------------+ -| base_ou | yes | | Base OU to search for user and group entries | -+-----------------+----------+---------+--------------------------------------------------------------------------------------------------------------------------------+ -| group_dns | yes | | Which groups user must be member of to be granted access | -+-----------------+----------+---------+--------------------------------------------------------------------------------------------------------------------------------+ -| group_dns_check | no | and | What kind of check to perform when validating user group membership (``and`` / ``or``). When ``and`` behavior is used, user | -| | | | needs to be part of all the specified groups and when ``or`` behavior is used, user needs to be part of at least one or more | -| | | | of the specified groups. | -+-----------------+----------+---------+--------------------------------------------------------------------------------------------------------------------------------+ -| host | yes | | Hostname of the LDAP server | -+-----------------+----------+---------+--------------------------------------------------------------------------------------------------------------------------------+ -| port | yes | | Port of the LDAP server | -+-----------------+----------+---------+--------------------------------------------------------------------------------------------------------------------------------+ -| use_ssl | no | false | Use LDAPS to connect | -+-----------------+----------+---------+--------------------------------------------------------------------------------------------------------------------------------+ -| use_tls | no | false | Start TLS on LDAP to connect | -+-----------------+----------+---------+--------------------------------------------------------------------------------------------------------------------------------+ -| cacert | no | None | Path to the CA cert used to validate certificate | -+-----------------+----------+---------+--------------------------------------------------------------------------------------------------------------------------------+ -| id_attr | no | uid | Field name of the user ID attribute | -+-----------------+----------+---------+--------------------------------------------------------------------------------------------------------------------------------+ -| scope | no | subtree | Search scope (base, onelevel, or subtree) | -+-----------------+----------+---------+--------------------------------------------------------------------------------------------------------------------------------+ -| network_timeout | no | 10.0 | Timeout for network operations (in seconds) | -+-----------------+----------+---------+--------------------------------------------------------------------------------------------------------------------------------+ -| chase_referrals | no | false | True if the referrals should be automatically chased within the underlying LDAP C lib | -+-----------------+----------+---------+--------------------------------------------------------------------------------------------------------------------------------+ -| debug | no | false | Enable debug mode. When debug mode is enabled all the calls (including the results) to LDAP server are logged | -+-----------------+----------+---------+--------------------------------------------------------------------------------------------------------------------------------+ -| client_options | no | | A dictionary with additional Python LDAP client options which can be passed to ``set_connection()`` method | -+-----------------+----------+---------+--------------------------------------------------------------------------------------------------------------------------------+ ++-----------------------------+----------+----------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| option | required | default | description | ++=++==========================+==========+====================================================================================================+=====++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++=================================================================+ +| bind_dn | yes | | DN of the service account to bind with the LDAP server | ++-----------------------------+----------+----------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| bind_password | yes | | Password of the service account | ++-----------------------------+----------+----------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| base_ou | yes | | Base OU to search for user and group entries | ++-----------------------------+----------+----------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| group_dns | yes | | Which groups user must be member of to be granted access | ++-----------------------------+----------+----------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| group_dns_check | no | `and` | What kind of check to perform when validating user group membership (``and`` / ``or``). When ``and`` behavior is used, user | +| | | | needs to be part of all the specified groups and when ``or`` behavior is used, user needs to be part of at least one or more | +| | | | of the specified groups. | ++-----------------------------+----------+----------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| host | yes | | Hostname of the LDAP server | ++-----------------------------+----------+----------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| port | yes | | Port of the LDAP server | ++-----------------------------+----------+----------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| use_ssl | no | `false` | Use LDAPS to connect | ++-----------------------------+----------+----------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| use_tls | no | `false` | Start TLS on LDAP to connect | ++-----------------------------+----------+----------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| cacert | no | `None` | Path to the CA cert used to validate certificate | ++-----------------------------+----------+----------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| id_attr | no | `uid` | Field name of the user ID attribute | ++-----------------------------+----------+----------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| account_pattern | no | `{id_attr}={{username}}` | LDAP subtree pattern to match user. The user's username is escaped and interpolated into this string (see example). | +| | | | | ++-----------------------------+----------+----------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| group_pattern | no | `(|(& (objectClass=*)(|(member={user_dn})(uniqueMember={user_dn})(memberUid={username}))))` | LDAP subtree pattern for user groups. Both user_dn and username are escaped and then interpolated into this string (see example.) | +| | | | | +| | | | | +| | | | | +| | | | | +| | | | | +| | | | | +| | | | | ++-----------------------------+----------+----------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| scope | no | `subtree` | Search scope (base, onelevel, or subtree) | ++-----------------------------+----------+----------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| network_timeout | no | `10.0` | Timeout for network operations (in seconds) | ++-----------------------------+----------+----------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| chase_referrals | no | `false` | True if the referrals should be automatically chased within the underlying LDAP C lib | ++-----------------------------+----------+----------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| debug | no | `false` | Enable debug mode. When debug mode is enabled all the calls (including the results) to LDAP server are logged | ++-----------------------------+----------+----------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| client_options | no | | A dictionary with additional Python LDAP client options which can be passed to ``set_connection()`` method | ++-----------------------------+----------+----------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| cache_user_groups_response | no | `true` | When true, LDAP user groups response is cached for 120 seconds (by default) in memory. This decreases load on LDAP server | +| | | | and increases performance when remote LDAP group to RBAC role sync is enabled and / or when the same user authenticates | +| | | | concurrency in a short time frame. Keep in mind that even when this feature is enabled, single (authenticate) request to | +| | | | LDAP server will still be performed when user authenticates to st2auth - authentication information is not cached - only | +| | | | user groups are cached. | ++-----------------------------+----------+----------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| cache_user_groups_ttl | no | `120` | How long (in seconds) | ++-----------------------------+----------+----------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+ .. note:: @@ -211,6 +230,23 @@ The following is a sample auth section for the LDAP backend in the st2 config fi api_url = http://myhost.example.com:9101/ debug = False +If your LDAP server uses a different name for the user ID attribute, you can simply specify the id_attr configuration option. + +.. sourcecode:: ini + + [auth] + mode = standalone + backend = ldap + backend_kwargs = {"bind_dn": "CN=st2admin,ou=users,dc=example,dc=com", "bind_password": "foobar123", "base_ou": "dc=example,dc=com", "id_attr": "username", "group_dns": ["CN=st2users,ou=groups,dc=example,dc=com", "CN=st2developers,ou=groups,dc=example,dc=com"], "host": "identity.example.com", "port": 636, "use_ssl": true, "cacert": "/path/to/cacert.pem"} + enable = True + use_ssl = True + cert = /path/to/mycert.crt + key = /path/to/mycert.key + logging = /etc/st2/logging.auth.conf + api_url = http://myhost.example.com:9101/ + debug = False + + This will need customization for your environment - e.g. the LDAP server to bind to, and the ``cert`` and ``key`` paths if you are using SSL. Running the Service