TUTORIAL – RUBY API
The Conjur API for Ruby provides a robust programmatic interface to Conjur. You can use the Ruby API to authenticate with Conjur, load policies, fetch secrets, perform permission checks, and more.
- A Conjur server endpoint.
- The Conjur API for Ruby, version 5.0 or later.
To demonstrate the usage the Conjur API, we need some sample data loaded into the server.
Save this file as “conjur.yml”:
variable:db/passwordContains the database password.
layer:myappA layer (group of hosts) with access to the password and the webservice.
In addition, it ensures that the host
myapp-01 is able to access the
db/password secret and is a member of the
backend/clients group that has permission to
Load the policy using the following command:
Now, use OpenSSL to generate a random secret, and load it into the database password variable:
The Ruby API is configured using the
Conjur.configuration object. The most important options are:
appliance_urlThe URL to the Conjur server.
accountThe Conjur organization account name.
Create a new Ruby program, require the
conjur-api library, and set these two parameters in the following manner:
Once the server connection is configured, the next step is to authenticate to obtain an access token. When you create a Conjur Host, the server issues an API key which you can use to authenticate as that host. Here’s how you use it in Ruby (note: token formatted and abridged in the interests of readability):
CONJUR_AUTHN_API_KEY for the API key.
Once authenticated, the API client can be used to fetch the database password:
To check a permission, load the Conjur resource (typically a Webservice) on which the permission is defined.
Then use the
permitted? method to test whether the Conjur user has a specified privilege on the resource.
In this example, we determine that
host:myapp-01 is permitted to
execute but not
update the resource
Conjur can provide a declarative system for authenticating and authorizing access to web services. As we have seen above, the first step is to create a
!webservice object in a policy. Then, privileges on the web service can be managed using
In the runtime environment, a bit of code will intercept the inbound request and check for authentication and authorization. Here’s how to simulate that in an interactive Ruby session.
First, the web service client will authenticate with Conjur to obtain an access token. Then this token is formed into an HTTP Authorization header:
Of course, the client does not have to be Ruby, it can be any language or even a tool like cURL.
On the server side, the HTTP request is intercepted and the access token is parsed out of the header.
Once the token is obtained, it can be used to construct a
Conjur::API object. Then the
webservice resource is obtained from the Conjur API, and the permission check is performed:
If the token is expired or invalid, then the Conjur API will raise an authentication error. If the token is valid, but the client does not have the requested privilege, then
permitted? will return
false. In either case, the authorization interceptor should deny access to the web service function.
Note that different web service functions may have different required privileges. For example, a
GET method may require
read, and a
DELETE method may require
update. The semantic mapping between the web service methods and the Conjur privileges is up to you.
Now let’s run through an example of implementing the above using Sinatra.
First, let’s create a new folder for our demo project
Next, let’s create
Gemfile to manage our dependencies:
Note that we’re building the Conjur API gem from source rather than downloading it from Ruby Gems. The Conjur CE release marks a major overhaul of the API. This version will be published to Ruby Gems prior to our public release.
Now we can install all our required gems with:
Now let’s setup our Rackup file:
The above will let us pass our Conjur Account name and URL when we start the app.
Now let’s write a simple page that displays the secret stored in Conjur using the Host API token above:
The above application can be run with:
and displays the value of the secret stored in Conjur.
- Read the Ruby API code on GitHub.
- Visit the Ruby API code on RubyGems.