ben/mcollective-actionpolicy-auth
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update the README with more complete policy format documentation

Browse Source 
This rolls in changes from the wiki.
This commit is contained in:
Nick Fagerlund
2013-06-23 16:29:29 -07:00
committed by R.I.Pienaar
parent 2248e5bcd9
commit 1458469122
1 changed files with 62 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files

108
README.md
View File

@@ -1,74 +1,104 @@
Action Policy Authorization Plugin Action Policy Authorization Plugin
============================= =============================
This is a plugin that provides fine grained action level authorization for agents. This 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.
Installation Installation
============================= ============
* Follow the [basic plugin install guide](http://projects.puppetlabs.com/projects/mcollective-plugins/wiki/InstalingPlugins) by placing actionpolicy.rb * [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.
and actionpolicy.ddl in the util directory.
Note that it is not currently possible to use the 'mco plugin package' command to package this plugin. Note that it is not currently possible to use the 'mco plugin package' command to package this plugin.
Configuration Configuration
============================= =============
There are three configuration options for the actionpolicy plugin There are three settings available for the actionpolicy plugin:
* allow_unconfigured - allow requests to agents that do not have policy files configured * `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`.
* enable_default - enables a default policy file * `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`.
* default_name - the name of the default policy file * `default_name` -- the name of the default policy file, if `enable_default` is set to `1` or `y`.
General authentication configuration options can also be set in the config file. General authentication configuration options can be set in the server config file.
# Enables system wide rpc authorization # Enables system wide rpc authorization
rpcauthorization = 1 rpcauthorization = 1
# Sets the authorization provider to use the actionpolicy plugin # Sets the authorization provider to use the actionpolicy plugin
rpcauthprovider = action_policy rpcauthprovider = action_policy
# Allow requests to agents without policies
plugin.actionpolicy.allow_unconfigured = 1
Enabling a default policy ## Default Policy Files
You can optionally have a default policy file that applies in the absence of an agent-specific policy file.
plugin.actionpolicy.enable_default = 1 plugin.actionpolicy.enable_default = 1
plugin.actionpolicy.default_name = default plugin.actionpolicy.default_name = default
This allows you to create a policy file called default.policy which will be used unless a specific policy file exists. Note that if both This allows you to create a policy file called default.policy which will be used unless a specific policy file exists. Note that if both
allow_unconfigured and enable_default are configured all requests will go through the default policy, as enable_default takes precedence `allow_unconfigured` and `enable_default` are configured, all requests will go through the default policy, as `enable_default` takes precedence
over allow_unconfigured. over `allow_unconfigured`.
Usage Usage
============================= =====
Policies are defined in files like <configdir>/policies/<agent>.policy Policies are defined in files like `<configdir>/policies/<agent>.policy`
Example: Puppet agent policy file Example: Puppet agent policy file
# /etc/mcollective/policies/puppet.policy
policy default deny policy default deny
allow uid=500 * * * allow cert=admin * * *
allow uid=600 * customer=acme acme::devserver allow cert=acme-devs * customer=acme acme::devserver
allow uid=600 enable disable status customer=acme * allow cert=acme-devs enable disable status customer=acme *
allow uid=700 restart (puppet().enabled=false and environment=production) or environment=development
# /etc/mcollective/policies/service.policy
policy default deny
allow cert=puppet-admins restart (puppet().enabled=false and environment=production) or environment=development
The above policy can be described as: The above policy can be described as:
* allow unix user id 500 to do all actions on all servers. * Allow the `admin` user to invoke all Puppet actions on all servers.
* allow unix user id 600 to do all actions on machines with the fact customer=acme and the config class acme::devserver * Allow the `acme-devs` user to invoke _all_ Puppet actions on machines with the fact _customer=acme_ and the config class _acme::devserver_
* allow unix user id 600 to do enable, disable and status on all other machines with fact customer=acme * Allow the `acme-devs` user to invoke the _enable, disable and status_ actions on all other machines with fact _customer=acme_
* allow unix user id 700 to restart services at any time in development but in production only when Puppet has been disabled * Allow the `puppet-admins` user to restart services at any time in development but in production only when Puppet has been disabled
* Everything else gets denied * All other commands get denied
The format of the userid will depend on your security plugin, other plugins might have a certificate name as caller it. Policy File Format
-----
Like with actions you can space separate facts and config classes too which means all facts of classes listed has to be present on the system. Policy files must have the following format:
The last line in the example uses the compound statement language to do matching on facts and classes and allows any data plugin to be used. * Any lines starting with `#` are comments.
This requires at least MCollective 2.2.x. When using data plugins in action policies you should avoid using slow ones as this will impact * 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.
the response times of agents and impact the client waiting time etc. * 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:
1. `allow` or `deny`
2. Caller ID --- must be either `*` (always matches) or **one** caller ID string (see below)
3. Actions --- must be either `*` (always matches) or a space-separated list of actions
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]
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]
Using it in a specific Agent ### Notes
=============================
You can now activate it in your agents: * 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.
* Policy lines **must** use hard tabs; editor features that convert tabs to spaces (like Vim's `expandtab`) will result in non-functional policy lines.
* 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.
[compound]: http://docs.puppetlabs.com/mcollective/reference/basic/basic_cli_usage.html#complex-compound-or-select-queries
### Caller ID
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.
* 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.
* 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.
Hardcoding ActionPolicy Into a Specific Agent
============================
Instead of using the site-wide authorization settings (as described above), you can also hardcode authorization plugins in your agents:
module MCollective::Agent module MCollective::Agent
class Service<RPC::Agent class Service<RPC::Agent
@@ -77,17 +107,3 @@ You can now activate it in your agents:
# ... # ...
end end
end end
System wide configuration
=============================
You can apply this policy to all agents – but ones that specify specific policies as above will use that:
# authorization
rpcauthorization = 1
rpcauthprovider = action_policy
plugin.actionpolicy.allow_unconfigured = 1
This enables system wide authorization, tells it to use the action_policy plugin and tells it to allow agents without a policy to be used.
If you had set allow_unconfigured to 0 all requests to agents without policy files will be denied. This is configured in your server.cfg file.