Setting up AuthZHelper and SSH Key Authorization Rules

This topic explains how to install, configure, and authenticate AuthZHelper so administrators can use Trust Protection Foundation (TPF) and SSH Manager to manage SSH activity with SSH key authorization rules. See SSH Key Authorization Rules and AuthZHelper

Use this topic when you are ready to deploy AuthZHelper on your systems. These steps help you prepare your environment, configure SSH, install AuthZHelper, and confirm it is working. Each step depends on the previous step. Completing all steps ensures AuthZHelper is installed correctly and TPF can track and report SSH key authorization rules.

• Step 0: Download AuthZHelper package for your system

• Step 1: Design your system for AuthZHelper

• Step 2: Meet system requirements for AuthZHelper

• Step 3: Set up AuthZHelper users

• Step 4: Prepare Linux environment for AuthZHelper

• Step 5: Configure SSH for AuthZHelper

• Step 6: Install AuthZHelper on Linux distributions

• Step 7: Configure SELinux for AuthZHelper (RHEL only)

• Step 8: Review the setup after installing AuthZHelper on Linux (any distribution)

• Step 9: Authenticate AuthZHelper

• Step 10: Verify the AuthZHelper setup

• Step 11: Troubleshoot the AuthZHelper setup

After you complete these steps, AuthZHelper is ready to use. You can then monitor and enforce SSH key authorization rules by following the instructions in Managing and monitoring SSH Key Authorization Rules.

---

Step 0: Download AuthZHelper package for your system

Download the AuthZHelper package for your system. These URLs always serve the most recent release.

System	File	URL
Fedora / RHEL	Package	https://dl.ngts.paloaltonetworks.com/ssh/authzhelper-amd64-latest.rpm
Fedora / RHEL	Signature	https://dl.ngts.paloaltonetworks.com/ssh/authzhelper-amd64-latest.rpm.sig
Ubuntu / Debian	Package	https://dl.ngts.paloaltonetworks.com/ssh/authzhelper-amd64-latest.deb
Ubuntu / Debian	Signature	https://dl.ngts.paloaltonetworks.com/ssh/authzhelper-amd64-latest.deb.sig
Other Linux distributions	Package	https://dl.ngts.paloaltonetworks.com/ssh/authzhelper-amd64-latest.tar.gz
Other Linux distributions	Signature	https://dl.ngts.paloaltonetworks.com/ssh/authzhelper-amd64-latest.tar.gz.sig
All	Checksums	https://dl.ngts.paloaltonetworks.com/ssh/SHA256SUMS

File names don't include the release version. To see which version you downloaded, run one of these commands:

• .deb packages: dpkg -I authzhelper-amd64-latest.deb

• .rpm packages: rpm -qip authzhelper-amd64-latest.rpm

---

Step 1: Design your system for AuthZHelper

To control SSH access and to populate SSH key authorization rules in Trust Protection Foundation (TPF), you must design and implement AuthZHelper correctly.

• Use both traditional SSH agent and AuthZHelper tools.. The most secure deployment of SSH Managerincludes configuring and managing machines through traditional SSH agent and agentless tooling in addition to using AuthZHelper. Combining both technologies provides robust discovery, remediation (key rotation), trust mapping and authorization tracking.

• Design your architecture. Identify device groups, proxy requirements and connection state. Each machine must be configured to communicate with TPF to track SSH key authorization rules.

  Host machines that use AuthZHelper must follow a local-policy approach. They must trust the authorized keys specified in their configuration file, even if they cannot connect to TPF. This behavior is intentional and ensures that SSH access is not disrupted during network outages or connectivity issues.

• Design your deployment.: You can deploy the AuthZHelper utility passively with Ansible or other orchestration tools. A sample playbook is provided in the download package and is also available from CyberArk Customer Support and Professional Services.

  For best results, deploy AuthZHelper in groups that align with your strategic objectives. Each group can be rolled out separately, allowing you to assess performance and impact. On the backend, every machine receives a unique identifier that is used for applying authorization rules.

• Deploy, test and monitor: Deploy the AuthZHelper utility to your initial device group and verify that it is functioning as expected. Detailed deployment steps are provided later in this topic, but in summary, deployment involves:

  • Install, configure and authenticate AuthZHelper.

  • (Optional) Set up advanced configuration for TrustedUserCAKeys or Authorized Principals.

  • Update the sshd_config file to use only AuthZHelper for authentication. Verify and restart the service.

  • Monitor and report on authorizations through TPF.

  After deployment, you should monitor the system to ensure proper operation before proceeding to additional device groups.

• Create reports and set up alerting: Once SSH key authorization rules are being routed through AuthZHelper and Trust Protection Foundation, administrators can view and generate reports showing which SSH keys are being used to access host devices and under which principal (user or service account). See Managing and monitoring SSH Key Authorization Rules.

---

Step 2: Meet system requirements for AuthZHelper

When setting up SSH Manager with AuthZHelper and the SSH Key Authorization Rules features, you should consider the following:

• As of TPF version 25.3, you should have a dedicated TPF instance to accommodate SSH Manager. This is due to increased overhead related to SSH authorization frequency.

• When using the SSH Key Authorization Rules feature, note that Agentless Discovery may incorrectly report authorized keys when AuthZHelper is enabled. This is because AuthZHelper uses its own configuration to specify the locations of authorized keys files, which may differ from the locations that the agent scans. As a result, the agent may not detect authorized keys managed by AuthZHelper, leading to discrepancies in reported key data.

  In a standard scenario, AuthZHelper and Agent(less) use a known folder (for example, /home/%u/.ssh/) and point to the same AuthorizedKeys file.

• Because SSHD is configured with AuthorizedKeys set to none when using AuthZHelper, the agent does not detect any authorized keys. Instead, AuthZHelper uses its own config.yaml to identify authorized keys, which can cause keys to appear mis-labeled or appear as public keys.

• AuthZHelper supports OpenSSH Match directives with additional configuration. OpenSSH can change authorization settings such as AuthorizedKeysFile, TrustedUserCAKeys, and AuthorizedPrincipalsFile based on conditions like the user name, group, or source IP address. AuthZHelper does not directly evaluate these Match conditions. It uses the authorization settings defined in config.yml.

  If your sshd_config contains Match directives that override AuthorizedKeysFile, TrustedUserCAKeys, and AuthorizedPrincipalsFile, you must configure AuthorizedKeysCommand in the Match section to use AuthZHelper and provide a separate configuration (config.yml) containing the overridden authorization values. This ensures that AuthZHelper uses the same authorization settings as OpenSSH for the applicable connection.

• Known conflict: If a user has configured their authorized_keys file with conflicting SSH options (i.e. no-port-forwarding with permit-listen="[HOST]:PORT"), the default behavior of SSHD is to reconcile the options, generally preferring the most restrictive result. However, some combinations are considered invalid by SSHD (i.e. multiple command= options). Any of these invalid combinations will result in a failed login attempt by SSHD. In these cases, SSH Manager reflects an "observed" rule, indicating that the account does have access to the host. This choice was made to show all potential accesses in the ruleset even if SSHD would ultimately deny those attempts due to the user's misconfiguration of authorized_keys.

Supported distributions for AuthZHelper

OS family	Distribution / OS name	BASH version	OpenSSH (min)	Notes
Linux	Ubuntu (server) 24.04 LTS	5.2.15	9.6p1
Debian	12 (Bookworm)	5.2.15	9.2p1	Limited support
Debian	13 Trixie	5.2.37	9.2p1
Fedora	40	5.2.26	9.8p1
Arch Linux	Rolling release	5.2.x	10.0p1
CentOS Stream	9	5.1.8	8.7p1	Limited support
Alpine	3.21	5.2.15	10.0p1
RHEL	10	5.x	9.9
RHEL	9	5.x	8.7p1	Limited support
RHEL	8.x	5.x	8.0p1	Limited functionality. Connection and routing data are omitted from audit logs.
RHEL	7.4 - 7.9	5.x	7.4p1	Limited functionality. Supports local users only. Connection and routing data are omitted from audit logs.
Unix	AIX 7.2	5.1.4	9.6p1	Limited support
HP-UX	11i v3	4.3.33	9.6p1	Limited support
Solaris	11.4.81	5.2.37	9.6p1
FreeBSD	13.5	5.2.15	8.7p1
Windows	NOT SUPPORTED

OpenSSH tokens for AuthZHelper

AuthZHelper uses OpenSSH tokens to get information about login attempts. This information helps AuthZHelper create detailed audit logs and make access decisions.

The table below shows the tokens that AuthZHelper needs:

Token	What it describes	Min. OpenSSH version	What it enables
%u	The username of the person logging in.	6.2	Identifies the user.
%h	The home directory of the user.	6.2	Finds paths for local users.
%t	The type of SSH key (for example: ssh-rsa).	6.2	Shows the key type in logs.
%f	The fingerprint of the SSH key.	6.2	Identifies the specific key in logs.
%k	The full SSH key (base64 encoded).	6.2	Validates the key.
%C	The source and destination IP addresses and ports.	9.6p1	Enriched Logging: Adds network and routing data to audit logs.

---

Step 3: Set up AuthZHelper users

Before deploying AuthZHelper, you should create dedicated user accounts for each AuthZHelper instance or group. These users must be granted the necessary permissions within Trust Protection Foundation (TPF) to enable secure integration and management.

The following outlines how to create and configure these users, ensuring your AuthZHelper deployment is properly authorized and ready for installation.

• Create dedicated user accounts or groups specifically for AuthZHelper instances.

• Assign the Platform/API/Integrations > CyberArk AuthZHelper permission to these users.

• To create a new user:

  • Navigate to SSH Manager > Policy Tree > Identity > Local in TPF.

  • After creating the user, assign API permissions under Platform > API > Integrations > CyberArk AuthZHelper.

Recommended OAuth settings for AuthZHelper users

• Running a supported version of SSH Manager .

• Access to the TPF server through the browser-based Admin Console or direct access to the Windows Server console running TPF.

• Ability to deploy AuthZHelper to Linux hosts.

• Hosts can reach TPF directly or through a proxy.

• Ability to use Ansible or another orchestration tool for deployment.

AuthZHelper command line reference

When Trust Protection Foundation (TPF) is properly configured, users are set up, and you have identified your target systems for AuthZHelper deployment, you can proceed to distribute the AuthZHelper files and authenticate the utility.

---

Step 4: Prepare Linux environment for AuthZHelper

Recommendations and prerequisites

• Before you begin: Review Supported distributions for AuthZHelper when planning your target groups for AuthZHelper. Make sure that all functions are supported and that network access is possible.

• To quickly obtain and save the TPF server's TLS certificate, you can run the following command, using your Trust Protection Foundation endpoint FQDN in place of TPF.local:

  openssl s_client -connect TPF.local:443 -showcerts </dev/null 2>/dev/null | awk '/BEGIN CERTIFICATE/,/END CERTIFICATE/ { print $0 }' > /var/opt/cyberark/sshmanager/ca-cert.pem

  Modifying this command and applying it to cron or similar tasks can assist with automating certificate renewals.

• Consider the impact of DNS changes. Consider setting static host locations for TPF via /etc/hosts on each AuthZHelper client. The AuthZHelper configuration will rely on an FQDN that is resolvable to TPF and matches the FQDN of the TLS certificate.

• In the event of a misconfiguration, you may not be able to connect to a host via SSH. You should proceed with caution and review console access options before deployments.

• For large scale deployments, Ansible Playbook is available through the Palo Alto Networks Support Team.

Recommended file hierarchy

• Binary: /usr/bin/authzhelper

  NOTE  This is the only supported executable path. Do not treat this executable as a directory.

• Config: /var/opt/cyberark/sshmanager/config.yml

• TPF Trust Bundle: /var/opt/cyberark/sshmanager/ca-cert.pem

  ICA/Root must be trusted to support certificate rotation.

• Authorized keys: .ssh/authorized_keys .ssh/authorized_keys2

  This matches the recommended location based on SSHD config. Each user's /home/%u/.ssh/AuthorizedKeys file is searched for a matching public key.

  This location is customizable and accepts variables such as /export/home/%u/.ssh/AuthorizedKeys. However, if the location begins with %, it will need to be quoted. For example, in config.yaml: AuthorizedKeysFile '%u/home/.ssh/authorizedkeys'.

• Machine identity: /var/opt/cyberark/sshmanager/.authzid

  This file contains a unique machine identifier (UUID) that is generated automatically the first time AuthZHelper authenticates. It is used to bind OAuth tokens to the specific machine. Do not edit or copy this file to other machines. Permissions must be 0600.

• Secret: /var/opt/cyberark/sshmanager/.authzhelper_secret

  Encrypted OAuth token (AES-256-GCM, 26.2+). Created during authentication. Do not edit or copy. Permissions: 0600.

 

---

Step 5: Configure SSH for AuthZHelper

Do not change your SSH configuration or restart the service until you have installed the AuthZHelper utility. If you do, you might be locked out of your server.

To configure SSH for AuthZHelper

1. Create a backup: Save a copy of your current configuration file.

   cp /etc/ssh/sshd_config /etc/ssh/sshd_config_backup_Authz

2. Update the configuration: Open /etc/ssh/sshd_config and set the following values. If a line starts with #, remove the #.

   PubkeyAuthentication yes #this can be left commented out, defaults to yes.

   AuthorizedKeysCommand /usr/bin/authzhelper a -u %u -f %f -h %h -k %k -t %t -C %C -D %D -U %U

   AuthorizedKeysCommandUser root

   AuthorizedKeysFile none

   TrustedUserCAKeys none

   AuthorizedPrincipalsFile none

3. Check for conflicting files: Review any files in /etc/ssh/sshd_config.d/*.conf. Some systems use these files to enable PasswordAuthentication, which might conflict with your AuthZHelper setup.

Configuration notes

• Non-root users: If you set AuthorizedKeysCommandUser to a user that is not root, that user must have permission to read the authorized_keys files for every person on the server. If it cannot read these files, public-key authentication will fail for all users.

• How it works: In this setup, SSH does not use local files for authorization. Instead, it sends the request to AuthZHelper. AuthZHelper then checks the keys and reports the connection to TPF.

---

Step 6: Install AuthZHelper on Linux distributions

Consider the following as you install and configure your Linux system files for the AuthZHelper utility:

• The AuthZhelper tar.gz or rpm file is available through your client download portal.

• Before running the installation files, make sure they are in a location accessible to the _apt user; such as /tmp.

• When copying values from sshd_config, if a directive is commented out, the default value will be set.

  For example, if sshd-config has AuthorizedKeysFile commented out, it will then be set to check your current AuthorizedKeysFile reference and/or the TrustedUserCAKeys reference.

  This is typically part of the /etc/ssh/sshd_config file. You should create backups and local copies for reference. These values will be updated by the installation and referenced in the config.yaml file for AuthZHelper.

  Before making changes, the default settings should look something similar to this:

  #RSAAuthentication yes

  PubkeyAuthentication yes

  AuthorizedKeysFile .ssh/authorized_keys

  #AuthorizedKeysCommand none

  #AuthorizedKeysCommandRunAs nobody

  TrustedUserCAKeys /etc/ssh/ca_user_key.pub

  #AuthorizedPrincipalsFile /etc/ssh/principals

---

Step 7: Configure SELinux for AuthZHelper (RHEL only)

This step ensures that SELinux does not block AuthZHelper on RHEL systems. When SELinux is enabled, additional configuration is required so AuthZHelper can read files and connect to Trust Protection Foundation (TPF).

Complete this step after installing AuthZHelper and before authenticating it.

Why SELinux configuration is required for AuthZHelper

On RHEL systems with SELinux enabled, AuthZHelper runs in the sshd_t domain. By default, SELinux restricts what this domain can access. Without additional SELinux configuration, AuthZHelper may be blocked from:

• Reading its configuration file

• Writing identity, secret, or cache files

• Connecting to Trust Protection Foundation (TPF) over HTTPS (port 443)

When AuthZHelper is blocked, SSH connections may still succeed, but authorization events stop reporting or fail silently. Issues can appear after initial success, for example, the day after installation, when cache or identity files are accessed again.

Completing this step ensures that:

• AuthZHelper can read and write all required files

• AuthZHelper can send authorization data to TPF

• SELinux remains enabled and enforced at the system level

Check if this step applies to you

This step applies only if all of the following are true:

• You are running RHEL 8 or RHEL 9

• SELinux is enabled on the host

• You installed AuthZHelper and plan to authenticate it

To check whether SELinux is enabled, you can run:

getenforce.

• If the command returns Enforcing, you must do this step.

• If the command returns Permissive, you should do this step if you plan to switch to Enforcing (or want to prevent future enforcement issues).

• If the command returns Disabled, you can skip to the next step.

If SELinux is enabled, it can block AuthZHelper from reading its configuration files, writing identity and cache files, and connecting to Trust Protection Foundation (TPF) over HTTPS.

Assign SELinux file context to AuthZHelper working files

Assign the correct SELinux file context to all AuthZHelper working files so AuthZHelper can read and write them.

Run the following commands as root:

The user_home_t type allows AuthZHelper to read and write these files while SELinux enforcement remains enabled. These rules allow AuthZHelper to access its configuration, identity, secret, and cache files.

Allow outbound HTTPS from AuthZHelper (sshd_t domain)

SELinux blocks outbound HTTPS connections from the sshd_t domain by default. This prevents AuthZHelper from sending authorization data to Trust Protection Foundation (TPF).

You may see audit messages like this:

avc: denied { name_connect } for pid=208725 comm="authzhelper" dest=443 …

As a workaround, set the sshd_t domain to permissive so SELinux no longer blocks AuthzHelper actions (including outbound HTTPS). The permissive setting does not only allow outbound 443; it also disables SELinux enforcement for all actions performed in the sshd_t domain.

Run the following command as root:

Notes

• This action does not disable SELinux globally.

• Only the sshd_t domain is placed in permissive mode.

• This is the simplest and most validated configuration for AuthZHelper.

• An SELinux policy module can also be used, but permissive mode for sshd_t is the best approach.

Verify SELinux configuration

Confirm that the file contexts are applied correctly by running: semanage fcontext -l | grep sshmanager

Expected result

• user_home_t is assigned to:

  • config.yml

  • .authzid

  • .authzhelper_secret

  • .cache/*

Check for symptoms of misconfigured SELinux

If SELinux is not configured correctly, you may see one or more of the following issues:

• SSH authorization results appear on the first day, then stop appearing the next day

• AuthZHelper logs show permission denied errors when reading files

• Trust Protection Foundation stops receiving SSH authorization sessions

• SELinux audit logs show sshd_t denial events

Review these files for errors:

• /var/log/messages

• /var/log/audit/audit.log (look for AVC denials)

• /var/opt/cyberark/sshmanager/authzhelper.log

Step 8: Review the setup after installing AuthZHelper on Linux (any distribution)

After AuthZHelper files are installed and configured, you should review config.yaml for accuracy. The example below is meant as a reference and may not match your configuration.

Config definitions

• proxy-url: The FQDN or IP of the proxy server that will be used to reach Trust Protection Foundation.

• proxy-ca-trust: The trust bundle associated with the proxy connection / server.

• api-host: The FQDN of the Trust Protection Foundation (TPF) server. This should match a SAN entry of the presented TLS certificate.

• ca-trust: Trust bundle (root+ICA) for the TPF server.

• AuthorizedKeysFile: Location of user public keys. Formatting should comply with the OpenSSH documentation.

• TrustedUserCAKeys: Location of the TrustedUserCAKeys file. Formatting should match that of OpenSSH documentation.

• AuthorizedPrincipalsFile: Location of the AuthorizedPrincipals files. Formatting should match that of OpenSSH documentation.

• log: Location of the log file. By default, events and logs are sent to journalctl.

• failure_mode: fail_open/fail_closed This relates to how AuthzHelper will act when a connection to TPF can not be established.

• debug: Debug level for logging and auditing.

• disableTlsRenegotiation: (Set to true) Required when explicit TLS 1.3 is enabled on the TPF server.

---

Step 9: Authenticate AuthZHelper

Before AuthZHelper can begin reporting SSH authorization events to the Trust Protection Foundation, it must first be authenticated using the credentials of the dedicated user you created in Trust Protection Foundation.

This section provides steps to authenticate AuthZHelper to Trust Protection Foundation.

1. From the location of the binary (/usr/bin/authzhelper), authenticate the AuthZHelper client to Trust Protection Foundation by running sudo authzhelper authenticate --debug and providing the username and password that was assigned when creating the user in Trust Protection Foundation.

2. Confirm that the authentication was successfully completed:

   

3. Verify that AuthZHelper has authenticated to Trust Protection Foundation and is capable of reporting SSH authorizations by performing the following:

   1. Ensure the SSHD configuration is set up as shown under SSH Configuration.

   2. Restart the SSH service or reboot the machine. For example systemctl restart sshd or service ssh restart (distribution dependent)

   3. Visit theAuthorization menu option in SSH Manager in TPF Admin Console to verify that the SSH Key Authorization Rules features are available.

What happens during authentication

When you run authzhelper authenticate, AuthZHelper obtains an OAuth token from Trust Protection Foundation and stores it locally. This token is encrypted at rest using AES-256-GCM. The encryption key is derived from the Agent ID of this AuthZHelper installation.

This means:

• The token file (.authzhelper_secret) contains encrypted content instead of readable JSON. This is expected behavior.

• An Agent ID file (.authzid) is created automatically if it does not already exist. This file is used to encrypt and decrypt the token.

• There is no configuration option to disable encryption. It is always on.

• All existing commands, workflows, and configuration files remain unchanged. There is no performance impact.

How to verify encryption is active

To confirm that the token is encrypted run:

cat /var/opt/cyberark/sshmanager/.authzhelper_secret

• Encrypted (expected): The output is random-looking Base64 text.

• Not encrypted (pre-26.2): The output is readable JSON containing an "access_token" field.

Upgrading from a version prior to 26.2

If you are upgrading from a version prior to 26.2, existing plaintext tokens are automatically migrated to encrypted format the first time authzhelper authorize runs after the upgrade. No manual action is required.

To confirm migration completed, run authzhelper authorize with debug logging enabled and look for the following message in the log output:

Successfully migrated token to encrypted format

With all previous steps completed, AuthZHelper should now be fully integrated with Trust Protection Foundation. You should now verify the AuthZHelper setup.

---

Step 10: Verify the AuthZHelper setup

After you authenticate AuthZHelper, you must check that it is working. The host will not show up in the Authorization menu until you complete a successful SSH login using AuthZHelper.

To verify the setup:

1. Start a new SSH session: Use a different computer or a new terminal window to log in to the host. Use a real account that uses an SSH key.

   • IMPORTANT  Keep your current administrative window open. Do not close it until you are sure the new login works. This prevents you from being locked out of the server.

   • Example command: ssh -i ~/.ssh/id_ed25519 username@host-ip

2. Confirm the login works: Make sure you can enter the server. If you are using the default "Observability" mode, the login will work like a normal SSH connection.

3. Check for the Identity file: On the host server, look for the .authzid file. This file contains the unique UUID that connects the host to TPF.

   • File location: /var/opt/cyberark/sshmanager/.authzid

   • NOTE  This file is created during setup or during your first login. Finding this file confirms the host identity for AuthZHelper is correct.

4. Check the Web Console: Log in to the (browser-based) TPF Web Console. Go to the Authorization menu in SSH Manager. The host should now appear in the list.

   NOTE  If you use an older system like RHEL 7 or 8, you might not see IP addresses or port numbers in the logs. This is normal for older versions of OpenSSH. AuthZHelper is still working correctly. To learn more, see the "Missing connection or routing data" section in the troubleshooting section.

If the host does not appear or the login fails, you should troubleshoot the AuthZHelper setup.

---

Step 11: Troubleshoot the AuthZHelper setup

If you encounter problems setting up AuthZHelper, see this section.

Multi-host environments

Each machine that runs AuthZHelper must authenticate independently. Because credentials are encrypted and bound to the machine's Agent ID, you cannot share or copy credential files between hosts.

To deploy AuthZHelper across multiple machines:

1. Install AuthZHelper on each host.

2. Run authzhelper authenticate on each host individually.

3. Verify that each host has its own .authzid and .authzhelper_secret files.

Do not copy .authzid or .authzhelper_secret from one host to another. Doing so will cause authentication failures.

Backup and restore guidelines

Not all AuthZHelper files are portable across machines. The following matrix shows which files can be backed up and restored to a different host.

File	Path	Backup?	Restore to same host?	Restore to different host?	Notes
Config	/var/opt/cyberark/sshmanager/config.yml	Yes	Yes	Yes	Configuration is portable across hosts.
TPF Trust Bundle	/var/opt/cyberark/sshmanager/ca-cert.pem	Yes	Yes	Yes	Certificate bundle is portable across hosts.
Encrypted token	/var/opt/cyberark/sshmanager/.authzhelper_secret	Yes	Yes	Yes	Token is encrypted using the Agent ID (.authzid).If you restore this file to a different host, you must also restore .authzid from the same installation. Without the matching .authzid, decryption will fail.
Machine identity	/var/opt/cyberark/sshmanager/.authzid	Yes	Yes	Yes	Contains the Agent ID used to encrypt the OAuth token.Must be restored together with .authzhelper_secret. Do not restore one without the other. A new one is generated automatically during authentication.

Troubleshooting encrypted credentials

Error message	Cause	Resolution
decrypt failed or cipher: message authentication failed	The .authzhelper_secret file was copied from another machine, or the .authzid file is missing or corrupted.	Delete both .authzhelper_secret and .authzid, then re-authenticate using one of the following methods: Interactive (recommended): authzhelper authenticate With flags: authzhelper authenticate -u <username> -p <password> Device code: authzhelper authenticate -c Debug mode: sudo authzhelper authenticate -d
invalid agent ID	The .authzid file has been modified or contains an invalid UUID.	Delete .authzid and re-authenticate using one of the following methods.. A new Agent ID will be generated automatically. Interactive (recommended): authzhelper authenticate With flags: authzhelper authenticate -u <username> -p <password> Device code: authzhelper authenticate -c Debug mode: sudo authzhelper authenticate -d
Token file contains unreadable content	Expected behavior in 26.2+. The token is now AES-256-GCM encrypted.	No action needed. AuthZHelper decrypts the token automatically at runtime.
Authentication works on one host but not another	Credential files were copied between hosts instead of authenticating each host independently.	Run the following on the failing host to generate its own credentials. Interactive (recommended): authzhelper authenticate With flags: authzhelper authenticate -u <username> -p <password> Device code: authzhelper authenticate -c Debug mode: sudo authzhelper authenticate -d
token migration failed: <reason>	AuthZHelper attempted to migrate a pre-26.2 plaintext token to encrypted format but failed.	Check file permissions on /var/opt/cyberark/sshmanager/.authzhelper_secret (must be 0600). Verify /etc/machine-id or /var/lib/dbus/machine-id exists and is readable. Then re-authenticate using one of the following methods: Interactive (recommended): authzhelper authenticate With flags: authzhelper authenticate -u <username> -p <password> Device code: authzhelper authenticate -c Debug mode: sudo authzhelper authenticate -d

Missing connection or routing data in audit logs

• Problem: AuthZHelper audit logs do not show source IP addresses, destination IP addresses, or port numbers.

• Cause: This happens when the host operating system uses an older version of OpenSSH (older than version 9.6p1). These older versions do not support the %C token, which AuthZHelper uses to collect network data.

• Resolution: This is a known limitation for older systems, such as RHEL 7 and RHEL 8. AuthZHelper will still authorize users, but it cannot record the network data.

  To see full network data in your logs, you must upgrade the host operating system to a version that includes OpenSSH 9.6p1 or later.

---

.