conjur-quickstart

This repository guides you through a sample installation of Conjur Open Source using Docker Compose.

• Certification level
• Requirements
• Usage instructions
  • Using this quick start with Conjur Open Source
  • Step by step guide
    • Set up a Conjur Open Source environment
    • Define policy
    • Store a secret
    • Run the demo app
  • Next steps
  • Explore the Conjur database
  • Use Conjur with telemetry
  • Configuring Conjur with predefined admin password
  • Using persistent Conjur configuration
    • Set up a Conjur Open Source environment with persistence
    • Restarting the Conjur Open Source environment using persistence
    • Delete the Conjur data directory when done
  • Adding or Modifying Container Environment Variables
  • Troubleshooting
    • Failed to open TCP connection error for Conjur login
• Contributing

Table of contents generated with markdown-toc

Certification level

This repo is a Community level project. It's a community contributed project that is not reviewed or supported by CyberArk. For more detailed information on our certification levels, see our community guidelines.

Requirements

To follow this quick start guide, you will need to install Docker Desktop.

You will also need to clone this repository to your working directory:

git clone https://github.com/cyberark/conjur-quickstart.git

Usage instructions

Using this quick start with Conjur Open Source

We strongly recommend choosing the version of this project to use from the latest Conjur OSS suite release. Conjur maintainers perform additional testing on the suite release versions to ensure compatibility. When possible, upgrade your Conjur version to match the latest suite release; when using integrations, choose the latest suite release that matches your Conjur version. For any questions, please contact us on Discourse.

Step by step guide

In the sections below, we'll walk through standing this environment up step by step. Alternatively, you can follow the instructions by visiting the web tutorial: https://www.conjur.org/get-started/quick-start/oss-environment/.

Set up a Conjur Open Source environment

In this unit you will learn how to install Conjur OpenSource using Docker.

At the end of this section: You will have a working Conjur Open Source environment with a Conjur account and an admin user.

1. Pull the Docker images

   Open a terminal session and browse to conjur-quickstart. Pull the Docker images defined in docker-compose.yml:

   docker compose pull
   

   Verification When the required images are successfully pulled, the terminal returns the following:

   ⠿ openssl Skipped - Image is already being pulled by conjur
   ⠿ database Pulled
   ⠿ bot_app Pulled
   ⠿ proxy Pulled
   ⠿ pgadmin Pulled
     ...
   ⠿ conjur Pulled
   ⠿ client Pulled
   

2. Generate the master key

   The master data key will be used later to encrypt the database. In the working directory, generate the key and store it to a file:

   * Tip: Although not mandatory, we prefer to store sensitive data to a file and not to display it directly on console screen.

   docker compose run --no-deps --rm conjur data-key generate > data_key
   

   The data key is generated in the working directory and is stored in a file called data_key.

   Verification When the key is generated, the terminal returns the following:

   Network conjur-quickstart_default  Created
   

3. Load master key as an environment variable

   Load data_key file content (the master data key) as an environment variable:

   export CONJUR_DATA_KEY="$(< data_key)"
   

4. Start the Conjur Open Source environment

   Start the Conjur Open Source environment:

   docker compose up -d
   

   When Conjur Open Source starts, the terminal returns the following:

   ⠿ Container bot_app                      Started
   ⠿ Container conjur-quickstart-pgadmin-1  Started
   ⠿ Container postgres_database            Started
   ⠿ Container openssl                      Started
   ⠿ Container conjur_server                Started
   ⠿ Container nginx_proxy                  Started
   ⠿ Container conjur_client                Started
   

   Verification Run the following command to see a list of running containers:

   docker ps -a
   

5. Create an admin account

   Create a Conjur account and initialize the built-in admin user.

   docker compose exec conjur conjurctl account create myConjurAccount > admin_data
   

   An account named myConjurAccount is created and the admin user is initialized, following keys are created and stored at admin_data file:

   • admin user API key. Later on, we will use this key to log in to Conjur.
   • myConjurAccount Conjur account public key.

6. Connect the Conjur client to the Conjur server

   This is a one-time action. For the duration of the container’s life or until additional initcommand is issued, the Conjur client and the Conjur server remain connected.

   Use the account name that you created in step 5. You will be prompted to trust the TLS certificate of the Conjur server. Type y to trust the certificate:

   docker compose exec client conjur init -u https://proxy -a myConjurAccount --self-signed
   

   Verification The terminal returns the following output:

   Wrote certificate to /root/conjur-server.pem
   Wrote configuration to /root/.conjurrc
   

Define policy

In this unit you will learn how to load your first policy. Formatted in YAML, policy defines Conjur entities and the relationships between them. An entity can be a policy, a host, a user, a layer, a group, or a variable.

A sample application policy named BotApp.yml is provided in the client container under policy directory.

At the end of this section: As a privileged user, you will load a policy that defines a human user, a non-human user that represents your application, and a variable.

1. Log in to Conjur as admin

   Log in to Conjur as admin. When prompted for a password, insert the API key stored in the admin_data file:

   docker compose exec client conjur login -i admin
   

   Verification When you successfully log in, the terminal returns:

   Logged in
   

2. Load the sample policy

   Load the provided sample policy into Conjur built-in root policy to create the resources for the BotApp:

   docker compose exec client conjur policy load -b root -f policy/BotApp.yml > my_app_data
   

   Conjur generates the following API keys and stores them in a file, my_app_data:

   • An API key for Dave, the human user. This key is used to authenticate user Dave to Conjur.
   • An API key for BotApp, the non-human identity. This key is used to authenticate BotApp application to Conjur.

   Those API keys is correlated with the number of Users & Hosts defined in a policy.

   Verification The terminal returns:

   Loaded policy 'root'
   

3. Log out of Conjur

   Log out of Conjur:

   docker compose exec client conjur logout
   

   Verification When you successfully log out, the terminal returns:

   Logged out
   

Store a secret

In this unit you will learn how to store your first secret in Conjur.

1. Log in as Dave

   Log in as Dave, the human user. When prompted for a password, copy and paste Dave’s API key stored in the my_app_data file:

   docker compose exec client conjur login -i Dave@BotApp
   

   Verification To verify that you logged in successfully, run:

   docker compose exec client conjur whoami
   

   The terminal returns:

   {
     "client_ip": "xxx.xx.x.x",
     "user_agent": "Go-http-client/1.1",
     "account": "myConjurAccount",
     "username": "Dave@BotApp",
     "token_issued_at": "yyyy-mm-ddThh:mm:ss.sss+00:00"
   }
   

2. Generate a secret

   Generate a value for your application’s secret:

   secretVal=$(openssl rand -hex 12 | tr -d '\r\n')
   

   This generates a 12-hex-character value.

3. Store the secret

   Store the generated value in Conjur:

   docker compose exec client conjur variable set -i BotApp/secretVar -v ${secretVal}
   

   A policy predefined variable named BotApp/secretVar is set with a random generated secret.

   Verification The terminal returns a message:

   Value added
   

Run the demo app

In this unit you will learn how to program an application to fetch a secret from Conjur using the REST API.

At the end of this section: You will know how to leverage Conjur’s ability to store your application’s secrets securely.

1. Start a bash session

   Enter the BotApp container.

   docker exec -it bot_app bash
   

2. Generate a Conjur token

   Generate a Conjur token to the conjur_token file, using the BotApp API key:

   curl -d "<BotApp API Key>" -k https://proxy/authn/myConjurAccount/host%2FBotApp%2FmyDemoApp/authenticate > /tmp/conjur_token
   

   The Conjur token is stored in the conjur_token file.

3. Fetch the secret

   Run program to fetch the secret:

   /tmp/program.sh
   

   The secret is displayed.

   TIP: If the secret is not displayed, try generating the token again. You have eight minutes between generating the conjur token and fetching the secret with BotApp.

Congratulations! You are ready to secure your own apps with Conjur.

Next steps

Now that you've got a local Conjur instance running, what can you do with it?

Try some of our tutorials on Conjur.org.

Explore the Conjur database

This section is about exploring the database. The admin panel from pgAdmin can be used to discover and explore the database schema, stored procedures and triggers that constitute a significant part of the inner working of Conjur. It offers a glimpse into the data model of Conjur.

This section should follow only after completion of the Store a secret section. There's more insight to be gleamed from the database when it has become reasonably populated with some representative data i.e. roles, identities, permissions etc.

As part of Setting up a Conjur Open Source environment the pgadmin service is spun up. It will be accessible on your local machine at http://localhost:8081.

To explore the database

1. Visit http://localhost:8081
2. Login with email "[email protected]" and password "SuperSecret"
3. Add a new server. Name it "Conjur DB". Set the connection details. Host is "database", Port is "5432", Database is "postgres", Username is "postgres", and there is no password. Note that pgamdin is running inside the docker-compose network, it is for this reason that the Host of "database" is resolvable.
4. Dig in as shown below!

Use Conjur with telemetry

Conjur supports telemetry as an opt-in feature. The telemetry feature has a general purpose mechanism for collection, but currently only supports a single method for export, a Prometheus scrape target endpoint. Below are instructions for enabling and exploring the telemetry feature.

In order to enable telemetry in Conjur you must opt-in via configuration. You have a choice between setting an environment variable:

CONJUR_TELEMETRY_ENABLED=true

or updating a value in the conjur.conf configuration file:

telemetry_enabled: true

Note that the environment variables takes precedence.

1. If you are already running the Conjur Open Source quickstart environment without telemetry, bring down the Conjur container:

   docker compose down conjur
   

2. Modify docker-compose.yml in this repository to enable telemetry by setting the CONJUR_TELEMETRY_ENABLED environment variable to the value 'true' (It needs to be a string otherwise the docker compose YAML parser will not be happy). Below is an illustration of the required change:

   services:
      # ...
      conjur:
         environment:
            # ...
            CONJUR_TELEMETRY_ENABLED: 'true'

3. Start the Conjur Open Source environment using telemetry:

   • If you had previously been running the Conjur Open Source environment, follow the steps 2 and 3 of the Set up a Conjur Open Source environment section above in order to recreate the Conjur container.
   • Otherwise, follow the steps starting from Step 1 of the Set up a Conjur Open Source environment section above.

4. Navigate to the telemetry README and, starting from step 2, follow the instructions to set up the telemetry related services.

   The telemetry README provides instructions for a comprehensive quickstart for setting up services such as Prometheus and Grafana, creating relevant connections between those services and the Conjur Prometheus scrape target endpoint, and providing an example dashboard with the metrics collected by Conjur.

Configuring Conjur with predefined admin password

The following command will allow you to specify the admin user's password:

docker compose exec conjur bash -c 'echo -n "MySecretP@SS1" | conjurctl account create --password-from-stdin --name  myConjurAccount'

The password must be provided via STDIN in any manner you prefer and must meet the following complexity rules:

• Between 12 and 128 characters
• 2 uppercase letters
• 2 lowercase letters
• 1 special character
• 1 digit

Note: This feature is available in Conjur v1.11.5+

Using persistent Conjur configuration

With small variations to the steps outlined above, it is possible to set up a Conjur Open Source environment that retains Conjur configuration or state across Docker container restarts. Using the steps outlined below, a Conjur Open Source environment can be set up that uses a local directory on the host to persist Conjur configuration across container restarts.

Set up a Conjur Open Source environment with persistence

1. If you are already running the Conjur Open Source quickstart environment without persistence, bring down the associated containers:

   docker compose down
   

2. Create a directory for storing persistent state. For example:

   mkdir temp-db-data
   

   NOTE: The permissions on this directory will automatically be changed to 700 by docker compose when the directory gets host-mounted by the Conjur container.

3. Modify docker-compose.yml in this repository to support persistent storage of Conjur state. Add the following line to the bottom of the database service configuration, replacing <PATH-TO-CONJUR-DATA-DIRECTORY> with the path to the directory created in the previous step:

       volumes:
         - <PATH-TO-CONJUR-DATA-DIRECTORY>:/var/lib/postgresql/data
   

   For example:

       volumes:
         - /home/myusername/conjur-quickstart/temp-db-data:/var/lib/postgresql/data
   

4. Start the Conjur Open Source environment using persistence:

   • If you had previously been running the Conjur Open Source environment, follow the steps outlined above starting with Step 4 of the Set up a Conjur Open Source environment section above.
   • Otherwise, follow the steps starting with Step 1 of the Set up a Conjur Open Source environment section above.

Restarting the Conjur Open Source environment using persistence

Once you have set up the Conjur Open Source environment to support persistent Conjur state, you can restart your environment as follows:

1. Bring the containers down:

   docker compose down
   

   NOTE: You must use the docker compose down command here rather than the docker compose stop in order to avoid having stale, ephemeral connection state in the Conjur container. If you use the docker compose stop command here instead, you may see errors as described in the Failed to open TCP connection error for Conjur login section below.

2. Bring the containers back up:

   docker compose up -d
   

3. Reconnect the Conjur client to the Conjur server. Use the account name that you created in the Create an admin account section above. For example:

   docker compose exec client conjur init -u https://proxy -a myConjurAccount --self-signed
   

4. Log in again to Conjur as admin. When prompted for a password, insert the API key stored in the admin_data file:

   docker compose exec client conjur login -i admin
   

   Verification When you successfully log in, the terminal returns:

   Logged in
   

Delete the Conjur data directory when done

For added security, remember to delete the data directory that you created in Step 1 of the Set up a Conjur Open Source environment with persistence section above.

Adding or Modifying Container Environment Variables

This section describes the process of either adding or modifying environment variables for a docker-compose service. The process recreates a service with the desired changes, while the rest of the system continues running. Note that for a stateful service, there should be a persistence mechanism in place (e.g. volume mounts), otherwise data will be lost when the container is recreated.

The example below will add an environment variable CONJUR_LOG_LEVEL=debug to the conjur service container.

1. Add or modify environment variables in docker-compose.yml

   docker-compose.yml is used to define the Conjur Open Source system. Additions and modifications to environment variables are made in the environment configuration of the desired service, and are of the form:

   version: '3'
   services:
     ...
     conjur:
       ...
       environment:
         CONJUR_LOG_LEVEL: debug
   

2. Recreate the container

   docker compose up -d --no-deps conjur
   

   The new container now contains the updated configuration defined in docker-compose.yml.

3. Verify that the desired environment variables are now defined in the container

   Run the following:

   docker compose exec conjur printenv CONJUR_LOG_LEVEL
   

   If the environment variable was correctly assigned in the container, the terminal returns the value of the variable:

   debug
   

Troubleshooting

Failed to open TCP connection error for Conjur login

If you are using persistent Conjur configuration, and you see the following error when trying to log into Conjur:

error: Failed to open TCP connection to conjur:80 (Connection refused - connect(2) for "conjur" port 80)

Then try the following:

1. Run the following command:

   docker compose logs conjur | grep "already running"
   

2. If the command in Step 1 produces the following line:

   A server is already running. Check /opt/conjur-server/tmp/pids/server.pid.
   

   then it may be that the Conjur container was stopped (e.g. docker compose stop conjur) and restarted (docker compose up -d conjur) without being brought fully down (e.g. with docker compose down conjur), leaving the container with stale connection state.

   To recover from this, run:

   docker compose down conjur
   docker compose up -d conjur
   

   And log in again, e.g.:

   docker compose exec client conjur login -i admin
   

3. If "A server is already running" does not show in the Conjur container logs, or Step 2 above is unsuccessful, then try restarting all containers:

   docker compose down
   docker compose up -d
   

   and try logging in again, e.g.:

   docker compose exec client conjur login -i admin
   

Contributing

We welcome contributions of all kinds to this repository. For instructions on how to get started and descriptions of our development workflows, please see our contributing guide.