Creating a Panorama application object

A Panorama application object provisions a certificate into a Panorama configuration, where Panorama distributes it to the firewalls it manages. This lets you rotate a certificate once, centrally, instead of once per firewall.

For version compatibility information, see Supported integrations with Trust Protection Foundation.

BEST PRACTICE Consider managing object settings using a policy. For more information, see Managing applications using policies.

Before you begin: choose a provisioning scope and a binding target

Two settings shape most of this page, and they constrain each other. Decide both before you start.

Provisioning Type is where in the Panorama hierarchy the certificate is stored:

Panorama stores the certificate on Panorama itself, for Panorama's own use. Nothing is pushed to managed firewalls.
Template stores the certificate in a template, where the firewalls that inherit that template pick it up.
Template Stack stores the certificate in a template stack.

Certificate Binding Target is what the certificate is attached to once it is stored. Not every combination is valid:

Certificate Binding Target	Valid with which Provisioning Type
None	Any. The certificate is provisioned and nothing is bound to it.
SSL/TLS Service Profile	Any.
Decryption Policy Rule	Template or Template Stack only.
Web Management UI Profile	Panorama only.

On the application object, an invalid combination cannot be selected: changing Provisioning Type removes the binding targets it does not allow from the Certificate Binding Target list, and if one of those was already selected, the value switches to None (for Decryption Policy Rule) or to SSL/TLS Service Profile (for Web Management UI Profile). A policy folder shows all four binding targets regardless of provisioning type, so an invalid combination can be set there. It is rejected when provisioning starts, with Decryption Policy Rule binding is not supported when Provisioning Type is Panorama or Web Management UI Profile binding is only supported when Provisioning Type is Panorama.

Choosing Web Management UI Profile replaces the certificate that secures Panorama's own administrative interface. In this mode Trust Protection Foundation always installs the full certificate chain and always uses the shared partition, whatever those fields are set to, because an incomplete chain would lock administrators out of Panorama.

WARNING! Provisioning to Web Management UI Profile restarts Panorama's web server.

Administrators lose the Panorama web interface for a few moments, and must reload the page afterward to pick up the new certificate. Browsers that cached the old session may need a new tab or a cleared cache.

Trust Protection Foundation can lose its own connection during that restart and log Unable to connect to the remote server. That message does not mean the certificate failed to install. Reload the Panorama interface and check Panorama > Setup > Management before retrying — the provisioning has usually already succeeded, and retrying restarts the web server again for nothing.

NOTE Accepting every default does not put certificates on your firewalls.

Provisioning Type defaults to Panorama, which stores the certificate on Panorama for its own use and distributes nothing. To reach managed firewalls you must choose Template or Template Stack, and set Push to Devices to Yes — which also defaults to No. Neither default changes on its own.

If most of your applications push to devices, set Push to Devices once on the policy folder rather than on each application object.

To create and configure a Panorama application object

From the Certificate Manager menu bar, click Policy tree.
In the Policy tree, select the device object to which you want to add the new application object, and then click Add > Application, and then select Panorama.
When the new application object page appears, then under Status, clear the Processing Disabled checkbox.

When checked, this option disables provisioning of the certificates installed on the current application. This means that Trust Protection Foundation does not attempt to install, renew, process, or validate certificates on the application.
(Optional) In the Device Certificate box, click to select and associate a certificate with the new application.

NOTE If you don't have a certificate ready, you can do this later or you can do it on the certificate's Association tab.

To associate a certificate with the current application, you must have write permissions to the application object and either write or associate permissions to the certificate object.

For detailed information on associating a certificate with an application, see Associating a certificate with an application object.
Under General, do the following:
1. In the Application Name field, type a name for the new application.
2. (Optional) In the Description field, type a description for the purpose of the application.
  
  A strong description can help to provide context for other administrators who might need to manage the new application.
3. In the Contacts field, select user or group identities you want assigned to this application object (or choose the Use policy value to configure contacts using a policy).
  
  Default system notifications are sent to the contact identities. The default contact is the master administrator.
  
  TIP If the Identity Selector dialog is not populated when it first opens, enter a search query to retrieve the Identity list. The administration console does not automatically display external users and groups. You must first enter a search string so Trust Protection Foundation can query the external Identity store, then return the list of requested users or groups. If you want to display all user or group entries, enter the wildcard character (*).
  
  Press Shift+click to select multiple, contiguous users and groups. Press Ctrl+click to select multiple, discontiguous users and groups.
4. In the Approvers field, select user or group Identities you want to assign to approve workflows (certificate approval or injection command) for the new application.
  
  The default approver is the master administrator. For more information on defining workflow objects, see Implementing certificate workflow management.
5. (Conditional) If your application (or certificate) object is affected by a defined workflow and you want users to use a console other than Policy Tree, click Managed By and select which administration console to use as part of the workflow.
  
  You only need to configure this if you are using workflows and expect users to perform a task using a particular administration console. The default setting is Policy Tree.
  
  For more information, see Specify folders and certificates to be managed by Certificate Manager .

Refer to the following table to complete the settings for the application object.

Several fields appear only when another field is set a particular way. Those are marked (Conditional) and the condition is stated in the description.

Field	Policy	Description
Application Information
Application Credential		The credential that Trust Protection Foundation uses to authenticate to Panorama's XML API. Use a username and password credential, or an Adaptable credential whose script returns a username and password. An Adaptable credential that returns any other kind of credential is rejected when the application provisions. You can leave this empty and set the credential on the parent device object instead, where every application object under that device inherits it. That is usually the better choice, since one Panorama device typically hosts many application objects.
HTTPS Port		The port Trust Protection Foundation uses to reach Panorama. Defaults to 443.
Provisioning Scope
Provisioning Type		Where the certificate is stored in the Panorama hierarchy: Panorama, Template, or Template Stack. Required. Defaults to Panorama. This choice limits which Certificate Binding Target values are valid, and — together with the binding target you pick — it decides whether the Template, Template Stack, Device Group, Push to Devices, Certificate Partition, and Binding Target Partition fields appear at all. Template Stack cannot be combined with remote key generation. If the certificate has Generate Keypair on Application enabled, the run fails at the start with Remote Key Generation is not supported when Provisioning Type is 'Template Stack'. Use Template or Panorama provisioning for remotely generated keys.
(Conditional) Template		The template that receives the certificate. Appears and is required only when Provisioning Type is Template.
(Conditional) Template Stack		The template stack that receives the certificate, or that the change is pushed through. It appears, and is required, in exactly three cases: Provisioning Type is Template Stack — the stack is the install target. Provisioning Type is Template and Push to Devices is Yes — the stack is the target of the push. Provisioning Type is Template and Certificate Binding Target is Decryption Policy Rule. With Template provisioning and none of those conditions met, the field does not appear and no stack is needed.
(Conditional) Device Group		The device group that owns the decryption policy rule. Appears and is required only when Certificate Binding Target is Decryption Policy Rule.
(Conditional) Push to Devices		When Yes, Trust Protection Foundation follows its commit with a commit-all, so Panorama pushes the change out to managed devices. When No, the change is committed on Panorama only and reaches the firewalls at your next push. Appears only when Provisioning Type is not Panorama, because Panorama-scoped certificates are not distributed to firewalls. Defaults to No. What gets pushed depends on the binding target: Decryption Policy Rule — a shared-policy commit-all to the Device Group, including its templates. The rule lives at device-group scope, so that is what has to be pushed. Any other binding target — a commit-all to the Template Stack named on the application. With Template provisioning, setting this to Yes makes Template Stack required: a template is only the wrapper, and the stack is what owns the devices. One template can belong to several stacks, so naming the stack is how you choose which devices receive the certificate. With Template Stack provisioning the stack is already required. The push is slow. Trust Protection Foundation commits, then polls Panorama for the commit result rather than assuming it worked, so expect the work item to sit in progress for a while. If Panorama's own push task stalls, Trust Protection Foundation keeps rescheduling the status check instead of failing — check the task list at the bottom right of the Panorama interface to see whether the delay is on the Panorama side.
Certificate & Key Settings
(Conditional) Certificate Partition		The virtual system the certificate is uploaded to, for example vsys1. Leave it empty for the shared partition. Appears only when Provisioning Type is Template. This field leads the binding-target scope: if you name a specific vsys here, Binding Target Partition must be that same vsys. To bind across virtual systems, leave this empty or set it to shared.
Certificate Binding Target		What the certificate is attached to after it is provisioned. Required. Defaults to SSL/TLS Service Profile. None — provision the certificate and bind nothing. Use this when Trust Protection Foundation manages the certificate and your Panorama administrator manages the bindings. SSL/TLS Service Profile — bind to the profile named in SSL/TLS Service Profile. Decryption Policy Rule — bind to the rule named in Decryption Policy Rule Name. Requires Template or Template Stack provisioning. Web Management UI Profile — replace the certificate on Panorama's own management interface. Requires Panorama provisioning. The driver reads the profile off the management interface, so there is no profile name to supply.
(Conditional) Create Binding Target		When Yes, Trust Protection Foundation creates the binding target if it does not already exist, using the name you typed. Defaults to No, which is the recommended setting — it keeps a typo from silently creating a second profile or rule alongside the real one. Appears when Certificate Binding Target is SSL/TLS Service Profile or Decryption Policy Rule. It does not apply to None or Web Management UI Profile. When this is No and the named target does not exist on Panorama, the application still saves without complaint. The failure appears when you provision, not when you save, because Trust Protection Foundation only looks for the target at that point. After that failure, reset the application before you retry.
(Conditional) Binding Target Partition		The virtual system the SSL/TLS service profile lives in. Leave it empty for the shared partition. Appears only when Provisioning Type is Template and Certificate Binding Target is SSL/TLS Service Profile. Certificate Partition decides what you may put here, not the other way around: When Certificate Partition is empty or shared, any value is allowed here — a shared certificate can be bound in any virtual system. When Certificate Partition names a virtual system, this field must name the same virtual system. Leaving it empty or setting it to shared is not a way to widen the scope; it fails with Certificate Partition 'vsys1' is vsys-scoped, so the Binding Target Partition must be the same vsys ('vsys1') — but it is ''. Use a shared Certificate Partition to bind across vsys. The two partition names are compared exactly, including case. vsys1 and VSYS1 save without complaint and then fail when the application provisions.
(Conditional) SSL/TLS Service Profile		The name of the SSL/TLS service profile to bind the certificate to. Appears and is required only when Certificate Binding Target is SSL/TLS Service Profile.
(Conditional) Decryption Policy Rule Name		The name of the decryption policy rule to bind the certificate to. Appears and is required only when Certificate Binding Target is Decryption Policy Rule, which also makes Device Group and Template Stack required. This is the rule name, not the device group name. If Create Binding Target is Yes, you can type a name that does not exist yet and Trust Protection Foundation creates the rule. Find existing rules on Panorama under Policies, within the device group you intend to use. A decryption policy rule holds at most 12 certificates. Trust Protection Foundation adds one certificate per provisioning run and counts the rule's existing members first, so certificates that other applications or an administrator placed on the rule count toward the 12. WARNING! Certificates accumulate on this rule, and the rule eventually fills. Every renewal adds the new certificate to the rule. Trust Protection Foundation never removes the one it added last time, and Replace Certificate has no effect for this binding target. After enough renewals the rule fills and the next renewal fails. Prune superseded certificates from the rule on Panorama as part of your normal maintenance, rather than waiting for the failure. When the rule is already full, the Bind Certificate stage fails. The rule's current members are read from Panorama to make that count, and the stage runs after Install Certificate has already imported the new certificate, so this is a run-time failure rather than something caught when you save the application. The failed run discards every uncommitted change belonging to the administrator account Trust Protection Foundation signed in with, which takes the import back with it.
Install Chain		When Yes, the root and intermediate certificates are installed alongside the certificate and private key. Defaults to No. This field stays editable when Certificate Binding Target is Web Management UI Profile, but its value is ignored: that mode always installs the full chain, whether this is set to Yes or No.
(Conditional) Replace Certificate		When Yes, Trust Protection Foundation makes a best-effort attempt to remove the certificate it previously provisioned for this application before installing the new one. Defaults to No. It has no effect the first time an application provisions, because there is no previous certificate on record to replace. It takes effect from the first renewal onward. Appears when Certificate Binding Target is None, SSL/TLS Service Profile, or Web Management UI Profile — the three targets that reference a single certificate. A decryption policy rule holds a list of certificates instead, so replacement does not apply; if you set this through a policy folder, it is ignored for that binding target.
Provisioned Certificate Name		Read-only. The name of the certificate object the driver created in Panorama. Trust Protection Foundation writes this field; you cannot set it, and it cannot be managed by policy.
Device Configuration
Lock Config		When Yes, Trust Protection Foundation takes Panorama's configuration lock while it provisions the certificate, and releases it afterward. Defaults to No. This setting does not change what gets committed. With the lock or without it, Trust Protection Foundation performs a partial commit scoped to its own administrator account, so changes another administrator has pending are never swept up in it. If another session already holds the lock, provisioning does not fail — the work item reports Device config lock is held by another administrator; will retry and retries later.

When you are finished, click Save.

Give Trust Protection Foundation its own Panorama administrator account

BEST PRACTICE Do not share the Application Credential account with anything else that signs in to Panorama.

Two behaviors make a shared account costly, and neither depends on Lock Config:

When a provisioning stage fails, Trust Protection Foundation discards all uncommitted changes belonging to the account it signed in with — not only the ones this run made. Another administrator's pending work is safe, but a person or script using the same account loses theirs.
Push to Devices issues a commit-all, which is not scoped to an administrator at all. Whatever is pending in the candidate configuration for the targeted template stack or device group goes out with it.

After a failed provisioning, reset the application before retrying

When provisioning fails — a binding target that does not exist, a connection lost while the web interface restarted, a rejected commit — the application object stays in an error state. Correct the setting that caused the failure, then reset the application before you push again.

A retry resumes at the stage that failed rather than starting over, and the failed run has already discarded its uncommitted changes on Panorama. Resetting returns the application to the first stage, so the whole sequence runs again against the configuration you corrected.

Your corrected settings are read fresh at the start of every run, so the reset is about where the run starts, not about whether your change is picked up.

If you also run Onboard Discovery against this device

Onboard Discovery creates Panorama application objects for the certificate bindings it finds, and it reconciles those against the application objects Trust Protection Foundation already has. An application you create here is part of that comparison.

WARNING! Provision this application before you run Onboard Discovery against its device.

Part of what Onboard Discovery matches on is recorded only when an application provisions. An application that you created by hand, linked a certificate to, and have not yet provisioned does not match, so the first run disables it, renames it with an - obsolete suffix, and creates a replacement carrying only the discovered binding and default settings. The settings you chose on this page are not carried over, and anything that refers to the application by name or DN then points at a disabled object.

An application that has no certificate linked to it yet is adopted instead. It keeps its name, its settings and its history, and Onboard Discovery adds only the certificate.

For what a scan reads, what it creates, and what to prepare first, see Onboard Discovery prerequisites.

Naming rules for Panorama objects

The Template, Template Stack, Device Group, SSL/TLS Service Profile, and Decryption Policy Rule Name fields all name objects on Panorama, and all follow the same rule: names may contain only letters, digits, spaces, dots, hyphens, and underscores, and must start with a letter or a digit. A name also cannot end with a space — a trailing space is invisible in the field, and Panorama would treat profile and profile as two different objects.

Trust Protection Foundation checks the name before it takes the configuration lock, so an invalid name fails immediately rather than part-way through provisioning.

What's next?

After you've created an application object, here are other things you can do to manage the new application:

On the application's Settings sub-tab:
- Click to push a certificate to its associated application.
  
  For more information, see Pushing a certificate and private key to an application .
- Click Reset to stop processing the application and reset the status and stage.
- Click to reattempt installation of the certificate to its associated application, .
- Click Validate Now to validate the applications associated certificate.
  
  Validation requests are placed into a queue. When your validation runs, the application and its associated certificate are scanned according to the settings configured in the application object’s Validation tab.
  
  For more information, see About certificate and application validation.
On the application object's Validation tab, you can configure validation settings for the application object.
On an object's General tab:
- Click the Log sub-tab to view any events that are triggered by the template object.
- Click the Permissions sub-tab to configure the users or groups to whom you want to grant permissions to the new object. For more information, see Permissions overview.