Automating FreeIPA certificates on Palo Alto devices
Djerk | 1 May 2023 10:12pan_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
- Test with:
- 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:
*) 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:
-nCertificate name in the Palo Alto configuration, if none is given the Certificate Subject will be used.-YCertificate name postfix of a four-digit year, prevents the existing certificate from being replaced.<certificate.name_2023>-pName 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.-sName 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
- Uses the privileges set in FreeIPA (managed by) to call ipa-getcert and request a certificate from FreeIPA.
- 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.
- 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
- Randomly generates a certificate passphrase using “openssl rand”.
- Creates a temporary, password-protected PKCS12 cert file
/tmp/getcert_pkcs12.pfxfrom the individual private and public keys issued by ipa-getcert. - 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.
- Deletes the temporary PKCS12 certificate from the Linux host.
- (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.
- Commits the candidate configuration (synchronously) and reports the commit result.
- 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.
- A web upload to /config/shared/certificate.
- A web upload to /config/shared/certificate/entry[@name=’FQDN(_YYYY)’], under the FreeIPA root CA certificate.
- One or more web “set” commands to /config/shared/ssl-tls-service-profile/entry[@name=’YOUR_PROFILE(S)’]
- 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:
-bKey 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.-GCertificate 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.-SService 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.
Recent Comments