Skip to content

auth-origin-pull.md

Latest commit

 

History

History
185 lines (125 loc) · 9.65 KB

auth-origin-pull.md

File metadata and controls

185 lines (125 loc) · 9.65 KB
copyright
years
2021, 2025
lastupdated 2025-07-18
keywords
subcollection cis

{{site.data.keyword.attribute-definition-list}}

Authenticated origin pull

{: #authenticated-origin-pull}

Authenticated Origin Pull is a security feature that helps ensure secure communication between the {{site.data.keyword.cis_full}} and your origin server. It uses mutual TLS (mTLS) to authenticate both the CIS and the origin server, which allows only requests from the trusted {{site.data.keyword.cis_full}} to access your server. This setup protects your origin server from unauthorized access and enhances the overall security of your web applications. {: shortdesc}

Origin web servers validate that a web request came from {{site.data.keyword.cis_full}} through authenticated origin pulls. {{site.data.keyword.cis_short_notm}} uses TLS client certificate authentication, a feature that is supported by most web servers to present a {{site.data.keyword.cis_short_notm}} certificate when it establishes a connection between {{site.data.keyword.cis_short_notm}} and the origin web server. By validating this certificate at your origin web server, access is limited to {{site.data.keyword.cis_short_notm}} connections.

An authenticated origin pull is important when you take advantage of the Web Application Firewall (WAF). After your origin web server enforces authenticated origin pulls, all HTTPS requests outside of {{site.data.keyword.cis_short_notm}} are blocked from reaching your origin.

You can configure authenticated origin pull by using one of the following options:

  • Zone-level authenticated origin pull by using {{site.data.keyword.cis_short_notm}} certificates
  • Zone-level authenticated origin pull by using customer certificates
  • Per-Hostname authenticated origin pull by using customer certificates

Client certificates are not deleted from {{site.data.keyword.cis_short_notm}} upon expiration unless a delete or replace request is sent to the {{site.data.keyword.cis_short_notm}} API. However, requests are dropped at your origin if your origin accepts only a valid client certificate.

Authenticated Origin Pull does not work in SSL mode Off (not secure) or Client-to-Edge. {: note}

Zone-level authenticated origin pull with {{site.data.keyword.cis_short_notm}} certificates

{: #cis-cert-zone-auth-org-pull}

This option allows secure content access from the origin server by authenticating requests with {{site.data.keyword.cis_short_notm}} provided certificates at the zone level.

{{site.data.keyword.cis_short_notm}} uses the following CA to sign certificates for the authenticated origin pull service:

Download the certificate and store the file on your origin web server, for example in /path/to/origin-pull-ca.pem.

To enable authenticated origin, pull globally on a zone:

  1. Install the certificate at the origin web server to authenticate all connections.
  2. Configure {{site.data.keyword.cis_short_notm}} with End-to-End flexible.
  3. Configure the origin web server to accept client certificates.
  4. Enable authenticated origin pull by using the {{site.data.keyword.cis_short_notm}} CLI.

Zone-level authenticated origin pull with custom certificates

{: #cust-cert-zone-auth-org-pull}

This option enables secure content access from the origin server by using customer-uploaded certificates for authentication at the zone level.

  1. If you use an ECC key that is generated by OpenSSL, first remove -----BEGIN EC PARAMETERS-----...-----END EC PARAMETERS----- from the certificate file.

  2. Ensure the certificate and key are in the following format before you upload to {{site.data.keyword.cis_short_notm}}:

    $ cat app_example_com.pem
-----BEGIN CERTIFICATE-----
MIIFJDCCBAygAwIBAgIQD0ifmj/Yi5Nz2gdUySbfzANBgkqhkiG9w0BAQsFADBN
MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMScwJQYDVQQDEx5E
...
SzSHfXp5lnu/3V08I72q1QNzOCgY1XeL4GKVcj4or6cT6tX6oJH7ePPmfrBfqI/O
OeH8gMJ+FuwtXYEPa4hBf38M5eU5xWG7
-----END CERTIFICATE-----

    {: codeblock}

  3. Replace line endings with the string \n:

    MYCERT="$(cat app_example_com.pem|perl -pe 's/\r?\n/\\n/'|sed -e 's/..$//')" $ MYKEY="$(cat app_example_com.key|perl -pe 's/\r?\n/\\n/'| sed -e's/..$//')"

echo $MYCERT -----BEGIN CERTIFICATE-----\nMIIFJDCCBAygAwIBAgIQD0ifmj/Yi5NP/ 2gdUySbfzANBgkqhkiG9w0BAQsFADBN\nMQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMScwJQYDVQQDEx5E...SzSHfXp5lnu/ 3V08I72q1QNzOCgY1XeL4GKVcj4or6cT6tX6oJH7ePPmfrBfqI/O\nOeH8gMJ+FuwtXYEPa4hBf38M5eU5xWG7\n-----END CERTIFICATE-----\n

    {: codeblock}

  4. Build the payload:

    $ request_body=$(< <(cat <<EOF { "certificate": "$MYCERT", "private_key": "$MYKEY" } } EOF ))

  5. Upload the client certificate and private key from the {{site.data.keyword.cis_short_notm}} CLI.

  6. Enable authenticated origin pull from the {{site.data.keyword.cis_short_notm}} CLI.

Per-hostname authenticated origin pull by using customer certificates

{: #per-host-zone-auth-org-pull}

This option allows secure content access from the origin server by authenticating requests with customer certificates on a per-hostname basis.

When you enable authenticated origin pull per hostname, all proxied traffic to the specified hostname is authenticated at the origin web server. You can use client certificates from your own public key infrastructure to authenticate connections from {{site.data.keyword.cis_short_notm}}.

To upload a client certificate in {{site.data.keyword.cis_short_notm}}:

  1. If you use an ECC key that is generated by OpenSSL, first remove -----BEGIN EC PARAMETERS-----...-----END EC PARAMETERS----- from the certificate file.

  2. Make sure that the certificate is in the following format before you upload it to {{site.data.keyword.cis_short_notm}}.

    $ cat app_example_com.pem
-----BEGIN CERTIFICATE-----
MIIFJDCCBAygAwIBAgIQD0ifmj/Yi5NP/2gdUySbfzANBgkqhkiG9w0BAQsFADBN
MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMScwJQYDVQQDEx5E
...
SzSHfXp5lnu/3V08I72q1QNzOCgY1XeL4GKVcj4or6cT6tX6oJH7ePPmfrBfqI/O
OeH8gMJ+FuwtXYEPa4hBf38M5eU5xWG7
-----END CERTIFICATE-----

    {: codeblock}

  3. Replace line endings with the string \n:

    MYCERT="$(cat app_example_com.pem|perl -pe 's/\r?\n/\\n/'|sed -e 's/..$//')" $ MYKEY="$(cat app_example_com.key|perl -pe 's/\r?\n/\\n/'|sed -e's/..$//')"

echo $MYCERT -----BEGIN CERTIFICATE-----\nMIIFJDCCBAygAwIBAgIQD0ifmj/Yi5NP/2gdUySbfzANBgkqhkiG9w0BAQsFADBN\nMQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMScwJQYDVQQDEx5E...SzSHfXp5lnu/3V08I72q1QNzOCgY1XeL4GKVcj4or6cT6tX6oJH7ePPmfrBfqI/O\nOeH8gMJ+FuwtXYEPa4hBf38M5eU5xWG7\n-----END CERTIFICATE-----\n

    {: codeblock}

  4. Build the payload:

    $ request_body=$(< <(cat <<EOF { "certificate": "$MYCERT", "private_key": "$MYKEY" } } EOF ))

  5. Upload the client certificate and private key from the {{site.data.keyword.cis_short_notm}} CLI.

  6. Enable authenticated origin pull on the specified hostname through the {{site.data.keyword.cis_short_notm}} CLI. Link the client certificate to the specific hostname.

Replacing a client certificate without downtime

{: #replace-client-cert}

For hostname:

  1. Upload the new certificate.
  2. Link the new certificate ID and hostname and enabled values.

For global:

  1. Upload the new certificate.
  2. Check that the new certificate is in Active state.
  3. After the certificate is active, delete the old certificate.

Apply a different client certificate (at zone and hostname level) simultaneously

{: #apply-different-certs}

  1. Upload a certificate by following the steps in the Zone-level authenticated origin pull section.
  2. Upload multiple certificates by following the steps in the Per-hostname authenticated origin pull by using customer certificates section.

Installing on Apache and NGINX

{: #apache-nginx}

Use the following instructions for configuring TLS authenticated origin pulls for either NGINX or Apache origin web servers.

Setting up Apache

{: #apache-setup}

Use End-to-End flexible and update the origin web server SSL configuration by using the following steps.

  1. Download the authenticated origin pull certificate (origin-pull-ca.pem).

  2. Store the certificate in a file on your origin web server, for example in /path/to/origin-pull-ca.pem.

  3. Add the following lines to the SSL configuration for your origin web server:

    SSLVerifyClient require
SSLVerifyDepth 1
SSLCACertificateFile /path/to/origin-pull-ca.pem

    {: codeblock}

Setting up NGINX

{: #nginx-setup}

Use End-to-End flexible and update the origin web server SSL configuration by using the following steps.

  1. Download the authenticated origin pull certificate (origin-pull-ca.pem).

  2. Store the certificate in a file on your origin web server, for example in /etc/nginx/certs/cloudflare.crt.

  3. Add the following lines to the SSL configuration for your origin web server:

    ssl_client_certificate /etc/nginx/certs/cloudflare.crt;
ssl_verify_client on;

    {: codeblock}