From 3ea05a59dc6b309bda5eace2b88eb50c33b8f068 Mon Sep 17 00:00:00 2001 From: ngala Date: Tue, 14 May 2024 13:15:00 +0530 Subject: [PATCH 1/8] Docs: Support mutual TLS in GitLab Pages with GitLab API Related: https://gitlab.com/gitlab-org/gitlab-pages/-/issues/548 Changelog: other --- doc/administration/pages/index.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index d85682f3580d2c..5b6670b40849fd 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -397,6 +397,8 @@ control over how the Pages daemon runs and serves content in your environment. | `artifacts_server_url` | API URL to proxy artifact requests to. Defaults to GitLab `external URL` + `/api/v4`, for example `https://gitlab.com/api/v4`. When running a [separate Pages server](#running-gitlab-pages-on-a-separate-server), this URL must point to the main GitLab server's API. | | `auth_redirect_uri` | Callback URL for authenticating with GitLab. Defaults to project's subdomain of `pages_external_url` + `/auth`, for example `https://projects.example.io/auth`. When `namespace_in_path` is enabled, defaults to `pages_external_url` + `/projects/auth`, for example `https://example.io/projects/auth`. | | `auth_secret` | Secret key for signing authentication requests. Leave blank to pull automatically from GitLab during OAuth registration. | +| `client_cert_key_pairs` | Client certificates and keys used for mutual TLS with the GitLab API. See [Support mutual TLS when calling the GitLab API](#support-mutual-tls-when-calling-the-gitlab-api) for details. | +| `ca_certs` | Root CA certificates used to sign client certificate used for mutual TLS with the GitLab API. See [Support mutual TLS when calling the GitLab API](#support-mutual-tls-when-calling-the-gitlab-api) for details. | | `dir` | Working directory for configuration and secrets files. | | `enable` | Enable or disable GitLab Pages on the current system. | | `external_http` | Configure Pages to bind to one or more secondary IP addresses, serving HTTP requests. Multiple addresses can be given as an array, along with exact ports, for example `['1.2.3.4', '1.2.3.5:8063']`. Sets value for `listen_http`. | @@ -683,6 +685,34 @@ For Linux package installations, this is fixed by [installing a custom CA](https For self-compiled installations, this can be fixed by installing the custom Certificate Authority (CA) in the system certificate store. +### Support mutual TLS when calling the GitLab API + +If GitLab has been [configured to require mutual TLS](https://docs.gitlab.com/omnibus/settings/ssl/#enable-2-way-ssl-client-authentication), +you need to add the client certificates to Pages: + +#### Certificate requirements + +- The certificate must specify the address you use to access the GitLab Pages. You must add the hostname or IP address as a Subject Alternative Name to the certificate. +- The certificate's Common Name field is ignored. +- The certificate should be full chain of certificate containing end user certificate, all intermediate certificate and root certificate. + +1. Configure in `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_pages['client_cert_key_pairs'] = [':'] + ``` + + Where `` and `` are the file paths to the client certificate and its respective key file. +1. When using certificates issued by a custom CA, add root certificate to Pages in `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_pages['ca-certs'] = [''] + ``` + + Where `` are the file paths to the root CA certificates seperated by commas. +1. To configure GitLab to trust the GitLab Pages certificates, Copy the full chain of certificate file into the `/etc/gitlab/trusted-certs` directory. + If you have a multi-node installation, make sure to copy the certificate in all nodes. + ### ZIP serving and cache configuration WARNING: -- GitLab From 952938bd802bc30cf53b08435a96a8b5f0cb55ca Mon Sep 17 00:00:00 2001 From: Naman Jagdish Gala Date: Wed, 15 May 2024 04:58:57 +0000 Subject: [PATCH 2/8] Apply suggestions --- doc/administration/pages/index.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 5b6670b40849fd..ec8eb668684664 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -688,29 +688,31 @@ Authority (CA) in the system certificate store. ### Support mutual TLS when calling the GitLab API If GitLab has been [configured to require mutual TLS](https://docs.gitlab.com/omnibus/settings/ssl/#enable-2-way-ssl-client-authentication), -you need to add the client certificates to Pages: +you need to add a client certificates to your GitLab Pages configuration. -#### Certificate requirements +**Certificate requirements**: -- The certificate must specify the address you use to access the GitLab Pages. You must add the hostname or IP address as a Subject Alternative Name to the certificate. +- The certificate must specify the hostname or IP address as a Subject Alternative Name to the certificate. - The certificate's Common Name field is ignored. -- The certificate should be full chain of certificate containing end user certificate, all intermediate certificate and root certificate. +- The full certificate chain is required. It must include the root and intermediate certificates, as well as the end user certificate. -1. Configure in `/etc/gitlab/gitlab.rb`: +Follow these steps to configure the certificates in your GitLab Pages server: + +1. Edit `/etc/gitlab/gitlab.rb`: ```ruby gitlab_pages['client_cert_key_pairs'] = [':'] ``` - Where `` and `` are the file paths to the client certificate and its respective key file. -1. When using certificates issued by a custom CA, add root certificate to Pages in `/etc/gitlab/gitlab.rb`: +1. If you used a custom Certificate Authority (CA), you must add the root certificate to `/etc/gitlab/gitlab.rb`: ```ruby gitlab_pages['ca-certs'] = [''] ``` Where `` are the file paths to the root CA certificates seperated by commas. -1. To configure GitLab to trust the GitLab Pages certificates, Copy the full chain of certificate file into the `/etc/gitlab/trusted-certs` directory. + +1. Copy the full certificate chain file(s) into the `/etc/gitlab/trusted-certs` directory of all your GitLab Nodes. If you have a multi-node installation, make sure to copy the certificate in all nodes. ### ZIP serving and cache configuration -- GitLab From 10f0727e952784c15a64720d1d4edf057209d240 Mon Sep 17 00:00:00 2001 From: Naman Jagdish Gala Date: Wed, 15 May 2024 10:53:11 +0000 Subject: [PATCH 3/8] Apply suggestions --- doc/administration/pages/index.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index ec8eb668684664..f74c5acaac5f45 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -687,16 +687,20 @@ Authority (CA) in the system certificate store. ### Support mutual TLS when calling the GitLab API -If GitLab has been [configured to require mutual TLS](https://docs.gitlab.com/omnibus/settings/ssl/#enable-2-way-ssl-client-authentication), -you need to add a client certificates to your GitLab Pages configuration. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/548) in GitLab 17.1. -**Certificate requirements**: +If GitLab is [configured to require mutual TLS](https://docs.gitlab.com/omnibus/settings/ssl/#enable-2-way-ssl-client-authentication), +you must add client certificates to your GitLab Pages configuration. -- The certificate must specify the hostname or IP address as a Subject Alternative Name to the certificate. -- The certificate's Common Name field is ignored. -- The full certificate chain is required. It must include the root and intermediate certificates, as well as the end user certificate. +Certificates have these requirements: -Follow these steps to configure the certificates in your GitLab Pages server: +- The certificate must specify the hostname or IP address as a Subject Alternative Name. +- The full certificate chain is required, including the root and intermediate certificates, + and the end user certificate. + +The certificate's Common Name field is ignored. + +To configure the certificates in your GitLab Pages server: 1. Edit `/etc/gitlab/gitlab.rb`: @@ -710,7 +714,7 @@ Follow these steps to configure the certificates in your GitLab Pages server: gitlab_pages['ca-certs'] = [''] ``` - Where `` are the file paths to the root CA certificates seperated by commas. + Where `` are the file paths to the root CA certificates separated by commas. 1. Copy the full certificate chain file(s) into the `/etc/gitlab/trusted-certs` directory of all your GitLab Nodes. If you have a multi-node installation, make sure to copy the certificate in all nodes. -- GitLab From 0fcd036bd13b380738f8b1cfe6d3f075fbecb4ad Mon Sep 17 00:00:00 2001 From: ngala Date: Wed, 15 May 2024 18:25:07 +0530 Subject: [PATCH 4/8] Docs: Support mutual TLS in GitLab Pages with GitLab API --- doc/administration/pages/index.md | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index f74c5acaac5f45..070a53136c373b 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -695,29 +695,39 @@ you must add client certificates to your GitLab Pages configuration. Certificates have these requirements: - The certificate must specify the hostname or IP address as a Subject Alternative Name. -- The full certificate chain is required, including the root and intermediate certificates, - and the end user certificate. +- The full certificate chain is required, including the end-user certificate, intermediate certificates, + and the root certificate in the specified order. The certificate's Common Name field is ignored. To configure the certificates in your GitLab Pages server: +1. On the GitLab Pages nodes, create the `/etc/gitlab/ssl` directory and copy your key and full certificate chain there: + + ```shell + sudo mkdir -p /etc/gitlab/ssl + sudo chmod 755 /etc/gitlab/ssl + sudo cp key.pem cert.pem /etc/gitlab/ssl/ + sudo chmod 644 key.pem cert.pem + ``` + 1. Edit `/etc/gitlab/gitlab.rb`: ```ruby - gitlab_pages['client_cert_key_pairs'] = [':'] + gitlab_pages['client_cert_key_pairs'] = ['/etc/gitlab/ssl/cert.pem:/etc/gitlab/ssl/key.pem'] ``` -1. If you used a custom Certificate Authority (CA), you must add the root certificate to `/etc/gitlab/gitlab.rb`: +1. If you used a custom Certificate Authority (CA), you must copy root CA certificate to `/etc/gitlab/ssl` + and edit `/etc/gitlab/gitlab.rb`: ```ruby - gitlab_pages['ca-certs'] = [''] + gitlab_pages['ca_certs'] = ['/etc/gitlab/ssl/ca.pem'] ``` - Where `` are the file paths to the root CA certificates separated by commas. + Where the file paths to the custom Certificate Authority (CA)s are separated by commas. -1. Copy the full certificate chain file(s) into the `/etc/gitlab/trusted-certs` directory of all your GitLab Nodes. - If you have a multi-node installation, make sure to copy the certificate in all nodes. +1. If you have a multi-node GitLab Pages installation, perform above steps in all the nodes. +1. Save a copy of the full certificate chain files in the `/etc/gitlab/trusted-certs` directory on all your GitLab Nodes. ### ZIP serving and cache configuration -- GitLab From c49f0136d78f2e66168e5ef1f3e05a51f0734ad6 Mon Sep 17 00:00:00 2001 From: Naman Jagdish Gala Date: Thu, 16 May 2024 05:00:10 +0000 Subject: [PATCH 5/8] Apply suggestions --- doc/administration/pages/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 070a53136c373b..eafd61aa1f462d 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -696,7 +696,7 @@ Certificates have these requirements: - The certificate must specify the hostname or IP address as a Subject Alternative Name. - The full certificate chain is required, including the end-user certificate, intermediate certificates, - and the root certificate in the specified order. + and the root certificate, in that order. The certificate's Common Name field is ignored. @@ -717,16 +717,16 @@ To configure the certificates in your GitLab Pages server: gitlab_pages['client_cert_key_pairs'] = ['/etc/gitlab/ssl/cert.pem:/etc/gitlab/ssl/key.pem'] ``` -1. If you used a custom Certificate Authority (CA), you must copy root CA certificate to `/etc/gitlab/ssl` +1. If you used a custom Certificate Authority (CA), you must copy the root CA certificate to `/etc/gitlab/ssl` and edit `/etc/gitlab/gitlab.rb`: ```ruby gitlab_pages['ca_certs'] = ['/etc/gitlab/ssl/ca.pem'] ``` - Where the file paths to the custom Certificate Authority (CA)s are separated by commas. + File paths for multiple custom Certificate Authority (CA)s are separated by commas. -1. If you have a multi-node GitLab Pages installation, perform above steps in all the nodes. +1. If you have a multi-node GitLab Pages installation, repeat these steps in all the nodes. 1. Save a copy of the full certificate chain files in the `/etc/gitlab/trusted-certs` directory on all your GitLab Nodes. ### ZIP serving and cache configuration -- GitLab From 071a7745d5e8d2dee86a06eb35f98e205a996c12 Mon Sep 17 00:00:00 2001 From: ngala Date: Mon, 20 May 2024 09:52:50 +0530 Subject: [PATCH 6/8] Client cert and key as separate fields --- doc/administration/pages/index.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index eafd61aa1f462d..6e4330044c560e 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -397,7 +397,8 @@ control over how the Pages daemon runs and serves content in your environment. | `artifacts_server_url` | API URL to proxy artifact requests to. Defaults to GitLab `external URL` + `/api/v4`, for example `https://gitlab.com/api/v4`. When running a [separate Pages server](#running-gitlab-pages-on-a-separate-server), this URL must point to the main GitLab server's API. | | `auth_redirect_uri` | Callback URL for authenticating with GitLab. Defaults to project's subdomain of `pages_external_url` + `/auth`, for example `https://projects.example.io/auth`. When `namespace_in_path` is enabled, defaults to `pages_external_url` + `/projects/auth`, for example `https://example.io/projects/auth`. | | `auth_secret` | Secret key for signing authentication requests. Leave blank to pull automatically from GitLab during OAuth registration. | -| `client_cert_key_pairs` | Client certificates and keys used for mutual TLS with the GitLab API. See [Support mutual TLS when calling the GitLab API](#support-mutual-tls-when-calling-the-gitlab-api) for details. | +| `client_cert` | Client certificate used for mutual TLS with the GitLab API. See [Support mutual TLS when calling the GitLab API](#support-mutual-tls-when-calling-the-gitlab-api) for details. | +| `client_key` | Client key used for mutual TLS with the GitLab API. See [Support mutual TLS when calling the GitLab API](#support-mutual-tls-when-calling-the-gitlab-api) for details. | | `ca_certs` | Root CA certificates used to sign client certificate used for mutual TLS with the GitLab API. See [Support mutual TLS when calling the GitLab API](#support-mutual-tls-when-calling-the-gitlab-api) for details. | | `dir` | Working directory for configuration and secrets files. | | `enable` | Enable or disable GitLab Pages on the current system. | @@ -714,7 +715,8 @@ To configure the certificates in your GitLab Pages server: 1. Edit `/etc/gitlab/gitlab.rb`: ```ruby - gitlab_pages['client_cert_key_pairs'] = ['/etc/gitlab/ssl/cert.pem:/etc/gitlab/ssl/key.pem'] + gitlab_pages['client_cert'] = ['/etc/gitlab/ssl/cert.pem'] + gitlab_pages['client_key'] = ['/etc/gitlab/ssl/key.pem'] ``` 1. If you used a custom Certificate Authority (CA), you must copy the root CA certificate to `/etc/gitlab/ssl` -- GitLab From 586812dc4bbb5caa57f69c2f83a3dcfecfe219d7 Mon Sep 17 00:00:00 2001 From: ngala Date: Tue, 28 May 2024 17:19:21 +0530 Subject: [PATCH 7/8] Rename ca_certs to client_ca_certs --- doc/administration/pages/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 6e4330044c560e..8e33cad0bd134c 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -399,7 +399,7 @@ control over how the Pages daemon runs and serves content in your environment. | `auth_secret` | Secret key for signing authentication requests. Leave blank to pull automatically from GitLab during OAuth registration. | | `client_cert` | Client certificate used for mutual TLS with the GitLab API. See [Support mutual TLS when calling the GitLab API](#support-mutual-tls-when-calling-the-gitlab-api) for details. | | `client_key` | Client key used for mutual TLS with the GitLab API. See [Support mutual TLS when calling the GitLab API](#support-mutual-tls-when-calling-the-gitlab-api) for details. | -| `ca_certs` | Root CA certificates used to sign client certificate used for mutual TLS with the GitLab API. See [Support mutual TLS when calling the GitLab API](#support-mutual-tls-when-calling-the-gitlab-api) for details. | +| `client_ca_certs` | Root CA certificates used to sign client certificate used for mutual TLS with the GitLab API. See [Support mutual TLS when calling the GitLab API](#support-mutual-tls-when-calling-the-gitlab-api) for details. | | `dir` | Working directory for configuration and secrets files. | | `enable` | Enable or disable GitLab Pages on the current system. | | `external_http` | Configure Pages to bind to one or more secondary IP addresses, serving HTTP requests. Multiple addresses can be given as an array, along with exact ports, for example `['1.2.3.4', '1.2.3.5:8063']`. Sets value for `listen_http`. | @@ -723,7 +723,7 @@ To configure the certificates in your GitLab Pages server: and edit `/etc/gitlab/gitlab.rb`: ```ruby - gitlab_pages['ca_certs'] = ['/etc/gitlab/ssl/ca.pem'] + gitlab_pages['client_ca_certs'] = ['/etc/gitlab/ssl/ca.pem'] ``` File paths for multiple custom Certificate Authority (CA)s are separated by commas. -- GitLab From 889e4c5bb408cebdd2e190eb23b0e606e82870cb Mon Sep 17 00:00:00 2001 From: ngala Date: Wed, 5 Jun 2024 13:03:06 +0530 Subject: [PATCH 8/8] Added prerequisites for Linux package installation --- doc/administration/pages/index.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 8e33cad0bd134c..6b451fb7441beb 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -690,6 +690,10 @@ Authority (CA) in the system certificate store. > - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/548) in GitLab 17.1. +Prerequisites: + +- Your instance must use the Linux package installation method. + If GitLab is [configured to require mutual TLS](https://docs.gitlab.com/omnibus/settings/ssl/#enable-2-way-ssl-client-authentication), you must add client certificates to your GitLab Pages configuration. -- GitLab