salt.modules.ldap3
Query and modify an LDAP database (alternative interface)
New in version 2016.3.0.
This is an alternative to the ldap
interface provided by the ldapmod
execution module.
- depends
-
ldap
Python module
- exception
salt.modules.ldap3.
LDAPError
(message, cause=None) -
Base class of all LDAP exceptions raised by backends.
This is only used for errors encountered while interacting with the LDAP server; usage errors (e.g., invalid backend name) will have a different type.
- Variables
-
cause -- backend exception object, if applicable
-
Add an entry to an LDAP database.
- Parameters
-
connect_spec -- See the documentation for the
connect_spec
parameter forconnect()
.dn -- Distinguished name of the entry.
attributes -- Non-empty dict mapping each of the new entry's attributes to a non-empty iterable of values.
- Returns
-
True
if successful, raises an exception otherwise.
CLI Example:
salt '*' ldap3.add "{ 'url': 'ldaps://ldap.example.com/', 'bind': { 'method': 'simple', 'password': 'secret', }, }" "dn='dc=example,dc=com'" "attributes={'example': 'values'}"
salt.modules.ldap3.add(connect_spec, dn, attributes)
-
Modify an entry in an LDAP database.
This does the same thing as
modify()
, but with a simpler interface. Instead of taking a list of directives, it takes a before and after view of an entry, determines the differences between the two, computes the directives, and executes them.Any attribute value present in
before
but missing inafter
is deleted. Any attribute value present inafter
but missing inbefore
is added. Any attribute value in the database that is not mentioned in eitherbefore
orafter
is not altered. Any attribute value that is present in bothbefore
andafter
is ignored, regardless of whether that attribute value exists in the database.- Parameters
-
connect_spec -- See the documentation for the
connect_spec
parameter forconnect()
.dn -- Distinguished name of the entry.
before -- The expected state of the entry before modification. This is a dict mapping each attribute name to an iterable of values.
after -- The desired state of the entry after modification. This is a dict mapping each attribute name to an iterable of values.
- Returns
-
True
if successful, raises an exception otherwise.
CLI Example:
salt '*' ldap3.change "{ 'url': 'ldaps://ldap.example.com/', 'bind': { 'method': 'simple', 'password': 'secret'} }" dn='cn=admin,dc=example,dc=com' before="{'example_value': 'before_val'}" after="{'example_value': 'after_val'}"
salt.modules.ldap3.change(connect_spec, dn, before, after)
-
Connect and optionally bind to an LDAP server.
- Parameters
-
connect_spec --
This can be an LDAP connection object returned by a previous call to
connect()
(in which case the argument is simply returned),None
(in which case an empty dict is used), or a dict with the following keys:-
'backend'
-
Optional; default depends on which Python LDAP modules are installed. Name of the Python LDAP module to use. Only
'ldap'
is supported at the moment.
-
'url'
-
Optional; defaults to
'ldapi:///'
. URL to the LDAP server.
-
'bind'
-
Optional; defaults to
None
. Describes how to bind an identity to the LDAP connection. IfNone
, an anonymous connection is made. Valid keys:-
'method'
-
Optional; defaults to
None
. The authentication method to use. Valid values include but are not necessarily limited to'simple'
,'sasl'
, andNone
. IfNone
, an anonymous connection is made. Available methods depend on the chosen backend.
-
'mechanism'
-
Optional; defaults to
'EXTERNAL'
. The SASL mechanism to use. Ignored unless the method is'sasl'
. Available methods depend on the chosen backend and the server's capabilities.
-
'credentials'
-
Optional; defaults to
None
. An object specific to the chosen SASL mechanism and backend that represents the authentication credentials. Ignored unless the method is'sasl'
.For the
'ldap'
backend, this is a dictionary. IfNone
, an empty dict is used. Keys:-
'args'
-
Optional; defaults to an empty list. A list of arguments to pass to the SASL mechanism constructor. See the SASL mechanism constructor documentation in the
ldap.sasl
Python module.
-
'kwargs'
-
Optional; defaults to an empty dict. A dict of keyword arguments to pass to the SASL mechanism constructor. See the SASL mechanism constructor documentation in the
ldap.sasl
Python module.
-
-
'dn'
-
Optional; defaults to an empty string. The distinguished name to bind.
-
'password'
-
Optional; defaults to an empty string. Password for binding. Ignored if the method is
'sasl'
.
-
-
'tls'
-
Optional; defaults to
None
. A backend-specific object containing settings to override default TLS behavior.For the
'ldap'
backend, this is a dictionary. Not all settings in this dictionary are supported by all versions ofpython-ldap
or the underlying TLS library. IfNone
, an empty dict is used. Possible keys:-
'starttls'
-
If present, initiate a TLS connection using StartTLS. (The value associated with this key is ignored.)
-
'cacertdir'
-
Set the path of the directory containing CA certificates.
-
'cacertfile'
-
Set the pathname of the CA certificate file.
-
'certfile'
-
Set the pathname of the certificate file.
-
'cipher_suite'
-
Set the allowed cipher suite.
-
'crlcheck'
-
Set the CRL evaluation strategy. Valid values are
'none'
,'peer'
, and'all'
.
-
'crlfile'
-
Set the pathname of the CRL file.
-
'dhfile'
-
Set the pathname of the file containing the parameters for Diffie-Hellman ephemeral key exchange.
-
'keyfile'
-
Set the pathname of the certificate key file.
-
'newctx'
-
If present, instruct the underlying TLS library to create a new TLS context. (The value associated with this key is ignored.)
-
'protocol_min'
-
Set the minimum protocol version.
-
'random_file'
-
Set the pathname of the random file when
/dev/random
and/dev/urandom
are not available.
-
'require_cert'
-
Set the certificate validation policy. Valid values are
'never'
,'hard'
,'demand'
,'allow'
, and'try'
.
-
-
'opts'
-
Optional; defaults to
None
. A backend-specific object containing options for the backend.For the
'ldap'
backend, this is a dictionary of OpenLDAP options to set. IfNone
, an empty dict is used. Each key is a the name of an OpenLDAP option constant without the'LDAP_OPT_'
prefix, then converted to lower case.
-
- Returns
-
an object representing an LDAP connection that can be used as the
connect_spec
argument to any of the functions in this module (to avoid the overhead of making and terminating multiple connections).This object should be used as a context manager. It is safe to nest
with
statements.
CLI Example:
salt '*' ldap3.connect "{ 'url': 'ldaps://ldap.example.com/', 'bind': { 'method': 'simple', 'dn': 'cn=admin,dc=example,dc=com', 'password': 'secret'} }"
salt.modules.ldap3.connect(connect_spec=None)
-
Delete an entry from an LDAP database.
- Parameters
-
connect_spec -- See the documentation for the
connect_spec
parameter forconnect()
.dn -- Distinguished name of the entry.
- Returns
-
True
if successful, raises an exception otherwise.
CLI Example:
salt '*' ldap3.delete "{ 'url': 'ldaps://ldap.example.com/', 'bind': { 'method': 'simple', 'password': 'secret'} }" dn='cn=admin,dc=example,dc=com'
salt.modules.ldap3.delete(connect_spec, dn)
-
Modify an entry in an LDAP database.
- Parameters
-
connect_spec -- See the documentation for the
connect_spec
parameter forconnect()
.dn -- Distinguished name of the entry.
-
directives --
Iterable of directives that indicate how to modify the entry. Each directive is a tuple of the form
(op, attr, vals)
, where:-
op
identifies the modification operation to perform. One of:'add'
to add one or more values to the attribute'delete'
to delete some or all of the values from the attribute. If no values are specified with this operation, all of the attribute's values are deleted. Otherwise, only the named values are deleted.'replace'
to replace all of the attribute's values with zero or more new values
attr
names the attribute to modifyvals
is an iterable of values to add or delete
-
- Returns
-
True
if successful, raises an exception otherwise.
CLI Example:
salt '*' ldap3.modify "{ 'url': 'ldaps://ldap.example.com/', 'bind': { 'method': 'simple', 'password': 'secret'} }" dn='cn=admin,dc=example,dc=com' directives="('add', 'example', ['example_val'])"
salt.modules.ldap3.modify(connect_spec, dn, directives)
-
Search an LDAP database.
- Parameters
-
connect_spec -- See the documentation for the
connect_spec
parameter forconnect()
.base -- Distinguished name of the entry at which to start the search.
-
scope --
One of the following:
-
'subtree'
-
Search the base and all of its descendants.
-
'base'
-
Search only the base itself.
-
'onelevel'
-
Search only the base's immediate children.
-
filterstr -- String representation of the filter to apply in the search.
attrlist -- Limit the returned attributes to those in the specified list. If
None
, all attributes of each entry are returned.attrsonly -- If non-zero, don't return any attribute values.
- Returns
-
a dict of results. The dict is empty if there are no results. The dict maps each returned entry's distinguished name to a dict that maps each of the matching attribute names to a list of its values.
CLI Example:
salt '*' ldap3.search "{ 'url': 'ldaps://ldap.example.com/', 'bind': { 'method': 'simple', 'dn': 'cn=admin,dc=example,dc=com', 'password': 'secret', }, }" "base='dc=example,dc=com'"
salt.modules.ldap3.search(connect_spec, base, scope='subtree', filterstr='(objectClass=*)', attrlist=None, attrsonly=0)
© 2021 SaltStack.
Licensed under the Apache License, Version 2.0.
https://docs.saltproject.io/en/latest/ref/modules/all/salt.modules.ldap3.html