conjur

Table of Contents

• Description
• Setup
  • Setup requirements
  • Deprecations
    • Puppet v5
    • Conjur Enterprise v4
    • Use of Host Factory Tokens
  • Using conjur-puppet with Conjur OSS
  • Conjur module basics
    • Sensitive data type
• Usage
  • Creating a Conjur host and providing its identity and API key
  • Using Conjur host factory
  • Using pre-established host identities (Conjur Enterprise v4 only)
• 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.

Setup

Setup requirements

This module requires that you have:

• Supported Puppet version:
  • Puppet v6 or equivalent EE version (Preliminary [Community level](https://github.com/cyberark/community/blob/master/Conjur/conventions/certification-levels.md#community support only)
  • Puppet v5 or equivalent EE version
• Conjur endpoint available to both the Puppet server and the Puppet nodes using this module. Supported versions:
  • Conjur OSS v1+
  • DAP v10+
  • Conjur Enterprise v4.9+

Deprecations

Puppet v5

Puppet v5 support is deprecated. 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 support is deprecated. 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 through this module is deprecated and will be removed in the next major version. 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.

Using conjur-puppet with Conjur OSS

Are you using this project with Conjur OSS? 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 function that can be used to retrieve secrets from Conjur. Given a Conjur variable identifier, conjur::secret uses the node’s Conjur identity to resolve and return the variable’s value.

$dbpass = conjur::secret('production/postgres/password')

Hiera attributes can also be used to inform which secret should be fetched, depending on the node running the Conjur module. For example, if hiera('domain') returns app1.example.com and a Conjur variable named domains/app1.example.com/ssl-cert exists, the SSL certificate can be retrieved and written to a file as shown below:

file { '/abslute/path/to/cert.pem':
  ensure    => file,
  content   => conjur::secret("domains/%{hiera('domain')}/ssl-cert"),
  show_diff => false # only required for Puppet < 4.6
  # diff will automatically get redacted in 4.6 if content is Sensitive
}

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

Sensitive data type

Note 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 secret as a string, you need to explicitly request it using the unwrap function; the result of the processing should be again wrapped in a Sensitive value.

In particular, you should not pass unwrapped secrets as resource parameters if you can avoid it. Many resource types support Sensitive data type and handle it correctly. If a resource you're using does not, file a bug.

$dbpass = conjur::secret('production/postgres/password')

# Use Sensitive data type to handle anything sensitive
$db_yaml = Sensitive("password: ${dbpass.unwrap}")

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

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.

In this module, we provide multiple ways to establish Conjur application identity for Puppet nodes, including:

• Creating a Conjur host and providing its identity and API key
• Using Conjur host factory
• Using pre-established host identities (Conjur Enterprise v4 only)

Note that the establishment of identity using host factory tokens and use of this module against Conjur Enterprise v4 is deprecated. See deprecations for more info.

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 or using host factories, 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 DAP instance you are connecting to. If using DAP, this may be the URL of a load balancer for the cluster's DAP follower instances.
• account - the account name for the Conjur / DAP instance you are connecting to.
• authn_login: The identity you are using to authenticate to the Conjur / DAP 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 / DAP instance.
• host_factory_token: The Conjur host factory token, provided as a string or using the Puppet file resource type.
• ssl_certificate: The PEM-encoded x509 CA certificate chain for the DAP instance you are connecting to, provided as a string 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: 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 and its API key to your manifest like this:

class { 'conjur':
  appliance_url   => 'https://conjur.mycompany.com/',
  account         => 'myorg',
  authn_login     => 'host/redis001',
  authn_api_key   => Sensitive('f9yykd2r0dajz398rh32xz2fxp1tws1qq2baw4112n4am9x3ncqbk3'),
  ssl_certificate => file('/absolute/path/to/conjur-ca.pem')
}

Using Hiera

You can also add the Conjur identity configuration to Hiera, which provides the Conjur identity information to the Puppet server:

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

conjur::appliance_url: 'https://conjur.mycompany.com/'
conjur::account: 'myorg'
conjur::authn_login: 'host/redis001'
conjur::authn_api_key: 'f9yykd2r0dajz398rh32xz2fxp1tws1qq2baw4112n4am9x3ncqbk3'
conjur::ssl_certificate: |
  -----BEGIN CERTIFICATE-----
  ...
  -----END CERTIFICATE-----

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

and 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.

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:

Value Name	Value Type	Description
Account	REG_SZ	Conjur account specified during Conjur setup.
ApplianceUrl	REG_SZ	Conjur API endpoint.
SslCertificate	REG_SZ	Public Conjur SSL cert. Overwritten by the contents read from CertFile when it is present.
Version	REG_DWORD	Conjur API version. Defaults to 5.

These may be set using Powershell (use either SslCertificate or CertFile but not both):

> 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-----..."
> reg ADD HKLM\Software\CyberArk\Conjur /v CertFile /t REG_SZ /d "C:\Absolute\Path\To\SslCertificate"

Or using a .reg registry file (use either SslCertificate or CertFile but not both):

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\CyberArk\Conjur]
"ApplianceUrl"="https://conjur.mycompany.com"
"Version"=dword:00000005
"Account"="myorg"
"SslCertificate"="-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----"
"CertFile"="C:\Absolute\Path\To\SslCertificate"

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.

Conjur host factory

Note that the establishment of identity using host factory tokens is deprecated. See deprecations for more info.

Conjur Host Factories are another method for creating new host identities in Conjur, and it ensures new hosts are created in an existing Conjur policy layer that is already entitled to access some secret values in Conjur. That is, when using host factory, nodes inherit the permissions of the layer for which the Host Factory token was generated.

The Conjur Puppet module is provided with a host factory token which is only used on the initial Puppet run to establish identity. In the initial Puppet run, the Conjur identity is created by the Puppet server and then stored on the agent's host. Subsequent runs use the created identity for Conjur authentication on the agent side (at the time of collecting facts), and the agent only provides the Puppet server with a temporary token to fetch secrets from Conjur.

Updating the Puppet manifest

To use a Host Factory token with this module, set variables authn_login and host_factory_token in the Puppet manifest. Do not set the variable authn_api_key when using host_factory_token as it is not required. authn_login should have a host/ prefix. The part after the slash is used as the node’s name in Conjur.

class { 'conjur':
  appliance_url      => 'https://conjur.mycompany.com/',
  account            => 'myorg',
  authn_login        => 'host/redis001',
  host_factory_token => Sensitive('3zt94bb200p69nanj64v9sdn1e15rjqqt12kf68x1d6gb7z33vfskx'),
  ssl_certificate    => file('/absolute/path/to/conjur-ca.pem')
}

Conjur automatically adds the annotation puppet: true to the Conjur host identities of all nodes using this Puppet module to bootstrap identity with host_factory_token.

Note that the establishment of identity using host factory tokens is deprecated. See deprecations for more info.

Using Hiera

Rather than storing the host factory token in the manifest, Puppet server can also be configured to retrieve the host factory token from Hiera when communicating with its agents:

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

conjur::appliance_url: 'https://conjur.mycompany.com/'
conjur::account: 'myorg'
conjur::authn_login: 'host/redis001'
conjur::host_factory_token: '3zt94bb200p69nanj64v9sdn1e15rjqqt12kf68x1d6gb7z33vfskx'
conjur::ssl_certificate: |
  -----BEGIN CERTIFICATE-----
  ...
  -----END CERTIFICATE-----

Note that the establishment of identity using host factory tokens is deprecated. See deprecations for more info.

Pre-established host identity (Conjur Enterprise v4 only)

Note that support for Conjur Enterprise v4 is deprecated. See deprecations for more info.

When using Conjur Enterprise v4 only, you can use conjurize or a similar method to establish host identity before running Puppet to configure. This way the Puppet master only ever handles a temporary access token instead of real, permanent Conjur credentials of the hosts it manages.

If a host is so pre-configured, the settings and credentials are automatically obtained and used. In this case, all that is needed to use conjur::secret is a simple

include conjur

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.