ansible-ldap-modules/ldap_attr

#!/usr/bin/env python

from traceback import format_exc

import ldap
import ldap.sasl


DOCUMENTATION = """
---
module: ldap_attr
short_description: Add or remove LDAP attribute values.
description:
    - Add or remove LDAP attribute values.
notes:
    - This only deals with attributes on existing entries. To add or remove
      whole entries, see M(ldap_entry).
    - The default authentication settings will attempt to use a SASL EXTERNAL
      bind over a UNIX domain socket. This works well with the default Ubuntu
      install for example, which includes a cn=peercred,cn=external,cn=auth ACL
      rule allowing root to modify the server configuration. If you need to use
      a simple bind to access your server, pass the credentials in C(bind_dn)
      and C(bind_pw).
    - For C(state=present) and C(state=absent), all value comparisons are
      performed on the server for maximum accuracy. For C(state=exact), values
      have to be compared in Python, which obviously ignores LDAP matching
      rules. This should work out in most cases, but it is theoretically
      possible to see spurious changes when target and actual values are
      semantically identical but lexically distinct.
version_added: null
author: Peter Sagerson
requirements:
    - python-ldap
options:
    dn:
        required: true
        description:
            - The DN of the entry to modify.
    name:
        required: true
        description:
            - The name of the attribute to modify.
    values:
        required: true
        description:
            - The value(s) to add or remove. This can be a string or a list of
              strings. The complex argument format is required in order to pass
              a list of strings (see examples).
    state:
        required: false
        choices: [present, absent, exact]
        default: present
        description:
            - The state of the attribute values. If C(present), all given
              values will be added if they're missing. If C(absent), all given
              values will be removed if present. If C(exact), the set of values
              will be forced to exactly those provided and no others. If
              C(state=exact) and C(values) is empty, all values for this
              attribute will be removed.
    server_uri:
        required: false
        default: ldapi:///
        description:
            - A URI to the LDAP server. The default value lets the underlying
              LDAP client library look for a UNIX domain socket in its default
              location.
    start_tls:
        required: false
        default: false
        description:
            - If true, we'll use the START_TLS LDAP extension.
    bind_dn:
        required: false
        description:
            - A DN to bind with. If this is omitted, we'll try a SASL bind with
              the EXTERNAL mechanism (see note). If this is blank, we'll use an
              anonymous bind.
    bind_pw:
        required: false
        description:
            - The password to use with C(bind_dn).
"""


EXAMPLES = """
# Configure directory number 1 for example.com.
- ldap_attr: dn='olcDatabase={1}hdb,cn=config' name=olcSuffix values='dc=example,dc=com' state=exact
  sudo: true

# Set up the ACL. The complex argument format is required here to pass a list
# of ACL strings.
- ldap_attr:
  sudo: true
  args:
    dn: olcDatabase={1}hdb,cn=config
    name: olcAccess
    values:
      - '{0}to attrs=userPassword,shadowLastChange
         by self write
         by anonymous auth
         by dn="cn=admin,dc=example,dc=com" write
         by * none'
      - '{1}to dn.base="dc=example,dc=com"
         by dn="cn=admin,dc=example,dc=com" write
         by * read'
    state: exact

# Declare some indexes.
- ldap_attr: dn='olcDatabase={1}hdb,cn=config' name=olcDbIndex values={{ item }}
  sudo: true
  with_items:
    - objectClass eq
    - uid eq

# Set up a root user, which we can use later to bootstrap the directory.
- ldap_attr: dn='olcDatabase={1}hdb,cn=config' name={{ item.key }} values={{ item.value }} state=exact
  sudo: true
  with_dict:
    olcRootDN: 'cn=root,dc=example,dc=com'
    olcRootPW: '{SSHA}mRskON0Stk+5wO5K+MMk2xmakKt8h7eJ'
"""


def main():
    module = AnsibleModule(
        argument_spec={
            'dn': dict(required=True),
            'name': dict(required=True),
            'values': dict(required=True),
            'state': dict(default='present', choices=['present', 'absent', 'exact']),
            'server_uri': dict(default='ldapi:///'),
            'start_tls': dict(default='false', choices=(BOOLEANS+['True', True, 'False', False])),
            'bind_dn': dict(default=None),
            'bind_pw': dict(default='', no_log=True),
        },
        supports_check_mode=True,
    )

    try:
        LdapAttr(module).main()
    except ldap.LDAPError, e:
        module.fail_json(msg=str(e), exc=format_exc())


class LdapAttr(object):
    def __init__(self, module):
        self.module = module

        # python-ldap doesn't understand unicode strings. Parameters that are
        # just going to get passed to python-ldap APIs are stored as utf-8.
        self.dn = self._utf8_param('dn')
        self.name = self._utf8_param('name')
        self.values = self._normalized_values()
        self.state = self.module.params['state']
        self.server_uri = self.module.params['server_uri']
        self.start_tls = self.module.boolean(self.module.params['start_tls'])
        self.bind_dn = self._utf8_param('bind_dn')
        self.bind_pw = self._utf8_param('bind_pw')

        self._connection = None

    def _utf8_param(self, name):
        return self._force_utf8(self.module.params[name])

    def _normalized_values(self):
        """ Parses the value parameter into a list of utf-8 strings. """
        values = self.module.params['values']

        if isinstance(values, basestring):
            if values == '':
                values = []
            else:
                values = [values]

        if not (isinstance(values, list) and all(isinstance(value, basestring) for value in values)):
            self.module.fail_json(msg="values must be a string or list of strings.")

        return map(self._force_utf8, values)

    def _force_utf8(self, value):
        """ If value is unicode, encode to utf-8. """
        if isinstance(value, unicode):
            value = value.encode('utf-8')

        return value

    def main(self):
        if self.state == 'present':
            modlist = self.handle_present()
        elif self.state == 'absent':
            modlist = self.handle_absent()
        elif self.state == 'exact':
            modlist = self.handle_exact()
        else:
            modlist = []

        if len(modlist) > 0:
            changed = True
            if not self.module.check_mode:
                self.connection.modify_s(self.dn, modlist)
        else:
            changed = False

        self.module.exit_json(changed=changed, modlist=modlist)

    #
    # State Implementations
    #

    def handle_present(self):
        values_to_add = filter(self.is_value_absent, self.values)
        if len(values_to_add) > 0:
            modlist = [(ldap.MOD_ADD, self.name, values_to_add)]
        else:
            modlist = []

        return modlist

    def handle_absent(self):
        values_to_delete = filter(self.is_value_present, self.values)
        if len(values_to_delete) > 0:
            modlist = [(ldap.MOD_DELETE, self.name, values_to_delete)]
        else:
            modlist = []

        return modlist

    def handle_exact(self):
        modlist = []

        current = self.current_values()
        if frozenset(self.values) != frozenset(current):
            if len(current) == 0:
                modlist = [(ldap.MOD_ADD, self.name, self.values)]
            elif len(self.values) == 0:
                modlist = [(ldap.MOD_DELETE, self.name, None)]
            else:
                modlist = [(ldap.MOD_REPLACE, self.name, self.values)]

        return modlist

    #
    # Util
    #

    def is_value_present(self, value):
        """ True if the target attribute has the given value. """
        try:
            is_present = bool(self.connection.compare_s(self.dn, self.name, value))
        except ldap.NO_SUCH_ATTRIBUTE:
            is_present = False

        return is_present

    def is_value_absent(self, value):
        """ True if the target attribute does not have the given value. """
        return (not self.is_value_present(value))

    def current_values(self):
        """ Returns the full list of values on the target attribute. """
        results = self.connection.search_s(self.dn, ldap.SCOPE_BASE, attrlist=[self.name])
        values = results[0][1].get(self.name, [])

        return values

    #
    # LDAP Connection
    #

    @property
    def connection(self):
        """ An authenticated connection to the LDAP server (cached). """
        if self._connection is None:
            self._connection = self._connect_to_ldap()

        return self._connection

    def _connect_to_ldap(self):
        connection = ldap.initialize(self.server_uri)

        if self.start_tls:
            connection.start_tls_s()

        if self.bind_dn is not None:
            connection.simple_bind_s(self.bind_dn, self.bind_pw)
        else:
            connection.sasl_interactive_bind_s('', ldap.sasl.external())

        return connection


from ansible.module_utils.basic import *  # noqa
main()