Conjur Terraform Provider

This topic describes how to integrate Terraform with Conjur using the Conjur Terraform provider.

Overview

The Conjur Terraform provider is Open Source, available on GitHub.

The provider manages authentication with Conjur, allowing Terraform to fetch and use secrets stored in Conjur. The provider includes the following features and benefits:

  • Simple setup in the Terraform manifest.

  • The provider authenticates to Conjur.

  • Conjur policy controls access to requested Conjur variables.

  • A provider method fetches variable values and makes them available for use elsewhere in the manifest.

  • The Terraform sensitive flag may be used against any fetched secret value to keep the value from appearing in logs and on-screen.

Authentication

The Conjur Terraform provider authenticates to Conjur using the underlying Conjur API, as is required with all Conjur access. The following authentication mechanisms are supported:

  • A human user authenticates by logging into the CLI before running Terraform commands.

  • Automation software establishes credentials by being an enrolled application associated with a host. The host stores Conjur credentials.

  • Developers using the API can configure credentials in environment variables.

Authorization to access Conjur variables

Conjur policy controls access to variable values. For the Conjur Terraform provider to obtain the value of a requested variable, the authenticated user or host must have execute privilege on that variable.

Install Conjur Terraform provider using binaries

The recommended way to install the Conjur Terraform provider (terraform-provider-conjur) is to use the binary distributions from this project's GitHub Releases page. The packages are available for Linux, macOS and Windows.

The provider is implemented using the Conjur Go API (conjur-api-go). The installation packages include all required libraries.

The following steps use Linux in the examples.

  1. Download the latest release for your operating system from https://github.com/cyberark/terraform-provider-conjur/releases.

      
    $ wget https://github.com/cyberark/terraform-provider-conjur/releases/download/v<version_number>/terraform-provider-conjur-<version_number>-linux-amd64.tar.gz

    For example:

      
    $ wget https://github.com/cyberark/terraform-provider-conjur/releases/download/v0.4.0/terraform-provider-conjur-0.4.0-linux-amd64.tar.gz

  2. Uncompress the tar file.

      
    $ tar -xvf terraform-provider-conjur*.tar.gz

  3. Create a folder for Terraform plugins. If you already have such a folder, use the existing one.

      
    $ mkdir -p ~/.terraform.d/plugins/

  4. Copy the binary to the Terraform plugins folder.

      
    $ cp terraform-provider-conjur*/terraform-provider-conjur_v* ~/.terraform.d/plugins/

Installation Options for Developers

For additional installation options, such as Homebrew for macOS or compiling from source, see the Readme on our GitHub repository.

Assumptions

  • You have a running Conjur server.

  • You are familiar with Conjur policy.

  • You are familiar with Terraform manifests.

  • You have installed the Conjur Terraform provider as described above.

Ensure Conjur Policy Provides Access

Your existing Conjur policy may already include all of the permissions required for your integration. No additional Terraform-specific statements are required.

Make sure that your policy includes the following: 

  • The users or hosts that will authenticate to Conjur are declared in policy.

  • The secrets that the manifest will request are declared as Conjur variables.

  • The authenticated entity (user or host) has execute privilege to the variables that the manifest will attempt to fetch. Privileges are declared in permit statements in Conjur policy.

Prepare the Terraform Manifest

  1. Include the conjur provider in the manifest:

      
    # main.tf
provider "conjur" {}

  2. Use the conjur_secret method to request secrets from Conjur.

      
    data "conjur_secret" "<manifest-variable>" {
  name = "<fully-qualified-conjur-variable>"
}

    Where:

    Variable Description
    <manifest-variable> The name to use elsewhere in the manifest to refer to the fetched value.
    <fully-qualified-conjur-variable>

    Identifies the variable in Conjur.

    • If the variable was declared in the root policy, this value is a single component showing the variable name. For example: name = "dbpassword".
    • If the variable was declared in a policy under root, this value specifies the hierarchy of policy ids, with the last component being the variable name. Examples are: 
      • name = "app/dbpassword"
      • name = "apps/my-app/dbpassword"

    For example:

      
    data "conjur_secret" "dbpass" {
  name = "apps/my-app/dbpassword"
}

  3. Use the Terraform output block with the sensitive attribute to hide values.

    This step is required for Terraform v0.15+. The sensitive attribute redacts values when outputs are displayed on-screen or in logs following a terraform apply or terraform refresh. The syntax is:

      
    output "dbpass_output" {
  value = "${data.conjur_secret.dbpass.value}"
  sensitive = true
}

    Here is an example of formatted output:

      
    output "dbpass_output" {
  value = "${data.conjur_secret.dbpass.value}"

  # Must mark this output value as sensitive for Terraform v0.15+,
  # because it's derived from a Conjur variable value that is declared
  # as sensitive.
  sensitive = true
}

  4. Reference fetched secrets in configurations throughout the manifest.

    Use values obtained from the data block.

Authenticate to Conjur

There are several ways to provide authentication credentials.

  1. A human user authenticates to Conjur on the CLI using the conjur authn login command. This command places credentials in a local file which the Conjur Terraform provider can access.

  2. Automated configuration solutions must be enrolled applications in policy. Applications are typically defined as layers associated with a host. The host holds credentials in local files which the Conjur Terraform provider can access.

    • Automation software establishes credentials by being an enrolled application associated with a host. The host stores Conjur credentials. Hosts can be defined as:

      • A static host declared in policy.
      • A host defined by a Host Factory.
      • A host defined by other Conjur integrations, such as Kubernetes or Cloud Foundry instances.

  3. If you are a developer, you can conveniently override all of the values from the environment through the manifest. However, hard coding the api_key is strongly discouraged. The following configuration example sets almost all variables in the manifest, but uses the Terraform conjur_api_key as the source for conjur_api_key value:

      
    variable "conjur_api_key" {}

provider "conjur" {
  appliance_url = "https://conjur-server"
  account = "myaccount"
  login = "admin"
  api_key = var.conjur_api_key
  # ssl_cert = var.conjur_ssl_cert
  ssl_cert_path = "/etc/conjur.pem"
}
     

    If the .tf configuration does not include both login and api_key, then environment variables will be used for these values instead.

  4. Using the API, you can set the Conjur instance and user credentials as environment variables. The environment variables take precedence over the configuration file settings. Here is the list of supported environment variables with example values: 

      
    export CONJUR_APPLIANCE_URL="https://localhost:8443"
export CONJUR_ACCOUNT="quick-start"
export CONJUR_AUTHN_LOGIN="admin"
export CONJUR_AUTHN_API_KEY="3ahcddy39rcxzh3ggac4cwk3j2r8pqwdg33059y835ys2rh2kzs2a"
export CONJUR_CERT_FILE="/etc/conjur.pem"

Run Terraform Commands

Run terraform plan and terraform apply on the same machine where authentication is configured: 

  • A logged in Conjur user must run the Terraform commands on the same machine that was used to log into Conjur.
  • An automation application must execute the Terraform commands on the host machine where the Conjur application identity resides.
  • A developer must execute the commands on the same machine where the Conjur environment variables were set.

Manage state files

 

The terraform apply command generates artifacts (state files) that contain the fetched secret values in plain text.

This is normal and expected Terraform behavior. Use your existing Terraform best practices to manage these state files, such as managing the files into a protected vault and restricting access to the files.