website/simplerpc/authorization.md

   1 ---
   2 layout: default
   3 title: SimpleRPC Authorization
   4 toc: false
   5 ---
   6 [SimpleRPCIntroduction]: index.html
   7 [SecurityWithActiveMQ]: /mcollective/reference/integration/activemq_security.html
   8 [SimpleRPCAuditing]: /mcollective/simplerpc/auditing.html
   9 [ActionPolicy]: http://projects.puppetlabs.com/projects/mcollective-plugins/wiki/AuthorizationActionPolicy
  10
  11 As part of the [SimpleRPC][SimpleRPCIntroduction] framework we've added an authorization system that you can use to exert fine grained control over who can call agents and actions.
  12
  13 Combined with [Connection Security][SecurityWithActiveMQ], [Centralized Auditing][SimpleRPCAuditing] and Crypto signed messages this rounds out a series of extremely important features for large companies that in combination allow for very precise control over your MCollective Cluster.
  14
  15 The clients will include the _uid_ of the process running the client library in the requests and the authorization function will have access to that on the requests.
  16
  17 There is a sample full featured plugin called [ActionPolicy] that you can use or get some inspiration from.
  18
  19 ## Writing Authorization Plugins
  20
  21 Writing an Authorization plugin is pretty simple, the below example will only allow RPC calls from Unix UID 500.
  22
  23 {% highlight ruby linenos %}
  24 module MCollective::Util
  25     class AuthorizeIt
  26         def self.authorize(request)
  27             if request.caller != "uid=500"
  28                 raise("Not authorized")
  29             end
  30         end
  31     end
  32 end
  33 {% endhighlight %}
  34
  35 Any exception thrown by your class will just result in the message not being processed or audited.
  36
  37 You'd install this in your libdir where you should already have a Util directory for these kinds of classes.
  38
  39 To use your authorization plugin in an agent simply do something like this:
  40
  41 {% highlight ruby linenos %}
  42 module MCollective::Agent
  43     class Service<RPC::Agent
  44         authorized_by :authorize_it
  45
  46         # ...
  47     end
  48 end
  49 {% endhighlight %}
  50
  51 The call extra _authorized`_`by :authorize`_`it_ line tells your agent to use the _MCollective::Util::AuthorizeIt_ class for authorization.
  52
  53 ## Enabling RPC authorization globally
  54 You can enable a specific plugin on all RPC agents in the server config file.  If you do this and an agent also specify it's own authorization the agent will take priority.
  55
  56 {% highlight ini %}
  57 rpcauthorization = yes
  58 rpcauthprovider = action_policy
  59 {% endhighlight %}
  60
  61 Note setting _rpcauthorization = no_ here doesn't disable it everywhere, agents that specify authorization will still be used.  This boolean enables the global auth policy not the per agent.