{"action":"created","comment":{"url":"https://api.github.com/repos/puppetlabs/puppet-server/pulls/comments/41556721","id":41556721,"diff_hunk":"@@ -0,0 +1,151 @@\n+---\n+layout: default\n+title: \"Puppet Server Configuration Files: auth.conf\"\n+canonical: \"/puppetserver/latest/config_file_auth.html\"\n+---\n+\n+[`trapperkeeper-authorization`]: https://github.com/puppetlabs/trapperkeeper-authorization\n+[new `auth.conf`]: ./conf_file_auth.html\n+[Puppet `auth.conf`]: /puppet/latest/reference/config_file_auth.html\n+[deprecated]: ./deprecated_features.html\n+[`puppetserver.conf`]: ./conf_file_puppetserver.html\n+\n+The `auth.conf` file contains rules for authorizing access to Puppet Server's HTTP API endpoints. For a broader overview of Puppet Server configuration, see the [configuration documentation](./configuration.html).\n+\n+> **Deprecation Note:** As of version 2.2, Puppet Server can use [`trapperkeeper-authorization`][] for authentication, which is configured by rules and settings in `auth.conf` using a new HOCON configuration file format, and the new `conf.d` location for Puppet Server configuration files. The legacy [Puppet `auth.conf`][] whitelist-based authorization method and configuration file format are [deprecated][] and will be removed in a future version of Puppet Server.\n+>\n+> You can enable this new method by setting the `use-legacy-auth-conf` parameter in the `jruby-puppet` section to `false`. It defaults to `true`. \n+>\n+> Puppet Server warns you that the legacy authentication method is deprecated if `use-legacy-auth-conf` is set to `true` or to its default.\n+\n+The new Puppet Server authentication configuration and functionality is fundamentally similar to the legacy method: you define rules in `auth.conf`, and Puppet Server applies the settings when a request's endpoint matches a rule. \n+\n+However, the new HOCON format provides different parameters and syntax, and the new method provides slightly different functionality. The following sections document how to configure both methods.\n+\n+## Parameters\n+\n+Use the following parameters when writing or migrating custom authorization rules.\n+\n+### `path`\n+\n+Rules with a `path` parameter only apply to endpoints with URLs that start with the parameter's value.\n+\n+In a HOCON `auth.conf` rule, distinguish between regular expressions and literal strings by explicitly stating the `type` parameter.\n+\n+~~~\n+# Regular expression to match a path in a URL.\n+path: \"^/puppet/v3/report/([^/]+)$\"\n+type: regex\n+\n+# Literal string to match at the start of a URL's path.\n+path: \"/puppet/v3/report/\"\n+type: path\n+~~~\n+\n+> **Note:** Remember to delimit the contents of the `path` with double quotes for HOCON `auth.conf` rules. While the HOCON format does not always require wrapping string values with double quotes, special characters commonly used in regular expressions (such as `*`) break HOCON parsing unless the entire value is surrounded by double quotes.\n+\n+The legacy `auth.conf` format uses the presence of a tilde (`~`) character to distinguish a regular expression `path` value from a literal string value.\n+\n+~~~\n+# Regular expression to match a path in a URL.\n+path ~ ^/puppet/v3/report/([^/]+)$\n+\n+# Literal string to match at the start of a URL's path.\n+path /puppet/v3/report/\n+~~~\n+\n+### `method`\n+\n+If a rule contains the `method` parameter, it only applies to requests that use the value's corresponding HTTP methods.\n+\n+In a HOCON `auth.conf` rule, list the HTTP methods.\n+\n+~~~\n+# Use GET and POST.\n+method: [get, post]\n+\n+# Use PUT.\n+method: put\n+~~~\n+\n+The legacy `auth.conf` format uses indirector names for the `method` value instead of the request's HTTP method:\n+\n+Indirector | HTTP","path":"documentation/config_file_auth.md","position":73,"original_position":73,"commit_id":"9827f3e0b4ec6409e0058b9eb1372ffcfb2f7f7b","original_commit_id":"9827f3e0b4ec6409e0058b9eb1372ffcfb2f7f7b","user":{"login":"camlow325","id":5652737,"avatar_url":"https://avatars.githubusercontent.com/u/5652737?v=3","gravatar_id":"","url":"https://api.github.com/users/camlow325","html_url":"https://github.com/camlow325","followers_url":"https://api.github.com/users/camlow325/followers","following_url":"https://api.github.com/users/camlow325/following{/other_user}","gists_url":"https://api.github.com/users/camlow325/gists{/gist_id}","starred_url":"https://api.github.com/users/camlow325/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/camlow325/subscriptions","organizations_url":"https://api.github.com/users/camlow325/orgs","repos_url":"https://api.github.com/users/camlow325/repos","events_url":"https://api.github.com/users/camlow325/events{/privacy}","received_events_url":"https://api.github.com/users/camlow325/received_events","type":"User","site_admin":false},"body":"Good idea putting the whole table in - thanks!","created_at":"2015-10-08T19:25:30Z","updated_at":"2015-10-08T19:25:30Z","html_url":"https://github.com/puppetlabs/puppet-server/pull/732#discussion_r41556721","pull_request_url":"https://api.github.com/repos/puppetlabs/puppet-server/pulls/732","_links":{"self":{"href":"https://api.github.com/repos/puppetlabs/puppet-server/pulls/comments/41556721"},"html":{"href":"https://github.com/puppetlabs/puppet-server/pull/732#discussion_r41556721"},"pull_request":{"href":"https://api.github.com/repos/puppetlabs/puppet-server/pulls/732"}}},"pull_request":{"url":"https://api.github.com/repos/puppetlabs/puppet-server/pulls/732","id":47194581,"html_url":"https://github.com/puppetlabs/puppet-server/pull/732","diff_url":"https://github.com/puppetlabs/puppet-server/pull/732.diff","patch_url":"https://github.com/puppetlabs/puppet-server/pull/732.patch","issue_url":"https://api.github.com/repos/puppetlabs/puppet-server/issues/732","number":732,"state":"open","locked":false,"title":"Implement tk-auth documentation changes.","user":{"login":"gguillotte","id":1296917,"avatar_url":"https://avatars.githubusercontent.com/u/1296917?v=3","gravatar_id":"","url":"https://api.github.com/users/gguillotte","html_url":"https://github.com/gguillotte","followers_url":"https://api.github.com/users/gguillotte/followers","following_url":"https://api.github.com/users/gguillotte/following{/other_user}","gists_url":"https://api.github.com/users/gguillotte/gists{/gist_id}","starred_url":"https://api.github.com/users/gguillotte/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/gguillotte/subscriptions","organizations_url":"https://api.github.com/users/gguillotte/orgs","repos_url":"https://api.github.com/users/gguillotte/repos","events_url":"https://api.github.com/users/gguillotte/events{/privacy}","received_events_url":"https://api.github.com/users/gguillotte/received_events","type":"User","site_admin":false},"body":"Revise and expand tk-auth predocs. Notable changes:\r\n\r\n- Split `configuration.markdown` into separate files.\r\n- Added deprecation notices where applicable.\r\n- Added a `deprecated_settings.md` similar to the Puppet docs to consolidate deprecation references.\r\n- Expanded explanations of `auth.conf` parameters.\r\n- Moved several links to Puppet API documentation from GitHub to the docs site.","created_at":"2015-10-08T19:20:00Z","updated_at":"2015-10-08T19:25:30Z","closed_at":null,"merged_at":null,"merge_commit_sha":"dee84a0bd8766c4467b39bc012de79fa2c3e8e6f","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/puppetlabs/puppet-server/pulls/732/commits","review_comments_url":"https://api.github.com/repos/puppetlabs/puppet-server/pulls/732/comments","review_comment_url":"https://api.github.com/repos/puppetlabs/puppet-server/pulls/comments{/number}","comments_url":"https://api.github.com/repos/puppetlabs/puppet-server/issues/732/comments","statuses_url":"https://api.github.com/repos/puppetlabs/puppet-server/statuses/9827f3e0b4ec6409e0058b9eb1372ffcfb2f7f7b","head":{"label":"gguillotte:tk-auth-docs-2","ref":"tk-auth-docs-2","sha":"9827f3e0b4ec6409e0058b9eb1372ffcfb2f7f7b","user":{"login":"gguillotte","id":1296917,"avatar_url":"https://avatars.githubusercontent.com/u/1296917?v=3","gravatar_id":"","url":"https://api.github.com/users/gguillotte","html_url":"https://github.com/gguillotte","followers_url":"https://api.github.com/users/gguillotte/followers","following_url":"https://api.github.com/users/gguillotte/following{/other_user}","gists_url":"https://api.github.com/users/gguillotte/gists{/gist_id}","starred_url":"https://api.github.com/users/gguillotte/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/gguillotte/subscriptions","organizations_url":"https://api.github.com/users/gguillotte/orgs","repos_url":"https://api.github.com/users/gguillotte/repos","events_url":"https://api.github.com/users/gguillotte/events{/privacy}","received_events_url":"https://api.github.com/users/gguillotte/received_events","type":"User","site_admin":false},"repo":{"id":43591856,"name":"puppet-server","full_name":"gguillotte/puppet-server","owner":{"login":"gguillotte","id":1296917,"avatar_url":"https://avatars.githubusercontent.com/u/1296917?v=3","gravatar_id":"","url":"https://api.github.com/users/gguillotte","html_url":"https://github.com/gguillotte","followers_url":"https://api.github.com/users/gguillotte/followers","following_url":"https://api.github.com/users/gguillotte/following{/other_user}","gists_url":"https://api.github.com/users/gguillotte/gists{/gist_id}","starred_url":"https://api.github.com/users/gguillotte/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/gguillotte/subscriptions","organizations_url":"https://api.github.com/users/gguillotte/orgs","repos_url":"https://api.github.com/users/gguillotte/repos","events_url":"https://api.github.com/users/gguillotte/events{/privacy}","received_events_url":"https://api.github.com/users/gguillotte/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/gguillotte/puppet-server","description":"Server automation framework and application","fork":true,"url":"https://api.github.com/repos/gguillotte/puppet-server","forks_url":"https://api.github.com/repos/gguillotte/puppet-server/forks","keys_url":"https://api.github.com/repos/gguillotte/puppet-server/keys{/key_id}","collaborators_url":"https://api.github.com/repos/gguillotte/puppet-server/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/gguillotte/puppet-server/teams","hooks_url":"https://api.github.com/repos/gguillotte/puppet-server/hooks","issue_events_url":"https://api.github.com/repos/gguillotte/puppet-server/issues/events{/number}","events_url":"https://api.github.com/repos/gguillotte/puppet-server/events","assignees_url":"https://api.github.com/repos/gguillotte/puppet-server/assignees{/user}","branches_url":"https://api.github.com/repos/gguillotte/puppet-server/branches{/branch}","tags_url":"https://api.github.com/repos/gguillotte/puppet-server/tags","blobs_url":"https://api.github.com/repos/gguillotte/puppet-server/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/gguillotte/puppet-server/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/gguillotte/puppet-server/git/refs{/sha}","trees_url":"https://api.github.com/repos/gguillotte/puppet-server/git/trees{/sha}","statuses_url":"https://api.github.com/repos/gguillotte/puppet-server/statuses/{sha}","languages_url":"https://api.github.com/repos/gguillotte/puppet-server/languages","stargazers_url":"https://api.github.com/repos/gguillotte/puppet-server/stargazers","contributors_url":"https://api.github.com/repos/gguillotte/puppet-server/contributors","subscribers_url":"https://api.github.com/repos/gguillotte/puppet-server/subscribers","subscription_url":"https://api.github.com/repos/gguillotte/puppet-server/subscription","commits_url":"https://api.github.com/repos/gguillotte/puppet-server/commits{/sha}","git_commits_url":"https://api.github.com/repos/gguillotte/puppet-server/git/commits{/sha}","comments_url":"https://api.github.com/repos/gguillotte/puppet-server/comments{/number}","issue_comment_url":"https://api.github.com/repos/gguillotte/puppet-server/issues/comments{/number}","contents_url":"https://api.github.com/repos/gguillotte/puppet-server/contents/{+path}","compare_url":"https://api.github.com/repos/gguillotte/puppet-server/compare/{base}...{head}","merges_url":"https://api.github.com/repos/gguillotte/puppet-server/merges","archive_url":"https://api.github.com/repos/gguillotte/puppet-server/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/gguillotte/puppet-server/downloads","issues_url":"https://api.github.com/repos/gguillotte/puppet-server/issues{/number}","pulls_url":"https://api.github.com/repos/gguillotte/puppet-server/pulls{/number}","milestones_url":"https://api.github.com/repos/gguillotte/puppet-server/milestones{/number}","notifications_url":"https://api.github.com/repos/gguillotte/puppet-server/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/gguillotte/puppet-server/labels{/name}","releases_url":"https://api.github.com/repos/gguillotte/puppet-server/releases{/id}","created_at":"2015-10-03T07:47:11Z","updated_at":"2015-10-03T07:47:13Z","pushed_at":"2015-10-08T19:19:10Z","git_url":"git://github.com/gguillotte/puppet-server.git","ssh_url":"git@github.com:gguillotte/puppet-server.git","clone_url":"https://github.com/gguillotte/puppet-server.git","svn_url":"https://github.com/gguillotte/puppet-server","homepage":"https://tickets.puppetlabs.com/browse/SERVER","size":2721,"stargazers_count":0,"watchers_count":0,"language":"Clojure","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"puppetlabs:master","ref":"master","sha":"c9518053fb0888cf1edae1d53ac5def46236eba2","user":{"login":"puppetlabs","id":234268,"avatar_url":"https://avatars.githubusercontent.com/u/234268?v=3","gravatar_id":"","url":"https://api.github.com/users/puppetlabs","html_url":"https://github.com/puppetlabs","followers_url":"https://api.github.com/users/puppetlabs/followers","following_url":"https://api.github.com/users/puppetlabs/following{/other_user}","gists_url":"https://api.github.com/users/puppetlabs/gists{/gist_id}","starred_url":"https://api.github.com/users/puppetlabs/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/puppetlabs/subscriptions","organizations_url":"https://api.github.com/users/puppetlabs/orgs","repos_url":"https://api.github.com/users/puppetlabs/repos","events_url":"https://api.github.com/users/puppetlabs/events{/privacy}","received_events_url":"https://api.github.com/users/puppetlabs/received_events","type":"Organization","site_admin":false},"repo":{"id":19546488,"name":"puppet-server","full_name":"puppetlabs/puppet-server","owner":{"login":"puppetlabs","id":234268,"avatar_url":"https://avatars.githubusercontent.com/u/234268?v=3","gravatar_id":"","url":"https://api.github.com/users/puppetlabs","html_url":"https://github.com/puppetlabs","followers_url":"https://api.github.com/users/puppetlabs/followers","following_url":"https://api.github.com/users/puppetlabs/following{/other_user}","gists_url":"https://api.github.com/users/puppetlabs/gists{/gist_id}","starred_url":"https://api.github.com/users/puppetlabs/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/puppetlabs/subscriptions","organizations_url":"https://api.github.com/users/puppetlabs/orgs","repos_url":"https://api.github.com/users/puppetlabs/repos","events_url":"https://api.github.com/users/puppetlabs/events{/privacy}","received_events_url":"https://api.github.com/users/puppetlabs/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/puppetlabs/puppet-server","description":"Server automation framework and application","fork":false,"url":"https://api.github.com/repos/puppetlabs/puppet-server","forks_url":"https://api.github.com/repos/puppetlabs/puppet-server/forks","keys_url":"https://api.github.com/repos/puppetlabs/puppet-server/keys{/key_id}","collaborators_url":"https://api.github.com/repos/puppetlabs/puppet-server/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/puppetlabs/puppet-server/teams","hooks_url":"https://api.github.com/repos/puppetlabs/puppet-server/hooks","issue_events_url":"https://api.github.com/repos/puppetlabs/puppet-server/issues/events{/number}","events_url":"https://api.github.com/repos/puppetlabs/puppet-server/events","assignees_url":"https://api.github.com/repos/puppetlabs/puppet-server/assignees{/user}","branches_url":"https://api.github.com/repos/puppetlabs/puppet-server/branches{/branch}","tags_url":"https://api.github.com/repos/puppetlabs/puppet-server/tags","blobs_url":"https://api.github.com/repos/puppetlabs/puppet-server/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/puppetlabs/puppet-server/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/puppetlabs/puppet-server/git/refs{/sha}","trees_url":"https://api.github.com/repos/puppetlabs/puppet-server/git/trees{/sha}","statuses_url":"https://api.github.com/repos/puppetlabs/puppet-server/statuses/{sha}","languages_url":"https://api.github.com/repos/puppetlabs/puppet-server/languages","stargazers_url":"https://api.github.com/repos/puppetlabs/puppet-server/stargazers","contributors_url":"https://api.github.com/repos/puppetlabs/puppet-server/contributors","subscribers_url":"https://api.github.com/repos/puppetlabs/puppet-server/subscribers","subscription_url":"https://api.github.com/repos/puppetlabs/puppet-server/subscription","commits_url":"https://api.github.com/repos/puppetlabs/puppet-server/commits{/sha}","git_commits_url":"https://api.github.com/repos/puppetlabs/puppet-server/git/commits{/sha}","comments_url":"https://api.github.com/repos/puppetlabs/puppet-server/comments{/number}","issue_comment_url":"https://api.github.com/repos/puppetlabs/puppet-server/issues/comments{/number}","contents_url":"https://api.github.com/repos/puppetlabs/puppet-server/contents/{+path}","compare_url":"https://api.github.com/repos/puppetlabs/puppet-server/compare/{base}...{head}","merges_url":"https://api.github.com/repos/puppetlabs/puppet-server/merges","archive_url":"https://api.github.com/repos/puppetlabs/puppet-server/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/puppetlabs/puppet-server/downloads","issues_url":"https://api.github.com/repos/puppetlabs/puppet-server/issues{/number}","pulls_url":"https://api.github.com/repos/puppetlabs/puppet-server/pulls{/number}","milestones_url":"https://api.github.com/repos/puppetlabs/puppet-server/milestones{/number}","notifications_url":"https://api.github.com/repos/puppetlabs/puppet-server/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/puppetlabs/puppet-server/labels{/name}","releases_url":"https://api.github.com/repos/puppetlabs/puppet-server/releases{/id}","created_at":"2014-05-07T19:00:24Z","updated_at":"2015-10-02T06:03:46Z","pushed_at":"2015-10-08T19:20:01Z","git_url":"git://github.com/puppetlabs/puppet-server.git","ssh_url":"git@github.com:puppetlabs/puppet-server.git","clone_url":"https://github.com/puppetlabs/puppet-server.git","svn_url":"https://github.com/puppetlabs/puppet-server","homepage":"https://tickets.puppetlabs.com/browse/SERVER","size":9009,"stargazers_count":119,"watchers_count":119,"language":"Clojure","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":68,"mirror_url":null,"open_issues_count":3,"forks":68,"open_issues":3,"watchers":119,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/puppetlabs/puppet-server/pulls/732"},"html":{"href":"https://github.com/puppetlabs/puppet-server/pull/732"},"issue":{"href":"https://api.github.com/repos/puppetlabs/puppet-server/issues/732"},"comments":{"href":"https://api.github.com/repos/puppetlabs/puppet-server/issues/732/comments"},"review_comments":{"href":"https://api.github.com/repos/puppetlabs/puppet-server/pulls/732/comments"},"review_comment":{"href":"https://api.github.com/repos/puppetlabs/puppet-server/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/puppetlabs/puppet-server/pulls/732/commits"},"statuses":{"href":"https://api.github.com/repos/puppetlabs/puppet-server/statuses/9827f3e0b4ec6409e0058b9eb1372ffcfb2f7f7b"}}}}