keystone ldap #35

Supports: xenial bionic focal groovy hirsute

Description

Keystone v3 deployments support the use of domain specific identity drivers, allowing different types of authentication backend to be deployed in a single Keystone deployment. . This charm supports use of LDAP or Active Directory domain backends, with configuration details provided by charm configuration options.


Overview

Keystone is the identity service used by OpenStack for authentication and high-level authorisation.

The keystone-ldap subordinate charm provides an LDAP domain backend for integrating a Keystone v3 deployment with an LDAP based authentication system. It is used in conjunction with the keystone charm.

An external LDAP server is a prerequisite.

Usage

Configuration

This section covers common and/or important configuration options. See file config.yaml for the full list of options, along with their descriptions and default values. See the Juju documentation for details on configuring applications.

domain-name

The domain-name option provides the name of the Keystone domain for which a domain-specific configuration will be generated. The default value is the name of the application (e.g. the default being 'keystone-ldap'). The keystone charm will automatically create a domain to support the backend once keystone-ldap is deployed.

ldap-config-flags

The ldap-config-flags option allows for arbitrary LDAP server settings to be passed to Keystone.

Important: This option should only be considered when an equivalent charm option is not available. The explicit charm option takes precedence if identical parameters are set.

Such a configuration can be added post-deploy by using a string of comma delimited key=value pairs:

juju config keystone-ldap \
    ldap-config-flags="user_id_attribute=cn,user_name_attribute=cn"

For a more complex environment, such as Microsoft Active Directory, a YAML file is normally used (e.g. ldap-config.yaml). For example:

keystone-ldap:
    ldap-config-flags: "{
            user_tree_dn: 'DC=dc1,DC=ad,DC=example,DC=com',
            user_filter: '(memberOf=CN=users-cn,OU=Groups,DC=dc1,DC=ad,DC=example,DC=com)',
            query_scope: sub,
            user_objectclass: person,
            user_name_attribute: sAMAccountName,
            user_id_attribute: sAMAccountName,
            user_mail_attribute: mail,
            user_enabled_attribute: userAccountControl,
            user_enabled_mask: 2,
            user_enabled_default: 512,
            user_attribute_ignore: 'password,tenant_id,tenants',
            user_allow_create: False,
            user_allow_update: False,
            user_allow_delete: False,
            }"

In the above, values are given as a JSON-like string. A combination of double quotes and braces are needed around the string, and single quotes are used for individual complex values.

A file-based configuration can be added post-deploy in this way:

juju config keystone-ldap --file ldap-config.yaml

ldap-password

The ldap-password option supplies the password associated with the LDAP user (given by option ldap-user).

ldap-server

The ldap-server option states the LDAP URL(s) of the Keystone LDAP identity backend. Example values:

ldap://10.10.10.10/
ldaps://10.10.10.10/
ldap://example.com:389,ldaps://ldaps.example.com:636

Note: An ldap:// URL will result in mandatory StartTLS usage if either the charm's tls-ca-ldap option has been specified or if the 'certificates' relation is present.

When the LDAP server is an Active Directory it is best practice to connect to its Global Catalog ports (3268 and 3269) instead of the standard ports (389 and 636):

ldap://active-directory-host.com:3268/
ldaps://active-directory-host.com:3269/

There are several reasons for this:

  1. Objects can be searched without specifying the domain name. This can be useful for multi-(AD)domain user management.
  2. Entries are returned with a single query rather than requiring Keystone to chase referrals. The latter can lead to connectivity issues if the referred server is not accessible (due to firewalls, routing, DNS resolution, etc.).
  3. The Global Catalog is an optimised subsection of all of the data within the AD services forest. This results in faster query responses.
  4. The Global Catalog is a single-source, multi-master high availability endpoint for the AD forest.

One reason for not doing so is when user management is being keyed off of fields that are not populated to the Global Catalog.

ldap-suffix

The ldap-suffix option states the LDAP server suffix to be used by Keystone.

ldap-user

The ldap-user option states the username (Distinguished Name) used to bind to the LDAP server (given by option ldap-server).

Deployment

Let file keystone-ldap.yaml contain the deployment configuration:

    keystone-ldap:
        ldap-server:"ldap://10.10.10.10/"
        ldap-user:"cn=admin,dc=test,dc=com"
        ldap-password:"password"
        ldap-suffix:"dc=test,dc=com"

If applicable, the ldap-config-flags option can be added:

    keystone-ldap:
        ldap-server:"ldap://10.10.10.10/"
        ldap-user:"cn=admin,dc=test,dc=com"
        ldap-password:"password"
        ldap-suffix:"dc=test,dc=com"
        ldap-config-flags: "{
                user_tree_dn: 'DC=dc1,DC=ad,DC=example,DC=com',
                ...,
                }"

Deploy keystone (requesting API v3 explicitly) and keystone-ldap:

juju deploy --config preferred-api-version=3 keystone
juju deploy --config keystone-ldap.yaml keystone-ldap
juju add-relation keystone-ldap:domain-backend keystone:domain-backend

Further reading

The below topics are covered in the upstream OpenStack documentation.

Bugs

Please report bugs on Launchpad.

For general charm questions refer to the OpenStack Charm Guide.


Configuration

domain-name
(string) Name of the keystone domain to configure; defaults to the deployed application name.
ldap-config-flags
(string) Additional LDAP configuration options. For simple configurations use a comma separated string of key=value pairs. "user_allow_create=False, user_allow_update=False, user_allow_delete=False" For more complex configurations use a json like string with double quotes and braces around all the options and single quotes around complex values. "{user_tree_dn: 'DC=dc1,DC=ad,DC=example,DC=com', user_allow_create: False, user_allow_delete: False}" See the README for more details. Note: The explicitly defined ldap-* charm config options take precedence over the same LDAP config option also specified in ldap-config-flags. For example, if the LDAP config query_scope is defined in ldap-query-scope as 'one' and in ldap-config-flags as "{query_scope: 'sub'}" then the config query_scope is set to 'one'.
ldap-group-id-attribute
(string) This option sets the LDAP attribute mapped to group IDs in keystone.
ldap-group-member-attribute
(string) This option sets the LDAP attribute that indicates user is a member of the group.
ldap-group-members-are-ids
(boolean) Enable this option if the members of group object class are keystone user IDs rather than LDAP DNs.
ldap-group-name-attribute
(string) This option sets the LDAP attribute mapped to group names in keystone.
ldap-group-objectclass
(string) This option sets the LDAP object class for groups.
ldap-group-tree-dn
(string) This option sets the search base to use for the groups.
ldap-password
(string) Password of the LDAP identity server.
ldap-pool-connection-timeout
(int) The connection timeout to use when pooling LDAP connections. A value of -1 means the connection will never timeout.
ldap-pool-retry-max
(int) This option allows to set the maximum number of retry attempts to connect to LDAP server before aborting.
ldap-pool-size
(int) This option sets the size of LDAP connection pool.
ldap-query-scope
(string) This option controls the scope level of data presented through LDAP.
ldap-readonly
(boolean) LDAP identity server backend readonly to keystone.
True
ldap-server
(string) LDAP server URL for keystone LDAP identity backend. Examples: ldap://10.10.10.10/ ldaps://10.10.10.10/ ldap://example.com:389,ldaps://ldaps.example.com:636 ldap://active-directory-host.com:3268/ ldaps://active-directory-host.com:3269/ An ldap:// URL will result in mandatory StartTLS usage if either the charm's tls-ca-ldap option has been specified or if the 'certificates' relation is present.
ldap-suffix
(string) LDAP server suffix to be used by keystone.
ldap-use-pool
(boolean) This option enables LDAP connection pooling.
ldap-user
(string) Username (Distinguished Name) used to bind to LDAP identity server. . Example: cn=admin,dc=test,dc=com
ldap-user-enabled-attribute
(string) This option sets the LDAP attribute mapped to the user enabled attribute in keystone.
ldap-user-enabled-default
(string) The default value to enable users. The LDAP servers can use boolean or bit in the user enabled attribute to indicate if a user is enabled or disabled. If boolean is used by the ldap schema, then the appropriate value for this option is 'True' or 'False'. If bit is used by the ldap schema, this option should match an appropriate integer value based on ldap-user-enabled-mask. Please note the integer value should be specified as a string in quotes. This option is typically used when ldap-user-enabled-attribute is set to 'userAccountControl'. Example: Configuration options to use for ldap schema with userAccountControl as control attribute, uses bit 1 in control attribute to indicate enablement. ldap-user-enabled-attribute = "userAccountControl" ldap-user-enabled-mask = 2 ldap-user-enabled-default = "512" ldap-user-enabled-default should be set to integer value that represents a user being enabled. For Active Directory, 512 represents Normal Account. For more information on how to set up those config options, please refer to the OpenStack docs on Keystone and LDAP integration at https://docs.openstack.org/keystone/latest/admin/configuration.html#integrate-identity-back-end-with-ldap
ldap-user-enabled-emulation
(boolean) If enabled, keystone uses an alternative method to determine if a user is enabled or not by checking if they are a member of the group defined by the ldap-user-enabled_emulation-dn option.
ldap-user-enabled-emulation-dn
(string) DN of the group entry to hold enabled users when using enabled emulation. Setting this option has no effect when ldap-user-enabled-emulation is False.
ldap-user-enabled-invert
(boolean) Setting this option to True allows LDAP servers to use lock attributes. This option has no effect when ldap-user-enabled-mask or ldap-user-enabled-emulation are in use.
ldap-user-enabled-mask
(int) Bitmask integer to select which bit indicates the enabled value if the LDAP server represents enabled as a bit on an integer rather than as a discrete boolean. If the option is set to 0, the mask is not used. This option is typically used when ldap-user-enabled-attribute is set to 'userAccessControl'.
ldap-user-filter
(string) This option sets the LDAP search filter to use for the users.
ldap-user-id-attribute
(string) This option sets the LDAP attribute mapped to User IDs in keystone.
ldap-user-name-attribute
(string) This option sets the LDAP attribute mapped to User names in keystone.
ldap-user-objectclass
(string) This option sets the LDAP object class for users.
ldap-user-tree-dn
(string) This option sets the search base to use for the users.
tls-ca-ldap
(string) This option controls which certificate (or a chain) will be used to connect to an ldap server(s) over TLS. Certificate contents should be either used directly or included via include-file:// An LDAP url should also be considered as ldaps and StartTLS are both valid methods of using TLS (see RFC 4513) with StartTLS using a non-ldaps url which, of course, still requires a CA certificate.