Choria AAA

Choria features a full suite of Authentication, Authorization and Auditing capabilities.

  • Authentication - who you are, derived from a certificate
  • Authorization - what you may do on any given node, keyed to your certificate-based identity
  • Auditing - log of what you did, showing your certificate based identity and all requests

Earlier we made a certificate called rip.mcollective which is used to establish your identity as choria=rip.mcollective which will be used throughout in the AAA system.


Choria sets up the popular Action Policy based authorization and does so in a default deny mode which means by default, no-one can make any requests.

Some plugins may elect to ship authorization rules that allow certain read only actions by default, like the mco puppet status command, but you can change or override all of this.

Site Policies

You can allow your own users only certain access, previously when configuring your first user, we did this already via Hiera:

  - action: "allow"
    callers: "choria=rip.mcollective"
    actions: "*"
    facts: "*"
    classes: "*"

You’ll note this is an array so you can have many policies, site policies are applied to all agents.

Agent specific policies

This will allow a specific certificate to only block ip addresses on my firewall but nothing else:

  - action: "allow"
    callers: "choria=typhon.mcollective"
    actions: "block"
    facts: "*"
    classes: "*"

For full details see the Action Policy docs.

Per plugin default override

As mentioned by default all actions are denied across all agents, you can change a specific agent to default allow via Hiera:

mcollective_agent_puppet::policy_default: allow

Site wide default policy

By default all actions are denied, if like in a Lab environment you want to simplify things and allow all actions across all agents, you can set this in Hiera:


Enabling this will allow anyone with a signed mcollective cert to perform any action on any node, please consider carefully before changing this setting.

mcollective::policy_default: allow


Custom certificate names

Authentication is done via the certname embedded in the certificate, certificates must be signed by the Puppet CA.

By default the only certificates that will be accepted from clients are those matching the pattern /.mcollective$/, if you have some special needs you can adjust this via Hiera:

  security.certname_whitelist: "bob, jill, /\\.mcollective$/"

And you can request custom certificate names on the CLI:

$ choria enroll --certname bob

You can then instruct the CLI to use that other cert using export MCOLLECTIVE_CERTNAME=bob.

Revoking access

Public certificates are distributed automatically but will never be removed. To remove them you have to manually arrange for the files to be deleted from all nodes, perhaps using Puppet, before a new one can be distributed. These live in /etc/puppetlabs/puppet/choria_security/public_certs.

Privileged certificates

Unless specifically requested you should never use certificates matching the pattern /.privileged.mcollective$/, this is an advanced feature that is reserved for a future REST server where Authentication is delegated to a trusted piece of software.


Auditing is configured to write to a log file /var/log/puppetlabs/mcollective-audit.log by default, you should set up rotation if desired (it’s not done by the module), its contents looks like:

[2016-12-13 08:32:34 UTC] reqid=30d706be63e555db8c073ec17a23af44: reqtime=1481617954 agent=rpcutil action=ping data={:process_results=>true}
[2016-12-13 08:32:43 UTC] reqid=e0c60ad2f58d52699e6524039decc257: reqtime=1481617963 agent=puppet action=status data={:process_results=>true}
[2016-12-13 13:15:09 UTC] reqid=1235e001c9b15414b748ab26607e1063: reqtime=1481634909 agent=puppet action=status data={:process_results=>true}
[2016-12-13 13:15:35 UTC] reqid=cf95bc7621ff55a8a197e3f2e394406e: reqtime=1481634935 agent=puppet action=status data={:process_results=>true}
[2016-12-13 13:15:43 UTC] reqid=18192c7f260c5788a33b60ce4f01771c: reqtime=1481634943 agent=puppet action=status data={:process_results=>true}

The above is the native MCollective logging format, it’s a bit old and predates things like logstash being popular. There’s a new Choria plugin that you can enable via Hiera:

  rpcauditprovider: "choria"
  plugin.rpcaudit.logfile: "/var/log/puppetlabs/choria-audit.log"

The format this will log in can be seen below, works well with ES and things like ./jq.