Focus

Prisma Agent

Configure Certificate Selection in Prisma Agent

Table of Contents

Set Up LDAP Authentication for Prisma Agent

Configure Certificate Selection in Prisma Agent

Configure certificate selection criteria in Prisma Agent to ensure proper user identification and enhance security policy enforcement.

Where Can I Use This?	What Do I Need?
Prisma Agent deployment configuration file (config.json) Prisma Access (Managed by Panorama or Strata Cloud Manager)	Check the prerequisites for the deployment you're using Minimum Prisma Agent version for configuration via config.json: 25.6.1 Minimum Prisma Agent version for configuration via Strata Cloud Manager or Panorama: 26.3 macOS, Windows, Android, or Linux devices Contact your Palo Alto Networks account representative to activate the Prisma Agent feature

Certificate-based authentication in Prisma Agent provides a secure mechanism for verifying user identity, but requires precise certificate selection to maintain accurate User-ID mapping. By default, when a user certificate is unavailable, the agent might use a machine certificate, which can result in incorrect User-ID mapping where the device serial number is used instead of the actual username. This behavior can compromise policy rules that depend on accurate user identification.

The certificate selection feature allows administrators to define specific criteria for how Prisma Agent selects certificates during authentication. This ensures that the agent consistently chooses the correct certificate, leading to proper User-ID mapping and effective security policy enforcement.

There are two key components to understand when configuring certificate selection:

Certificate Store Filtering—Certificate store filtering determines where the agent searches for authentication certificates. On Windows, certificates can be stored in either the user's personal certificate store or the local machine's certificate store. On macOS, certificates are stored in login and system keychains, with similar separation between user and system. On Linux, certificates are stored in file-based certificate stores with distribution-specific paths configured through the config.json deployment file. The agent can search exclusively in the user store, exclusively in the machine store, or to search first in the user store and then fall back to the machine store if needed.
Extended Key Usage (EKU) OID Filtering—Extended Key Usage (EKU) OID filtering provides additional granularity by enabling you to specify which certificate purposes are valid for authentication. Every certificate includes information about its intended use through OIDs (Object Identifiers). By specifying particular EKU OIDs, you can ensure the agent only selects certificates that were issued for specific purposes, such as client authentication or smart card login.

When the agent needs to authenticate, it follows the configured store preference and EKU filtering criteria to select the appropriate certificate. If multiple valid certificates are found, end users will see a pop-up with the list of certificates that match the EKU OID filter and store. The users will need to select a certificate to continue. Be sure to distribute only a single certificate so the authentication experience is seamless for the user.

In pre-logon scenarios, the agent always uses the machine store regardless of the configured preference, as the user context is not yet available. (Does not apply to Prisma Agent Linux)

Interaction with SAML Authentication

For each authentication method configured in Prisma Agent, the certificate selection behavior will interact with Security Assertion Markup Language (SAML) authentication in distinct ways. Here's how each method works:

Client Certificate OR SAML—With this authentication method, the agent first attempts certificate-based authentication. If successful, the user is granted access without needing to provide SAML credentials. If certificate authentication fails (either because no valid certificate is found according to the configured criteria, or the certificate validation fails), the agent automatically falls back to SAML authentication, prompting the user for credentials.
Client Certificate AND SAML—This method implements multifactor authentication by requiring both certificate validation and SAML authentication. The agent first validates the user's certificate according to the configured criteria, and then prompts the user to complete the SAML authentication process. Both authentication methods must succeed for the user to be granted access. If certificate authentication fails due to no valid certificate being found, the entire authentication process fails, and an error message is displayed to the user.
Client Certificate—With this method, only certificate-based authentication is accepted. The agent attempts to locate and validate a certificate according to the configured certificate store and EKU OID criteria. If a valid certificate is found and validated, the user is granted access. If no valid certificate is found or certificate validation fails, the authentication fails completely, and the user is shown an appropriate error message. No fallback to other authentication methods is provided.

In all these authentication methods, the certificate selection process follows the configured client_cert_lookup_store setting (user, machine, or user_then_machine) and applies any configured EKU OID filtering criteria to determine which certificates are valid for authentication.

Certificate Selection Notes

These settings are applicable only to the configuration applied using the config.json file for the initial deployment of Prisma Agent and are used for certificate authentication
The settings enabled through the config.json file are preserved upon reboot, restart, and agent upgrade unless overridden by the Agent Settings in Prisma Access (Managed by Panorama or Strata Cloud Manager).
The Agent Settings take precedence from the second login onward; the config.json settings are used on the first login only.
In pre-logon scenarios, the client_cert_lookup_store configuration is ignored, and the agent only uses the "Machine Store" for certificate lookup. However, the client_cert_eku_oid_list configuration is still applied (Does not apply to Prisma Agent Linux)
If client_cert_eku_oid_list is not specified, the agent defaults to using only certificates with the Client Authentication OID (1.3.6.1.5.5.7.3.2)
Certificate selection information on the Endpoint Manager server resets to the default value when the agent switches to a different Endpoint Manager server or when the agent is unenrolled. When the user reconnects after a reset, default certificate selection takes place.
On Linux, switching between Endpoint Manager servers from Prisma Agent is not supported. To unenroll from an Endpoint Manager, run pacli epm unenroll. Certificate selection resets to the default value after unenrollment.
On Linux, when multiple certificates match the configured criteria, Prisma Agent displays a certificate selection dialog so users can choose the appropriate certificate.

To configure the certificate selection:

Configure Certificate Selection in Prisma Agent (config.json)

Configure certificate selection criteria in the Prisma Agent deployment configuration file.

Edit the configuration file (config.json) file to be used for the deployment of Prisma Agent.
Add or modify the following parameters within the JSON structure:
- Client Certificate Lookup Store
  - Parameter Name: client_cert_lookup_store
  - Possible Values:
    user—Agent searches only in the certificate store of the currently logged-in user
    machine—Agent searches only in the local machine's certificate store
    user_then_machine—Agent searches first in the user store, then in the machine store if no certificate is found (Default)
- Extended Key Usage (EKU) OIDs for Client Certificate
  - Parameter Name: client_cert_eku_oid_list
  - Value Format: Comma-separated OID strings. This value can be empty, have one value, or a list of values.
  - Common OIDs:
    Client Authentication (1.3.6.1.5.5.7.3.2) (Default if not specified)
    Smart Card Logon (1.3.6.1.4.1.311.20.2.2)
    Any Extended Key Usage (2.5.29.37.0)
    IPSec End System (1.3.6.1.5.5.7.3.5)
    IPSec Tunnel (1.3.6.1.5.5.7.3.6)
    IPSec User (1.3.6.1.5.5.7.3.7)
    OCSP Signing (1.3.6.1.5.5.7.3.9)
Example Configurations:

To search only in the user store for certificates with Client Authentication, Server Authentication, and OCSP Signing OIDs:
```
{
     "server_url":"xxxxx.epm.gpcloudservice.com,
     "tenant_id":"xxxxxxxxxx",
     "unload_gp":true,
     "client_cert_lookup_store" : "user",
     "client_cert_eku_oid_list": [
          "1.3.6.1.5.5.7.3.2",
          "1.3.6.1.5.5.7.3.1",
          "1.3.6.1.5.5.7.3.9"
     ]
}
```
To search only in the machine store for certificates with the Client Authentication OID:
```
{
     "server_url":"xxxxx.epm.gpcloudservice.com",
     "tenant_id":"xxxxxxxxxx",
     "unload_gp":true,
     "client_cert_lookup_store" : "machine",
     "client_cert_eku_oid_list": ["1.3.6.1.5.5.7.3.2"]
}
```
To search first in the user store and then the machine store for certificates with the Client Authentication OID (default for unspecified client_cert_eku_oid_list value):
```
{
     "server_url":"xxxxx.epm.gpcloudservice.com",
     "tenant_id":"xxxxxxxxxx",
     "unload_gp":true,
     "client_cert_lookup_store" : "user_then_machine",
     "client_cert_eku_oid_list": []
}
```
Linux Example Configuration:

To filter certificates by EKU OID on Linux:
```
{
     "server_url":"xxxxx.epm.gpcloudservice.com",
     "tenant_id":"xxxxxxxxxx",
     "client_cert_eku_oid_list": ["1.3.6.1.5.5.7.3.2"]
}
```
Save the config.json file and deploy it along with the Prisma Agent.
Monitor the certificate activity by reviewing the Prisma Agent logs on the endpoints.
The agent logs activity in the PAS.log file on Windows. On macOS, the activity is logged in the PAS.log and PAUI.log files. On Linux, the activity is logged in the PAS.log file. The agent stores the following information in the logs:
- Certificate lookup store and EKU OIDs configured in config.json
- Whether the certificate selection passed or failed

Configure Certificate Selection in Prisma Agent (Strata Cloud Manager)

Configure certificate selection criteria for Prisma Agent authentication in Strata Cloud Manager Managed Prisma Access.

To configure certificate selection criteria for Prisma Agent authentication in Strata Cloud Manager Managed Prisma Access.

Select ConfigurationNGFW and Prisma AccessConfiguration ScopeAccess AgentSetupPrisma Access Agent.
Add Agent Settings, or edit an existing agent settings profile.
Expand Show Advanced Options and then expand Authentication.
For Client Certificate Lookup Store, choose the certificate store the agent searches when selecting certificates for authentication:
- User Store—Searches only the certificate store of the currently logged-in user.
- Machine Store—Searches only the local machine's certificate store.
- User, then Machine Store—Searches the user store first; if no matching certificate is found, searches the machine store. (Default)
During a pre-logon tunnel, the agent always uses the machine store regardless of this setting.
(Optional) In Extended Key Usage OID for Client Certificate, enter the OID values you want the agent to use to filter which certificates are valid for authentication. Enter OIDs as comma-separated values. If you leave this field blank, the agent doesn't perform EKU-based filtering.
- The agent selects certificates that match any one of the specified OIDs.
- You can enter up to 20 OIDs. Hover your cursor over the tool tip to show the common OIDS.
- Common OIDs:
  - Client Authentication (1.3.6.1.5.5.7.3.2) (Default if not specified)
  - Smart Card Logon (1.3.6.1.4.1.311.20.2.2)
  - Any Extended Key Usage (2.5.29.37.0)
  - IPSec End System (1.3.6.1.5.5.7.3.5)
  - IPSec Tunnel (1.3.6.1.5.5.7.3.6)
  - IPSec User (1.3.6.1.5.5.7.3.7)
  - OCSP Signing (1.3.6.1.5.5.7.3.9)
Save your agent settings.
Push the Prisma Agent configuration to apply the changes to endpoints.

Configure Certificate Selection in Prisma Agent (Panorama)

Configure certificate selection criteria for Prisma Agent authentication in Panorama Managed Prisma Access.

To configure certificate selection criteria for Prisma Agent authentication in Panorama Managed Prisma Access:

From the Cloud Services plugin in Panorama, select PanoramaCloud ServicesPrisma Access AgentLaunch Prisma Access Agent.
Select ConfigurationPrisma Access AgentSettings.
Select the Prisma Access Agent tab.
Add Agent Settings, or edit an existing agent settings profile.
Under the Authentication section, for Client Certificate Lookup Store, choose the certificate store the agent searches when selecting certificates for authentication:
- User Store—Searches only the certificate store of the currently logged-in user.
- Machine Store—Searches only the local machine's certificate store.
- User, then Machine Store—Searches the user store first; if no matching certificate is found, searches the machine store. (Default)
During a pre-logon tunnel, the agent always uses the machine store regardless of this setting.
(Optional) In Extended Key Usage OID for Client Certificate, enter the OID values you want the agent to use to filter which certificates are valid for authentication. Enter OIDs as comma-separated values. If you leave this field blank, the agent doesn't perform EKU-based filtering.
- The agent selects certificates that match any one of the specified OIDs.
- You can enter up to 20 OIDs. Hover your cursor over the tooltip to show the common OIDS.
- Common OIDs:
  - Client Authentication (1.3.6.1.5.5.7.3.2) (Default if not specified)
  - Smart Card Logon (1.3.6.1.4.1.311.20.2.2)
  - Any Extended Key Usage (2.5.29.37.0)
  - IPSec End System (1.3.6.1.5.5.7.3.5)
  - IPSec Tunnel (1.3.6.1.5.5.7.3.6)
  - IPSec User (1.3.6.1.5.5.7.3.7)
  - OCSP Signing (1.3.6.1.5.5.7.3.9)
Save your agent settings.
Push the Prisma Agent configuration to apply the changes to endpoints.

Set Up LDAP Authentication for Prisma Agent

Set Up the Prisma Agent

Prisma Agent Docs

Configure Certificate Selection in Prisma Agent

Prisma Agent Docs

Configure Certificate Selection in Prisma Agent

Configure Certificate Selection in Prisma Agent (config.json)

Configure Certificate Selection in Prisma Agent (Strata Cloud Manager)

Configure Certificate Selection in Prisma Agent (Panorama)

Activation and Onboarding

SASE

Cloud-Delivered Security Services

Network Security

Endpoints

Visibility & Monitoring

Best Practices

Experts Corner