Forge Home

Modules

Puppet

Resources

PuppetEcosystemPuppet CommunityUpdates

puppet_authorization

Module to manage auth.conf.
Project URLRSS FeedReport issues

947,125 downloads

4,024 latest version

4.7 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.0.0 (latest)
  • 0.5.1
  • 0.5.0
  • 0.4.0
  • 0.3.0
  • 0.2.0
  • 0.1.0
released Apr 15th 2024
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
  • Puppet >= 7.0.0 < 9.0.0
  • , , , , ,

Start using this module

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

Add this module to your Puppetfile:

mod 'puppetlabs-puppet_authorization', '1.0.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add puppetlabs-puppet_authorization
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install puppetlabs-puppet_authorization --version 1.0.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

puppetlabs/puppet_authorization — version 1.0.0 Apr 15th 2024

puppet_authorization

Table of Contents

  1. Module Description - What the module does and why it is useful
  2. Setup - The basics of getting started with puppet_authorization
  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

Module Description

The puppet_authorization module generates or changes the auth.conf file using authorization rules written as Puppet resources.

Note that this module is used only for the new auth.conf file used by Puppet Server 2.2.0 and later. If you are using the auth.conf file used by core Puppet, this module will not affect it. See Puppet Server documentation for detailed information about the auth.conf file.

This module allows you to add custom rules to your auth.conf file by writing Puppet resources that can create, modify, or remove the associated rules from the auth.conf file. It allows the auth.conf to be created entirely from Puppet code---you never have to touch the auth.conf file directly.

This module is maintained by Puppet, but we have no plans for future feature development. We will keep it working with current versions of Puppet, but new feature development will come from community contributions. It does not qualify for Puppet Support plans.

[tier:maintenance-mode]

Setup

Beginning with puppet_authorization

Note that this section applies only to open source Puppet. In Puppet Enterprise, this resource is managed automatically.

The puppet_authorization resource sets up the auth.conf and configures settings that apply globally, rather than being specific to individual rules.

For example, this code:

puppet_authorization { '/etc/puppetlabs/puppetserver/conf.d/auth.conf':
  version                => 1,
  allow_header_cert_info => false
}

...would populate the following corresponding settings into the "auth.conf" file:

authorization: {
  version: 1
  allow-header-cert-info: false
  rules: ...
}

Note that the value for rules in this case would be set to [] if the rules array was not yet present in the file. Otherwise, whatever value was already in the target file for rules is preserved.

The values used above are:

  • version: Currently, 1 is the only supported value and is the default.
  • allow-header-cert-info: Controls whether the identity of the client will be inferred from the client's SSL certificate, when false, or from special X-Client HTTP headers, when true. The default for this setting is false. See Puppet Server documentation for information about disabling HTTPS for Puppet Server and allow-header-cert-info setting.

Usage

The following usage examples assume an empty auth.conf file that looks like this:

authorization: {
  version: 1
  rules: []
}

Add a rule

The main resource to use is puppet_authorization::rule, which manages a single rule in the authorization configuration file (auth.conf). This authorization file also needs to be managed with a resource, which is done with puppet_authorization.

The following declares a resource to manage the top-level structure, followed by a resource to add a rule for controlling access to the "environments" HTTP endpoint:

puppet_authorization::rule { 'environments':
  match_request_path   => '/puppet/v3/environments',
  match_request_type   => 'path',
  match_request_method => 'get',
  allow                => 'your.special.admin',
  sort_order           => 300,
  path                 => '/etc/puppetlabs/puppetserver/conf.d/auth.conf',
}

Here, we've declared that only 'your.special.admin' can access the /puppet/v3/environments endpoint.

Delete a rule

Continuing from the previous example to add the "environments" rule, the following example declares a resource that removes it from the file.

puppet_authorization::rule { 'environments':
  ensure => absent,
  path   => '/etc/puppetlabs/puppetserver/conf.d/auth.conf',
}

When removing a rule, you have only to provide the rule name and path to the configuration file where it can be found. Since rules must have unique names, you don't have to define the other attributes (match_request_path, etc); the rule with the matching name will be removed, regardless.

Configure the catalog endpoint

You can configure the catalog HTTP endpoint for Puppet Server to:

  • Permit an administrative node to access the catalog for any node.
  • Permit other nodes to be able to access their own catalog, but no other node’s catalog.

In this example, we'll configure the rule to apply only to requests made to the production or test directory environments in Puppet.

puppet_authorization::rule { 'catalog_request':
  match_request_path         => '^/puppet/v3/catalog/([^/]+)$',
  match_request_type         => 'regex',
  match_request_method       => ['get','post'],
  match_request_query_params => {'environment' => [ 'production', 'test' ]},
  allow                      => ['$1', 'adminhost.mydomain.com'],
  sort_order                 => 200,
  path                       => '/etc/puppetlabs/puppetserver/conf.d/auth.conf',
}

If the original auth.conf file looked like this:

authorization: {
  version: 1
  allow-header-cert-info: false
  rules: []
}

...then it should look something like this after the new rule is applied:

authorization: {
  version: 1
  allow-header-cert-info: false
  rules: [
      {
          "allow" : [
              "$1",
              "adminhost.mydomain.com",
          ],
          "match-request" : {
              "method" : [
                  "get",
                  "post"
              ],
              "path" : "^/puppet/v3/catalog/([^/]+)$",
              "query-params" : {
                  "environment" : [
                      "production",
                      "test"
                  ]
              },
              "type" : "regex"
          },
          "name" : "catalog_request",
          "sort-order" : 200
      }
  ,
  ]
}

Trigger rule changes

Puppet Server does not automatically start using the new rule definitions in the auth.conf file as they are applied. Before your auth.conf file changes take effect, the Puppet Server service needs to be restarted. Add the following code to each rule resource to restart the service any time rules in the auth.conf file changes.

If you're using open source Puppet Server, add the following code to your rule resource:

notify => Service['puppetserver']

If you're using Puppet Server in PE, add:

notify => Service['pe-puppetserver']

For example, with this code added, the full rule definition might look like this:

puppet_authorization::rule { 'catalog_request':
  match_request_path         => '^/puppet/v3/catalog/([^/]+)$',
  match_request_type         => 'regex',
  match_request_method       => ['get','post'],
  match_request_query_params => {'environment' => [ 'production', 'test' ]},
  allow                      => ['$1', 'adminhost.mydomain.com'],
  sort_order                 => 200,
  path                       => '/etc/puppetlabs/puppetserver/conf.d/auth.conf',
  notify                     => Service['pe-puppetserver'],
}

Reference

Defined Types

Providers

Defined Type: puppet_authorization

Sets up the skeleton server auth.conf file if it doesn't exist.

Parameters (all optional)

  • version: The authorization.version setting in the server auth.conf. Valid options: an integer (currently, 1 is the only supported value). Default: 1.

  • allow_header_cert_info: The authorization.allow-header-cert-info setting in the server auth.conf. Valid options: true, false. Default: false.

  • replace: Whether or not to replace existing file at path. If set to true this will cause the file to be regenerated on every puppet run. Valid options: true, false. Default: false.

  • path: Absolute path for auth.conf. Defaults to name.

Defined Type: puppet_authorization::rule

Adds individual rules to auth.conf.

Parameters (optional unless otherwise specified)

  • match_request_path: Required. Valid options: a string.

  • match_request_type: Required. Valid options: 'path', 'regex'.

  • path: Required. The absolute path for the auth.conf file.

  • ensure: Whether to add or remove the rule. Valid options: 'present', 'absent'. Defaults to 'present'.

  • rule_name: The name setting for the rule. Valid options: a string. Defaults to name.

  • allow: The allow setting for the rule. Cannot be set along with an allow_unauthenticated value of true. Valid options: a hash, a string or an array of strings and/or hashes. A hash here must contain only one of extensions or certname. Defaults to undef. For more details on the allow setting, see https://github.com/puppetlabs/trapperkeeper-authorization/blob/master/doc/authorization-config.md#allow.

  • deny: The deny setting for the rule. Cannot be set along with an allow_unauthenticated value of true. Valid options: a hash, a string or an array of strings and/or hashes. A hash here must contain only one of extensions or certname. Defaults to undef. For more details on the deny setting, see https://github.com/puppetlabs/trapperkeeper-authorization/blob/master/doc/authorization-config.md#deny.

  • allow_unauthenticated: The allow_unauthenticated setting for the rule. Cannot be set to true along with deny or allow. Valid options: true, false. Defaults to false.

  • match_request_method: The method setting for the match_request in the rule. Valid options: String or array of strings containing: 'put', 'post', 'get', 'head', 'delete'. Defaults to undef.

  • match_request_query_params: The query_params setting for the match_request in the rule. Valid options: Hash. Defaults to {}.

  • sort_order: The sort order for the rule. Valid options: an integer. Defaults to 200.

Limitations

The auth.conf file this module writes is supported only in open source Puppet Server 2.2.0 or greater or Puppet Enterprise 2015.3.0 or greater. See (https://docs.puppetlabs.com/puppetserver/latest/config_file_auth.html) for more details about authorization in Puppet Server.