Add support for PostgreSQL certificate authentication

* Adds postgresql['cert_auth_addresses'] attribute
* Updates pg_hba.conf template to add entries in that attribute

changelogs/unreleased/postgresql-cert-hba.yml

+---
+title: Add support for cert authentication with PostgreSQL
+merge_request: 4618
+author:
+type: changed

doc/settings/database.md

@@ -168,7 +168,59 @@ gitlabhq_production=> SELECT * FROM pg_stat_ssl;
 (19 rows)
 ```
-Rows that have `t` listed under the `ssl` column are enabled.
+1. Rows that have `t` listed under the `ssl` column are enabled.
+1. Rows that have a value in the `clientdn` are using the `cert` authentication method
+
+#### Configure SSL client authentication
+
+Client SSL certificates can be used to authenticate to the database server. Creating the certificates
+is beyond the scope of `omnibus-gitlab`. But users who have an existing SSL certificate management solution
+can use this.
+
+##### Configure the database server
+
+1. Create a certificate and key for the server, the common name should equal the DNS name of the server
+1. Copy the server certificate, key, and CA file to the PostgreSQL server, and ensure the permissions are correct
+   1. The certificate should be owned by the database user (default: `gitlab-psql`)
+   1. The key file should be owned by the database user, and its permissions should be `0400`
+   1. The CA file should be owned by the database user, and its permissions should be `0400`
+
+   NOTE: **Note:**
+   Do not use the filenames `server.crt` or `server.key` for these files. These are reserved for internal use of `omnibus-gitlab`.
+
+1. Ensure the following is set in `gitlab.rb`.
+
+   ```ruby
+   postgresql['ssl_cert_file'] = 'PATH_TO_CERTIFICATE'
+   postgresql['ssl_key_file'] = 'PATH_TO_KEY_FILE'
+   postgresql['ssl_ca_file'] = 'PATH_TO_CA_FILE'
+   postgresql['listen_address'] = 'IP_ADDRESS'
+   postgresql['cert_auth_addresses'] = {
+   'IP_ADDRESS' => {
+     'database' => 'gitlabhq_production',
+     'user' => 'gitlab'
+   }
+   ```
+
+   `listen_address` should be set to an IP address of the server that the clients will use to connect to the database.
+   `cert_auth_addresses` should contain a list of IP addresses, and the databases and users that are allowed to connect to the database.
+1. Run `gitlab-ctl reconfigure` then `gitlab-ctl restart postgresql` in order for the new settings to take effect
+
+#### Configure the Rails client
+
+In order for the rails client to connect to the server, you will need a certficate and key with the `commonName` set to `gitlab`, that is signed by a certificate authority trusted in the CA file specified in `ssl_ca_file` on the database server.
+
+1. Configure `gitlab.rb`
+
+   ```ruby
+   gitlab_rails['db_host'] = 'IP_ADDRESS_OR_HOSTNAME_OF_DATABASE_SERVER'
+   gitlab_rails['db_sslcert'] = 'PATH_TO_CERTIFICATE_FILE'
+   gitlab_rails['db_sslkey'] = 'PATH_TO_KEY_FILE'
+   gitlab_rails['db_rootcert'] = 'PATH_TO_CA_FILE'
+   ```
+
+1. Run `gitlab-ctl reconfigure` for the rails client to use the new settings
+1. Follow the steps in [Verifying that SSL is being used](#verifying-that-ssl-is-being-used) to ensure the authentication is working.
 ### Configure packaged PostgreSQL server to listen on TCP/IP

files/gitlab-config-template/gitlab.rb.template

@@ -1048,6 +1048,12 @@ gitlab_rails['object_store']['objects']['pages']['bucket'] = nil
 # postgresql['ssl_key_file'] = 'server.key'
 # postgresql['ssl_ca_file'] = '/opt/gitlab/embedded/ssl/certs/cacert.pem'
 # postgresql['ssl_crl_file'] = nil
+# postgresql['cert_auth_addresses'] = {
+#   'ADDRESS' => {
+#     database: 'gitlabhq_production',
+#     user: 'gitlab'
+#   }
+# }
 ### Replication settings
 ###! Note, some replication settings do not require a full restart. They are documented below.

files/gitlab-cookbooks/postgresql/attributes/default.rb

@@ -34,6 +34,7 @@ default['postgresql']['ssl_cert_file'] = 'server.crt'
 default['postgresql']['ssl_key_file'] = 'server.key'
 default['postgresql']['ssl_ca_file'] = "#{node['package']['install-dir']}/embedded/ssl/certs/cacert.pem"
 default['postgresql']['ssl_crl_file'] = nil
+default['postgresql']['cert_auth_addresses'] = {}
 default['postgresql']['shmmax'] = /x86_64/.match?(node['kernel']['machine']) ? 17179869184 : 4294967295
 default['postgresql']['shmall'] = /x86_64/.match?(node['kernel']['machine']) ? 4194304 : 1048575

files/gitlab-cookbooks/postgresql/templates/default/pg_hba.conf.erb

@@ -89,3 +89,6 @@ host<% if @hostssl %>ssl<% end %>    replication <%= @sql_replication_user %> <%
   <% end %>
 <% end %>
+<% @cert_auth_addresses.each do |addr, data| %>
+hostssl <%= data['database'] %> <%= data['user'] %> <%= addr %> cert
+<% end %>

spec/chef/recipes/postgresql_spec.rb

@@ -832,6 +832,33 @@ RSpec.describe 'postgresql 9.6' do
       expect(postgresql_config).to notify('execute[reload postgresql]').to(:run).immediately
       expect(postgresql_config).to notify('execute[start postgresql]').to(:run).immediately
     end
+
+    context 'cert authentication' do
+      it 'is disabled by default' do
+        expect(chef_run).to render_file(pg_hba_conf).with_content { |content|
+          expect(content).to_not match(/cert$/)
+        }
+      end
+
+      it 'can be enabled' do
+        stub_gitlab_rb(
+          postgresql: {
+            cert_auth_addresses: {
+              '1.2.3.4/32' => {
+                database: 'fakedatabase',
+                user: 'fakeuser'
+              },
+              'fakehostname' => {
+                database: 'anotherfakedatabase',
+                user: 'anotherfakeuser'
+              },
+            }
+          }
+        )
+        expect(chef_run).to render_file(pg_hba_conf).with_content('hostssl fakedatabase fakeuser 1.2.3.4/32 cert')
+        expect(chef_run).to render_file(pg_hba_conf).with_content('hostssl anotherfakedatabase anotherfakeuser fakehostname cert')
+      end
+    end
   end
   it 'creates sysctl files' do