azure_key_vault

Table of Contents

1. Description
2. Setup
3. Managed Service Identity (MSI) vs Service Principal Credentials
4. How it works
   • Puppet Function
   • Hiera Backend
5. How it's secure by default
6. Usage
   • Embedding a secret in a file
   • Retrieving a specific version of a secret
   • Retrieving a certificate
7. Reference - An under-the-hood peek at what the module is doing and how
8. Development - Guide for contributing to the module

Description

Secure secrets management is essential and critical in order to protect data in the cloud. Key Vault is Microsoft Azure's solution to make this happen. This module provides a Puppet function and a Hiera backend that allows you to easily fetch secrets securely on the puppet server and embed them into catalogs during compilation time.

Setup

The module requires the following:

• Puppet Agent 6.0.0 or later.
• Azure Subscription with one or more vaults already created and loaded with secrets.
• One of the following authentication strategies
  • Managed Service Identity ( MSI )
    • Puppet Server running on a machine with Managed Service Identity ( MSI ) and assigned the appropriate permissions to pull secrets from the vault. To learn more or get help with this please visit https://docs.microsoft.com/en-us/azure/active-directory/managed-service-identity/tutorial-windows-vm-access-nonaad
  • Service Principal
    • Following the required steps to setup a Service Principal. To learn more or get help with this please visit https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app

Managed Service Identity (MSI) vs Service Principal Credentials

This module provides 2 ways for users to authenticate with azure key vault and pull secrets. These 2 options are Managed Service Identity ( MSI ) and Service Principal Credentials. We highly recommend you utilize Managed Service Identity over service principal credentials whenever possible. This is because you do not have to manage and secure a file on our machines that contain credentials! In some cases, Managed Service Identity ( MSI ) might not be an option for you. One example of this is if your Puppet server and some of your puppet agents are not hosted in Azure. In that case, you can create a Service Principal in Azure Active Directory, assign the appropriate permissions to this Service Principal, and both the function and Hiera Backend provided in this module can authenticate to Azure Keyvault using the credentials of this Service Principal.

How it works

Puppet Function

This module contains a Puppet 4 function that allows you to securely retrieve secrets from Azure Key Vault. In order to get started simply call the function in your manifests passing in the required parameters.

Using Managed Service Identity ( MSI )

$important_secret = azure_key_vault::secret('production-vault', 'important-secret', {
  vault_api_version    => '2016-10-01',
  metadata_api_version => '2018-04-02',
})

This example fetches the latest secret with the name "important-secret" from the vault named "production-vault". Under the covers it calls the Azure instance metadata service api to get an access token in order to make authenticated requests to the vault api on-behalf-of the MSI. Once the secret is returned you can begin to use it throughout your puppet code.

NOTE: In order to improve performance and avoid the request limit for the metadata service api the api token retrieved once then stored in a cache that exists for the duration of the puppet run.

In the above example the api_versions hash is important. It is pinning both of the Azure specific api's ( instance metadata api & vault api ) used under the hood to specific versions so that you have full control as to when your puppet code starts calling newer/older versions of the apis. In order to understand what versions are available to your regions please visit the azure documentation

• Instance Metadata Service Versions ( https://docs.microsoft.com/en-us/azure/virtual-machines/windows/instance-metadata-service )
• Vault Versions ( TBD )

Using Service Principal Credentials

$important_secret = azure_key_vault::secret('production-vault', 'important-secret', {
  vault_api_version    => '2016-10-01',
  service_principal_credentials => {
    tenant_id     => '00000000-0000-1234-1234-000000000000',
    client_id     => '00000000-0000-1234-1234-000000000000',
    client_secret => lookup('azure_client_secret'),
  }
})

This example show how to utilize service principal credentials if you for some reason are unable to use Managed Service Identity ( MSI ) at your organization. The client_secret must be of type "Sensitive". Please ensure you configure hiera to return the value wrapped in this type as this is what the secret function expects to ensure there is possibilty of leaking the client_secret.

Hiera Backend

This module contains a Hiera 5 backend that allows you to securely retrieve secrets from Azure key vault and use them in hiera.

Using Managed Service Identity ( MSI )

Add a new entry to the hierarchy hash in hiera.yaml providing the following required lookup options:

- name: 'Azure Key Vault Secrets'
    lookup_key: azure_key_vault::lookup
    options:
      vault_name: production-vault
      vault_api_version: '2016-10-01'
      metadata_api_version: '2018-04-02'
      key_replacement_token: '-'
      confine_to_keys:
        - '^azure_.*'
        - '^.*_password$'
        - '^password.*'

Using Service Principal Credentials

To utilize service principal credentials in hiera simply replace metadata_api_version with service_principal_credentials and ensure it points to a valid yaml file that contains the service principal credentials you would like to use.

- name: 'Azure Key Vault Secrets'
    lookup_key: azure_key_vault::lookup
    options:
      vault_name: production-vault
      vault_api_version: '2016-10-01'
      service_principal_credentials: '/etc/puppetlabs/puppet/azure_key_vault_credentials.yaml'
      key_replacement_token: '-'
      confine_to_keys:
        - '^azure_.*'
        - '^.*_password$'
        - '^password.*'

Below is the format of the file that is expected to contain your service principal credentials.

tenant_id: '00000000-0000-1234-1234-000000000000'
client_id: '00000000-0000-1234-1234-000000000000'
client_secret: some-secret

To retrieve a secret in puppet code you can use the lookup function:

notify { 'lookup':
  message => lookup('important-secret'),
}

The alias function can also be used in hiera files, for example to set class parameters:

some_class::password: "%{alias('important-secret')}"

NOTE: The alias function must be used in the above example. Attempting to use the lookup function inside of your hiera files will not work. This is because, when using lookup, the result is interpolated as a string. Since this module is safe by default, it always returns secrets as Sensitive[String]. The reason we have to use alias is because it will preserve the datatype of the value. More information can be found here

You can use a fact to specify different vaults for different groups of nodes. It is recommended to use a trusted fact such as trusted.extensions.pp_environment as these facts cannot be altered. Alternatively a custom trusted fact can be included in the certificate request

- name: 'Azure Key Vault Secrets from trusted fact'
    lookup_key: azure_key_vault::lookup
    options:
      vault_name: "%{trusted.extensions.pp_environment}"
      vault_api_version: '2016-10-01'
      metadata_api_version: '2018-04-02'
      key_replacement_token: '-'
      confine_to_keys:
        - '^azure_.*'
        - '^.*_password$'
        - '^password.*'

NOTE: While the above examples show manual lookups happening, it's recommended and considered a best practice to utilize Hiera's automatic parameter lookup (APL) within your puppet code

What is confine_to_keys?

By design, hiera will traverse the configured heiarchy for a given key until one is found. This means that there can be a potentially large number of web requests against azure key vault. In order to improve performance and prevent hitting the Azure KeyVault rate limits ( ex: currently there is a maximum of 2,000 lookups every 10 seconds allowed against a key vault), the confine_to_keys allows you to provide an array of regexs that help avoid making a remote call.

As an example, if you defined your confine_to_keys as shown below, hiera will only make a web request to get the secret in azure key vault when the key being lookedup matches atleast one of the provided regular expressions in the confine_to_keys array.

- name: 'Azure Key Vault Secrets from trusted fact'
    lookup_key: azure_key_vault::lookup
    options:
      vault_name: "%{trusted.extensions.pp_environment}"
      vault_api_version: '2016-10-01'
      metadata_api_version: '2018-04-02'
      key_replacement_token: '-'
      confine_to_keys:
        - '^azure_.*'
        - '^.*_password$'
        - '^password.*'

NOTE: The confine_to_keys is very important to make you sure get right. As a best practice, come up with some conventions to avoid having a large number of regexs you have to add/update/remove and also test. The above example provides a great starting point.

What is key_replacement_token?

KeyVault secret names can only contain the characters 0-9, a-z, A-Z, and -.

When relying on automatic parameter lookup, this is almost always going to contain the module delimiter (::) or underscores.

This module will automatically convert the variable name to a valid value by replacing every invalid character with the key_replacement_token value, which defaults to -.

For example, the hiera variable puppetdb::master::config::puppetdb_server will automatically be converted to puppetdb--master--config--puppetdb-server before being queried up in KeyVault.

When troubleshooting, you can run hiera from the commandline with the --explain option to see the key name being used :

  Using normalized KeyVault secret key for lookup: puppetdb--master--config--puppetdb-server

How it's secure by default

In order to prevent accidental leakage of your secrets throughout all of the locations puppet stores information the returned value of the azure_key_vault::secret function & Hiera backend return a string wrapped in a Sensitive data type. Lets look at an example of what this means and why it's important. Below is an example of pulling a secret and trying to output the value in a notice function.

$secret = azure_key_vault::secret('production-vault', 'important-secret', {
  metadata_api_version => '2018-04-02',
  vault_api_version    => '2016-10-01',
})
notice($secret)

This outputs Notice: Scope(Class[main]): Sensitive [value redacted]

However, Sometimes you need to unwrap the secret to get to the original data. This is typically needed under the following but not limited to circumstances.

1. You need to programatically change/alter/append to the secret that was retrieved.
2. The resource you are passing the secret to does not natively handle the Sensitive data type.

These 2 special cases are discussed in detail next.

Special Case 1 - Programatically Changing/Altering/Appending to a secret

In order to change the original secret you always follow the same 3 step process.

1. unwrap
2. alter/change
3. rewrap

$secret = azure_key_vault::secret('production-vault', 'important-secret', {
  metadata_api_version => '2018-04-02',
  vault_api_version    => '2016-10-01',
})

$rewraped_secret = Sensitive("password: ${secret.unwrap}")

file { 'C:\\DataForApplication.secret':
  content   => $rewraped_secret,
  ensure    => file,
}

Special Case 2 - A Resource doesn't natively support Puppet's Sensitive Data type

Unfortunately, All resource's don't magically handle the sensitive data type. In order to know if a resource supports it or not simply read the documentation or browse through the code if it's available. If you are using a resource that doesn't support the sensitive data type you can unwrap the secret but but you are no longer guaranteed the secret will not get leaked in logs/reports depending on what the resource does with the secret you passed to it. Below is an example of an imaginary resource that doesn't support the sensitive data type and how you can unwrap to handle this situation.

$admin_password_secret = azure_key_vault::secret('production-vault', 'important-secret', {
  metadata_api_version => '2018-04-02',
  vault_api_version    => '2016-10-01',
})

resource_not_supporting_sensitive { 'my_resource':
    username => 'admin',
    password => $admin_password_secret.unwrap,
}

NOTE: Whatever resource you run into that doesn't support the sensitive data type you should open a issue/ticket with the person/organization maintaining the resource.

Usage

Embedding a secret in a file

Below shows an example of how to retrieve a secret and place it in a file on a node. This is typically done because some application/process is expecting the file to exist with the secret in order to get some work done ( such as connecting to a database ).

file { 'C:\\DataForApplication.secret':
  content   => azure_key_vault::secret('production-vault', 'important-secret', {
    metadata_api_version => '2018-04-02',
    vault_api_version    => '2016-10-01',
  }),
  ensure    => file,
}

Retrieving a specific version of a secret

By Default, the latest secret is always retrieved from the vault. If you want to ensure only a specific version of a secret is retrieved simply pass a parameter to specify the exact version you want.

$admin_password_secret = azure_key_vault::secret('production-vault', 'admin-password', {
  metadata_api_version => '2018-04-02',
  vault_api_version    => '2016-10-01',
},
'067e89990f0a4a50a7bd854b40a56089')

NOTE: Retrieving a specific version of a secret is currently not available via the hiera backend

Retrieving a certificate

Azure Key Vault stores certificates "under-the-covers" as secrets. This means you retrieving certificates can be done using the same azure_key_vault::secret function. One thing to keep in mind is that the certificate will be based64 encoded and will need to be decoded before usage to have a valid certificate file.

$certificate_secret = azure_key_vault::secret('production-vault', "webapp-certificate", {
  metadata_api_version => '2018-04-02',
  vault_api_version    => '2016-10-01',
})

file { "C:/tmp/webapp-certificate.pfx" :
  content   => base64('decode', "${certificate_secret.unwrap}"),
  ensure    => file,
}

sslcertificate { "Install-WebApp-Certificate" :
  name       => "${filename}",
  location   => 'C:\tmp',
  root_store => 'LocalMachine',
  thumbprint => "${certificate_thumbprint}"
}

NOTE: Retrieving a specific version of a secret is currently not available via the hiera backend

Reference

See REFERENCE.md

Development

Contributing

1. Fork it ( https://github.com/tragiccode/tragiccode-azure_key_vault/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Reference

Table of Contents

Functions

• azure_key_vault::lookup
• azure_key_vault::secret: Retrieves secrets from Azure's Key Vault.

Functions

azure_key_vault::lookup

Type: Ruby 4.x API

The azure_key_vault::lookup function.

`azure_key_vault::lookup(Variant[String, Numeric] $secret_name, Struct[{

  vault_name => String,
  vault_api_version => String,
  Optional[metadata_api_version] => String,
  confine_to_keys => Array[String],
  Optional[key_replacement_token] => String,
  Optional[service_principal_credentials] => String
}] $options, Puppet::LookupContext $context)`

The azure_key_vault::lookup function.

Returns: Variant[Sensitive, Undef]

secret_name

Data type: Variant[String, Numeric]

options

Data type:

Struct[{
      vault_name => String,
      vault_api_version => String,
      Optional[metadata_api_version] => String,
      confine_to_keys => Array[String],
      Optional[key_replacement_token] => String,
      Optional[service_principal_credentials] => String
    }]

context

Data type: Puppet::LookupContext

azure_key_vault::secret

Type: Ruby 4.x API

Retrieves secrets from Azure's Key Vault.

`azure_key_vault::secret(String $vault_name, String $secret_name, Struct[{

  vault_api_version => String,
  Optional[metadata_api_version] => String,
  Optional[service_principal_credentials] => Struct[{
    tenant_id => String,
    client_id => String,
    client_secret => String
  }]
}] $api_endpoint_hash, Optional[String] $secret_version)`

Retrieves secrets from Azure's Key Vault.

Returns: Sensitive[String] Returns the secret as a String wrapped with the Sensitive data type.

vault_name

Data type: String

Name of the vault in your Azure subscription.

secret_name

Data type: String

Name of the secret to be retrieved.

api_endpoint_hash

Data type:

Struct[{
      vault_api_version => String,
      Optional[metadata_api_version] => String,
      Optional[service_principal_credentials] => Struct[{
        tenant_id => String,
        client_id => String,
        client_secret => String
      }]
    }]

A Hash with API endpoint and authentication information

secret_version

Data type: Optional[String]

The version of the secret you want to retrieve. This parameter is optional and if not passed the default behavior is to retrieve the latest version.

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.

v3.5.0 - 2024-10-29

Full Changelog

Added

• (GH-132) Update all github workflows to match puppetlabs #133 (TraGicCode)

v3.4.0 - 2024-10-29

Full Changelog

Added

• (GH-124) Update supported Operating Systems #125 (TraGicCode)

v3.3.0 - 2023-09-08

Full Changelog

Added

• (GH-114) Update supported os #117 (TraGicCode)
• (GH-114) Update supported os versions #115 (TraGicCode)
• (GH-107) Add puppet 8 support #111 (TraGicCode)

v3.2.0 - 2023-09-08

Full Changelog

Added

• (GH-107) Add puppet 8 support #108 (TraGicCode)

v3.1.1 - 2023-01-14

Full Changelog

Fixed

• (GH-101) Fix documentation for secret lookup using hiera data file interpolation #102 (TraGicCode)

v3.1.0 - 2022-09-23

Full Changelog

Added

• (GH-94) Support for service principal authentication #93 (kev-in-shu)

v3.0.0 - 2022-08-14

Full Changelog

Changed

• (GH-95) Wrap hiera return in puppet sensitive data type #96 (TraGicCode)

v2.1.0 - 2022-08-07

Full Changelog

Added

• (GH-90) Add windows server 2022 support #91 (TraGicCode)

v2.0.2 - 2022-08-03

Full Changelog

Fixed

• (GH-87) Stop logging secret not found in hiera lookup as warning #88 (TraGicCode)
• Fix issue in which confine_to_keys must be an array of strings instead of regexp's #77 (TraGicCode)

v2.0.1 - 2021-07-14

Full Changelog

Fixed

• Fix issue in which confine_to_keys must be an array of strings instead of regexp's #77 (TraGicCode)

v2.0.0 - 2021-07-14

Full Changelog

Changed

• (GH-69) Add code and tests for new requires confine_to_keys options #75 (TraGicCode)

v1.1.2 - 2021-04-29

Full Changelog

Fixed

• (GH-39) Normalize key names for hiera lookup #67 (dowlingw)

v1.1.1 - 2021-04-22

Full Changelog

Fixed

• (GH-65) Managed identity access token not being cached in hiera lookups #66 (dowlingw)

v1.1.0 - 2020-02-17

Full Changelog

Added

• (GH-58) Cache Metadata API Token for lifetime of puppet run #59 (TraGicCode)

1.0.2 - 2018-12-19

Full Changelog

Fixed

• (GH-47) Fix ruby 1.9 issue with uri #48 (TraGicCode)

1.0.1 - 2018-12-14

Full Changelog

Fixed

• (GH-42) Fix .empty? method missing on uri #45 (TraGicCode)
• (GH-43) Fix debug message #44 (TraGicCode)
• Fix typo in readme.md #29 (lupyana)

1.0.0 - 2018-10-25

Full Changelog

Added

• (GH-12) Added Better Unit Tests to puppet function #25 (TraGicCode)

0.4.0 - 2018-10-24

Full Changelog

Added

• Add a Hiera backend #13 (hbuckle)

0.3.0 - 2018-09-26

Full Changelog

Added

• Specify Puppet 6 support #8 (turbodog)

Fixed

• Change log level from info to debug #10 (TraGicCode)
• Add missing comma in readme.md #9 (TraGicCode)

0.2.0 - 2018-08-23

Full Changelog

Added

• (feature) Update to pdk 1.7.0 #2 (TraGicCode)

0.1.0 - 2018-05-15

Full Changelog