Configuring security settings

Ensure your PE environment is secure by configuring security settings.

Configure cipher suites

Due to regulatory compliance or other security requirements, you may need to change which cipher suites your SSL-enabled PE services use to communicate with other PE components. See Compatible ciphers to ensure your ciphers are compatible with PE.

To add or remove cipher suites for certain types of services, use Hiera to add an array of ciphers to these parameters:

puppet_enterprise::ssl_cipher_suites
Set an array of ciphers, in IANA format, for all Java-based services: PuppetDB, Puppet Server, console services, and the orchestrator.
For example:
puppet_enterprise::ssl_cipher_suites:
- 'TLS_AES_256_GCM_SHA384'
- 'TLS_AES_128_GCM_SHA256'
- 'TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256'
- 'TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384'
puppet_enterprise::ssl_cipher_suites_non_java
Set an array of ciphers, in OpenSSL format, for all non-Java services: Bolt Server, ACE Server, PostgreSQL.
For example:
puppet_enterprise::ssl_cipher_suites_non_java:
- 'ECDHE-ECDSA-AES128-GCM-SHA256'
- 'ECDHE-ECDSA-AES256-GCM-SHA384'
- 'ECDHE-RSA-AES128-GCM-SHA256'
- 'ECDHE-RSA-AES256-GCM-SHA384'
puppet_enterprise::ssl_cipher_suites_browser
Set an array of ciphers, in OpenSSL format, accepted by the PE console in the browser (NGINX).
For example:
puppet_enterprise::ssl_cipher_suites_browser:
- 'TLS_CHACHA20_POLY1305_SHA256'
- 'ECDHE-ECDSA-CHACHA20-POLY1305'
- 'ECDHE-RSA-CHACHA20-POLY1305'
- 'ECDHE-ECDSA-AES128-GCM-SHA256'

Configure SSL protocols

Add or remove SSL protocols in your PE infrastructure.

To change what SSL protocols your PE infrastructure uses, use Hiera or the console to add or remove protocols.

Use the parameter puppet_enterprise::master::puppetserver::ssl_protocols and add an array for protocols you want to include, or remove protocols you no longer want to use.

For example, to enable TLSv1.1 and TLSv1.2, set the following parameter in the PE Infrastructure group in the console or in your Hiera data.
puppet_enterprise::master::puppetserver::ssl_protocols: ["TLSv1.3", "TLSv1.2"]
Note: To comply with security regulations, PE 2019.8.9 and later uses only version 1.2 and 1.3 of the Transport Layer Security (TLS) protocol.

Configure RBAC and token-based authentication settings

Tune RBAC and token-based authentication settings, like setting the number of failed attempts a user has before they are locked out of the console or changing the amount of time a token is valid for.

RBAC and token authentication settings can be changed in the PE Infrastructure group in the console or in your Hiera data. Below is a list of related settings.
puppet_enterprise::profile::console::rbac_failed_attempts_lockout
An integer specifying how many failed login attempts are allowed on an account before the account is revoked. The default is "10" (attempts).
puppet_enterprise::profile::console::rbac_password_reset_expiration
An integer representing the number of hours that password reset tokens are valid. An administrator generates these token for users to reset their passwords.
Default: 24 hours
puppet_enterprise::profile::console::rbac_session_timeout
Integer representing, in minutes, how long a user's session can last. The session length is the same for node classification, RBAC, and the console. The default is "60" (minutes).
puppet_enterprise::profile::console::rbac_token_auth_lifetime
A value representing the default authentication lifetime for a token. It cannot exceed the rbac_token_maximum_lifetime. This is represented as a numeric value followed by "y" (years), "d" (days), "h" (hours), "m" (minutes), or "s" (seconds). The default is "1h".
puppet_enterprise::profile::console::rbac_token_maximum_lifetime
A value representing the maximum allowable lifetime for all tokens. This is represented as a numeric value followed by "y" (years), "d" (days), "h" (hours), "m" (minutes), or "s" (seconds). The default is "10y".
puppet_enterprise::profile::console::rbac_account_expiry_check_minutes
An integer that specifies, in minutes, how often the application checks for idle user accounts. The default value is "60" (minutes).
puppet_enterprise::profile::console::rbac_account_expiry_days
An integer that specifies, in days, the duration before an inactive user account expires. The default is undefined. To activate the feature, add a value of "1" or greater.
If a non-superuser hasn't logged into the console during this specified period, their user status updates to revoked. After creating an account, if a non-superuser hasn't logged in to the console during the specified period, their user status updates to revoked.
Note: If you do not specify the rbac_account_expiry_days parameter, the rbac_account_expiry_check_minutes parameter is ignored.

RBAC database configuration

Credential information for the RBAC service is stored in a PostgreSQL database.

The configuration information for that database is found in the 'rbac-database' section of the config.

For example:

rbac-database: {
  classname: org.postgresql.Driver
  subprotocol: postgresql
  subname: "//<path-to-host>:5432/perbac"
  user: <username here>
  password: <password here>
}

classname

Used by the RBAC service for connecting to the database; this option should always be org.postgresql.Driver.

subprotocol

Used by the RBAC service for connecting to the database; this options should always be postgresql.

subname

JDBC connection path used by the RBAC service for connecting to the database. This should be set to the hostname and configured port of the PostgreSQL database. perbac is the database the RBAC service uses to store credentials.

user

This is the username the RBAC service should use to connect to the PostgreSQL database.

password

This is the password the RBAC service should use to connect to the PostgreSQL database.

Configure the password algorithm

PE uses SHA-256 as a default password algorithm, but you can change the algorithm to argon2id by editing or adding password algorithm parameters using the console or Hiera. Before changing your password algorithm to argon2id, review argon2 specifications.

Note: If you are using a FIPS-enabled install of PE, we recommend you continue to use the default SHA-256 algorithm. Argon2id isn’t available for FIPS-enabled systems.
puppet_enterprise::profile::console::password_algorithm
String. One of either SHA-256 or ARGON2ID
Defaullt: SHA-256
puppet_enterprise::profile::console::password_hash_output_size
Integer. The desired hash output size, in bytes. This is required when configuring argon2id only.
Default: 128 (bytes)
puppet_enterprise::profile::console::password_algorithm_parallelism
Integer. The number of parallel computations to do at once. This is required when configuring argon2id only.
Default: Twice the number of cores in your system.
puppet_enterprise::profile::console::password_algorithm_memory_in_kb
Integer. The amount of memory the algorithm consumes when running, in kb. This value is required when configuring argon2id only. To start, we recommend setting it to 25% of your CPU memory.
puppet_enterprise::profile::console::number_of_iterations
Integer. The number of times a password is hashed before it’s stored. We recommend you update this value when switching from SHA-256 to argon2id.The minimum recommended value for argon2id is 3 (iterations).
Default: 500000 (iterations)
puppet_enterprise::profile::console::password_salt_size_bytes
Integer. The size of each generated salt, in bytes.
Default: 128 (bytes)

Add a custom HSTS header to NGINX

An HTTP Strict Transport Security response header (HSTS) is a security header that blocks access to non-HTTPS content, preventing the browser from being exploited by man-in-the-middle attacks. HSTS headers do not allow the use of self-signed certificates, so if you want to enable an HSTS header, you must first add a custom certificate with a trusted CA to the console. Then, use a custom NGINX module to define and manage the header content.

Before you begin
Add a custom certificate. See Use a custom SSL certificate for the console.

  1. Write a custom NGINX module for managing the headers that includes a headers.conf file. For example, the custom module nginxcustom has this location and structure:
    /etc/puppetlabs/code/environments/production/modules/nginxcustom
    ├── files 
    │       └── headers.conf 
    └── manifests 
    	└── init.pp
    To learn about writing custom modules, see the Beginner's guide to writing modules.
  2. Define the header content in the header.conf file. For example:
    # cat files/headers.conf
    
    #Custom headers 
    add_header X-Frame-Options SAMEORIGIN always; 
    add_header X-Content-Type-Options nosniff; 
    add_header X-XSS-Protection '1; mode=block'; 
    add_header Strict-Transport-Security 'max-age=63072000; includeSubDomains; preload;';
  3. In manifests/init.pp, create a file resource that points to the module you're using to manage your headers.conf file. For example, to point to the nginxcustom module:
    # cat manifests/init.pp
    
     #File resource to create headers.conf
     class nginxcustom {
        file { '/etc/puppetlabs/nginx/headers.conf':
          ensure => file,
          group => 'root',
          owner => 'root',
          mode => '0644',
          source =>'puppet:///modules/nginxcustom/headers.conf',
         }
    }
  4. In manifests/init.pp, use pe_nginx::directive to include the headers.conf file in the proxy.conf configuration file, allowing the headers to appear in the NGINX configuration in PE.
    #Nginx directive to add include statement 
    pe_nginx::directive { 'include custom headers': 
    directive_ensure => 'present', 
    target => '/etc/puppetlabs/nginx/conf.d/proxy.conf', 
    directive_name => 'include', 
    value => 'headers.conf', 
    server_context => $::fqdn, } 
    }
  5. Run Puppet: puppet agent -t