How to Authenticate Puppet Enterprise with FreeIPA LDAP

Using a Linux Domain controller such as FreeIPA? If so then the fields are a bit different than some other LDAP interfaces, which makes it difficult for some to connect to for authentication. In this blog, we break down how to use FreeIPA LDAP.

Table of Contents:

• What Is FreeIPA LDAP?
• How to Setup Puppet Enterprise With FreeIPA LDAP
• Get Started With Puppet Enterprise

What Is FreeIPA LDAP?

FreeIPA is an identity and authentication solution for Linux/UNIX that can be used for LDAP (Lightweight Directory Access Protocol). 

How to Setup Puppet Enterprise With FreeIPA LDAP

Here is a quick how-to on setting up Puppet Enterprise with authentication from FreeIPA. I am assuming that you already have Puppet Enterprise installed with eyaml configured. If not, then you may want to visit these prerequisites.

• Installing Puppet Enterprise
• Setting up Encrypted YAML (eyaml)

I am using the Roles and Profiles design pattern. If you’re not familiar with the Roles and Profiles method, then make sure to read up on it first.

Setup of FreeIPA server

I used the forge module addulact/freeipa to set up my FreeIPA server. I created a profile such as this:

    # Manage FreeIPA domain controller
    class profile::linux::ipa::server (
      String $admin_pass,
      String $dirsvc_pass,
    ) {
      class {'freeipa':
        ipa_role                    => 'master',
        domain                      => 'example.local',
        ipa_master_fqdn             => 'dc01.example.local',
        ipa_server_fqdn             => 'dc01.example.local',
        puppet_admin_password       => $admin_pass,
        directory_services_password => $dirsvc_pass,
        install_ipa_server          => true,
        ip_address                  => '10.0.10.2',
        enable_ip_address           => true,
        enable_hostname             => true,
        manage_host_entry           => true,
        install_epel                => true,
        custom_dns_forwarders       => [ '8.8.8.8', '8.8.4.4' ],
      }
    }

After grouping and classifying my FreeIPA domain controller to use this profile, I ran the Puppet agent and watched as FreeIPA was installed.

Notes:

If the installation of FreeIPA server fails for any reason, then you must uninstall FreeIPA before you try again. Do this by running /usr/sbin/ipa-server-install --uninstall.

If managing DNS with FreeIPA, then the zone must not be managed anywhere else that can be found with the configured DNS servers. This is why I chose to use a local extension to the domain.

Setup of FreeIPA client

I used the same forge module to configure the client and created a profile for the IPA client that was attached to my linux baseline profile.

    # Manage FreeIPA client
    class profile::linux::ipa::client (
      String $admin_pass,
      String $dirsvc_pass,
    ) {
      class {'freeipa':
        ipa_role                    => 'client',
        domain                      => 'example.local',
        ipa_master_fqdn             => 'dc01.example.local',
        puppet_admin_password       => $admin_pass,
        directory_services_password => $dirsvc_pass,
        ip_address                  => $facts['ipaddress'],
        enable_hostname             => true,
        manage_host_entry           => true,
        install_epel                => true,
      }
    }

This profile sets up the ipa-client on the Linux nodes to authenticate to FreeIPA. In addition, since I have set up the DNS server in my FreeIPA server, this also adds A and PTR records to the zone.

Configure Puppet Enterprise console to use FreeIPA

I started this step by creating a service account in FreeIPA. You can reference the FreeIPA administration guide section 1.1.1 for more information on how to do this.

After setting up the user account, read up on connecting external directory services to PE.

I'll walk through the settings that I used for the domain example.local

• Directory name: FreeIPA
  • Friendly name for your directory.
• Hostname: dc01.example.local
  • FQDN for your FreeIPA domain controller.
• Port: 636
  • I chose to use SSL over port 636, but use what your organization requires
• Lookup user (optional):uid=svc_ldap_pe,cn=users,cn=accounts,dc=example,dc=local
  • Although this is optional for Puppet Enterprise, FreeIPA requires auth to browse directory, at least with defaults.
• Lookup password (optional)
  • Not optional for FreeIPA with default settings.
• Connection timeout (seconds): 30
  • You will probably want to adjust this according to your environment and latency thresholds.
• Validate the hostname: checked
  • With this being authentication, I want to validate hostnames match certs.
• Base distinguished name:cn=accounts,dc=example,dc=local
  • This is going to be the base search path for LDAP queries.
• User login attribute:uid
  • This is where one of the variances are with other LDAP servers such as Active Directory.
• User email address:mail
• User full name:displayName
• Group object class:ipausergroup
  • This is where one of the variances are with other LDAP servers, such as Active Directory.
• Group membership field:member
• Group name attribute:cn
  • This is where one of the variances are with other LDAP servers such as Active Directory.
• Group lookup attribute:cn
• Search nested groups: checked
  • I checked this in my lab to be able to search nested groups, but this can cause a performance impact.

After you populate these fields, you should click Test Changes to ensure successful connection, then click Commit Changes to save the changes.

Congratulations, you have configured Puppet Enterprise to authenticate against FreeIPA, but you are not done yet. Next you will need to go in and map what FreeIPA groups have permissions to perform actions in Puppet Enterprise. 

Get Started With Puppet Enterprise

Not using Puppet Enterprise yet? Get started with your free trial today. 

START MY TRIAL