Skip to content

Commit

Permalink
Backport auth.conf file to 3.8 reference
Browse files Browse the repository at this point in the history
  • Loading branch information
@nfagerlund
nfagerlund committed May 20, 2015
1 parent b6993b3 commit c01332f
Showing 1 changed file with 203 additions and 26 deletions.
229 changes: 203 additions & 26 deletions source/puppet/3.8/reference/config_file_auth.markdown
View file
Expand Up @@ -5,23 +5,27 @@ canonical: "/puppet/latest/reference/config_file_auth.html"
---

[rest_authconfig]: /references/3.8.latest/configuration.html#restauthconfig

[api]: https://github.com/puppetlabs/puppet/blob/3.8.0/api/docs/http_api_index.md
[default_file]: https://github.com/puppetlabs/puppet/blob/3.8.0/conf/auth.conf
[environment]: ./environments.html
[server_ca]: /puppetserver/1.0/configuration.html#caconf
[puppet server]: /puppetserver/1.0/

Access to Puppet's HTTPS API is configured in `auth.conf`.

## About Puppet's HTTPS API

When running in the standard agent/master arrangement, Puppet agent nodes receive all of their configurations by contacting the Puppet master over HTTPS. In general, a single configuration run includes:
(For full details about Puppet's HTTPS API, see [the API reference.][api])

The Puppet agent service requests configurations over HTTPS, and the Puppet master application provides several HTTPS endpoints to support this. (For example, requesting a catalog uses a different endpoint than submitting a report.) There are also a few endpoints that aren't used by Puppet agent.

* Fetching a node object (to read the node's environment)
* Fetching plugins
* Requesting a catalog (and submitting the node's facts as POST data in the request)
* Fetching file metadata and contents while applying the catalog
* Submitting a report after applying the catalog
Since some endpoints should have restricted access (for example, a node shouldn't request another node's configuration catalog), Puppet master has a list of access rules for all of its HTTPS services. These rules can be edited in `auth.conf`.

All of these are provided as HTTPS services (sometimes called "endpoints") by the Puppet master server. Additionally, the Puppet master provides other services, some of which are used less frequently by agent nodes (such as the CA services) and some of which shouldn't be used by agent nodes at all (such as the `certificate_status` service, which can sign and revoke certificates).
### Puppet Server Ignores CA ACLs in auth.conf

Since not all agent nodes should have access to all services, and since certain services should have restricted access (for example, nodes should not be able to request some other node's configuration catalog), the Puppet master keeps a list of access rules for all of its HTTPS services. These rules can be edited in `auth.conf`.
[Puppet Server][] uses a different implementation of the Puppet CA, and ignores auth.conf's access rules for any CA-related endpoints.

For most CA endpoints, where anyone should be able to download public certificates and submit a CSR, Puppet Server simply hardcodes open access. For the optional `certificate_status` endpoint, which allows remote control of the CA, you can [selectively enable access in ca.conf.][server_ca]

## Location

Expand All @@ -33,29 +37,202 @@ The location of the `confdir` varies; it depends on the OS, Puppet distribution,

## Example

# Example auth.conf:
# allow nodes to retrieve their own catalog
path ~ ^/catalog/([^/]+)$
method find
allow $1

# allow nodes to retrieve their own node definition
path ~ ^/node/([^/]+)$
method find
allow $1

# allow all nodes to access the certificates services
path /certificate_revocation_list/ca
method find
allow *

# allow all nodes to store their own reports
path ~ ^/report/([^/]+)$
method save
allow $1

# control access to the custom user_files mount point
path ~ ^/file_(metadata|content)s?/user_files/
auth yes
allow *.example.com
allow_ip 192.168.100.0/24

# Allow all nodes to access all file services
path /file
allow *

### Unauthenticated ACLs, for clients without valid certificates; authenticated
### clients can also access these paths, though they rarely need to.

# allow access to the CA certificate; unauthenticated nodes need this
# in order to validate the puppet master's certificate
path /certificate/ca
auth any
method find
allow *

# allow nodes to retrieve the certificate they requested earlier
path /certificate/
auth any
method find
allow *

# allow nodes to request a new certificate
path /certificate_request
auth any
method find, save
allow *

path /v2.0/environments
method find
allow *

# deny everything else; this ACL is not strictly necessary, but
# illustrates the default policy.
path /
auth true
environment override
allow magpie.example.com
auth any


## Access Control Behavior

Whenever Puppet master receives a valid HTTPS request, it checks it against its full list of authorization rules, in order. As soon as it finds a rule that matches the request, it will use that rule's `allow` and `allow_ip` permissions to decide whether to allow the request. If the request isn't allowed, Puppet will deny it, and will not check any further authorization rules.

In other words, authorization rules work like simple firewall rules. If you want to specifically allow a request that could be caught and rejected by some more general rule, you need to put the more specific rule earlier in the auth.conf file.

### Default Auth Rules

Puppet master uses two sets of auth rules: the rules from auth.conf, which it checks first, and a set of hardcoded default rules, which it only checks if a request doesn't match any rules in auth.conf.

If you are modifying auth.conf at all, **you should never rely on the hardcoded default rules.** Start with [a default auth.conf that explicitly includes copies of all of the default rules.][default_file]

There are two reasons for this:

* Visibility. It's easier to see where your custom rules should go if you can see the whole picture.
* Poor behavior in the default rules code. If an ACL in auth.conf has the same `path` value as a default rule, Puppet will magically exclude the default rule even if the additional directives in the ACL mean they match completely disjunct sets of nodes.

## File Format

path /certificate_status
auth true
environment production
allow magpie.example.com
The auth.conf file is an ordered list of access control lists (ACLs). ACLs are separated by one or more empty lines.

path /facts
The file can also include comments, which are lines starting with `#`. Comments do not count as empty lines for separating ACLs.

## ACL Syntax

[inpage_acl]: #acl-syntax

path ~ ^/report/([^/]+)$
method save
auth true
allow magpie.example.com
allow $1

An ACL is a series of adjacent lines, with one directive per line. It describes some set of requests, and says who is allowed to make those requests.

The following directives describe which requests should match the ACL:

* `path` --- Which URLs the ACL applies to. **Required.** Must be the first directive in the ACL.
* `environment` --- Which environments the ACL applies to. Optional; defaults to all environments.
* `method` --- Which HTTP methods the ACL applies to. Optional; defaults to all methods.
* `auth` --- Whether the ACL applies to client-verified or non-client-verified HTTPS requests. Optional; defaults to `yes` (verified).

The following directives control who is allowed to make requests that match the ACL:

* `allow` --- Which certificate names or hostnames can make matching requests. Optional; defaults to allowing no one.
* `allow_ip` --- Which IP addresses can make matching requests. Optional; defaults to allowing no one.

An ACL can include multiple `allow` and `allow_ip` directives.

There are also `deny` and `deny_ip` directives, but their behavior is complicated and unintuitive. Avoid them.

### `path`

Which URLs the ACL applies to. **Required.** Must be the first directive in the ACL.

**Allowed values:** This directive must describe some set of URLs in the Puppet 3.x HTTPS API. However, it _must omit the environment portion of the URL._ That is, for a real URL of `/production/report/web01.example.com`, you would use a `path` of `/report/web01.example.com`. You can handle environments with the `environment` directive; see below.

You can specify a group of URLs as a prefix, or as a regular expression.

#### URL Prefix

path /puppet/v3/report

If the value of `path` is just an absolute path, Puppet master interprets it as a prefix. The ACL will match any URL that _begins_ with that string.

#### Regular Expression

path ~ ^/report/([^/]+)$

If the value of `path` is a tilde (`~`), a space, and then a regular expression, the ACL will match any URL that matches the regular expression. Regexps in paths should NOT be delimited with slashes.

**Note:** You should almost always include at least a start anchor (`^`) in your regular expressions, to prevent them from matching URLs you didn't intend.

If a regular expression path includes capturing parentheses, you can reference the captures in `allow` directives with numbered variables like `$1`.

### `environment`

Which environments the ACL applies to.

**Allowed values:** A valid [environment][] or a comma-separated list of environments. Optional; defaults to all environments if omitted.

Most of Puppet's endpoints require an environment to be provided as the first portion of the URL. See the [HTTPS API docs][api] for details.

### `method`

Which HTTP methods the ACL applies to.

**Allowed values:** `find`, `search`, `save`, `destroy`, or a comma-separated list of those values. Optional; defaults to all methods if omitted.

This directive is kind of obfuscated, and you have to map these indirector methods to the actual HTTP methods you want to control.

Indirector | HTTP
-----------|------
find | GET and POST
search | GET and POST, for endpoints whose names end in "s" or "_search"
save | PUT
destroy | DELETE


### `auth`

Whether the ACL applies to client-verified or non-client-verified HTTPS requests.

**Allowed values:** `yes`, `any`, `no` (with `on` and `off` as synonyms). Must be a single value. Optional; defaults to `yes` (verified) if omitted.

Puppet agent makes client-verified requests to fetch configuration data and submit reports, but makes unverified requests to ask for a certificate.

If you set `auth any`, it allows nodes to access an endpoint without a valid certificate. (Setting it to `no` is not very useful, since it will _reject_ requests that have valid certificates.)


### `allow`

Which certificate names or hostnames can make requests that match the ACL. For client-verified requests, Puppet will check `allow` directives against the common name (CN) from the client's SSL certificate. For unverified requests, Puppet will use reverse DNS to figure out the client's hostname, and compare that to the `allow` directives.

**Allowed values:** One of the following (or a comma-separated list of them):

* A certificate name (for client-verified requests)
* A hostname (for unverified requests only)
* A glob of certificate names or hostnames, with an asterisk (`*`) in place of the leftmost segment of the name (e.g. `*.delivery.example.com`).
* A regular expression, delimited with slashes (`/`), matching some number of certificate names or hostnames (e.g. `/^[\w-]+.example.com$/`).
* The string `*`, which will allow _all_ requests.

Optional; if you don't specify any `allow` or `allow_ip` directives, Puppet will reject all requests matching the ACL.

If an ACL's `path` was a regular expression with capturing parentheses, its `allow` directives can reference the captured text with numbered variables like `$1`. This is useful for things like requesting catalogs, where the name of the node is included in the URL and nodes should only be able to access their own catalogs.

### `allow_ip`

Which IP addresses can make matching requests.

path /facts
auth true
method find, search
allow magpie.example.com, dashboard.example.com, finch.example.com
**Allowed values:** One of the following:

## Format
* A single IP address.
* A glob representing a group of IP addresses (e.g. `192.168.100.*`).
* CIDR notation representing a group of IP addresses (e.g. `192.168.100.0/24`).

**[See the HTTPS access control documentation for full details about the `auth.conf` file](/guides/rest_auth_conf.html).**
An `allow_ip` directive will apply to both client-verified and unverified requests.

Optional; if you don't specify any `allow` or `allow_ip` directives, Puppet will reject all requests matching the ACL.

0 comments on commit c01332f

Please sign in to comment.