#!/usr/bin/env python

DOCUMENTATION = """

---

module: ldap_permissions

short_description: Sets permissions/ACL for LDAP database.

description:

  - Sets permissions (access control list) for LDAP database.

version_added: 1.7.2

author: Branko Majic

notes:

  - Requires the python-ldap Python package on remote host. For Debian and

    derivatives, this is as easy as apt-get install python-ldap.

requirements:

  - python-ldap

options:

  filter:

    description:

      - LDAP filter that should be used for locating the database on which the

        ACL rules should be applied. This filter will be used for search under

        the C(cn=config) base DN. For regular user databases, the filter should

        probably be based on the C(olcSuffix) attribute. The filter must result

        in a unique entry.

    required: true

    default: ""

  rules:

    description:

      - LDAP rules that should be applied to the LDAP database. The rules should

        be provided as a list of strings. Each string should be an access rule

        as described in OpenLDAP administrator guide at

        U(http://www.openldap.org/doc/admin24/access-control.html). Use long

        format for specifying this parameter (see examples below).

    required: true

    default: ""

"""

EXAMPLES = """

# Set-up of rules for regular database.

ldap_permissions:

  - filter: '(olcSuffix=dc=example,dc=com)'

    rules:

      - >

        to *

        by dn.exact=gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth manage

        by * break

      - >

        to attrs=userPassword,shadowLastChange

        by self write

        by anonymous auth

        by dn="cn=admin,dc=example,dc=com" write

        by * none

      - >

        to dn.base=""

        by * read

      - >

        to *

        by self write

        by dn="cn=admin,dc=example,dc=com" write

        by * none

# Set-up rules for a configuration database. This time with a single rule in a

# single line.

ldap_permissions:

  - filter: '(olcDatabase={0}config)'

    rules:

      - to * by dn.exact=gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth manage by * break

"""

# Try to load the Python LDAP module.

try:

    import ldap

    import ldap.sasl

    import ldap.modlist

except ImportError:

    ldap_found = False

else:

    ldap_found = True

class LDAPPermissions(object):

    """

    This class encapsulates functionality for applying ACL to an LDAP database.

    """

    def __init__(self, module):

        """

        Initialises class instance. Reads parameters from the passed

        AnsibleModule instance, and connects to the LDAP server.

        """

        self.module = module

        self.filter = module.params["filter"]

        self.rules = module.params["rules"]

        self._connect()

    def _connect(self):

        """

        Initialises LDAP connection and binds to the LDAP server.

        Binding is done using the SASL EXTERNAL mechanism.

        Returns:

        Nothing.

        """

        self.connection = ldap.initialize("ldapi:///")

        self.connection.sasl_interactive_bind_s("", ldap.sasl.external())

    def _get_database(self):

        """

        Retrieves the requested database entry.

        Returns:

        Database entry. Return format is same as for function ldap.search_s.

        """

        return self.connection.search_s(base="cn=config", scope=ldap.SCOPE_ONELEVEL, filterstr=self.filter)

    def _get_modifications(self, database):

        """

        Returns modification list for updatingn the current ACL with requested

        ACL.

        Returns:

        Modification list. The format is suitable for use with functions

        ldap.modify() and ldap.modify_s(). An empty list will be returned if no

        changes are necessary.

        """

        # Fetch the list of current rules.

        current_rules = database[1]["olcAccess"]

        # Set-up list of requested rules.

        requested_rules = []

        for n, rule in enumerate(self.rules):

            rule = "{%d}%s" % (n, rule)

            requested_rules.append(rule.rstrip().lstrip().decode("utf-8").encode("utf-8"))

        return ldap.modlist.modifyModlist({'olcAccess': current_rules}, {'olcAccess': requested_rules})

    def apply(self):

        """

        Applies permissions requested via the Ansible module configuration.

        The function also produces the necessary JSON output, and terminates

        module execution as appropriate.

        Returns:

        Nothing.

        """

        # Fetch the database config based on filter and verify and only one was

        # returned.

        databases = self._get_database()

        if databases == []:

            self.module.fail_json(msg="No database matched filter: %s" % self.filter)

        elif len(databases) > 1:

            self.module.fail_json(msg="More than one databases matched filter: %s" % self.filter)

        database = databases[0]

        # Set-up the modification list.

        modify_list = self._get_modifications(database)

        # Apply modifications if necessary.

        if modify_list == []:

            self.module.exit_json(changed=False)

        else:

            try:

                self.connection.modify_s(database[0], modify_list)

            except ldap.OTHER as e:

                self.module.fail_json(msg="Failed to modify permissions. Rule syntax was possibly incorrect. LDAP server responded: %s" % e)

            self.module.exit_json(changed=True)

def main():

    """

    Runs the module.

    """

    # Construct the module helper for parsing the arguments.

    module = AnsibleModule(

        argument_spec=dict(

            filter=dict(required=True),

            rules=dict(required=True),

            )

        )

    if not ldap_found:

        module.fail_json(msg="The Python LDAP module is required")

    ldap_rules = LDAPPermissions(module)

    ldap_rules.apply()

# Import module snippets.

from ansible.module_utils.basic import *

main()