Try Conjur

Conjur helps you build reliable software that’s hard to hack. It provides data encryption, identity management for humans and machines, and role-based access control for sensitive resources like passwords, SSH keys, and web services. With Conjur you can easily manage the lifecycle and access to every secret in your infrastructure.

Create an account on our hosted server to learn core Conjur workflows like storing secrets in the Conjur vault, apply a security policy to authorize access, and fetch them using a machine identity.

Create an Account to Evaluate Conjur

Get a free, temporary Conjur account to use on our evaluation server.

Email Already Exists

If you have forgotten your API key, you can reset it to get a new one. Would you like to reset your API key?

Preparation

This tutorial uses the Conjur command-line interface, but you don’t need to be an expert. All the commands you need to run, and files you need to create, are spelled out in explicit detail. You may want to download all of the tutorial files in advance.

Here are the developer tools you’ll need:

  1. A terminal application. Hyper is a nice one.
  2. Docker CE. It’s available for Mac, Windows, and GNU/Linux: scroll down and select the package for your operating system.
  3. The jq JSON processor. Download from its website.

Get Started

Create a project folder and set it as your terminal’s current directory:

$ mkdir conjur-eval
$ cd conjur-eval

Then download docker-compose.yml and put it in the folder.

docker-compose.yml

version: '2'
services:
  conjur:
    image: cyberark/conjur-cli:5
    working_dir: /root
    volumes:
      - ./:/root

To connect to your account, use the email you provided and the API key you created:

First, enter your account:

$ account="your.email@yourcompany.com"

Initialize the client

$ docker-compose run conjur init -u https://eval.conjur.org -a ${account}
$ docker-compose run conjur authn login -u admin

When prompted, type (or paste) your API key. (Optional Tip: save yourself typing with an alias.)

$ alias conjur="docker-compose run conjur"

Vault Secret

When a Conjur account is created, it’s a blank slate: all secrets, users, machines, and other objects in Conjur are part of a security policy. Let’s load a policy containing a variable container in the vault, then store a secret in there.

Loading a policy

This policy creates a single variable called eval/secret. Download one-variable.yml and put it in your folder.

one-variable.yml

- !policy
  id: eval
  body:
    - !variable secret

According to this policy, only the Conjur admin should be able to update the value of our secret.

Here’s how to load a policy into Conjur:

$ docker-compose run conjur policy load root one-variable.yml

The command policy load root means that we’re loading this policy at the root level of the account, like the root of a tree. For more complicated workloads, you can create nested policies, but we won’t use that feature yet.

For more about Conjur’s policy format and the philosophy behind it, visit Reference - Policies.

Vault a secret

Now let’s vault a secret into the variable. Vaulted secrets are automatically secured by encrypting them at rest and in transit. See also: Reference - Cryptography.

Usually your secret will be something like an API key. Let’s create our own fake faux-API key: the command openssl rand creates a random string.

Add a value to a secret

$ secret=$(docker-compose run --entrypoint openssl conjur rand -hex 12 | tr -d '\r\n')
$ docker-compose run conjur variable values add eval/secret ${secret}

Fetch the secret again (as admin)

Having vaulted our secret, let’s fetch it back out again as an admin:

$ docker-compose run conjur variable value eval/secret

Machine Identity

You should never let your production machines log in as admin. It’s too much responsibility, and there’s no need. With Conjur you can easily create a machine identity to represent your code and let it authenticate to fetch secrets.

Create a machine identity

Like before, we need a policy that defines a role for our machine. Unlike before, we’re going to define a relationship between a role (the machine) and a resource (the variable). Download variable-and-host.yml and put it in your folder.

variable-and-host.yml

- !policy
  id: eval
  body:
    # The objects:
    - !variable secret
    - !host machine

    # The relationship between the objects:
    - !permit
      role: !host machine
      privileges: [read, execute]
      resource: !variable secret

Now let’s load the variable+host policy

$ docker-compose run -T conjur policy load root variable-and-host.yml | tee roles.json

Note: the -T argument is needed to prevent the “Loaded policy” message from getting folded into our JSON output.

Authenticate using a machine identity (instead of admin)

When you loaded that policy, you got a response with an ID and API key. This is the data a machine needs to prove its identity. It’s now saved as roles.json.

Retrieve the host’s API key

$ api_key=$(jq -r '.created_roles | .[].api_key' roles.json | tr -d '\r\n')

Or you can just type api_key= and copy-paste the “api-key” data from the response. But smooth bash one-liners make you a code witch. You know.

What if I don't get any created_roles?

If you load the `variable-and-host.yml` policy a second time, you'll get a response like this:

  {
    "created_roles": {},
    "version": 2
  }
  

This is because policy loads are idempotent in Conjur. You can load the same policy multiple times and it won't change the state of the system.

If you're going through this flow a second time and want to get the host's API key, you can rotate it like so:

  $ api_key=$(docker-compose run conjur host rotate_api_key -h eval/machine | tr -d '\r\n')
  

Now that you have the host’s API key, you can assume its identity:

Login as host

$ docker-compose run conjur authn login -u host/eval/machine -p ${api_key}

Now you’re acting as the host.

Retrieve a secret using a machine identity

The policy gives this host permission to “read and execute” the variable. In Conjur permission terms, “read” lets you see the variable and its metadata, while “execute” lets you actually fetch the value.

Fetch a secret just like before

$ docker-compose run conjur variable value eval/secret

So far so good; and when we try to change the secret’s value, we get an error response because the machine is not authorized by the policy to do so:

Attempt to modify the secret

$ secret=$(docker-compose run --entrypoint openssl conjur rand -hex 12 | tr -d '\r\n')
$ conjur variable values add eval/secret ${secret}

Instead of a “Value added” message, you’ll get error: 403 Forbidden. This means that the security policy is working as intended: only the admin can change eval/secret, but the eval/machine host can fetch it.

Next Steps