Forge Home

Modules

Puppet

Resources

PuppetEcosystemPuppet CommunityUpdates

ldap_principal

the custom types needed to manage LDAP principals
Project URLRSS FeedReport issues

8,660 downloads

254 latest version

5.0 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 1.4.0 (latest)
  • 1.3.0
  • 1.2.0
  • 1.1.2
  • 1.1.1
  • 1.0.0
released May 19th 2023
This version is compatible with:
  • Puppet Enterprise 2023.8.x, 2023.7.x, 2023.6.x, 2023.5.x, 2023.4.x, 2023.3.x, 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x, 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x, 2018.1.x, 2017.3.x, 2017.2.x, 2017.1.x, 2016.5.x, 2016.4.x
  • Puppet >=4.0.0 < 9.0.0
  • , , , , , , ,
Tasks:
  • principal

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'enterprisemodules-ldap_principal', '1.4.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add enterprisemodules-ldap_principal
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install enterprisemodules-ldap_principal --version 1.4.0

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download

Documentation

enterprisemodules/ldap_principal — version 1.4.0 May 19th 2023

Enterprise Modules

Table of Contents

  1. Description
  2. Setup - The basics of getting started with ldap_principal
  3. Usage - Configuration options and additional functionality
  4. Reference - An under-the-hood peek at what the module is doing and how
  5. Limitations - OS compatibility, etc.
  6. Development - Guide for contributing to the module

Description

When you enter the search term 'LDAP' on the forge you get a whole load of modules that so something with LDAP. Most of these modules allow you to install and LDAP client or LDAP server. Some of these modules even allow you to do some management of entries inside of the LDAP server, but none of these solutions provide the whole spectrum of operations needed to manage LDAP in a large organization. This module does.

License

This is a commercially licensed module. But you can use the module on VirtualBox based development systems for FREE. When used on real systems a license is required. On regular nodes, usage upto 50 entries is for FREE.

You can license our modules in multiple ways. Our basic licensing model requires a subscription per node. But contact us for details.

Check the License for details.

Setup

Setup Requirements

The custom types and providers in this module have two external requirements:

(net_ldap gem)[https://github.com/ruby-ldap/ruby-net-ldap]

The ldap_principal custom type use the ruby gem (net_ldap gem)[https://github.com/ruby-ldap/ruby-net-ldap]. Your puppet manifest must ensure installation of the gem. The Puppet types and provider will ensure it only starts its operations after the gem installed.

package {
  'net-ldap':
    ensure   => 'present',
    provider => pe_gem;
}

Beginning with ldap_principal

After installation, the first thing is to do is tell your puppet environment what LDAP servers you have in your organization. Although most organizations prefer to keep user information as centrally managed as possible, reality is that most organizations have multiple LDAP servers they need to manage.

Add the ldap_server to the manifest

Using the ldap_server type you can add information about your servers to the Puppet manifest. Here is an example:

ldap_server { 'production_ldap':
  address           => 'prod_ldap.example.com',
  port              => '389',
  user_dn           => 'cn=admin,dc=example,dc=org',
  password          => 'admin',
  verify_ssl        => 'false',
  use_ssl           => 'false',
  base              => 'dc=example,dc=org',
}

The ldap_server type contains everyting needed to connect to the LDAP server and perform operations.

Because Puppet needs this information later, it will store it in /etc/ldap_server.yaml. To ensure safety, the file is adequately secured, and the password is encrypted.

When you have more LDAP servers, you need to add them to your manifest too.

Ensuring an container entry

When you want manage entries in "your own" container, you must first ensure that the container exists. For example:

ldap_principal { 'production_ldap:ou=mydepartment,dc=example,dc=org':
  ensure     => 'present',
  purge      => true,
  attributes => {
                'objectclass'  => ['organizationalUnit', 'top'],
                'ou'           => 'mydepartment',
              },
}

This example ensures there is an organizationalUnit LDAP container mydepartment. The purge property set to true makes sure that entries in this container that are not in the manifest, will be removed by puppet. This ensures there are no unmanaged LDAP entries in our container.

Enter persons

Now that we have the container, we can enter all the persons (or another type of entries) to it.

ldap_principal { 'production_ldap:cn=kermit,ou=muppetshow,dc=example,dc=org':
  ensure     => 'present',
  purge_attributes => true,
  attributes => {
    'objectclass'  => ['top', 'inetOrgPerson'],
    'userPassword' => "{SSHA512}2ZsyGTxVyEw14Cu9D/OXpTddfy/387D/rlR6R0VVdRIz+3Wn52fSYZpKAP1S\n9J/kRbkoBiPK/9eZMOZV6cgidzEyMzQ1Njc4",
    'givenName'    => 'Kermit the frog',
    'cn'           => 'kermit,
    'sn'           => 'Kermit',
  },
}

Here we make sure there is a kermit entry in the muppetshow. If the LDAP server doesn't contain an entry, Puppet will create it. If the LDAP server already contains this entry, but some of the properties are different, Puppet will update the specified attributes. Because the purge_attributes parameter is set to true any other attributes available on the LDAP server, but not in the manifest, will be removed.

Manage group entries

The LDAP directory also can contain groups. You can manage a group with the present_in or absent_in properties. Here we create a group muppets and we make sure kermit is in that group.

ldap_principal { 'production_ldap:cn=muppets,ou=muppetshow,dc=example,dc=org':
  ensure     => 'present',
  attributes => {
    'objectclass'  => ['top', 'groupOfNames'],
  },
  present_in => {
    'member'       => [
      'cn=kermit,ou=muppetshow,dc=example,dc=org',
    ],
  },
}

All other entries in the group muppets are left as the are. We only make sure that kermit is in the group. When we want to make sure an entry is NOT available in the group, we use the [absent_in(/docs/ldap_principal/ldap_principal.html#ldap_principal_absent_in)] property:

...
   absent_in       => {
     'member'       => [
       'cn=piggy,ou=muppetshow,dc=example,dc=org',
     ],
   },
...

Making sure an entry is not available

Like standard in Puppet, removing an entry is easy:

ldap_principal { 'production_ldap:cn=gonzo,ou=muppetshow,dc=example,dc=org':
  ensure => 'absent',
}

Managing the password

In the examples before, we use the hashed password. Some of the LDAP servers don't allow this, and you must use an unencrypted password. But because Puppet needs to manage encrypted attributes in an idempotent way, we need some way of control over the encrypted value. You can do this by using the transform property.

Here is an example:

ldap_principal { 'docker:cn=piggy,ou=muppetshow, dc=example,dc=org':
  ensure     => 'present',
  attributes => {
    'cn'           => 'piggy',
    'givenname'    => 'Miss Piggy',
    'objectclass'  => ['top', 'inetOrgPerson'],
    'sn'           => 'piggy',
    'userpassword' => 'MissPiggy'
  },
  transform  => {'userpassword' => 'hashed'},
}

In this definition, the value specified at the attribute ‘userPassword’, will first be presented to the Puppet function hashed_compare and then compared with the value returned from the ldap server. The specified function will NOT be applied before sending the value to the LDAP server.

At this point in time, we support passwords using the SSHA512 hash.

Manifest ordering

As you can see in the examples, we add no explicit ordering. This is because the ldap_principal type supports setting up automatic relations on all entries. When ensuring entries it will make sure the parents are created before the children. When absenting entries, it will first remove the children before removing the parents.

Basic setup done

This concludes setting up the basic entries. This example should help you get started and fill your manifest

Reference

Check our documentation for a full description of all properties.

Limitations

Supported Operation systems

This module support a broad range of Linux operating systems:

  • RHEL 4,5,6,7
  • CentOS 4,5,6,7
  • OracleLinux 4,5,6,7
  • Scientific 4,5,6,7

Supported Puppet versions

This module requires Puppet 4 to run. It suports both the opes source versions as well as Puppet Enterprise.