Migrating to the HOCON auth.conf format

The following rules, settings, and values have no direct equivalent in the new HOCON format. If you require them, you must reimplement them differently in the new format.

• on value of auth: The deprecated auth parameter's on value results in a match only when a request provides a client certificate. There is no equivalent behavior in the HOCON format.

• allow_ip or deny_ip parameters

• method parameter's search indirector: While there is no direct equivalent to the deprecated search indirector, you can create an equivalent HOCON rule. See below for an example.

Note: Puppet Server considers the state of a request's authentication differently depending on whether the authorization rules use the older Puppet auth.conf or newer HOCON formats. An authorization rule that uses the deprecated format evaluates the auth parameter as part of rule-matching process. A HOCON authorization rule first determines whether the request matches other parameters of the rule, and then considers the request's authentication state (using the rule's allow, deny, or allow-authenticated values) after a successful match only.

The HOCON auth.conf file has some fundamental structural requirements:

• An authorization section, which contains:

  • A version setting.

  • A rules array of map values, each representing an authorization rule. Each rule must contain:

    • A match-request section.

      • Each match-request section must contain at least one path and type.

    • A numeric sort-order value.

      • If the value is between 1 and 399, the rule supersedes Puppet Server's default authorization rules.

      • If the value is between 601 and 998, the rule can be overridden by Puppet Server's default authorization rules.

    • A string name value.

    • At least one of the following:

      • An allow value, a deny value, or both. The allow or deny values can contain:

        • A single string, representing the request's "name" derived from the Common Name (CN) attribute within an X.509 certificate's Subject Distinguished Name (DN). This string can be an exact name, a glob, or a regular expression.

        • A single map value containing an extension key.

        • A single map value containing a certname key.

        • An array of values, including string and map values.

      • An allow-unauthenticated value, but if present, there cannot also be an allow value.

For an full example of a HOCON auth.conf file, see the HOCON auth.conf documentation.

Let's convert this simple deprecated auth.conf authorization rule:

path /puppet/v3/environments
method find
allow *

We'll start with a skeletal, incomplete HOCON auth.conf file:

authorization: {
    version: 1
    rules: [
        {
            match-request: {
                path:
                type:
            }
            allow:
            sort-order: 1
            name:
        },
    ]
}

Next, let's convert each component of the deprecated rule to the new HOCON format.

1. Add the path to the new rule's path setting in its match-request section.

   ...
           match-request: {
               path: /puppet/v3/environments
               type:
           }
           allow:
           sort-order: 1
           name:
       },
   ...

2. Next, add its type to the section's type setting. Because this is a literal string path, the type is path.

   ...
           match-request: {
               path: /puppet/v3/environments
               type: path
           }
           allow:
           sort-order: 1
           name:
       },
   ...

3. The legacy rule has a method setting, with an indirector value of find that's equivalent to the GET and POST HTTP methods. We can implement these by adding an optional HOCON method setting in the rule's match-request section and specifying GET and POST as an array.

   ...
           match-request: {
               path: /puppet/v3/environments
               type: path
               method: [get, post]
           }
           allow:
           sort-order: 1
           name:
       },
   ...

4. Next, set the allow setting. The legacy rule used a * glob, which is also supported in HOCON.

   ...
           match-request: {
               path: /puppet/v3/environments
               type: path
               method: [get, post]
           }
           allow: "*"
           sort-order: 1
           name:
       },
   ...

5. Finally, give the rule a unique name value. Remember that the rule will appear in logs and in the body of error responses to unauthorized clients.

   ...
           match-request: {
               path: /puppet/v3/environments
               type: path
               method: [get, post]
           }
           allow: "*"
           sort-order: 1
           name: "environments"
       },
   ...

Our HOCON auth.conf file should now allow all authenticated clients to make GET and POST requests to the /puppet/v3/environments endpoint, and should look like this:

authorization: {
    version: 1
    rules: [
        {
            match-request: {
                path: /puppet/v3/environments
                type: path
                method: [get, post]
            }
            allow: "*"
            sort-order: 1
            name: "environments"
        },
    ]
}