Panorama Certificate Automation

This article will demonstrate how to in Panorama perform certificate automation with the ACME protocol. Both Let’s Encrypt and ZeroSSL will be demonstrated. acme.sh will be the ACME client used as it has a convenient deploy hook to the Palo Alto devices. acme.sh can be used as a standalone installation or ran as a docker daemon with the docker image here. The article will deploy acme.sh in a docker container.

Create a Firewall Administrator in Panorama

First, a firewall administrator should be created in your panorama instance and pushed out to the palo alto firewall devices. If you aren’t using panorama, just create the firewall administrator directly on the palo device. Note that these instructions are for PAN-OS 9.1 and newer.

Creating a firewall administrator consists of two steps, creating an Admin Role Profile and creating an Administrator.

To create a new Admin Role Profile in Panorama, perform the following steps:

Click Device -> Admin Roles -> Add
Fill out the form pictured below with a Name, Description, and correct permissions. For this role, all Web UI permissions should be disabled. The only XML/REST API permissions should be Commit and Import.

panorama certificate automation - admin role

To create a new Administrator in Panorama, perform the following steps:

Click Device -> Administrators -> Add
Fill out the form pictured below with a Name, Password, and Role Based Administrator Type choosing the previously created Admin Role.

panorama certificate automation - administrator

If you are running a version prior to PAN-OS 9.1 you must provide the administrator with Superuser access.

Configure acme.sh AWS Route53 DNS

The simplest way in Panorama to perform certificate automation with acme.sh is to use the DNS challenge method, so that you do not end up exposing the server you are running acme.sh on to stay open to the world.

There are several DNS APIs supported by acme.sh. This article will focus on the AWS Route53 API. To see all of the supported APIs, click here.

The example below will demonstrate how to pass the AWS Route53 DNS environment variables into your docker container.

The official documentation for using Amazon Route53 with acme.sh is here: https://github.com/acmesh-official/acme.sh/wiki/How-to-use-Amazon-Route53-API

Run acme.sh as a Docker daemon

The official documentation for running acme.sh in Docker can be found here: https://github.com/acmesh-official/acme.sh/wiki/Run-acme.sh-in-docker

For the purposes of this article we will be running acme.sh as a docker daemon. Running acme.sh as a docker daemon will allow the SSL certificate renewal to happen automatically with cron.

To run acme.sh with docker, run the following docker run command:

docker run --rm  -itd  \
  -v "$(pwd)/out":/acme.sh  \
  --net=host \
  --name=acme.sh \
  --env-file environment_variables \
  neilpang/acme.sh daemon

Where -v "$(pwd)/out":/acme.sh is the volume mount. Remember the host path is before the colon and the docker container path is after. The /acme.sh path must not be changed, but the local host path can be changed to the location you choose. --env-file environment_variables is pointing to the file containing the environment variables needed for the panorama certificate renewal. They should be the following:

PANOS_USER=user
PANOS_PASS=pass
PANOS_HOST=panorama.example.com
AWS_ACCESS_KEY_ID=keyid
AWS_SECRET_ACCESS_KEY=secret

Now that the docker container is running, you can issue any acme.sh commands to it using docker exec. Run the following to view any acme.sh commands that may be ran:

docker exec acme.sh --help

To issue a certificate to be installed on your firewall:

docker exec acme.sh --issue --dns dns_aws -d panorama.example.com -d palo1.example.com -d palo2.example.com -d palo3.example.com

Note that dns_aws is the same DNS option explored in the earlier section. You should already have the AWS API credentials configured for this. You may include as many names on the certificate as necessary by using the -d flag.

Note that acme.sh now uses ZeroSSL by default, instead of Let’s Encrypt. We recommend being specific in the --issue command in the event the default is changed again in the future. To specify the CA being used by acme.sh, add the --server flag to the command. To use Let’s Encrypt, use --server letsencrypt. To use ZeroSSL, use --server zerossl.

If using ZeroSSL you must first register your account or email address with the following command:

docker exec acme.sh --register-account -m example@example.com

The certificate should now be issued and will be renewed automatically every 60 days. Note that the validity period of letsencrypt and zerossl are both 90 days so in the event the renewal does not happen, you will have 30 days to fix the issue. You should have a certificate monitoring solution in place to monitor for expiring certificates.

To deploy the issued certificate onto your panorama and/or palo alto firewall devices, run the following command:

docker exec acme.sh --deploy -d panorama.example.com --deploy-hook panos

where -d panorama.example.com is the CN (Common Name) of the certificate that was issued. In your acme.sh directory, you should see a directory named as such.

Note that the previous command requires that the following environment variables be set:

PANOS_USER=user
PANOS_PASS=pass
PANOS_HOST=panorma.example.com

The panos deploy hook only commits changes made by this user, so other uncommitted changes will not be committed on accident. If you recieve SSL errors when running the panos deploy hook, try adding the --insecure flag, assuming a publicly trusted SSL certificate had never been installed on your palo devices before.

Additionally, you can use the --debug flag to further troubleshoot any issues you have with with any of the acme.sh commands including certificate issuance and deploy.