Automating FreeIPA certificates on Palo Alto devices

 | 1 May 2023 10:12

pan_getcert is a script that uses ipa-getcert to request a certificate from FreeIPA CA and then uploads it via Palo Alto XML API to a Palo Alto firewall or Panorama, optionally updating one or two SSL/TLS Profiles with the new certificate and commits to activate the changes.

It’s hosted on GitHub: https://github.com/dmgeurts/getcert_paloalto


Introduction

Palo Alto SSL/TLS Profiles

Some uses of FreeIPA certificates on a Palo Alto firewall or Panorama:

  • Global Protect Gateway
  • Global Protect Portal
  • Management UI

Should one use an internal certificate for an external service?

There’s no need to get a publicly signed certificate as long as all Global Protect clients trust the FreeIPA (root) CA. A nice bonus is not having to permit inbound HTTP-01 traffic, which in Let’s Encrypt’s case is cloud-hosted (what else is hosted there?). Or exposing internal domains, see: Terence Eden’s Blog – Should you use Let’s Encrypt for internal hostnames?

FreeIPA CA

FreeIPA with Dogtag PKI supports certificate requests and renewals from Certmonger via ipa-getcert and since FreeIPA v4.9 also via ACME.

ACME vs Certmonger

Palo Alto firewalls nor Panorama natively support ACME, nor would I expect them to. For my lab environment, ipa-getcert is a natural choice as the server in use for certificate management is FreeIPA enrolled already, hence I have no need for anonymous ACME.

Prerequisites

pan_getcert uses ipa-getcert, the requirements are identical as far as FreeIPA is concerned:

  • An enrolled FreeIPA client with reachability to the Palo Alto firewall or Panorama.
    • Test with: nc -zv fw-mgmt.domain.local 443
    • pan-python installed
  • A manually added host (with the Service hostname).
    • The manual host must be ‘managed by’ the host on which pan_getcert will be executed.
  • A Service Principal for the service domain
    • The Service Principal must be ‘managed by’ the host on which pan_getcert will be executed.
  • An API key for the Palo Alto firewall or Panorama
    • Ideally, use a system account to tie the API key to, users tend to churn and break their API keys.
    • Store the API key in /etc/ipa/.panrc
  • IPA CA root certificate manually installed on the Palo Alto firewall or Panorama, as a trusted CA.

To install pan-python on Ubuntu 22.04:

sudo apt install python3-pip
sudo pip install pan-python

To generate the API key; first, create a user account for/on the Palo Alto and then run this from the Linux host:

panxapi.py -h PAN_MGMT_IP_OR_FQDN -l USERNAME:'PASSWORD' -k

Copy the key and paste it into /etc/ipa/.panrc as follows:

api_key=C2M1P2h1tDEz8zF3SwhF2dWC1gzzhnE1qU39EmHtGZM=

And secure the file:

sudo chmod 600 /etc/ipa/.panrc

To install getcert_paloalto:

wget https://github.com/dmgeurts/getcert_paloalto/edit/master/pan_{get,inst}cert
chmod +x pan_{get,inst}cert
sudo cp pan_{get,inst}cert /usr/local/bin/
rm pan_{get,inst}cert

Automating the two

Now that the scope is clear, it’s time to explain how getcert_paloalto automates certificate requests, deployment and renewals.

Certmonger supports has pre- and post-save commands, these can be used to run things like systemctl restart apache but also more complex commands like the name of a script with its various options. It’s this post-save option that automates the renewal process but also makes certificate deployment interesting as the same command is executed when the certificate is first created (the first save).

This is the reason there are two scripts for the solution. Also note that, as opposed to ACME, for example, no crontab entry is needed for the renewal of FreeIPA certificates. Cernmonger takes care of monitoring certificates and renewing them before they expire.

pan_getcert – Introduction

pan_getcert uses ipa-getcert (part of freeipa-client) to request a certificate from IPA CA and then sets the post-save command to pan_instcert with options based on the parameters parsed to pan_getcert. The nodes involved and the processes used are as follows:

Process overview: FreeIPA <-- Linux --> Palo Alto.

*) My OS of choice is Ubuntu hence the Ubuntu logo for the FreeIPA client machine.

pan_getcert – Options

The bare minimum options to parse are the certificate Subject (aka Common Name) [-c] and the Palo Alto device hostname.

Note: pan_getcert must be run as root, ideally using sudo. This enables admins to give certificate managers the delegated privilege to run pan_getcert as root rather than all the commands in it that require elevated privileges.

Optional arguments:

  • -n Certificate name in the Palo Alto configuration, if none is given the Certificate Subject will be used.
  • -Y Certificate name postfix of a four-digit year, prevents the existing certificate from being replaced. <certificate.name_2023>
  • -p Name of the ‘primary’ SSL/TLS Profile, will see the currently configured certificate replaced with the new certificate. if none is given, no SSL/TLS Profile will be updated.
  • -s Name of the ‘secondary’ SSL/TLS Profile, will see the currently configured certificate replaced with the new certificate. Requires [-p] to be set.

The secondary Profile option is useful in cases where the same certificate must be updated on two different SSL/TLS Profiles. It is not possible to request more than one certificate using pan_getcert from FreeIPA.

Usage: pan_getcert [-hv] -c CERT_CN [-n CERT_NAME] [-Y] [OPTIONS] FQDN
This script requests a certificate from FreeIPA using ipa-getcert and calls a partner
script to deploy the certificate to a Palo Alto firewall or Panorama.

    FQDN              Fully qualified name of the Palo Alto firewall or Panorama
                      interface. Must be reachable from this host on port TCP/443.
    -c CERT_CN        REQUIRED. Common Name (Subject) of the certificate (must be a
                      FQDN). Will also present in the certificate as a SAN.

OPTIONS:
    -n CERT_NAME      Name of the certificate in PanOS configuration. Defaults to the
                      certificate Common Name.
    -Y                Parsed to pan_instcert to append the current year '_YYYY' to
                      the certificate name.

    -p PROFILE_NAME   Apply the certificate to a (primary) SSL/TLS Service Profile.
    -s PROFILE_NAME   Apply the certificate to a (secondary) SSL/TLS Service Profile.

    -h                Display this help and exit.
    -v                Verbose mode.

pan_getcert – Actions

  1. Uses the privileges set in FreeIPA (managed by) to call ipa-getcert and request a certificate from FreeIPA.
  2. ipa-getcert will automatically renew a certificate when it’s due, as long as the FQDN DNS record resolves, and the host and Service Principal still exist in FreeIPA.
  3. Sets the post-save command to pan_instcert with the same parameters as issued to pan_getcert, for automated installation of renewed certificates.
    • Post-save will run on the first certificate save, using pan_instcert for certificate installation.

pan_instcert – Introduction

Uses panxapi.py from pan-python and can be used on its own. For example, if the certificate is created without pan_getcert. Or one might choose to use it as the post-save command of a certificate already monitored by Certmonger.

Note: pan_instcert must be run as root, ideally using sudo. This enables admins to give certificate managers the delegated privilege to run pan_instcert as root rather than all the commands in it that require elevated privileges.

pan_getcert – Options

pan_instcert options and arguments are deliberately identical to pan_getcert.

Usage: pan_instcert [-hv] -c CERT_CN [-n CERT_NAME] [OPTIONS] FQDN
This script uploads a certificate issued by ipa-getcert to a Palo Alto firewall
or Panorama and optionally adds it to up to two SSL/TLS Profiles.

    FQDN              Fully qualified name of the Palo Alto firewall or Panorama
                      interface. Must be reachable from this host on port TCP/443.
    -c CERT_CN        REQUIRED. Common Name (Subject) of the certificate, to find
                      the certificate and key files.

OPTIONS:
    -n CERT_NAME      Name of the certificate in PanOS configuration. Defaults to the
                      certificate Common Name.
    -Y                Append the current year '_YYYY' to the certificate name.

    -p PROFILE_NAME   Apply the certificate to a (primary) SSL/TLS Service Profile.
    -s PROFILE_NAME   Apply the certificate to a (secondary) SSL/TLS Service Profile.

    -h                Display this help and exit.
    -v                Verbose mode.

pan_instcert – Actions

  1. Randomly generates a certificate passphrase using “openssl rand”.
  2. Creates a temporary, password-protected PKCS12 cert file /tmp/getcert_pkcs12.pfx from the individual private and public keys issued by ipa-getcert.
  3. Uploads the temporary PKCS12 file to the firewall using the randomly-generated passphrase.
    • (Optionally) adds a year (in 4-digit notation) to the certificate name.
  4. Deletes the temporary PKCS12 certificate from the Linux host.
  5. (Optionally) applies the certificate to up to two SSL/TLS Profiles.
    • Single SSL/TLS Profile: For example for the Management UI SSL/TLS profile.
    • Two SSL/TLS Profiles: For example for GlobalProtect Portal and GlobalProtect Gateway SSL/TLS Profiles.
  6. Commits the candidate configuration (synchronously) and reports the commit result.
  7. Logs all output to `/var/log/pan_instcert.log`.

Command execution

The expected output when requesting a certificate with pan_getcert is:

$ sudo pan_getcert -v -c gp.domain.com -Y -p GP_PORTAL_PROFILE -s GP_EXT_GW_PROFILE fw01.domain.local
Certificate Common Name: gp.domain.com
  verbose=1
  CERT_CN: gp.domain.com
  CERT_NAME: gp.domain.com_2023
  PAN_FQDN: fw01.domain.local
Primary SSL/TLS Profile name: GP_PORTAL_PROFILE
Secondary SSL/TLS Profile name: GP_EXT_GW_PROFILE
New signing request "20230427151532" added.
Certificate requested for: gp.domain.com
  Certificate issue took 6 seconds, waiting for the post-save process to finish.
  Certificate install and commit by the post-save process on: fw01.domain.local took 84 seconds.
FINISHED: Check the Palo Alto firewall or Panorama to check the commit succeeded.

And pan_instcert will log to /var/log/pan_instcert.log.

[2023-04-27 15:15:33+00:00]: START of pan_instcert.
[2023-04-27 15:15:33+00:00]: Certificate Common Name: gp.domain.com
[2023-04-27 15:15:34+00:00]: XML API output for crt: <response status="success"><result>Successfully imported gp.domain.com_2023 into candidate configuration</result></response>
[2023-04-27 15:15:35+00:00]: XML API output for key: <response status="success"><result>Successfully imported gp.domain.com_2023 into candidate configuration</result></response>
[2023-04-27 15:15:35+00:00]: Finished uploading certificate: gp.domain.com_2023
[2023-04-27 15:15:37+00:00]: Starting commit, please be patient.
[2023-04-27 15:17:01+00:00]: commit: success: "Configuration committed successfully"
[2023-04-27 15:17:01+00:00]: The commit took 84 seconds to complete.
[2023-04-27 15:17:01+00:00]: END - Finished certificate installation to: fw01.domain.local

Both pan_getcert and pan_instcert will report back how long it took to do certain tasks:

  • pan_getcert
    • Time spent waiting for the certificate to be issued.
    • Time spent waiting for pan_instcert to complete.
  • pan_instcert
    • Time spent waiting for the commit to finish.

Logrotate for pan_instcert.log

This log file shouldn’t grow quickly unless there’s a problem or the number of monitored certificates grows very large. By default, IPA certificates have a two-year validity, thus monthly log lines will average at about 0.375 per certificate (9 lines / 24 months). Generally speaking, you should not expect this file to grow by more than a few lines a year.

The bigger risk is misconfiguration or changes of ipa-getcert and the Palo Alto API. And from experience, I can confirm that getcert is very persistent in retrying failed post-save commands. A few times while testing my code the log file grew to >20GB within minutes, containing only repeated pan_instcert usage instructions.

Count yourself warned! A suggestion for a logrotate.d file is:

# /etc/logrotate.d/pan_instcert
/var/log/pan_instcert.log { 
	missingok
	rotate 5
	yearly
	size 50M
	notifempty
	create
}

Verify Certificate Status and Post-save Command

Use ipa-getcert to check that the certificate ended up in status MONITORING and that the post-save command is set according to the parameters and values parsed to pan_getcert:

$ sudo ipa-getcert list
Number of certificates and requests being tracked: 2.
Request ID '20230427151532':
        status: MONITORING
        stuck: no
        key pair storage: type=FILE,location='/etc/ssl/private/gp.domain.com.key'
        certificate: type=FILE,location='/etc/ssl/certs/gp.domain.com.crt'
        CA: IPA
        issuer: CN=Certificate Authority,O=IPA.LOCAL
        subject: CN=gp.domain.com,O=IPA.LOCAL
        issued: 2023-04-27 16:15:33 BST
        expires: 2025-04-27 16:15:33 BST
        dns: gp.domain.com
        principal name: HTTP/gp.domain.com@MM.EU
        key usage: digitalSignature,nonRepudiation,keyEncipherment,dataEncipherment
        eku: id-kp-serverAuth,id-kp-clientAuth
        pre-save command:
        post-save command: /usr/local/bin/pan_instcert -c gp.domain.com -n gp.domain.com -Y -p GP_PORTAL_PROFILE -s GP_EXT_GW_PROFILE fw01.domain.local
        track: yes
        auto-renew: yes
Request ID '20230428001508':
        status: MONITORING
        stuck: no
        key pair storage: type=FILE,location='/etc/ssl/private/fw01.domain.local.key'
        certificate: type=FILE,location='/etc/ssl/certs/fw01.domain.local.crt'
        CA: IPA
        issuer: CN=Certificate Authority,O=IPA.LOCAL
        subject: CN=fw01.domain.local,O=IPA.LOCAL
        issued: 2023-04-27 16:15:33 BST
        expires: 2025-04-27 16:15:33 BST
        dns: fw01.domain.local
        principal name: HTTP/fw01.domain.local@IPA.LOCAL
        key usage: digitalSignature,nonRepudiation,keyEncipherment,dataEncipherment
        eku: id-kp-serverAuth,id-kp-clientAuth
        pre-save command:
        post-save command: /usr/local/bin/pan_instcert -c fw01.domain.local -n fw01.domain.local -Y -p MGMT_UI_PROFILE fw01.domain.local
        track: yes
        auto-renew: yes

Note the status, location of the saved files and the post-save command. Tracking and auto-renew are enabled by default by ipa-getcert.

pan_instcert will only log to stdout when executed directly. However, it will always log to /var/log/pan_instcert.log. When requesting certificates, it can be helpful to run a tail to see the post-save command logging in real-time. If the log file doesn’t yet exist the tail will fail.

sudo touch -a /var/log/pan_instcert.log
sudo tail -f /var/log/pan_instcert.log

Wrong SSL/TLS profile name

If the SSL/TLS Service Profile doesn’t exist it will be created, but the following error will be shown in /var/log/pan_instcert.log and the commit will fail:

commit: success: "Validation Error:
 ssl-tls-service-profile -> Test_profile  is missing 'protocol-settings'
 ssl-tls-service-profile is invalid"

Verify the API calls on the Palo Alto Firewall or Panorama

Check the following locations on the Palo Alto firewall for additional confirmation: Monitor >> Logs >> Configuration There should be 3-5 operations shown, depending on whether or not the SSL/TLS service profile(s) are being updated.

  1. A web upload to /config/shared/certificate.
  2. A web upload to /config/shared/certificate/entry[@name=’FQDN(_YYYY)’], under the FreeIPA root CA certificate.
  3. One or more web “set” commands to /config/shared/ssl-tls-service-profile/entry[@name=’YOUR_PROFILE(S)’]
  4. And a web “commit” operation.

To see all API actions, filter by the admin username used for API key: ( admin eq [api-admin] )

Under Device >> Certificate Management >> Certificates the new certificate should be shown with a valid status and under the manually imported IPA CA root certificate.

If any SSL/TLS Profiles were parsed, then under Device >> Certificate Management >> SSL/TLS Service Profile the respective profiles should show the new certificate has replaced the previous certificate.

Recent script changes

[2023-05-02] Looking into issuing a subordinate certificate from FreeIPA for a Palo Alto firewall, for user VPN certificates and ideally SSL interception. I found that I needed to specify a Certificate Profile in the ipa-getcert command, I thus went about adding option -T to pan_getcert.

Furthermore, I also added the following options:

  • -b Key bit length, 2048 is the default but it’s good to be able to request 3072 and 4096 length RSA certificates.`-b Key bit length, 2048 is the default but it’s good to be able to request 3072 and 4096 length RSA certificates.
  • -G Certificate type, currently only RSA is supported by FreeIPA. But it’s good to be ready for when EC and ECDSA certificates can be issued from FreeIPA. I don’t think this will be any time soon, but the code is there now.
  • -S Service type. The subordinate certificate isn’t for an HTTP service, in fact it’s best suited to being tied to a host rather than a service. So now there’s an option to specify a service, if omitted HTTP is assumed.

No Responses to “Automating FreeIPA certificates on Palo Alto devices”

Care to comment?