conjur

Table of Contents

• Description
• Certification Level
• Setup
  • Setup requirements
  • Deprecations
    • Puppet v5
    • Conjur Enterprise v4
    • Use of Host Factory Tokens
  • Installation
  • Using conjur-puppet with Conjur Open Source
  • Conjur module basics
    • Example usage
    • Deferred functions
    • Sensitive type
• Usage
  • Methods to establish Conjur host identity
    • Conjur host identity with API key
      • Updating the Puppet manifest
      • Using Hiera
      • Using Conjur identity files (Linux agents only)
      • Using Windows Registry / Windows Credential Manager (Windows agents only)
• Troubleshooting
• Reference
• Limitations
• Contributing
• Support

Table of contents generated with markdown-toc

Description

This is the official Puppet module for Conjur, a robust identity and access management platform. This module simplifies the operations involved in establishing a Conjur host identity and allows authorized Puppet nodes to fetch secrets from Conjur.

You can find our official distributable releases on Puppet Forge under cyberark/conjur.

Certification level

This repo is a Certified project. It is officially approved to work with Conjur Open Source and Conjur Enterprise as documented. For more detailed information on our certification levels, see our community guidelines.

Setup

Setup requirements

This module requires that you have:

• Puppet v6 or equivalent EE version
• Conjur endpoint available to both the Puppet server and the Puppet nodes using this module. Supported versions:
  • Conjur Open Source v1+
  • Conjur Enterprise (formerly DAP) v10+

Deprecations

Puppet v5

Puppet v5 is not supported in v3+ of this module. If you are still using this version, please use the v2 branch of this project or a release version <3.0.0.

Conjur Enterprise v4

Conjur Enterprise v4 is not supported in v3+ of this module. If you are still using this version, please use the v2 branch of this project or a release version <3.0.0.

Use of Host Factory Tokens

Establishment of identity using host factory tokens directly through this module is no longer supported. Host factory tokens can still be used to create host identities, but these identities need to be established outside of the module itself. If you are still using the creation of identities with host factory tokens via this module, please use the v2 branch of this project or a release version <3.0.0.

Installation

To install this module, run the following command on the Puppet server:

puppet module install cyberark-conjur

To install a specific version of this module (e.g. v1.2.3), run the following command on the Puppet server:

puppet module install cyberark-conjur --version 1.2.3

Using conjur-puppet with Conjur Open Source

Are you using this project with Conjur Open Source? Then 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.

Conjur module basics

This module provides a conjur::secret Deferred function that can be used to retrieve secrets from Conjur. Given a Conjur variable identifier and optional identity parameters, conjur::secret uses the node’s Conjur identity to resolve and return the variable’s value as a Sensitive variable.

Using a pre-provisioned identity:

$dbpass = Deferred(conjur::secret, ['production/postgres/password'])

Using a manifest-provided identity:

$sslcert = @("EOT")
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
|-EOT

$dbpass = Deferred(conjur::secret, ['production/postgres/password', {
  appliance_url => "https://my.conjur.org",
  account => "myaccount",
  authn_login => "host/myhost",
  authn_api_key => Sensitive("2z9mndg1950gcx1mcrs6w18bwnp028dqkmc34vj8gh2p500ny1qk8n"),
  ssl_certificate => $sslcert
}])

Example usage

node 'server-123' {
  $db_password = Deferred(conjur::secret, ['inventory/db-password'])

  # Example of writing a secret to a file
  file { '/tmp/creds.txt':
    ensure => file,
    mode => '0600',
    content => $db_password,
  }

  # Example of using a secret in a templated file
  file { '/tmp/creds.ini':
    ensure => file,
    mode => '0600',
    content => Deferred('inline_epp', [
      'password=<%= $db_password.unwrap %>',
      { 'db_password' => $db_password }
    ]),
  }
}

Deferred functions

This module requires the use of Puppet v6+ Deferred functions to ensure that the credential retrieval is fully handled on the agent. Failure to use Deferred around the method will result in an error:

# GOOD: Function `conjur::secret` is wrapped in `Deferred` call
Deferred(conjur::secret, ['production/postgres/password'])

# BAD: This will not work!
conjur::secret('production/postgres/password')

Since the resolution of variables is done also on the agent after the catalog is compiled, anything that requires the value of the variable during the compilation step (e.g. template compilation) must also be wrapped in a Deferred invocation.

It is also important to note that you should make sure that you invoke the conjur::secret function using the proper Deferred syntax:

# GOOD: Passing the parameters as an array
Deferred(conjur::secret, ['production/postgres/password'])

# BAD: This will not work!
Deferred(conjur::secret('production/postgres/password'))

You can read more about Puppet's Deferred functions here.

Sensitive type

conjur::secret returns values wrapped in a Sensitive data type. In some contexts, such as string interpolation, it might cause surprising results (interpolating to Sensitive [value redacted]). This is intentional, as it makes it more difficult to accidentally mishandle secrets.

To use a Sensitive value as a string, you need to explicitly request it using the unwrap function. If you are setting other Puppet variables to the value of this secret or if you are creating composite Puppet variables from it, you should ensure that the resulting value is also wrapped in a Sensitive type. In particular, you should not pass unwrapped variables as parameters to Puppet methods if you can avoid it. Many Puppet resource functions support Sensitive data type and handle it correctly.

$dbpass = Deferred(conjur::secret, ['production/postgres/password'])

# Use Sensitive data type to handle anything sensitive
$db_yaml = Sensitive(Deferred('inline_epp', [
  'password: <%= $db_password.unwrap %>',
  { 'db_password' => $dbpass }
]))

file { '/etc/someservice/db.yaml':
  ensure  => file,
  mode    => '0600',
  content => $db_yaml, # This correctly handles both Sensitive and String
}

Note: We only enforce that the API key from the Conjur configuration is marked Sensitive, but if any other data in the function parameters is also considered sensitive by your organization you may also wrap the whole Deferred invocation in the Sensitive type to prevent accidental disclosure of the sensitive information to the logs. Note that if you do this, you will need to unwrap the output twice.

Usage

This module provides the conjur::secret function described above and the conjur class, which can be configured to establish Conjur host identity on the node running Puppet.

Methods to establish Conjur host identity

Conjur requires an application identity for any applications, machines, or processes that need to interact with Conjur.

Please note that before getting started configuring your Puppet environment, you'll need to load a policy in Conjur to define the application identities that you will be using to authenticate to Conjur. To learn more about creating hosts, please see the Conjur documentation.

In the sections below, we'll outline the different methods of providing this module with your Conjur configuration and credentials. In those sections we'll refer often to the following Conjur configuration variables:

• appliance_url: The URL of the Conjur or Conjur Enterprise instance you are connecting to. If using Conjur Enterprise, this may be the URL of a load balancer for the cluster's Conjur Enterprise follower instances.
• account - the account name for the Conjur / Conjur Enterprise instance you are connecting to.
• authn_login: The identity you are using to authenticate to the Conjur / Conjur Enterprise instance. For hosts / application identities, the fully qualified path should be prefixed by host/, eg host/production/my-app-host.
• authn_api_key: The API key of the identity you are using to authenticate to the Conjur / Conjur Enterprise instance.
• ssl_certificate: The raw PEM-encoded x509 CA certificate chain for the Conjur Enterprise instance you are connecting to, provided as a string (including newlines) or using the Puppet file resource type. This value may be obtained by running the command:

  $ openssl s_client -showcerts -servername [DAP_INSTANCE_DNS_NAME] \
    -connect [DAP_INSTANCE_DNS_NAME]:443 < /dev/null 2> /dev/null \
    | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p'
  -----BEGIN CERTIFICATE-----
  ...
  -----END CERTIFICATE-----
  

• version (optional): Conjur API version, defaults to 5.

Note that not all variables are required for each method of configuration.

Conjur host identity with API key

The simplest way to get started with a Conjur application identity is to create a host in Conjur and then provide its Conjur credentials to this module. There are a few ways to provide the Conjur Puppet module with these credentials and they are outlined in the following sections.

Updating the Puppet manifest

When you update the Puppet manifest to include the Conjur host identity and API key, you are configuring the Puppet server with the Conjur identity information.

In this example, after you have created a Conjur host named redis001, you can add its host identity information and its API key to your Deferred invocation as an optional hash like this:

$sslcert = @("EOT")
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
|-EOT

$dbpass = Deferred(conjur::secret, ['production/postgres/password', {
  appliance_url => "https://my.conjur.org",
  account => "default",
  authn_login => "host/redis001",
  authn_api_key => Sensitive("2z9mndg1950gcx1mcrs6w18bwnp028dqkmc34vj8gh2p500ny1qk8n"),
  ssl_certificate => $sslcert
}])

Using Hiera

You can also add the Conjur identity configuration to Hiera, which provides the Conjur identity information to the Puppet server. You then would use that information to populate the host identity information:

---
lookup_options:
  '^conjur::authn_api_key':
    convert_to: 'Sensitive'

conjur::account: 'default'
conjur::appliance_url: 'https://my.conjur.org'
conjur::authn_login: 'host/myhost'
conjur::authn_api_key: '<REPLACE_ME>'
conjur::ssl_certificate: |
  -----BEGIN CERTIFICATE-----
  ...
  -----END CERTIFICATE-----

Then in your manifest, you can fetch the secret like this:

$sslkey = Deferred(conjur::secret, ["domains/%{hiera('domain')}/ssl-cert", {
  appliance_url => lookup('conjur::appliance_url'),
  account => lookup('conjur::account'),
  authn_login => lookup('conjur::authn_login'),
  authn_api_key => lookup('conjur::authn_api_key'),
  ssl_certificate => lookup('conjur::ssl_certificate')
}])

file { '/abslute/path/to/cert.pem':
  ensure    => file,
  content   => $sslkey,
}

Using Conjur identity files (Linux agents only)

To configure Linux agents with a Conjur host identity, you can add the Conjur host and API key to Conjur identity files /etc/conjur.conf and /etc/conjur.identity.

Using the same redis001 host as above, you would create a conjur.conf file that contains:

---
account: myorg
plugins: []
appliance_url: https://conjur.mycompany.com
cert_file: "/absolute/path/to/conjur-ca.pem" # Read from the Puppet agent
# Alternative for providing the SSL cert
# ssl_certificate: |
#  -----BEGIN CERTIFICATE-----
#  ...
#  -----END CERTIFICATE-----

Note: use either SslCertificate or CertFile but not both as cert_file overrides the value of ssl_certificate setting.

You will also need a conjur.identity file that contains:

machine conjur.mycompany.com
    login host/redis001
    password f9yykd2r0dajz398rh32xz2fxp1tws1qq2baw4112n4am9x3ncqbk3

NOTE: The conjur.conf and conjur.identity files contain sensitive Conjur connection information. Care must be taken to ensure that the permissions for these files are set to 600 to disallow any access to these files by unauthorized (non-root) users on a Linux Puppet agent node.

The Conjur Puppet Module automatically checks for these files on your node and uses them if they are available.

To then fetch your credential, you would use the default form of conjur::secret:

$dbpass = Deferred(conjur::secret, ['production/postgres/password'])

Using Windows Registry / Windows Credential Manager (Windows agents only)

To configure Windows agents with a Conjur host identity, you set up the Conjur configuration in the Windows Registry and in the Windows Credential Manager. The Registry contains the connection general information and the Credential Manager is used to store the sensitive authentication credentials.

Connection settings for Conjur are stored in the Windows Registry under the key HKLM\Software\CyberArk\Conjur. This is equivalent to /etc/conjur.conf on Linux. The values available to set are:

These may be set using Powershell:

> reg ADD HKLM\Software\CyberArk\Conjur /v ApplianceUrl /t REG_SZ /d https://conjur.mycompany.com
> reg ADD HKLM\Software\CyberArk\Conjur /v Version /t REG_DWORD /d 5
> reg ADD HKLM\Software\CyberArk\Conjur /v Account /t REG_SZ /d myorg
> reg ADD HKLM\Software\CyberArk\Conjur /v SslCertificate /t REG_SZ /d "-----BEGIN CERTIFICATE-----..."

Or using a .reg registry file (SslCertificate value cannot be set this way - you must set this value via command line):

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\CyberArk\Conjur]
"ApplianceUrl"="https://conjur.mycompany.com"
"Version"=dword:00000005
"Account"="myorg"

NOTE: It is important from a security perspective to ensure that unauthorized, non-administrator users do not have write access to Conjur connection settings in the Windows Registry. Disabling write access for unauthorized users to these settings will help to prevent potential malicious redirection of sensitive Puppet agent messages. Read-only access for non-administrator users to Conjur connection information can be confirmed via regedit on the Windows Desktop, or by running the following command from a PowerShell to confirm that only the ReadKey flag is set:

PS C:\> Get-Acl -Path HKLM:SOFTWARE\CyberArk\Conjur | fl * | Out-String -stream | Select-String "BUIL
TIN\\Users"

AccessToString          : BUILTIN\Users Allow  ReadKey

Credentials for Conjur are stored in the Windows Credential Manager. The credential Target is the Conjur appliance URL (e.g. https://conjur.mycompany.com). The username is the host ID, with a host/ prefix (e.g. host/redis001, as in previous examples) and the credential password is the host's API key. This is equivalent to /etc/conjur.identity on Linux.

This may be set using Powershell:

> cmdkey /generic:https://conjur.mycompany.com /user:host/redis001 /pass
Enter the password for 'host/my-host' to connect to 'https://conjur.net/authn': #
{Prompt for API Key}

CMDKEY: Credential added successfully.

To then fetch your credential, you would use the default form of conjur::secret:

$dbpass = Deferred(conjur::secret, ['production/postgres/password'])

Troubleshooting

For a complete guide on troubleshooting, please see TROUBLESHOOTING.md.

Reference

For a complete reference, please see REFERENCE.md.

Limitations

See metadata.json for supported platforms.

At current, the Conjur Puppet module encrypts and decrypts the Conjur access token using the Puppet server’s private/public key pair. This is known to be incompatible with using multiple compile masters.

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.

Support

Please note, that this is a "Partner Supported" module, which means that technical customer support for this module is solely provided by CyberArk.

Puppet does not provide support for any Partner Supported modules. For technical support please visit the Conjur channnel at CyberArk Commons.

Reference

Table of Contents

Resource types

• credential: Manages Credential Manager credentials on Windows systems.

Functions

• conjur::secret: Function to retrieve a Conjur secret

Resource types

credential

Manages Credential Manager credentials on Windows systems.

Properties

The following properties are available in the credential type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

username

The identity used to authenticate to the Conjur instance

value

The API key matching the Conjur identity

Parameters

The following parameters are available in the credential type.

• provider
• target

provider

The specific backend to use for this credential resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

target

Conjur URL

Functions

conjur::secret

Type: Ruby 4.x API

Function to retrieve a Conjur secret

Examples

Agent-based identity invocation

Deferred(conjur::secret, ['production/postgres/password'])

Server-based identity invocation

$sslcert = @("EOT")
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
|-EOT

$dbpass = Deferred(conjur::secret, ['production/postgres/password', {
  appliance_url => "https://my.conjur.org",
  account => "myaccount",
  authn_login => "host/myhost",
  authn_api_key => Sensitive("2z9mndg1950gcx1mcrs6w18bwnp028dqkmc34vj8gh2p500ny1qk8n"),
  ssl_certificate => $sslcert
}])

conjur::secret(String $variable_id, Optional[Hash] $options)

Function to retrieve a Conjur secret

Returns: Sensitive Value of the Conjur variable.

Examples

Agent-based identity invocation

Deferred(conjur::secret, ['production/postgres/password'])

Server-based identity invocation

$sslcert = @("EOT")
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
|-EOT

$dbpass = Deferred(conjur::secret, ['production/postgres/password', {
  appliance_url => "https://my.conjur.org",
  account => "myaccount",
  authn_login => "host/myhost",
  authn_api_key => Sensitive("2z9mndg1950gcx1mcrs6w18bwnp028dqkmc34vj8gh2p500ny1qk8n"),
  ssl_certificate => $sslcert
}])

variable_id

Data type: String

Conjur variable ID that you want the value of.

options

Data type: Optional[Hash]

Optional parameter specifying server identity overrides The following keys are supported in the options hash:

• appliance_url: The URL of the Conjur instance.
• account: Name of the Conjur account that contains this variable.
• authn_login: The identity you are using to authenticate to the Conjur instance.
• authn_api_key: The API key of the identity you are using to authenticate with (must be Sensitive type).
• cert_file: The absolute path to CA certificate chain for the Conjur instance on the agent. This variable overrides ssl_certificate.
• sslcertificate: The _raw PEM-encoded x509 CA certificate chain for the Conjur instance. Overwritten by the contents read from cert_file when it is present.
• version: Conjur API version, defaults to 5.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

Unreleased

3.1.1 - 2023-08-23

Security

• Upgrade Ruby base image version to 3.3-rc-slim cyberark/conjur-puppet#259
• Upgrade PDK and Ruby base image version to 3.2.2 cyberark/conjur-puppet#256
• Upgrade PDK and Ruby base image version cyberark/conjur-puppet#253

3.1.0 - 2020-10-08

Added

• Module now fully supports the use of cert_file parameter, which accepts the path to the PEM-encoded x509 CA certificate chain for Conjur. Users can supply the module with certificate path in cert_file OR with certificate contents in ssl_certificate. cyberark/conjur-puppet#105

Changed

• Conjur server errors now have better descriptions. cyberark/conjur-puppet#241
• If authn_api_key is not wrapped in Sensitive class, we now raise a descriptive error as to why we cannot proceed. cyberark/conjur-puppet#232
• Warnings are now logged whenever this module attempts to use a non-HTTPS endpoint. cyberark/conjur-puppet#144

3.0.0 - 2020-09-17

Added

• Secrets are now retrieved by the Puppet agent, instead of the server, using Puppet's deferred function feature. This aligns with Puppet's documented best practices. cyberark/conjur-puppet#13
• Module now follows Puppet development best practices and uses PDK for linting, unit tests, and publishing. cyberark/conjur-puppet#64

Changed

• conjur::secret now must be used as a Deferred function. Method signature has changed as well, including providing of optional parameters as a Hash. cyberark/conjur-puppet#13 cyberark/conjur-puppet#184
• When Conjur configuration cannot be resolved on the agent, we now log a warning that this is potentially a result of misconfiguration. cyberark/conjur-puppet#125
• This module now logs a warning if no certificates are parsed from the provided certificate string. cyberark/conjur-puppet#115

Fixed

• Account names with special characters that require encoding (eg. +, , etc) are now properly escaped when variables are fetched from Conjur / DAP within the conjur::secret function. cyberark/conjur-puppet#170

Removed

• Support for using the Conjur Puppet module with Conjur Enterprise v4. cyberark/conjur-puppet#66
• Support for using this module with Puppet v5. cyberark/conjur-puppet#104
• Support for using host factory tokens, conjur class, cert_file parameter, and using server-side conjur class to pre-populate on-agent info. cyberark/conjur-puppet#104

2.0.6 - 2020-08-10

Deprecated

• Support for using the Conjur Puppet module with Puppet v5 is now deprecated. Support will be removed in the next major release. cyberark/conjur-puppet#180
• Support for configuring this module to exchange host factory tokens for Conjur host identities and API keys is now deprecated. You may still configure your systems to create a host using host factory, however, as long as you provide this module with the Conjur host identity and API key. cyberark/conjur-puppet#180

2.0.5 - 2020-07-28

Added

• Preliminary support for Puppet 6 with Linux agents, now including Ubuntu 18.04 and 20.04, Debian 9 and 10, and Alpine 3.9. Epic cyberark/conjur-puppet#20

Deprecated

• Support for using the Conjur Puppet module with Conjur Enterprise v4 is now deprecated. Support will be removed in the next major release. The conjurize method of providing the Conjur Puppet module with its Conjur identity will also no longer be supported as of the next version.
• Support for using the Conjur Puppet module with Windows Server 2008 or Debian 7 agents, since both operating systems have now reached end of life.

2.0.4 - 2020-07-20

Added

• Preliminary support for Puppet 6 with Windows agents (Server 2012 R2, Server 2016, Server 2019). Epic cyberark/conjur-puppet#20
• Support for using cert_file in the conjur class or CertFile in Windows Registry on Windows as an alternative to using the existing ssl_certificate parameter. cyberark/conjur-puppet#113

Changed

• Updated README to clarify configuration instructions. cyberark/conjur-puppet#128, PR cyberark/conjur-puppet#111, cyberark/conjur-puppet#98, cyberark/conjur-puppet#97, PR cyberark/conjur-puppet#108

Fixed

• Module no longer returns internal server errors when decrypting tokens when used with Puppet 6. cyberark/conjur-puppet#91
• Module no longer relies on Puppet 6-incompatible methods for retrieving Puppet CA chains. cyberark/conjur-puppet#44
• Module no longer reports "identity not found" on subsequent runs for nodes running with HFT-created identities, and is updated with improved logging for Windows-based configuration and credential fetching. cyberark/conjur-puppet#47
• Module no longer fails on the first run when using Conjur Host Factory tokens with Hiera. cyberark/conjur-puppet#112

2.0.3 - 2020-05-10

Changed

• We now encode the variable id before retrieving it from Conjur v5. Spaces are encoded into "%20" and slashes into "%2F". cyberark/conjur-puppet#72

2.0.2 - 2019-12-18

Added

• Update support contact info in README

2.0.1 - 2019-07-15

Added

• Update module manifest to include Puppet 5.x requirement

2.0.0 - 2019-07-08

Removed

• Remove support for Puppet older than 4.6.

Added

• Add support for Windows Puppet agents. See README.md for details.

Changed

• Change default Conjur version to 5. This a breaking change from 1.2.0.

1.2.0 - 2017-09-27

Added

• Support Conjur v5 API.

1.1.0 - 2017-05-24

Changed

• Cleanup and refactor of project files. No behavior change.

1.0.1 - 2017-03-10

Added

• Store Conjur configuration and identity on the node, if not present.

1.0.0 - 2017-03-02

Changed

• v1.0.0 is a complete revamp of the module.
• This release includes several breaking changes.
• See README.md for complete details.

0.0.4 - 2015-05-11

Fixed

• fixed another instance of the same bug

0.0.2 - 2014-09-24

Fixed

• fixed a bug in host identity manifest preventing usage of host factory