IBM Cloud Docs
Authenticated origin pull

Authenticated origin pull

Origin web servers validate that a web request came from IBM Cloud® Internet Services through authenticated origin pulls. CIS uses TLS client certificate authentication, a feature that is supported by most web servers, to present a CIS certificate when establishing a connection between CIS and the origin web server. By validating this certificate at your origin web server, access is limited to CIS connections.

An authenticated origin pull is important when taking advantage of the Web Application Firewall (WAF). After your origin web server enforces authenticated origin pulls, all HTTPS requests outside of CIS are blocked from reaching your origin.

Authenticated origin pull is configured by using one of the following options:

  • Zone-level authenticated origin pull by using CIS 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 CIS upon expiration unless a delete or replace request is sent to the CIS 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.

Zone-level authenticated origin pull with CIS certificates

CIS 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 CIS with End-to-End flexible
  3. Configure the origin web server to accept client certificates
  4. Enable authenticated origin pull by using the CIS CLI

Zone-level authenticated origin pull with customer certificates

  1. If using an ECC key 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 uploading to CIS:

    $ cat app_example_com.pem
    -----BEGIN CERTIFICATE-----
    MIIFJDCCBAygAwIBAgIQD0ifmj/Yi5Nz2gdUySbfzANBgkqhkiG9w0BAQsFADBN
    MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMScwJQYDVQQDEx5E
    ...
    SzSHfXp5lnu/3V08I72q1QNzOCgY1XeL4GKVcj4or6cT6tX6oJH7ePPmfrBfqI/O
    OeH8gMJ+FuwtXYEPa4hBf38M5eU5xWG7
    -----END CERTIFICATE-----
    
  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
    
  4. Build the payload:

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

  5. Upload the client certificate and private key via the CIS CLI

  6. Enable authenticated origin pull via CIS CLI

Per-hostname authenticated origin pull using customer certificates

When enabling 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 CIS.

To upload a client certificate in CIS:

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

  2. Ensure that the certificate is in the following format before you upload it to CIS.

    $ cat app_example_com.pem
    -----BEGIN CERTIFICATE-----
    MIIFJDCCBAygAwIBAgIQD0ifmj/Yi5NP/2gdUySbfzANBgkqhkiG9w0BAQsFADBN
    MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMScwJQYDVQQDEx5E
    ...
    SzSHfXp5lnu/3V08I72q1QNzOCgY1XeL4GKVcj4or6cT6tX6oJH7ePPmfrBfqI/O
    OeH8gMJ+FuwtXYEPa4hBf38M5eU5xWG7
    -----END CERTIFICATE-----
    
  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
    
  4. Build the payload:

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

  5. Upload the client certificate and private key via the CIS CLI

  6. Enable authenticated origin pull on specified hostname through the CIS CLI. Link the client certificate to the specific hostname

Replacing a client certificate without downtime

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

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

Installing on Apache and NGINX

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

Setting up Apache

Use End-to-End flexible and update the origin web server SSL configuration 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
    

Setting up NGINX

Use End-to-End flexible and update the origin web server SSL configuration 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;