docker/Keystone/LDAP.md

   1 <!--
   2 # Copyright 2020 Canonical Ltd.
   3 # All rights reserved.
   4 #
   5 # Licensed under the Apache License, Version 2.0 (the "License"); you may
   6 # not use this file except in compliance with the License. You may obtain
   7 # a copy of the License at
   8 #
   9 #         http://www.apache.org/licenses/LICENSE-2.0
  10 #
  11 # Unless required by applicable law or agreed to in writing, software
  12 # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  13 # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  14 # License for the specific language governing permissions and limitations
  15 # under the License.
  16 ## -->
  17
  18 # User authentication with external LDAP server
  19
  20 When using the Keystone back-end, an external LDAP server may be used for user authentication, whereas the assignment information (RBAC roles/projects) is always stored in the local mysql database. In this working model, two user and project domains are used.
  21
  22 - The "default" domain, in which the external LDAP is not checked, mainly intended for administrative users ("admin").
  23 - The the "ldap" domain, in which the validation of credentials is delegated to the LDAP server. User creation / deletion is also done in the external LDAP, and the GUI and osm client are used for configuring assignment only.
  24
  25 The name of "ldap" domain is configurable, and must be synchronized in the GUI, NBI and Keystone OSM modules.
  26
  27 ## LDAP Synchronization
  28
  29 For the "ldap" domain, Keystone will synchronize the user information between the LDAP server and the local mysql database. This is done at component startup time and periodically (in the cron), once a day, executing this command
  30
  31 ```bash
  32 keystone-manage mapping_purge --domain-name $LDAP_AUTHENTICATION_DOMAIN_NAME; keystone-manage mapping_populate --domain-name $LDAP_AUTHENTICATION_DOMAIN_NAME
  33 ```
  34
  35 If a user tries to authenticate but is not yet in the local database, the relevant data will be loaded to mysql automatically. For this reason is not crucial to execute synchronization too often. User deletion in LDAP will only be performed in mysql after the periodic synchronization. For this reason, it has to be taken into account that the user info shown by osm client may not be fully up to date until the next sync.
  36
  37 Keystone never deletes the assignment information, even if the LDAP user disappears. For this reason, if a new client is created in LDAP reusing the same identifier, the RBAC info associated will be the previous one.
  38
  39 The binding to the external LDAP may be:
  40
  41 - Anonymous. The remote LDAP server must support anonymous BIND with read permissions over the user branch
  42 - Authenticated. A user account must exist in the LDAP server for Keystone, having read permissions over the user branch. This account should never expire.
  43
  44 The connection may be in clear (which is rarely used) or TLS.
  45
  46 ### Configuration
  47
  48 The Keystone component will configure itself at startup time using a few environment variables as follows (see [this](https://www.oreilly.com/library/view/identity-authentication-and/9781491941249/ch04.html) for details):
  49
  50 - **LDAP_AUTHENTICATION_DOMAIN_NAME**: name of the domain which use LDAP authentication
  51 - **LDAP_URL**: URL of the LDAP server
  52 - **LDAP_BIND_USER** and **LDAP_BIND_PASSWORD**: This is the user/password to bind and search for users. If not specified, the user accessing Keystone needs to have anonymous query rights to the dn_tree specified in the next configuration option.
  53 - **LDAP_USER_TREE_DN**: This specifies the root of the tree in the LDAP server in which Keystone will search for users.
  54 - **LDAP_USER_OBJECTCLASS**: This specifies the LDAP object class that Keystone will filter on within user_tree_dn to find user objects. Any objects of other classes will be ignored.
  55 - **LDAP_USER_ID_ATTRIBUTE**, **LDAP_USER_NAME_ATTRIBUTE** and **LDAP_USER_PASS_ATTRIBUTE**: This set of options define the mapping to LDAP attributes for the three key user attributes supported by Keystone. The LDAP attribute chosen for user_id must be something that is immutable for a user and no more than 64 characters in length. Notice that Distinguished Name (DN) may be longer than 64 characters and thus is not suitable. An uid, or mail may be appropriate.
  56 - **LDAP_USER_FILTER**: This filter option allow additional filter (over and above user_objectclass) to be included into the search of user. One common use of this is to provide more efficient searching, where the recommended search for user objects is (&(objectCategory=person)(objectClass=user)). By specifying user_objectclass as user and user_filter as objectCategory=person in the Keystone configuration file, this can be achieved.
  57 - **LDAP_USER_ENABLED_ATTRIBUTE**: In Keystone, a user entity can be either enabled or disabled. Setting the above option will give a mapping to an equivalent attribute in LDAP, allowing your LDAP management tools to disable a user.
  58 - **LDAP_USER_ENABLED_MASK**: Some LDAP schemas, rather than having a dedicated attribute for user enablement, use a bit within a general control attribute (such as userAccountControl) to indicate this. Setting user_enabled_mask will cause Keystone to look at only the status of this bit in the attribute specified by user_enabled_attribute, with the bit set indicating the user is enabled.
  59 - **LDAP_USER_ENABLED_DEFAULT**: Most LDAP servers use a boolean or bit in a control field to indicate enablement. However, some schemas might use an integer value in an attribute. In this situation, set user_enabled_default to the integer value that represents a user being enabled.
  60 - **LDAP_USER_ENABLED_INVERT**: Some LDAP schemas have an “account locked” attribute, which is the equivalent to account being “disabled.” In order to map this to the Keystone enabled attribute, you can utilize the user_enabled_invert setting in conjunction with user_enabled_attribute to map the lock status to disabled in Keystone.
  61 - **LDAP_USE_STARTTLS**: Enable Transport Layer Security (TLS) for providing a secure connection from Keystone to LDAP (StartTLS, not LDAPS).
  62 - **LDAP_TLS_CACERT_BASE64**: CA certificate in Base64 format (if you have the PEM file, text inside "-----BEGIN CERTIFICATE-----"/"-----END CERTIFICATE-----" tags).
  63 - **LDAP_TLS_REQ_CERT**: Defines how the certificates are checked for validity in the client (i.e., Keystone end) of the secure connection (this doesn’t affect what level of checking the server is doing on the certificates it receives from Keystone). Possible values are "demand", "never", and "allow". The default of demand means the client always checks the certificate and will drop the connection if it is not provided or invalid. never is the opposite—it never checks it, nor requires it to be provided. allow means that if it is not provided then the connection is allowed to continue, but if it is provided it will be checked—and if invalid, the connection will be dropped.
  64
  65 #### default values
  66
  67 - **LDAP_AUTHENTICATION_DOMAIN_NAME**: no default
  68 - **LDAP_URL**: ldap://localhost
  69 - **LDAP_BIND_USER**: no default
  70 - **LDAP_BIND_PASSWORD**: no default
  71 - **LDAP_USER_TREE_DN**: no default
  72 - **LDAP_USER_OBJECTCLASS**: inetOrgPerson
  73 - **LDAP_USER_ID_ATTRIBUTE**: cn
  74 - **LDAP_USER_NAME_ATTRIBUTE**: sn
  75 - **LDAP_USER_PASS_ATTRIBUTE**: userPassword
  76 - **LDAP_USER_FILTER**: no default
  77 - **LDAP_USER_ENABLED_ATTRIBUTE**: enabled
  78 - **LDAP_USER_ENABLED_MASK**: 0
  79 - **LDAP_USER_ENABLED_DEFAULT**: true
  80 - **LDAP_USER_ENABLED_INVERT**: false
  81 - **LDAP_USE_STARTTLS**: false
  82 - **LDAP_TLS_CACERT_BASE64**: no default
  83 - **LDAP_TLS_REQ_CERT**: demand
  84
  85 #### Example
  86
  87 - **LDAP_AUTHENTICATION_DOMAIN_NAME**: ldap
  88 - **LDAP_URL**: ldap://ldap.example.com
  89 - **LDAP_BIND_USER**: cn=keystone,ou=Users,dc=example,dc=com
  90 - **LDAP_BIND_PASSWORD**: keystone
  91 - **LDAP_USER_TREE_DN**: ou=Users,dc=example,dc=com
  92 - **LDAP_USER_OBJECTCLASS**: person
  93 - **LDAP_USER_ID_ATTRIBUTE**: cn
  94 - **LDAP_USE_STARTTLS**: "true"
  95 - **LDAP_TLS_CACERT_BASE64**: MIID/TCCAmWg...