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.
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.
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
-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
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
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
If using ZeroSSL you must first register your account or email address with the following command:
docker exec acme.sh --register-account -m firstname.lastname@example.org
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
-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.
Panorama Certificate Automation – Conclusion
This article has demonstrated Panorama certificate automation including how to issue SSL certificates with acme.sh in a docker container and how to deploy the SSL certificate to the panorama or palo alto devices. We hope going forward that manual certificate installations are a thing of the past for your palo alto firewalls. Leave us a comment if you have any questions or need additional details or examples to automate certificate renewals for Panorama and Palo Alto.