Extending Conjur with Plugins
May 11, 2015 | DevOps | Dustin Collins
Conjur comes with a great set of features out of the box. But what if you need to add new functionality or change how Conjur does something to better fit your needs? You can do this with Conjur plugins. In this post I’ll cover when you may want to use Conjur plugins is, how they work , and show you how you can get started with your own plugins.
When would I use a plugin?
Here are a few use cases where a plugin can be helpful.
1. You want to administer a service that uses or modifies Conjur resources. For example, the aws plugin allows you to create an AWS IAM role with permission to read a Conjur host factory token stored in S3.
2. You want to abstract a common pattern into a higher-level workflow. Let’s say you have a data analytics team in your organization that uses several third party services and needs to store their credentials in Conjur. You want them to store the credentials in a uniform way: in a specific format with the correct roles granted access. You can write a plugin for your analytics team that prompts them for the service, username and password. The plugin would create the variable and grant the correct permissions to your groups and layers.
3. You want to augment an existing Conjur command. The audit-send plugin is an example of this pattern. It adds a
send subcommand to the
audit command that allows you to send custom audit events to Conjur.
4. You want to modify an existing Conjur command. For example, you can enforce a namespacing scheme for variables in your organization by modifying
conjur variable create command to suggest and enforce a namespace like
How do plugins work?
Conjur CLI plugins are implemented as Ruby gems. They use the naming scheme
conjur-asset-<plugin-name>. When you install a plugin, the gem is installed into the CLI package’s embedded Ruby and a marker is placed in your conjurrc file. Any commands the plugin defines are then available the next time you run the CLI.
Here is an example – we will install the proxy plugin. It allows you to simply add Conjur authentication headers on outbound requests.
After installation, the proxy plugin is available to use the same way you’d use other Conjur commands. You can read more about how to use proxy here.
How do I write a Conjur plugin?
Conjur plugins use the GLI library for command-line parsing. To write your own plugin, you inherit from the
Conjur::Command class. This gives you access to the
api object, a client you can use to make calls to Conjur. The client is authenticated as the user/host that is logged into the CLI.
Here is a simple example, an application of the first use case above, with Jenkins:
Now you can launch builds in Jenkins, if your user has access to the
jenkins/api-key variable. Access to the API key is managed and audited with Conjur.
We have released several plugins already that you can use as examples to work from. Here are the ones we use most often internally.
Let us know what great plugins you create or use!