1Action Policy Authorization Plugin 2============================= 3 4This is a plugin that provides fine grained action level authorization for agents. Any MCollective agent plugins based on SimpleRPC can be restricted with authorization plugins like this one. 5 6Installation 7============ 8 9* [Follow the plugin deployment guide](http://docs.puppetlabs.com/mcollective/deploy/plugins.html#method-2-copying-plugins-into-the-libdir), using the libdir copy method and placing the `actionpolicy.rb` and `actionpolicy.ddl` files in the `util` directory. 10 11Note that it is not currently possible to use the 'mco plugin package' command to package this plugin. 12 13Configuration 14============= 15 16There are three settings available for the actionpolicy plugin: 17 18* `allow_unconfigured` -- whether to allow requests to agents that do not have policy files configured. Boolean, with allowed values of `0`, `1`, `y`, `n`; values of `true` or `false` are not allowed. Defaults to `0`. 19* `enable_default` -- whether to use a default policy file. Boolean, with allowed values of `0`, `1`, `y`, `n`; values of `true` or `false` are not allowed. Defaults to `0`. 20* `default_name` -- the name of the default policy file, if `enable_default` is set to `1` or `y`. 21 22General authentication configuration options can be set in the server config file. 23 24 # Enables system wide rpc authorization 25 rpcauthorization = 1 26 # Sets the authorization provider to use the actionpolicy plugin 27 rpcauthprovider = action_policy 28 # Allow requests to agents without policies 29 plugin.actionpolicy.allow_unconfigured = 1 30 31## Default Policy Files 32 33You can optionally have a default policy file that applies in the absence of an agent-specific policy file. 34 35 plugin.actionpolicy.enable_default = 1 36 plugin.actionpolicy.default_name = default 37 38This allows you to create a policy file called default.policy which will be used unless a specific policy file exists. Note that if both 39`allow_unconfigured` and `enable_default` are configured, all requests will go through the default policy, as `enable_default` takes precedence 40over `allow_unconfigured`. 41 42Usage 43===== 44 45Policies are defined in files like `<configdir>/policies/<agent>.policy` 46 47Example: Puppet agent policy file 48 49 # /etc/mcollective/policies/puppet.policy 50 policy default deny 51 allow cert=admin * * * 52 allow cert=acme-devs * customer=acme acme::devserver 53 allow cert=acme-devs enable disable status customer=acme * 54 55 # /etc/mcollective/policies/service.policy 56 policy default deny 57 allow cert=puppet-admins restart (puppet().enabled=false and environment=production) or environment=development 58 59The above policy can be described as: 60 61* Allow the `admin` user to invoke all Puppet actions on all servers. 62* Allow the `acme-devs` user to invoke _all_ Puppet actions on machines with the fact _customer=acme_ and the config class _acme::devserver_ 63* Allow the `acme-devs` user to invoke the _enable, disable and status_ actions on all other machines with fact _customer=acme_ 64* Allow the `puppet-admins` user to restart services at any time in development but in production only when Puppet has been disabled 65* All other commands get denied 66 67Policy File Format 68----- 69 70Policy files must have the following format: 71 72* Any lines starting with `#` are comments. 73* A single `policy default deny` or `policy default allow` line is permitted; it can go anywhere in the file. This default policy will apply to any commands that don't match a specific rule. If you don't specify a default policy, the value of the `plugin.actionpolicy.allow_unconfigured` setting will be used as the default. 74* Any number of _policy lines_ are permitted. These must be **tab delimited** lines with either four or five fields (the final field is optional) in the following order: 75 1. `allow` or `deny` 76 2. Caller ID --- must be either `*` (always matches) or a space-separated list of caller ID strings (see below) 77 3. Actions --- must be either `*` (always matches) or a space-separated list of actions 78 4. Facts --- may be either `*` (always matches), a space-separated list of `fact=value` pairs (matches if _every_ listed fact matches), or any valid [compound filter string][compound] 79 5. Classes --- may be completely absent (always matches), `*` (always matches), a space-separated list of class names (matches if _every_ listed class is present), or any valid [compound filter string][compound] 80 81### Notes 82 83* Like firewall rules, policy lines are processed **in order** --- ActionPolicy will allow or deny each request using the _first_ rule that matches it. A policy line matches a request if **every** field after the allow/deny field matches. 84* Policy lines **must** use hard tabs; editor features that convert tabs to spaces (like Vim's `expandtab`) will result in non-functional policy lines. 85* Compound filter strings may match on facts, classes, and data plugins (MCollective 2.2.x or later). When using data plugins in action policies, you should avoid using slow ones, as this will impact the response times of agents, the client waiting time, etc. 86 87[compound]: http://docs.puppetlabs.com/mcollective/reference/basic/basic_cli_usage.html#complex-compound-or-select-queries 88 89 90### Caller ID 91 92In the case of a single user the Caller ID strings are always of the form `<kind>=<value>`, but both the kind and the value of the ID will depend on your security plugin. See your security plugin's documentation or code for details. Multiple Caller IDs separated by spaces are supported to allow grouping similar callers together. 93 94You can also define named groups of callers like `sysadmin`, see the Groups section below. 95 96* The recommended SSL security plugin sets caller IDs of `cert=<NAME>`, where `<NAME>` is the filename of the client's public key file (minus the `.pem` extension). So a request validated with the `puppet-admins.pem` public key file would be given a caller ID of `cert=puppet-admins`. This kind of caller ID is cryptographically authenticated. 97* The PSK security plugin defaults to caller IDs of `uid=<UID>`, where `<UID>` is the local UID of the client process. [There are several other options available](https://github.com/puppetlabs/marionette-collective/blob/master/plugins/mcollective/security/psk.rb#L79), which can be configured with the `plugin.psk.callertype` setting. **None of PSK's caller IDs are authenticated,** and you should generally not be relying on authorization at all if you are using the PSK security plugin. 98 99 100### Groups 101 102You can create a file called `<configdir>/policies/groups` with content as here: 103 104 # sample groups file 105 sysadmins cert=sa1 cert=sa2 106 107Fields are space separated, group names should match `^([\w\.\-]+)$` 108 109Here we create a `sysadmins` group that has 2 Caller IDs in it, the same rules as above for Caller IDs apply here. Only Caller IDs can be references not other groups. 110 111This group can then be used where you would normal put a Caller ID: 112 113 allow sysadmins * customer=acme acme::devserver 114 115You can list multiple groups in space separated lists. You cannot mix certnames and group names in the same policy line. 116 117Hardcoding ActionPolicy Into a Specific Agent 118============================ 119 120Instead of using the site-wide authorization settings (as described above), you can also hardcode authorization plugins in your agents: 121 122 module MCollective::Agent 123 class Service<RPC::Agent 124 authorized_by :action_policy 125 126 # ... 127 end 128 end 129