Skip to content

Latest commit

 

History

History
330 lines (226 loc) · 24.3 KB

README.md

File metadata and controls

330 lines (226 loc) · 24.3 KB

Palo Alto Orchestrator

The Palo Alto Orchestrator remotely manages certificates on either the Palo Alto PA-VM Firewall Device or the Panorama. If using Panorama, it will push changes to all the devices from Panorama. It supports adding certificates with or without private keys. Palo Alto does not support incremental certificate inventory. If you have large numbers of certificates in your environment it is recommended to limit the frequency of inventory jobs to 30 minutes or more.

Integration status: Production - Ready for use in production environments.

About the Keyfactor Universal Orchestrator Extension

This repository contains a Universal Orchestrator Extension which is a plugin to the Keyfactor Universal Orchestrator. Within the Keyfactor Platform, Orchestrators are used to manage “certificate stores” — collections of certificates and roots of trust that are found within and used by various applications.

The Universal Orchestrator is part of the Keyfactor software distribution and is available via the Keyfactor customer portal. For general instructions on installing Extensions, see the “Keyfactor Command Orchestrator Installation and Configuration Guide” section of the Keyfactor documentation. For configuration details of this specific Extension see below in this readme.

The Universal Orchestrator is the successor to the Windows Orchestrator. This Orchestrator Extension plugin only works with the Universal Orchestrator and does not work with the Windows Orchestrator.

Support for Palo Alto Orchestrator

Palo Alto Orchestrator is supported by Keyfactor for Keyfactor customers. If you have a support issue, please open a support ticket via the Keyfactor Support Portal at https://support.keyfactor.com

To report a problem or suggest a new feature, use the Issues tab. If you want to contribute actual bug fixes or proposed enhancements, use the Pull requests tab.


Keyfactor Version Supported

The minimum version of the Keyfactor Universal Orchestrator Framework needed to run this version of the extension is 10.1

Platform Specific Notes

The Keyfactor Universal Orchestrator may be installed on either Windows or Linux based platforms. The certificate operations supported by a capability may vary based what platform the capability is installed on. The table below indicates what capabilities are supported based on which platform the encompassing Universal Orchestrator is running.

Operation Win Linux
Supports Management Add
Supports Management Remove
Supports Create Store
Supports Discovery
Supports Reenrollment
Supports Inventory

PAM Integration

This orchestrator extension has the ability to connect to a variety of supported PAM providers to allow for the retrieval of various client hosted secrets right from the orchestrator server itself. This eliminates the need to set up the PAM integration on Keyfactor Command which may be in an environment that the client does not want to have access to their PAM provider.

The secrets that this orchestrator extension supports for use with a PAM Provider are:

Name Description
ServerPassword Key obtained from Palo Alto API to authenticate the server hosting the store

It is not necessary to use a PAM Provider for all of the secrets available above. If a PAM Provider should not be used, simply enter in the actual value to be used, as normal.

If a PAM Provider will be used for one of the fields above, start by referencing the Keyfactor Integration Catalog. The GitHub repo for the PAM Provider to be used contains important information such as the format of the json needed. What follows is an example but does not reflect the json values for all PAM Providers as they have different "instance" and "initialization" parameter names and values.

General PAM Provider Configuration

Example PAM Provider Setup

To use a PAM Provider to resolve a field, in this example the Server Password will be resolved by the Hashicorp-Vault provider, first install the PAM Provider extension from the Keyfactor Integration Catalog on the Universal Orchestrator.

Next, complete configuration of the PAM Provider on the UO by editing the manifest.json of the PAM Provider (e.g. located at extensions/Hashicorp-Vault/manifest.json). The "initialization" parameters need to be entered here:

  "Keyfactor:PAMProviders:Hashicorp-Vault:InitializationInfo": {
    "Host": "http://127.0.0.1:8200",
    "Path": "v1/secret/data",
    "Token": "xxxxxx"
  }

After these values are entered, the Orchestrator needs to be restarted to pick up the configuration. Now the PAM Provider can be used on other Orchestrator Extensions.

Use the PAM Provider

With the PAM Provider configured as an extenion on the UO, a json object can be passed instead of an actual value to resolve the field with a PAM Provider. Consult the Keyfactor Integration Catalog for the specific format of the json object.

To have the Server Password field resolved by the Hashicorp-Vault provider, the corresponding json object from the Hashicorp-Vault extension needs to be copied and filed in with the correct information:

{"Secret":"my-kv-secret","Key":"myServerPassword"}

This text would be entered in as the value for the Server Password, instead of entering in the actual password. The Orchestrator will attempt to use the PAM Provider to retrieve the Server Password. If PAM should not be used, just directly enter in the value for the field.


Release 2.2 Update on Entry Params

Important Note Entry params are no longer used. This version of the extension will only update certs on existing bindings and not add a cert to a new binding location. This was done to simplify the process since there are so many binding locations and reference issues.

Important Note Please review the new path considerations in the store section. It explains how the paths work for Panorama and the Firewalls. 'locahost.localdomain' will always be that constant value.

CERT STORE SETUP AND GENERAL PERMISSIONS

Cert Store Type Configuration

In Keyfactor Command create a new Certificate Store Type similar to the one below:

STORE TYPE CONFIGURATION

SETTING TAB CONFIG ELEMENT DESCRIPTION
Basic Name Descriptive name for the Store Type. PaloAlto can be used.
Basic Short Name The short name that identifies the registered functionality of the orchestrator. Must be PaloAlto
Basic Custom Capability You can leave this unchecked and use the default.
Basic Job Types Inventory, Add, and Remove are the supported job types.
Basic Needs Server Must be checked
Basic Blueprint Allowed Unchecked
Basic Requires Store Password Determines if a store password is required when configuring an individual store. This must be unchecked.
Basic Supports Entry Password Determined if an individual entry within a store can have a password. This must be unchecked.
Advanced Store Path Type Determines how the user will enter the store path when setting up the cert store. Freeform
Advanced Supports Custom Alias Determines if an individual entry within a store can have a custom Alias. This must be Required
Advanced Private Key Handling Determines how the orchestrator deals with private keys. Optional
Advanced PFX Password Style Determines password style for the PFX Password. Default

CUSTOM FIELDS FOR STORE TYPE

NAME DISPLAY NAME TYPE DEFAULT VALUE DEPENDS ON REQUIRED DESCRIPTION
ServerUsername Server Username Secret Unchecked Yes Palo Alto Api User Name
ServerPassword Server Password Secret Unchecked Yes Palo Alto Api Password
ServerUseSsl Use SSL Bool True Unchecked Yes Requires SSL Connection
DeviceGroup Device Group String Unchecked No Device Group on Panorama that changes will be pushed to.
InventoryTrustedCerts Inventory Trusted Certs Bool False Unchecked No If false, will not inventory default trusted certs, saves time.
TemplateStack Template Stack String Unchecked No Template stack used for device push of certificates via Template.

ENTRY PARAMETERS FOR STORE TYPE

The entry parameters for this version have been eliminated. It will not longer support new bindings but will just update existing bindings when the certificate is replaced.

PaloAlto Certificate Store In Keyfactor Command, navigate to Certificate Stores from the Locations Menu. Click the Add button to create a new Certificate Store using the settings defined below.

STORE CONFIGURATION

CONFIG ELEMENT DESCRIPTION
Category The type of certificate store to be configured. Select category based on the display name configured above "PaloAlto".
Container This is a logical grouping of like stores. This configuration is optional and does not impact the functionality of the store.
Client Machine The hostname of the Panorama or Firewall. Sample is "palourl.cloudapp.azure.com".
Store Path See Store Path Explanation Section Below
Orchestrator This is the orchestrator server registered with the appropriate capabilities to manage this certificate store type.
Inventory Schedule The interval that the system will use to report on what certificates are currently in the store.
Use SSL This should be checked.
User ApiUser Setup for either Panorama or the Firewall Device
Password Api Password Setup for the user above

Store Path Explanation

Important Note The store path permutations are show below

FIREWALL SHARED SYSTEM PATH


Path Example /config/shared

/config: This indicates that the path is within the configuration section of the firewall device. It contains all the configuration settings and parameters for the device.

/shared: This section specifies that the path is within the shared settings. Shared settings are common configurations that can be used across multiple virtual systems (vsys) or contexts within the firewall.


FIREWALL VIRTUAL SYSTEM PATH


Path Example: /config/devices/entry[@name='localhost.localdomain']/vsys/entry[@name='vsys1']

/config: This indicates that the path is within the configuration section of the firewall device. It contains all the configuration settings and parameters for the device.

/devices: This part specifies that the configuration relates to devices. In the context of a single firewall, this generally refers to the firewall itself.

/entry[@name='localhost.localdomain']: The entry tag with the attribute @name='localhost.localdomain' identifies a specific device by its name. In this case, it refers to the device named "localhost.localdomain," which is a default or placeholder name for the firewall device.

/vsys: This section specifies that the path is within the virtual systems (vsys) section. Virtual systems allow multiple virtualized instances of firewall configurations within a single physical firewall.

/entry[@name='vsys1']: The entry tag with the attribute @name='vsys1' identifies a specific virtual system by its name. In this case, it refers to a virtual system named "vsys1."


PANORAMA SHARED TEMPLATE PATH


Path Example: /config/devices/entry[@name='localhost.localdomain']/template/entry[@name='CertificatesTemplate']/config/shared

/config: This section indicates that the path is within the configuration section of the Panorama device. It contains all the configuration settings and parameters for the device.

/devices: This part specifies that the configuration relates to devices managed by Panorama. Panorama can manage multiple devices, such as firewalls.

/entry[@name='localhost.localdomain']: The entry tag with the attribute @name='localhost.localdomain' identifies a specific device by its name. In this case, it refers to the device named "localhost.localdomain," which is a default or placeholder name for the device.

/template: This section indicates that the path is within the templates section. Templates in Panorama are used to define configuration settings that can be applied to multiple devices.

/entry[@name='CertificatesTemplate']: The entry tag with the attribute @name='CertificatesTemplate' identifies a specific template by its name. In this case, it refers to a template named "CertificatesTemplate."

/config/shared: This part of the path indicates that the configuration settings within this template are shared settings. Shared settings are common configurations that can be used across multiple devices or contexts within the Panorama management system.


PANORAMA VIRTUAL SYSTEM PATH


Path Example: /config/devices/entry/template/entry[@name='CertificatesTemplate']/config/devices/entry/vsys/entry[@name='vsys2']

/config: This indicates that the path is within the configuration section of the Panorama device. It contains all the configuration settings and parameters for the device.

/devices: This part specifies that the configuration relates to devices managed by Panorama. Panorama can manage multiple devices, such as firewalls.

/entry: This is a generic entry point under devices. However, since it does not have a @name attribute specified at this level, it applies to the broader device category.

/template: This section indicates that the path is within the templates section. Templates in Panorama are used to define configuration settings that can be applied to multiple devices.

/entry[@name='CertificatesTemplate']: The entry tag with the attribute @name='CertificatesTemplate' identifies a specific template by its name. In this case, it refers to a template named "CertificatesTemplate."

/config/devices: This part of the path specifies that the configuration settings within this template apply to devices.

/entry: This again specifies a generic entry point under devices in the context of the template. This would typically be further defined by specific device attributes, but here it leads to the virtual systems (vsys) section.

/vsys: This section specifies that the path is within the virtual systems (vsys) section. Virtual systems allow multiple virtualized instances of firewall configurations within a single physical firewall.

/entry[@name='vsys2']: The entry tag with the attribute @name='vsys2' identifies a specific virtual system by its name. In this case, it refers to a virtual system named "vsys2."


PANORAMA LEVEL


Path Example: /config/panorama

/config: This indicates that the path is within the configuration section of the Panorama device. It contains all the configuration settings and parameters for the device.

/panorama: This section specifies that the path is within the Panorama-specific configuration settings. This part of the configuration contains settings that are specific to the Panorama management system itself, rather than the devices it manages.


API User Setup Permissions in Panorama or Firewall Required
Tab Security Items
Xml Api Report,Log,Configuration,Operational Requests,Commit,Export,Import
Rest Api Objects/Devices,Panorama/Scheduled Config Push,Panorama/Templates,Panorama/Template Stacks,Panorama/Device Groups,System/Configuration,Plugins/Plugins

Test Cases

Firewall, Panorama Template and Panorama Level
Case Number Case Name Store Path Enrollment Params Expected Results Passed Screenshots
TC1 Firewall Enroll No Bindings /config/shared Alias:
www.certandchain.com
Overwrite:
false
Cert and Chain Installed on Firewall True
TC1a Firewall Enroll Template Stack /config/shared Alias:
www.tc1a.com
Overwrite:
false
Error Stating Template Stacks Not Used for Firewall True
TC2 Firewall Replace No Bindings /config/shared Alias:
www.certandchain.com
Overwrite:
true
Cert and Chain Installed on Firewall True
TC3 Firewall Remove Bound Certificate /config/shared Alias:
0.13757535891685202
Overwrite:
false
Cert will not be removed because bound True
TC4 Firewall Enroll Bindings /config/shared Alias:0.13757535891685202
Overwrite:
false
Will not replace cert since Overwrite=false True
TC5 Firewall Replace Bound Certificate /config/shared Alias:0.13757535891685202
Overwrite:
true
Will replace cert bindings get automatically updated since Overwrite=true True
TC6 Firewall Inventory /config/shared N/A Inventory will finish and certs from shared location inventoried. True
TC6a Firewall Inventory No Trusted Certs /config/shared N/A Inventory will finish no Trusted Certs and certs from shared location inventoried. True
TC7 Firewall Inventory With Virtual System /config/devices/entry[@name='localhost.localdomain']/vsys/entry[@name='vsys1'] N/A Will Inventory all certificates from vsys1 on firewall True
TC8 Firewall Enroll cert and chain to Virtual System /config/devices/entry[@name='localhost.localdomain']/vsys/entry[@name='vsys1'] Alias:
www.ejbcacertandchain.com
Cert is installed along with chain. True
TC9 Firewall Remove unbound cert from Virtual System /config/devices/entry[@name='localhost.localdomain']/vsys/entry[@name='vsys1'] N/A Will remove cert from test case 8 from Firewall Virtual System True
TC10 Firewall Remove bound cert from Virtual System /config/devices/entry[@name='localhost.localdomain']/vsys/entry[@name='vsys1'] Alias:
0.8168##
Cert will not be removed because it is bound. True
TC11 Firewall Replace without Overwrite on Virtual System /config/devices/entry[@name='localhost.localdomain']/vsys/entry[@name='vsys1'] Alias:
0.8168##
Overwrite:
true
User is warned Overwrite needs checked. True
TC12 Firewall Renew cert on Shared and Virtual System /config/devices/entry[@name='localhost.localdomain']/vsys/entry[@name='vsys1'] and /config/shared Alias:
www.renewtester.com
Cert renewed on vsys and shared locations True
TC13 Firewall Replace bound cert on Virtual System /config/devices/entry[@name='localhost.localdomain']/vsys/entry[@name='vsys1'] Alias:
0.8168##
Overwrite:
true
Cert will be replaced and binding updated on vsys. True
TC14 Panorama Template Enroll Certificate /config/devices/entry[@name='localhost.localdomain']/template/entry[@name='CertificatesTemplate']/config/shared Alias:
www.pantemptc1.com
Certificate is enrolled to shared location for template True
TC14a Panorama Invalid Template Stack /config/devices/entry[@name='localhost.localdomain']/template/entry[@name='CertificatesTemplate']/config/shared Alias:
www.tc14a.com
Error Occurs with list of valid Template Stacks To Use True
TC15 Panorama Template Replace Certificate /config/devices/entry[@name='localhost.localdomain']/template/entry[@name='CertificatesTemplate']/config/shared Alias:
www.pantemptc1.com
Overwrite:
true
Certificate is replaced in shared location for template True
TC16 Panorama Template Remove unbound Certificate /config/devices/entry[@name='localhost.localdomain']/template/entry[@name='CertificatesTemplate']/config/shared Alias:
www.pantemptc1.com
Certificate is removed from shared location for template True
TC16a Panorama Template Stack Push /config/devices/entry[@name='localhost.localdomain']/template/entry[@name='CertificatesTemplate']/config/shared Alias:
www.tc16a.com
Certificate pushed to Template and Template Stack True
TC17 Panorama Template Replace bound Certificate /config/devices/entry[@name='localhost.localdomain']/template/entry[@name='CertificatesTemplate']/config/shared Alias:
LongNameTest
Overwrite:
true
Certificate is replaced, binding updated in shared location for template True
TC18 Panorama Template Remove bound Certificate /config/devices/entry[@name='localhost.localdomain']/template/entry[@name='CertificatesTemplate']/config/shared Alias:
LongNameTest
Certificate is not removed because it is bound True
TC19 Panorama Template Shared Inventory /config/devices/entry[@name='localhost.localdomain']/template/entry[@name='CertificatesTemplate']/config/shared N/A Certificates are inventoried from this location True
TC20 Panorama Template Virtual System Inventory /config/devices/entry/template/entry[@name='CertificatesTemplate']/config/devices/entry/vsys/entry[@name='vsys2'] N/A Certificates are inventoried from this template vsys location True
TC21 Panorama Template Virtual System Enroll Certificate /config/devices/entry/template/entry[@name='CertificatesTemplate']/config/devices/entry/vsys/entry[@name='vsys2'] Alias:
www.vsys2enroll.com
Certificate is enrolled to vsys2 location for template True
TC21a Panorama Level Inventory No Trusted Certs /config/panorama N/A Certificates are inventoried from this location No Trusted Certs True
TC22 Panorama Template Virtual System Replace unbound Certificate /config/devices/entry/template/entry[@name='CertificatesTemplate']/config/devices/entry/vsys/entry[@name='vsys2'] Alias:
www.vsys2enroll.com
Certificate is replaced in vsys2 location for template True
TC23 Panorama Template Virtual System Remove unbound Certificate /config/devices/entry/template/entry[@name='CertificatesTemplate']/config/devices/entry/vsys/entry[@name='vsys2'] Alias:
www.vsys2enroll.com
Certificate is removed in vsys2 location for template True
TC24 Panorama Template Virtual System Renew bound Certificate /config/devices/entry/template/entry[@name='CertificatesTemplate']/config/devices/entry/vsys/entry[@name='vsys2'] Alias:
www.vsys2enroll.com
Certificate is renewed, binding updated in vsys2 location for template True
TC25 Panorama Level Inventory /config/panorama N/A Certificates are inventoried from this location True
TC26 Panorama Level Enroll Cert and Chain /config/panorama Alias:
www.panlevelcertandchain.com
Panorama Level Install Cert and Chain True
TC27 Panorama Level Enroll Cert overwrite warning /config/panorama Alias:
www.panlevelcertandchain.com
Overwrite:
false
Cert is not installed warned Overwrite is needed True
TC28 Panorama Level Replace Cert /config/panorama Alias:
www.panlevelcertandchain.com
Overwrite:
true
Cert is replaced because Overwrite was used True
TC29 Panorama Level Remove unbound Cert /config/panorama N/A Cert is removed because not bound True
TC30 Panorama Level Replace bound Cert /config/panorama Alias:
PanoramaNoPK
Overwrite:
true
Cert is replaced, binding updated True
TC31 Firewall previous version cert store settings /config/shared Alias:
www.extraparams.com
Overwrite:
false
Cert is still installed because it ignores extra params True

When creating cert store type manually, that store property names and entry parameter names are case sensitive