Skip to content
Ruby client for the CyberArk Conjur API
Branch: master
Clone or download
alexkalish and jtuttle Provide improved inspect method
Added a custom inspect method to the BaseObject class that simply prints
the class name and the id, instead of the less readability version from
Object.  As this is a superclass, all subclasses will now inherit this
version of the inspect method.
Latest commit 5c60788 May 17, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin Added a script to automate release Sep 24, 2018
ci Add support for Conjur server version v4.x via "version" option (#129) Dec 14, 2017
dev Resolves failing Cucumber tests and adds a development environment (#138 Jun 5, 2018
example Add support for Conjur server version v4.x via "version" option (#129) Dec 14, 2017
features Updating tests to expected order results. Jun 12, 2018
features_v4 Add authn-local support to the API (#131) Dec 18, 2017
lib Provide improved inspect method May 17, 2019
spec Provide improved inspect method May 17, 2019
tmp Add support for Conjur server version v4.x via "version" option (#129) Dec 14, 2017
.codeclimate.yml Require fully qualified ids (#144) Sep 13, 2018
.dockerignore CE merge (#118) Aug 17, 2017
.gitignore Add authn-local support to the API (#131) Dec 18, 2017
.project added eclipse project file and .rvmrc Dec 27, 2012
.rubocop.yml Require fully qualified ids (#144) Sep 13, 2018
.rubocop_todo.yml Require fully qualified ids (#144) Sep 13, 2018
.yardopts add some yard options Mar 19, 2015
Dockerfile Add support for Conjur server version v4.x via "version" option (#129) Dec 14, 2017
Gemfile CE merge (#118) Aug 17, 2017
Jenkinsfile Add daily build trigger Mar 19, 2019 Changes license to Apache 2.0 per CyberArk's new license policy (#113) Aug 14, 2017 Small updates to docs Sep 24, 2018
Rakefile Add support for Conjur server version v4.x via "version" option (#129) Dec 14, 2017
conjur-api.gemspec Fix broken master build (#122) Sep 29, 2017
docker-compose.yml Add authn-local support to the API (#131) Dec 18, 2017 Leverage `publish-rubygems` image to build and publish gem (#120) Sep 19, 2017 Utils: Do not force pull in (#146) Aug 31, 2018


Programmatic Ruby access to the Conjur API.

RDocs are available from the through the Ruby Gem details page

Server Versions

The Conjur server comes in two major versions:

You can use the master branch of this project, which is conjur-api version 5.x, to do all of the following things against either type of Conjur server:

  • Authenticate
  • Fetch secrets
  • Check permissions
  • List roles, resources, members, memberships and permitted roles.
  • Create hosts using host factory
  • Rotate API keys

Use the configuration setting Conjur.configuration.version to select your server version, or set the environment variable CONJUR_VERSION. In either case, the valid values are 4 and 5; the default is 5.

If you are using Conjur server version 4.x, you can also choose to use the conjur-api version 4.x. In this case, the Configuration.version setting is not required (actually, it doesn't exist).


Add this line to your application's Gemfile:

gem 'conjur-api'

And then execute:

$ bundle

Or install it yourself as:

$ gem install conjur-api


Connecting to Conjur is a two-step process:

  • Configuration Instruct the API where to find the Conjur endpoint and how to secure the connection.
  • Authentication Provide the API with credentials that it can use to authenticate.


The simplest way to configure the Conjur API is to use the configuration file stored on the machine. If you have configured the machine with conjur init, its default location is ~/.conjurrc.

The Conjur configuration process also checks /etc/conjur.conf for global settings. This is typically used in server environments.

For custom scenarios, the location of the file can be overridden using the CONJURRC environment variable.

You can load the Conjur configuration file using the following Ruby code:

require 'conjur/cli'

Note this code requires the conjur-cli gem, which should also be in your gemset or bundle.


Once Conjur is configured, the connection can be established like this:

conjur = Conjur::Authn.connect nil, noask: true

To authenticate, the API client must provide a login name and api_key. The Conjur::Authn.connect will attempt the following, in order:

  1. Look for login in environment variable CONJUR_AUTHN_LOGIN, and api_key in CONJUR_AUTHN_API_KEY
  2. Look for credentials on disk. The default credentials file is ~/.netrc. The location of the credentials file can be overridden using the configuration file netrc_path option.
  3. Prompt for credentials. This can be disabled using the option noask: true.

Connecting Without Files

It's possible to configure and authenticate the Conjur connection without using any files, and without requiring the conjur-cli gem.

To accomplish this, apply the configuration settings directly to the Conjur::Configuration object.

For example, specify the account and appliance_url (both of which are required) like this:

Conjur.configuration.account = 'my-account'
Conjur.configuration.appliance_url = ''

You can also specify these values using environment variables, which is often a bit more convenient. Environment variables are mapped to configuration variables by prepending CONJUR_ to the all-caps name of the configuration variable. For example, appliance_url is CONJUR_APPLIANCE_URL, account is CONJUR_ACCOUNT.

In either case, you will also need to configure certificate trust. For example:

OpenSSL::SSL::SSLContext::DEFAULT_CERT_STORE.add_file "/etc/conjur-yourorg.pem"

Once Conjur is configured, you can create a new API client by providing a login and api_key:

Conjur::API.new_from_key login, api_key

Note that if you are connecting as a Host, the login should be prefixed with host/. For example: host/, not just

Development (V5)

To develop and run tests against Conjur V5, use the start and stop scripts in the dev folder. The start script brings up an open source Conjur (and Postgres database), CLI container, and a "work" container, with the gem code mounted into the working directory.

Starting a Shell

To begin:

$ cd dev
$ ./start

You'll be dropped into development container upon completion. From there, install the development gems:

root@9df0ac10ada2:/src/conjur-api# bundle

Running Tests

NOTE: There are some existing challenges around running tests from the development console. For now, run tests by using the ./ script utilized for Jenkins Pipelines.

Stopping & Environment Cleanup

Once you're done, exit the shell, and stop the containers:

root@9df0ac10ada2:/src/conjur-api# exit
$ ./stop

Development (V4)

The file docker-compose.yml is a self-contained development environment for the project.


To bring it up, run:

$ docker-compose build
$ docker-compose up -d pg conjur_4 conjur_5

Then configure the v4 and v5 servers:

$ ./ci/
$ ./ci/


Obtain the API key for the v5 admin user:

$ docker-compose exec conjur_5 rake 'role:retrieve-key[cucumber:user:admin]'

The password of the v4 admin user is "secret".

Now you can run the client dev container:

$ docker-compose run --rm dev

This gives you a shell session with conjur_4 and conjur_5 available as linked containers.


For a v5 demo, run:

$ bundle exec ./example/demo_v5.rb <admin-api-key>

For a v4 demo, run:

$ bundle exec ./example/demo_v4.rb


To bring it down, run:

$ docker-compose down


Releasing a new version of this Gem involves a two step process:

  1. Tag and Release (using bin/release)
  2. Approving the push to RubyGems in Jenkins

Step 1: Tag and Release

First, update the following files:

  • The version file (lib/conjur-api/version.rb) has been updated with an appropriate Semantic version number.
  • The file has been updated to reflect the release version and appropriate release notes.

Next, save -- but do not commit -- the changes above.

Finally, when you're ready to release, run the following:

$ bin/release

Step 2: Approve the push to RubyGems in Jenkins

The release is now complete.


  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Added some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request


Copyright 2016-2017 CyberArk

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this software except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

You can’t perform that action at this time.