Puppet Server 2.2.0 introduced a significant change in how it manages authentication to API endpoints. The older Puppet auth.conf
file and whitelist-based authorization method are deprecated. Puppet Server’s new auth.conf
file, illustrated below in examples, also uses a different format for authorization rules.
Use the following examples and methods to convert your authorization rules when upgrading to Puppet Server 2.2.0 and newer. For detailed information about using the new or deprecated auth.conf
rules with Puppet Server, see the Puppet Server auth.conf
documentation.
Note: To continue using the deprecated Puppet
auth.conf
file and authorization rule format, see the Deprecated Ruby Parameters section of theauth.conf
documentation. To support both Puppet 3 and Puppet 4 agents connecting to Puppet Server, see Backward Compatibility with Puppet 3 Agents.
You can reimplement and manage your authorization rules in the new HOCON format and auth.conf
file by using the puppetlabs-puppet_authorization
Puppet module. See the module’s documentation for details.
Most of the deprecated authorization rules and settings are available in the new 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.
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
parametersmethod
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 theauth
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’sallow
,deny
, orallow-authenticated
values) after a successful match only.
The HOCON auth.conf
file has some fundamental structural requirements:
authorization
section, which contains:
version
setting.rules
array of map values, each representing an authorization rule. Each rule must contain:
match-request
section.
sort-order
value.
name
value.allow
value, a deny
value, or both. The allow
or deny
values can contain:
extension
key.certname
key.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.
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:
},
...
Next, add its type to the section’s type
setting. Since this is a literal string path, the type is path
.
...
match-request: {
path: /puppet/v3/environments
type: path
}
allow:
sort-order: 1
name:
},
...
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:
},
...
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:
},
...
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"
},
]
}
To convert a regular expression path, enclose it in double quotation marks and slash characters (/
), and set the type
to regex.
Note: You must escape regular expressions to conform to HOCON standards, which are the same as JSON’s and differ from the deprecated format’s regular expressions. For instance, the digit-matching regular expression
\d
must be escaped with a second backslash, as\\d
.
Deprecated:
path ~ ^/puppet/v3/catalog/([^/]+)$
HOCON:
authorization: {
version: 1
rules: [
{
match-request: {
path: "^/puppet/v3/catalog/([^/]+)$"
type: regex
...
Note: You must escape regular expressions to conform to HOCON standards, which are the same as JSON’s and differ from the deprecated format’s regular expressions. For instance, the digit-matching regular expression
\d
must be escaped with a second backslash, as\\d
.
Backreferencing works the same way it does in the deprecated format.
Deprecated:
path ~ ^/puppet/v3/catalog/([^/]+)$
allow $1
HOCON:
authorization: {
version: 1
rules: [
{
match-request: {
path: "^/puppet/v3/catalog/([^/]+)$"
type: regex
}
allow: "$1"
...
To have a rule match any request regardless of its authentication state, including unauthenticated requests, a deprecated rule would assign the any value to the auth
parameter. In a HOCON rule, set the allow-unauthenticated
parameter to true. This overrides the allow
and deny
parameters and is an insecure configuration that should be used with caution.
Deprecated:
auth: any
HOCON:
authorization: {
version: 1
rules: [
{
match-request: {
...
}
allow-unauthenticated: true
...
method
indirectorsIf a deprecated rule has multiple method
indirectors, combine all of the related HTTP methods to the HOCON method
array.
Deprecated:
method find, save
The deprecated find indirector corresponds to the GET and POST methods, and the save indirector corresponds to the PUT method. In the HOCON format, simply combine these methods in an array.
HOCON:
authorization: {
version: 1
rules: [
{
match-request: {
...
method: [get, post, put]
}
...
In deprecated rules, the environment
parameter adds a comma-separated list of query parameters as a suffix to the base URL. HOCON rules allow you to pass them as an array environment
value inside the query-params
setting. Rules in both the deprecated and HOCON formats match any environment
value.
Deprecated:
environment: production,test
HOCON:
authorization: {
version: 1
rules: [
{
match-request: {
...
query-params: {
environment: [ production, test ]
}
}
...
Note: The
query-params
approach above replaces environment-specific rules for both Puppet 3 and Puppet 4. If you’re supporting agents running both Puppet 3 and Puppet 4, see Backward Compatibility with Puppet 3 Agents for more information.
method
There’s no direct equivalent to the search indirector for the deprecated method
setting. Create the equivalent rule by passing GET and POST to method
and specifying endpoint paths using the path
parameter.
Deprecated:
path ~ ^/puppet/v3/file_metadata/user_files/
method search
HOCON:
authorization: {
version: 1
rules: [
{
match-request: {
path: "^/puppet/v3/file_metadatas?/user_files/"
type: regex
method: [get, post]
}
...