Version information
This version is compatible with:
- Puppet Enterprise 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
- , , , , , , ,
Start using this module
Add this module to your Puppetfile:
mod 'enterprisemodules-ldap_principal', '1.0.0'
Learn more about managing modules with a PuppetfileDocumentation
ldap_principal
Table of Contents
- Description
- Setup - The basics of getting started with ldap_principal
- Usage - Configuration options and additional functionality
- Reference - An under-the-hood peek at what the module is doing and how
- Limitations - OS compatibility, etc.
- 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.
Supported
When you are developing on VirtualBox usage is FREE. On regular nodes, usage upto 50 entries is for FREE. When you need more, check our offers.
Setup
Setup Requirements
The custom types and providers in this module have two external requirements:
- easy_type
- the ruby gem (net_ldap gem)[https://github.com/ruby-ldap/ruby-net-ldap]
easy_type
The metadata
of this module contain the right informatiuon to allow libararian-puppet
to install all required module dependencies. If you want to takes control yourself:
forge "http://forge.enterprisemodules.com"
mod 'enterprisemodules/easy_type'
Then use the librarian-puppet
or r10K
to install the software.
You can also install the software using the puppet module
command:
puppet module install
--module_repository=http://forge.enterprisemodules.com
enterprisemodules-easy_type
(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.
Dependencies
- enterprisemodules/easy_type (>= 2.2.2)