Table of Contents

1. About This Document
What Is PrivX
Intended Audience
Deployment Workflow
Terminology
Documentation Conventions
2. Preparing for Deployment
Prerequisites for Installation
NTP Clock Synchronization
High-Availability Installation Requirements
Expected System Performance
3. Setting Up PrivX
PrivX Server Setup
PrivX License Management
Online Licensing
Deactivating PrivX Licenses
Multiple-Server Deployment
Backing Up and Restoring PrivX Servers
Backup and Restore Using Snapshots
Filesystem-Level Backup
Upgrading PrivX
Uninstalling PrivX
Manual PrivX Package Installation
4. Getting Started with PrivX
Creating Local Users and Roles
Adding Target Hosts
Connecting to Target Hosts
Enabling Certificate Authentication for OpenSSH Connections
Importing Users from Directories
Importing Hosts from Directories
5. Additional Configuration for PrivX Servers
SSL/TLS Security
Setting Up a Trusted Server Certificate
Allowed SSL Protocols and Ciphers for GUI Connections
Rotating PrivX CA Keys
PrivX Log Settings
6. PrivX Users and Permissions
Adding PrivX Users
Granting Permissions for PrivX Users
Managing Roles
Requesting and Approving Memberships
Granting Access to Target Hosts
Granting Administrator Permissions
Managing Workflows
Enabling Email Notifications
AD/LDAP Directory Configuration
Secure-Connection Setup
Adjusting User Matching
Refreshing Directory Data
OpenID-Connect Configuration
Advanced Authentication for PrivX Users
Kerberos Authentication for PrivX Users
Multi-Factor Authentication for PrivX Users
7. Authentication Methods for Host Connections
Supported Authentication Methods
Enabling Certificate-Based Authentication for SSH Connections
Requirements for Certificate Authentication Over SSH
Script-Based Certificate-Authentication Setup
Certificate-Authentication Setup via Chef
Manual Certificate-Authentication Setup
Enabling Role-Based Public-Key Authentication
Enabling Authentication with Stored Passwords
Enabling Certificate Authentication for RDP Connections
Requirements for Certificate-Based Authentication Over RDP
Steps for RDP Certificate-Authentication-Setup
Configure Known Targets in PrivX
Trusting Target-Host Identities
SSH Target-Host Authentication
RDP Target-Host Authentication
Importing Hosts from Directories
8. Establishing and Managing Connections
Connecting via the PrivX GUI
SSH GUI Features
RDP GUI Features
Connecting with Native Clients (SSH Only)
Native-Client Setup Usage (on Unix)
Native-Client Setup Usage (on MacOS)
Setting up Known Hosts
Monitoring and Managing Connections
Proxying Connections to Hosts
9. Auditing
Viewing Audit Data
Session Recording Setup
Audit Events in PrivX
10. Troubleshooting
A. Example Nginx Load-Balancer Configuration
B. PrivX Microservices
Authentication Service
Authorizer
Connection Manager
Host Store
Keyvault
Local User Store
Monitor Service
Role Store
SSH/RDP client
Workflow Engine
C. PrivX Analytics
Index

Chapter 1 About This Document

In this Administrator Manual you will find instructions for deploying and operating PrivX.

PrivX provides you with:

  • A web-based solution for accessing target hosts using SSH and RDP, removing the need for dedicated clients.

  • A customizable workflow-based mechanism for requesting and granting access through roles.

  • Integration with existing user and host directories.

  • Just-in-time, role-based access to target hosts – no SSH keys used, no need to rotate keys – access can be revoked at any time

  • Roles can be granted within PrivX, or they can be mapped from existing user groups and/or roles.

What Is PrivX

Problems with Common PAM Solutions

Traditional ways of provisioning access to servers rely on outdated methods and processes that are not compatible with the cloud. Additionally, credentials that provide access for privileged users are often left unprotected on client endpoints susceptible to theft or misuse.

Traditional Privileged Access Management (PAM) is based on password vaulting and automatic password rotation with special agent/client software to be installed on network machines. Password vaults become single points of failure, they are also expensive and difficult to deploy. Similarly, agents and clients need to be patched and kept up to date. All of this makes deploying, maintaining, and using traditional PAM expensive and complex.

The Solution: PrivX

PrivX uses short-term credentials to provide just-in-time access to servers. Access is granted based on the user’s role. Provisioned credentials are created on demand, only valid for a short time, and never stored to disk.

Improve security

Access to endpoints is provisioned using on-demand short-lived certificates that are valid for only a few minutes and never written to disk nor exposed to end-users. This completely eliminates the risk of credential theft, removing the greatest security risk in privileged access management.

Reduce costs

PrivX works using existing SSH clients and servers, so there is no need to add or replace components of the SSH infrastructure. The lack of dependence on external components translates to minimal disruptions to network infrastructure, and reduced maintenance costs.

Using short-lifetime access certificates provided by PrivX eliminates the need for certificate revocation or key rotation.

Intended Audience

This Administrator Manual is intended for technical personnel responsible for installing software to the company network, those responsible for security software, and personnel maintaining and auditing secure access in the corporate network.

Readers are expected to be familiar with the operating systems on which the PrivX will be installed.

Readers should also be familiar with the Tectia Server and any Secure Shell software used in their environment.

Deployment Workflow

Deploying PrivX involves the following steps:

  1. Set up PrivX servers (Chapter 2 and Chapter 3).

  2. Onboard users. Define roles for granting access privileges (Chapter 6).

  3. Set up passwordless authentication methods for target hosts (Chapter 7).

    To prevent having to reconfigure hosts later, we strongly recommend you set up the necessary roles in your environment before configuring authentication methods on target hosts.

  4. Use PrivX to connect to target hosts (Chapter 8).

Tip

For an introduction to the PrivX main features, see the examples in Chapter 4.

Terminology

The following terms are used throughout the documentation.

authorizer

Authorizer creates certificates with user’s roles as needed for users connecting to target hosts.

certificate

A certificate is a signed document that binds together the trusted issuer, and subject information such as public key, subject name, list of principals (role memberships), and information about access restrictions. Certificates on PrivX are short term, issued by the Authorizer, and verifiable using the Authorizer public key.

directory (in UI)

A directory in the PrivX UI refers to a source of user accounts, for example, an AD/LDAP directory.

host store

Host stores save host information, such as addresses, SSH/RDP services, and target-user-to-role mappings. Host stores also import hosts from existing directories.

known host

When the connection information of a host is stored in PrivX, that host is considered a known host. Known hosts enable PrivX features including passwordless and certificate-based connections.

local user directory

Local user directory provides an easy way to create local users for authentication and role mapping. Authentication is done via username or email, and a password.

OAuth2 service

OAuth2 service provides an authentication mechanism for a user to provide a username and password, and provides the given credentials against SSH PrivX Local User Store, and authentication providers, such as LDAP and AD.

principal

Principals are unique identities used in OpenSSH certificates, such as user names, or the UUIDs of PrivX roles.

PrivX deployment

PrivX servers using the same database. A PrivX deployment consists of one or more PrivX servers.

PrivX user

Any user account that is available via PrivX. Includes both PrivX local users, and users from AD/LDAP directories users that have been added to PrivX.

role

PrivX provides role-based access permissions: For a user to receive access permissions, they must be assigned to a role. Each role in the system has a unique principal (UUID) that represents the role in certificates and target host configurations.

role store

In PrivX, role store integrates against user directories and identity providers, for example, LDAP and AD. Role store contains rules which are evaluated to automatically map existing LDAP/AD user groups and roles into PrivX roles which are in turn used to access target hosts.

target host

Any destination host for a connection that has been authenticated/authorized using PrivX. In other words, any host to which access is granted using PrivX.

target user

The identity that PrivX users assume on target hosts.

Documentation Conventions

The following typographical conventions are used in SSH Communications Security documentation:

Table 1.1. Documentation conventions

ConventionUsageExample
BoldMenus, commands, GUI elements, strong emphasisClick Apply or OK.
Series of menu selectionsSelect File → Save
MonospaceFilenames, directories, URLs etc.Refer to readme.txt
ItalicsPlaceholder values in examples, reference to other documents or products, emphasisSee the Tectia SSH Client User Manual
#In front of a command, # indicates that the command is run as a privileged user (root).
# rpm --install package.rpm
$In front of a command, $ indicates that the command is run as a non-privileged user.
$ sshg3 user@host
OS#, OS$In front of a command, OS# or OS$ indicates that the command is specific for certain operating systems. Multiple operating systems are separated with a /.
SUSE$ sudo zypper update

RedHat/CentOS# yum upgrade
\At the end of a line in a command, \ indicates that the command continues on the next line, but there was not enough space to show it on one line.
$ ssh-keygen-g3 -t rsa \
-F -c mykey

Note

A Note indicates neutral or positive information that emphasizes or supplements important points of the main text. A Note supplies information that may apply only in special cases (for example, memory limitations, equipment configurations, or specific versions of a program).

Caution

A Caution advises users that failure to take or to avoid a specified action could result in loss of data.

Chapter 2 Preparing for Deployment

This chapter describes the prerequisites of PrivX deployment.

Prerequisites for Installation

Table 2.1. Standard Prerequirements for PrivX

Server
System Configuration4GB RAM, 2 cores and 15GB for < 10k users
8GB RAM, 8 cores and 100GB for < 100k users
Supported operating systemsRed Hat Enterprise Linux 7.4 or later
CentOS 7.4 or later
Supported databasesLocal or external PostgreSQL and Redis
Network Connectivity
Internet connectivity requiredFor installing dependant libraries during installation and upgrades, and for activating PrivX license
Default network ports in use
Web UI: Port 443 in
SSH sessions: Port 22 out
RDP sessions: Port 3389 out
Email notifications: Port 25, 465, or 587 out
CRL lists for RDP connections: Port 80 in
DNS: Port 53 out
External PostgreSQL: Port 5432 out
External Redis: Port 6379 out
Access to PrivX License Management Service184.106.60.185:443
Target-host Authentication
Supported OpenSSH versionsCertificate-based authentication - OpenSSH 6.9 or later, see the section called “Enabling Certificate-Based Authentication for SSH Connections”
Other authentication methods - OpenSSH 5.6 or later
Supported platforms for Windows Domain Controller and Certificate Authority ServerWindows Server 2016 with the latest service pack and updates
Windows Server 2012 R2 with the latest service pack and updates
Windows Server 2008 R2 with the latest service pack and updates
Client Experience
Supported browsersLatest versions of:
  • Firefox

  • Chrome

  • Safari

  • Edge

  • IE11


NTP Clock Synchronization

We strongly recommend enabling NTP clock synchronization for the system. Otherwise, please verify the system time and date manually before continuing with PrivX installation. We also recommend enabling time-server authentication for NTP connections.

The short-term user certificates issued by PrivX may be valid at incorrect times if system times are not synchronized correctly. Due to the just-in-time nature of the certificates issued by PrivX, even deviations of just a few minutes may cause authorizations to fail.

High-Availability Installation Requirements

If you plan to have multiple PrivX servers in your deployment (for high-availability and/or load balancing), you must set up an external PostgreSQL database and an external Redis server. You may also need to set up a load balancer to distribute connections to PrivX servers.

  • All PrivX servers must be able to access the PostgreSQL database using password authentication, as a database user with full permissions to the database.

  • All PrivX servers must be able to access the external Redis server.

  • The requests from a PrivX session must be handled by one PrivX server; for example the load balancer could be configured to use either IP hashing or sticky sessions.

  • To enable SSL-encrypted database connections (recommended for production deployments), the PostgreSQL server must satisfy the following:

    • Enable SSL mode (ssl = true).

    • The PostgreSQL server must be configured with a server certificate where the SubjectAltName specifies the DNS and IP address(es) of the server.

    PrivX servers must also be configured to trust the PostgreSQL-server certificate: On each PrivX server, add the PostgreSQL-server CA chain to the system trust anchors. For more information about adding trust anchors to PrivX servers, see the section called “Secure-Connection Setup”.

Expected System Performance

A PrivX server that satisfies or exceeds the production requirements is expected to support:

  • 100 000 PrivX users total, with 700 concurrent users.

  • 25 000 target hosts total, with:

    • Up to 1000 hosts added/deployed concurrently.

    • 20 000 target hosts scanned in 2 minutes.

  • Up to 200 concurrent RDP connections for performing typical user operations. Graphically intensive sessions (including video streaming) may reduce the number of supported concurrent connections.

Note

The PrivX microservice architecture supports multiprocessing and benefits from using multiple CPUs or multiple CPU cores.

Reserve enough space for the log data generated by PrivX. Also monitor the log-data growth periodically. In large deployments, PrivX may generate a considerable amount of log data over time. You may configure the PrivX machine to write its log data to an external logging server.

Chapter 3 Setting Up PrivX

This chapter provides instructions for setting up a PrivX server. This chapter also describes the PrivX server-management operations:

  • How to deploy PrivX for high availability and load-balancing.

  • PrivX server backup and restore.

  • Upgrading PrivX servers.

  • Uninstalling PrivX.

PrivX Server Setup

PrivX servers provide PrivX services, such as the PrivX GUI and certificate-based authentication services.

To set up a PrivX server:

  1. Set up repositories for downloading PrivX packages and dependencies.

    Add the EPEL repository:

    • On Red Hat:

      # yum install \
      https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
    • On CentOS:

      # yum install epel-release

    Then add the PrivX repository:

    # rpm --import https://product-repository.ssh.com/info.fi-ssh.com-pubkey.asc
    # wget https://product-repository.ssh.com/ssh-products.repo \
    -O /etc/yum.repos.d/ssh-products.repo
  2. Install the latest PrivX packages with:

    # yum install PrivX

    The application binaries are installed to the /opt/privx/bin/ directory. The configuration is installed to /opt/privx/etc/ directory. Utility scripts are found in the /opt/privx/scripts/ directory.

  3. Optional: To automate PrivX configuration, you may define post-installation settings using environment variables. The post-installation script skips prompting for any settings found in environment variables.

    Environment variables for the post-installation script are listed in:

    /opt/privx/scripts/postinstall_env

  4. Run the post-installation script to configure the server:

    # /opt/privx/scripts/postinstall.sh

    Unless specified in environment variables, you will be prompted for:

    • DNS and IP address(es) of the server.

    • Database settings: database name, database user credentials, database service address (if using an external database).

    • Credentials for the initial superuser account.

  5. Install the PrivX license to enable product functionality. You can do this by browsing to the PrivX GUI located at (replace privx.example.com with the DNS or IP address of the PrivX server):

    https://privx.example.com/

    Log in using the superuser credentials.

    In the GUI, navigate to Settings → License in the PrivX UI, and provide your license code under Online license update. Click Update, PrivX automatically contacts the license server to obtain and install your license.

    Unlicensed product does not allow adding hosts nor establishing SSH or RDP connections. For your license to be activated, ensure that the system time is set correctly.

    You have now set up a PrivX server.

  6. You may verify the status of the PrivX microservices on the status page, located at the following address (replace privx.example.com with the DNS or IP address of the PrivX server):

    https://privx.example.com/status.html

Note

Particularly in large production deployments, PrivX may accumulate large amounts of log data over time. We recommend that you configure log rotation for syslog and the microservice logs to prevent PrivX servers from running out of disk space.

PrivX License Management

This section describes the supported licensing methods, and license deactivation.

Ensure that you have a valid PrivX license code for taking PrivX into use. For license-subscription-related enquiries, please contact SSH Communications Security support at privx-sales@ssh.com

Online Licensing

Online licensing is the recommended way to license PrivX. This method is easy to set up, and after setup the license is automatically updated according to your subscription.

For online licensing to work, your PrivX servers must have Internet connectivity for certain operations:

  • Upon initial license activation: PrivX contacts license servers to fetch your license.

  • Upon license renewal: PrivX contacts license servers to automatically fetch your new license.

  • Upon license expiry: PrivX contacts license servers to fetch the grace period associated to your license.

To activate a PrivX license with the online method:

  1. Access the PrivX GUI and navigate to the Settings→License page.

  2. Under the License code section, enter your license code, and click Update License.

    PrivX automatically installs your license, which enables PrivX functionality according to your license subscription.

In online licensing mode, PrivX checks for license updates every 12 hours and automatically installs any new licenses found for your subscription. To trigger an immediate license-update check, click next to the Last refreshed section, then click Refresh.

Note

If you opt to not send product analytics, you may disable internet connectivity while no license updates are available. For more information about analytics, see Appendix C.

Note that if PrivX servers do not have Internet access when their license expires, the license expires immediately without entering grace period.

Deactivating PrivX Licenses

PrivX licenses can be activated only a limited number of times. To free up activations you must first deactivate a license.

To deactivate a PrivX license, go to the Settings→License page. Next to Status, click , then click Deactivate.

Multiple-Server Deployment

For high availability and load balancing, you can set up multiple PrivX servers as part of a single PrivX deployment. To do this:

  1. If you have not done so already, set up an external PostgreSQL database, and an external Redis server. You may also set up a load balancer to distribute sessions to individual PrivX servers.

    An example configuration for an Nginx load balancer is provided in Appendix A.

  2. Set up the first PrivX server according to the instructions in the section called “PrivX Server Setup”. Be sure to configure the PrivX server to use the external PostgreSQL database and Redis server.

  3. To set up additional PrivX servers by duplicating the initial PrivX server:

    • If using virtual servers: Clone the initial PrivX server and create additional instances from the clone.

    • If using physical servers: Create a backup of the initial PrivX server, then restore the backup to additional machines. Backup and restore is described in the section called “Backing Up and Restoring PrivX Servers”.

    Note

    Ensure that all PrivX server clocks are synchronized.

    When creating additional servers via cloning or backups, all servers will have the same server and CA certificates. If you want to create unique server certificates on a PrivX server, run the following on the target server:

    # /opt/privx/scripts/init_nginx.sh

Backing Up and Restoring PrivX Servers

This chapter describes procedures for backing up and restoring PrivX servers.

Backup and Restore Using Snapshots

This section provides instructions for backing up and restoring PrivX instances using virtual-image snapshots.

Readers are expected to be familiar with the virtualization platforms on which their PrivX instances are run.

Backing Up to a Snapshot

  1. Create a new snapshot of your PrivX server(s). For instructions about creating snapshots, please consult the documentation provided by your virtualization-platform vendor.

  2. The PrivX instance may have been frozen for the time when the virtualization platform was creating the snapshot. Verify the time on the PrivX instance and synchronize if necessary.

  3. If you are using an external database, back up the external PrivX database.

Restoring from a Snapshot

  1. If you are using an external database, restore the external PrivX database now.

  2. Restore a previously-taken snapshot of your PrivX server(s). For instructions about restoring snapshots, please consult the documentation provided by your virtualization-platform vendor.

  3. Verify the time on the PrivX instance and synchronize if necessary.

Filesystem-Level Backup

This section provides instructions for backing up and restoring PrivX instances using filesystem-level backups.

Backing Up the Necessary Files

  1. You can back up the PrivX local data by running:

    # /opt/privx/scripts/backup.sh

    This creates a backup directory to:

    /var/backups/privx/<hostname>_<date>

    Where <hostname> and <date> are the name of the host and the backup timestamp. A working example of a backup-directory path would be:

    /var/backups/privx/privx_2017-12-31-2350

    Repeat this step on each PrivX server in the deployment.

    Note

    If you have configured the server to store its certificates in non-default locations, or to use a non-default local database name. Check and adjust the Default options in backup.sh before running it.

    By default backup.sh backs up:

    • PrivX keyvault at /opt/privx/keyvault

    • PrivX configurations under /opt/privx/etc

    • SSL certificate files located under /etc/pki/CA and /etc/nginx/ssl

    • Local PostgreSQL database named privx (only if using local databases).

  2. Back up the PrivX database:

    • If using a local database: The database and the database user were backed up by running backup.sh, no additional actions required.

    • If using an external database: Manually back up the PrivX database.

  3. Copy the backups to a secure, external backup location.

Restoring from Backup Files

  1. If PrivX uses an external database, restore it now.

  2. Uninstall PrivX according to the instructions in the section called “Uninstalling PrivX”.

  3. Install the PrivX version from which your backups were taken.

  4. On all the PrivX servers, restore the PrivX local data.

    If your backups were created with backup.sh, you can do this by running (replace /path/to/backup with the path of the backup directory):

    # /opt/privx/scripts/restore.sh /path/to/backup

    To manually restore PrivX local data, restore the following:

    • PrivX keyvault to /opt/privx/keyvault

    • PrivX configurations to /opt/privx/etc/

    • SSL certificate files, be default located under /etc/pki/CA and /etc/nginx/ssl

    • Local PostgreSQL database (if using a local database).

    Be sure to restore the original ownerships and the permissions of the files.

  5. On all the PrivX servers, run the post-installation script to apply the restored configurations, and to restart the PrivX service:

    # /opt/privx/scripts/postinstall.sh

    Your PrivX deployment should now be restored.

Upgrading PrivX

This section provides instructions for upgrading your PrivX deployment.

Note

Before upgrade, we strongly recommend you to create a backup of your PrivX server(s), and of the PrivX database. If upgrade fails, you can restore your old PrivX version from these backups. Instructions for backing up and restoring PrivX are provided in the section called “Backing Up and Restoring PrivX Servers”.

To upgrade a PrivX deployment, perform the following:

  1. If your PrivX deployment includes multiple PrivX servers, stop the PrivX services for the duration of the upgrade (this prevents outdated data from being written to the database). To do this, run the following on all PrivX servers:

    # systemctl stop privx
  2. On your PrivX server(s), set up the latest PrivX version:

    # yum install PrivX
    # /opt/privx/scripts/postinstall.sh
  3. If you are running a multiple-server PrivX deployment, run the database migration from any PrivX server in the deployment (this needs to be done only once per deployment):

    # /opt/privx/bin/migration-tool -migrate-services-only

Uninstalling PrivX

This section provides steps for completely removing PrivX from a machine. These steps may be used in preparation for PrivX reinstallation.

To delete all PrivX related data from a PrivX server:

  1. Uninstall the PrivX package:

    # yum erase PrivX
  2. Remove the leftover PrivX installation directory (includes configurations and keyvault data):

    # rm -rf /opt/privx
  3. If using a local database, remove PostgreSQL and its data directory:

    # yum erase postgresql
    # rm -rf /var/lib/pgsql/
  4. Remove Nginx:

    # yum erase nginx

    Also remove the leftover Nginx server configuration and SSL-certificate files:

    # rm -rf /etc/nginx
  5. Finally remove the leftover privx-cert.json-file:

    # rm /tmp/privx-cert.json

Manual PrivX Package Installation

Instead of installing PrivX packages from the SSH product repository, you may install the PrivX package manually as follows:

  1. Obtain the PrivX RPM package. The PrivX RPM package is a file with a name like the following:

    PrivX-*.x86_64.rpm

    Where * is to be replaced with the product version.

  2. Copy the PrivX RPM to your target server.

  3. Install the PrivX RPM (replace PrivX-*.x86_64.rpm with the path of the PrivX RPM):

    # yum install PrivX-*.x86_64.rpm

Chapter 4 Getting Started with PrivX

This chapter describes a simple test setup for testing access from roles to hosts:

  1. Create local users and roles (the section called “Creating Local Users and Roles”).

  2. Add hosts, and specify who has access to them (the section called “Adding Target Hosts”).

  3. Access the host via the PrivX GUI (the section called “Connecting to Target Hosts”).

This chapter also provides examples for setting up some additional features:

The sections describing the simple test setup should be performed in order. The sections describing additional features may be attempted after the simple test setup.

Creating Local Users and Roles

PrivX users can log into PrivX to use features (such as connecting to target hosts).

To create a local PrivX user:

  1. Navigate to the address of the PrivX server and log in as superuser.

  2. In the PrivX GUI, navigate to the Settings→Users page and click Add User.

    You will be presented with the New User view.

  3. In the New User view, provide the required information about the user. Click Save to save the user.

    You should now be able to see your new local user back on the Settings→Users page.

PrivX provides access in a role-based manner. To create a role and assign members:

Now corrected to:

Set the directory Type to OpenID Connect.

Used to be:

Now corrected to:

Set the directory Type to OIDC provider

  1. In the PrivX GUI, navigate to the Settings→Roles page, and click Add Role.

    You will be presented with a form for providing information about the new role.

  2. Provide a name for the new role. Also add users to the role by defining rules. To define a new rule for the role, click Add Rule. In this example, we add a rule to include all local users who have the user name (cn) alice into the role:

    Tip

    The number of role members is indicated by Matching users. The count is updated when you unfocus from the Search String field (such as by pressing enter, or by clicking somewhere else in the GUI).

    Leave the other role settings as they are.

  3. Click Save to finalize role creation. Your new role should be visible back on the Settings→Roles page.

    To verify the users belonging to the role, click List Members:

Adding Target Hosts

Make hosts accessible via PrivX:

On the Settings→Hosts page, click Add Host. Provide at least:

  • The Name and the network Addresses of the host. This optional data helps users identify the target host.

  • The Services (SSH and/or RDP servers) available on the host. In this example we add the SSH server by providing its FQDN address and port number.

  • The Accounts to which roles are mapped on the target host. Leave the Password empty to require password authentication upon connecting. In this example we allow the previously-created example role to access the host as target user root.

    Note

     the username@domain syntax. For example, for domain account Domain\Administrator, the correct syntax is Administrator@Domain.


  • Enable SSH - Trust on first use to allow users to accept the SSH host key upon login.

Click Save to save the host.

You may verify that the host is listed back on the Settings→Hosts page.

Connecting to Target Hosts

After you have set up roles to access hosts, you may test connections as follows:

  1. Log into the PrivX GUI as the test user we created previously (in the section called “Creating Local Users and Roles”).

  2. Navigate to the Connections→New connection page. The hosts you can connect to are listed under Available hosts.

    Expand a host entry to display its available services. In this example, we click the SSH-server service to connect to our test host.

  3. Accept the SSH host key when prompted. Authenticate to the host by providing the password of the target account (not the PrivX account password). You should now be successfully connected to the host.

Enabling Certificate Authentication for OpenSSH Connections

To enable certificate authentication for OpenSSH connections, run the PrivX host-deployment script on the target host.

The host-deployment script is a Python script that configures the OpenSSH server on the target host to accept certificates issued by PrivX The script also sets up allowed principals for target users.

To obtain and run the host-provisioning script:

  1. Access the PrivX GUI as superuser. On the Settings→Deployment→Trusted Clients page, click Add Trusted Client. Give the new client a unique name and set its permissions to Host Provisioning. Click Save to create the client.

  2. Next to the client, click , then click Deployment Script to download the host-deployment script.

  3. Upload the host-deployment script to the target host. You can do this via the PrivX GUI by connecting to the target host (similarly as in the section called “Connecting to Target Hosts”), and then by navigating to the File Transfers tab.

  4. Execute the host-deployment script as root on the target host.

    In the command, use --principals to specify the target accounts and the roles that are allowed to access them. Also add the --standalone option if target host was not added previously using a scan script.

    For example, allowing both the target accounts root and johndoe to be accessed by members of Example Role and privx-admin (replace /path/to/deploy.py with the path of the host-deployment script, note that role names with spaces need to be quoted):

    # python /path/to/deploy.py --standalone --principals \
    root="Example Role",privx-admin:johndoe="Example Role",privx-admin

SSH connections to the target accounts from the specified roles are now authorized using certificates, without prompting users for passwords.

You may also verify that certificate-authorization is used by checking the OpenSSH-server logs on the target server. Upon successful certificate authorization there should be a log message like the following:

Accepted publickey for root from 192.0.2.26 port 50930 ssh2: RSA-CERT \
ID alice@127.0.0.1:53188 serial 4920619392583124720 (serial 4920619392583124720) \
CA RSA 98:16:36:bf:6e:c6:3f:e5:a1:5e:31:61:c1:37:ef:d8

Importing Users from Directories

You can set up PrivX to automatically add users from user directories. Such users can later be given SSH/RDP access to hosts via PrivX.

For example, to add Active Directory (AD) users:

  1. Configure PrivX to scan the AD server for users. To do this, log into PrivX as superuser (or other privx-admin user). Then on the Settings→Directories page, click Add Directory.

  2. Provide the required AD settings.

    Note

    %s in the User DN pattern stands for the user name by which AD users may log into PrivX. For example assume there is an AD user with the following fields:

    sAMAccountName: alice
    userPrincipalName: alice@ad.example.com

    In this case, if User DN pattern were set to (sAMAccountName=%s), the user can log in with the user name alice. If User DN pattern were set to (userPrincipalName=%s), the user can log in with the user name alice@ad.example.com.

    Save the directory settings. PrivX automatically connects to the AD server to add any users found with the given settings.

  3. You may verify the AD status back on the Settings→Directories page. After PrivX finishes adding users from the AD, the connection status should display OK, along with the number of users added.

    To list the users added from the AD, perform a List Users action on the AD entry.

    To grant AD users access to hosts and services, add them to roles (similarly as in the section called “Creating Local Users and Roles”). For example, you can add an additional rule to the Example Role that was created earlier.

    AD users may then log into the PrivX GUI and establish SSH/RDP connections. The allowed connection targets are determined by the role(s) assigned to the AD users.

Importing Hosts from Directories

You can set up PrivX to automatically add existing hosts on cloud platforms. Such hosts can later be connected to via PrivX.

For example, to add hosts from Amazon Web Services (AWS):

  1. In your AWS, add a policy to allow host scans. To do this, access your AWS and navigate to IAM→Policies, then create a policy with the following JSON:

    {
    "Version": "2012-10-17",
    "Statement": [
    {
    "Effect": "Allow",
    "Action": "ec2:Describe*",
    "Resource": "*"
    }
    ]
    }
  2. Create an IAM user with permissions to use the host-scan policy. This can be done on the IAM→Users page.

    The IAM user must have Programmatic access, and be attached with the host-scan policy.

    Note the Access key ID and the Secret access key of the user. These are required later for configuring PrivX against AWS.

  3. Configure PrivX to scan and add the AWS hosts.

    Log into PrivX as superuser (or other privx-admin user). On the Settings→Directories page, click Add Directory.

    Fill in the basic information of the directory. To allow PrivX to detect AWS hosts, add the Access key ID and the Secret access key of the IAM user.

    Save the directory settings. PrivX begins importing hosts from AWS.

    After a moment, you may verify the directory status back on the Settings→Directories page. The Connection should be in the OK state, and list the number of instances found on AWS.

    To list the imported hosts, click List Hosts.

    You may then Edit hosts to add services and account mappings to them, similarly as in the section called “Adding Target Hosts”.

Chapter 5 Additional Configuration for PrivX Servers

This chapter provides instructions for customizing PrivX servers to suit the needs of your environment. These procedures are applicable for PrivX servers that have been set up according to the instructions provided in Chapter 3.

SSL/TLS Security

This section describes the configuration topics related to SSL/TLS security.

Setting Up a Trusted Server Certificate

Freshly set-up PrivX servers are equipped with self-signed server certificates. For production deployments we recommend replacing the self-signed server certificate with a server certificate issued by a trusted Certificate Authority (CA).

Note

The self-signed server certificate should only be trusted in evaluation deployments. In production environments, we strongly recommend that you acquire and use a trusted server certificate. You can obtain a trusted server certificate by enrolling the certificate-signing request with your corporate CA.

  1. The initial setup has generated a certificate-signing request (CSR), which can be enrolled with a trusted CA for a trusted server certificate. The CSR is located at the following path on the PrivX server:

    /etc/nginx/ssl/nginx.csr

    Enroll this CSR with your CA. In response, the CA should provide you with the following:

    • The server certificate.

    • The CA-certificate chain of the CA itself.

    Note

    Note to certificate-signing authorities: The PrivX CSR contains subjectAltName definitions for DNS and IP addresses. These are critical to PrivX operation and must be preserved in the signed server certificate.

  2. Copy the server-certificate file to the ssl_certificate location on the PrivX instance. By default, the location is:

    /etc/nginx/ssl/nginx.crt

    Ensure that the server-certificate file has correct ownership, permissions, and SELinux context:

    # chown root:nginx /etc/nginx/ssl/nginx.crt
    # chmod 0640 /etc/nginx/ssl/nginx.crt
    # restorecon /etc/nginx/ssl/nginx.crt
  3. PrivX microservices must be configured to trust the local server certificate. To do this, run the following command (replace /path/to/ca_chain.crt with the path to the CA-certificate-chain file):

    # /opt/privx/scripts/init_nginx.sh update-trust /path/to/ca_chain.crt

    Note

    init_nginx.sh requires certificate files to have Unix line endings. If the command fails, ensure correct line endings in the CA-certificate-chain file, then rerun the command.

  4. Finally, restart the Nginx and PrivX services to start using the new server certificate:

    # systemctl restart nginx
    # systemctl restart privx

Allowed SSL Protocols and Ciphers for GUI Connections

Connections to the PrivX GUI are secured using TLS. The allowed SSL protocols and SSL ciphers may be adjusted if some browsers cannot establish connections to the PrivX GUI, or if you want to harden the PrivX instance.

The allowed SSL protocols and SSL ciphers are defined in the Nginx configuration file /etc/nginx/conf.d/privx.conf, by the parameters ssl_protocols and ssl_ciphers respectively, similarly to the following:

...
http {
sendfile on;
server_tokens off;

ssl_protocols  TLSv1.2;
ssl_ciphers 'AESGCM+EECDH:AESGCM+EDH:AES+EECDH: ... ';

tcp_nodelay on;
...

After any adjustments to Nginx settings, restart the Nginx web server to apply the changes:

# systemctl restart nginx

Rotating PrivX CA Keys

This section provides instructions for rotating the CA keys of your PrivX deployment.

You can replace the PrivX CA keys with freshly generated ones to minimize the risk of PrivX and its managed environment being compromised in the long run.

To generate the new CA keys, run the rotation script from the selected PrivX server in the deployment:

# /opt/privx/scripts/rotate_privx_ca.sh

The old PrivX CA certificates are deleted and new ones are generated. The script will then restart PrivX.

After rotating the CA keys, all SSH target hosts must be redeployed. This can be done automatically by running deploy.py --rotate-ca on target hosts.

Note

Restoring a PrivX backup will restore old CA certificates but will not delete any new generated keys. To ensure PrivX uses the correct certificates after backup, you must manually delete the new PrivX CA keys from the /opt/privx/keyvault/asymmetric folder before running the restore script. Note that you should only delete the PrivX CA keys, not signing keys.

PrivX Log Settings

By default, regular and audit events are logged to syslog. Audit events use the namespace SSH-PRIVX-AUDIT, and other (info/debug/error) messages use the namespace SSH_PRIVX.

You can adjust the locations to which PrivX writes logs, and the log level of each microservice.

The log locations are configured by settings defined in /opt/privx/etc/shared-config.toml

# Should we send PrivX system events to logs under /var/log/privx
# send_regular_events_to_stdout = false
send_regular_events_to_stdout = false

# Should we send PrivX audit events to syslog
# send_regular_events_to_syslog = true
send_audit_events_to_syslog = true

# Should we send PrivX system events to syslog
# send_regular_events_to_syslog = true
send_regular_events_to_syslog = true

To enable debug output for a microservice:

  1. Edit /opt/privx/scripts/<microservice_name>.sh (replace <microservice_name> with the name of the microservice) and set the SSH_TRACE parameter:

    dir="/opt/privx/bin"
    cmd="SSH_LOG_LEVEL=DEBUG SSH_TRACE=6 /opt/privx/bin/auth"
    user="privx"
  2. By default, the system-logging service rsyslog is configured to show INFO-level messages only, which blocks DEBUG messages. To configure rsyslog to show DEBUG-level messages, find the following line in the rsyslog configuration file, /etc/rsyslog.conf:

    *.info;mail.none;authpriv.none;cron.none    /var/log/messages

    And change it to, for example:

    *.debug;mail.none;authpriv.none;cron.none    /var/log/messages

    Restart rsyslog to apply the changes:

    systemctl restart rsyslog
  3. Restart the privx service to apply any changes to configuration files:

    # systemctl restart privx

Chapter 6 PrivX Users and Permissions

This chapter describes user and permission management:

  • Adding PrivX users.

  • Providing role-based permissions for PrivX users.

  • Workflows for requesting/revoking roles for PrivX users.

Adding PrivX Users

You can add PrivX users in the following ways:

Add local users

On the Settings→Users page click Add User, and then provide their information, such as credentials and contact information.

Local users are an easy way to add PrivX users.

Note

A local user must have a password that is at least eight characters long.

Import existing users from LDAP, AD, and/or OpenID Connect providers

On the Settings→Directories page click Add Directory. Select a Type from one of the supported User Directories. Provide other required information about the LDAP/AD directory, such as connection information and the query for obtaining user entries.

For additional information about LDAP/AD configuration, see the section called “AD/LDAP Directory Configuration”.

For additional information about OpenID Connect (OIDC) configuration, see the section called “OpenID-Connect Configuration”.

Granting Permissions for PrivX Users

PrivX users are given permissions via roles. Permissions allow, for example:

  • Accessing certain hosts.

  • Approving/denying requests.

  • Performing PrivX administration.

Members of a role automatically receive the permissions of their roles. In other words, users gain permissions by becoming members of roles. Users may become members of a role in either of the following ways:

A user can have any number of roles.

Managing Roles

You can create, edit, and remove roles from the Settings→Roles page. On this page you can also list the members belonging to the selected role and where the role grants access to.

A role may define rules: LDAP filters for specifying the members of the role. A user belongs to the role if they match one or more of the rules. Additionally, roles may specify restrictions for SSH connections, such as forced commands.

Role changes take effect within 1 - 5 minutes from being applied.

Role Restrictions

You can restrict a role using SSH options such as source addresses and forced SSH commands.

On the Settings→Roles page you can define SSH options for a role. These include source addresses and forced SSH commands. You can specify that access to target hosts is only allowed from certain source addresses. If a forced command is set, connections will only perform the specified command on the target host, then exit.

Requesting and Approving Memberships

PrivX users can submit requests to grant or remove membership from roles, either for themselves or on behalf of others. To submit a request, go to the Requests→My Requests page and click New Request.

In a request, you need to specify (at least):

  • The user whose membership is to be granted or revoked.

  • The role to be granted or revoked.

You can review the status of your requests on the Requests→My requests page.

PrivX users can approve and deny requests on the Requests→Approvals page. Click a request to submit a decision.

You need to have an existing workflow for a role before users can request/revoke memberships from the role. For more information about workflows, see the section called “Managing Workflows”.

Note

PrivX users may not approve their own requests.

A request must gather all the approvals to be approved; One denial is enough to deny an entire request.

Only the mapped users of a role can submit decisions required from the role.

Mapped-user memberships cannot be revoked. Mapped users are removed by adjusting the rules of the role.

Role changes take effect within 1 - 5 minutes from being applied.

Granting Access to Target Hosts

PrivX users may access a target host if one or more of their roles is mapped to a target user. To allow the members of a role to connect to a target host:

  1. Navigate to the Settings→Hosts page, and Edit the target host.

  2. Under the Accounts section, specify mappings from roles to target users. Multiple roles may be mapped to one target user. If a role is mapped to multiple target users, the members of that role may choose which user to connect as.

    Save your changes to the host. PrivX users belonging to the specified role(s) can now access the target host as the target user(s) they are mapped to. PrivX users can see accessible target hosts on the Connections→New Connection page.

    For more information about connecting to target hosts see Chapter 8.

Granting Administrator Permissions

You can grant PrivX administrator ppermissions for a user by giving them the privx-admin role. Similarly, you can remove administrator permissions by removing the user from the privx-admin role.

PrivX administrator permissions allow users to:

  • Manage directories, hosts, roles, users, and workflows.

  • Connect to any target host.

Managing Workflows

Workflows allow PrivX users to grant or revoke role memberships for themselves and for others. You can create, edit, and remove workflows from the Settings→Workflows page.

A workflow contains one to three steps, each defining some approval requirements. Once a request gets all the approvals from a step, it proceeds to the next step. Membership is granted to the target user once the approvals from each step have been gathered.

For more information about requests, see the section called “Requesting and Approving Memberships”.

Enabling Email Notifications

PrivX can automatically notify approvers when a new request requires their attention. This can happen when a new request is created, or when a request proceeds to a new step.

  1. To enable automatic email notifications, configure PrivX against an existing SMTP server. You can set the relevant email settings from the PrivX GUI, on the Settings→Workflows page.

  2. If the email-server connection uses TLS, the email-server root-CA certificate must be added to the system-wide trust anchors on your PrivX servers. To do this, copy the root-CA certificate under:

    /etc/pki/ca-trust/source/anchors/

    Then run:

    # update-ca-trust extract

AD/LDAP Directory Configuration

This section describes configuration topics for AD and LDAP directories.

Users from added AD/LDAP directories can log into PrivX, and furthermore to target hosts (as permitted by their roles). The general workflow for providing access to AD/LDAP users is as follows:

  1. To add an AD/LDAP directory, go to the Settings→Directories page and click Add Directory.

  2. Set the directory Type to Active Directory or LDAP. Provide any required directory settings, such as connection and bind parameters.

    After you have provided the necessary settings, click Save to apply your changes.

  3. Optional: Back on the Settings→Directories page, you may verify that PrivX is able to import users from the directory: the directory Status should be OK, and it should display the correct number of users.

    Any imported PrivX users can login to the PrivX GUI using their AD/LDAP credentials. To further allow such users to log into target hosts, add them to roles as described in the section called “Granting Permissions for PrivX Users”.

The following subsections provide instructions for some of the more advanced AD/LDAP setup scenarios.

Secure-Connection Setup

To allow TLS-based secure connections (STARTTLS or LDAPS) to directory servers, the following requirements must be met:

  • The directory-server certificate must specify its DNS and IP addresses in the Subject Alternative Name.

  • The server-certificate CA must be trusted on the PrivX server. This can be satisfied, for example, by adding the CA certificate to the trust store of the PrivX server.

To enable secure connections to user directories, perform the following steps on the PrivX server:

  1. Ensure the directory-server certificate specifies the server DNS and/or IP addresses in the SubjectAltName field. You can do this, for example, using openssl (replace directory.example.com and 636 with the address and the port of the directory service):

    $ echo "Q" | \
    openssl s_client -connect directory.example.com:636 | \
    openssl x509 -noout -text
  2. On the PrivX server, place the directory-server CA certificate under the trust-anchors directory, located at:

    /etc/pki/ca-trust/source/anchors/

    Then to add the certificate to the system trust store, run:

    # update-ca-trust extract
  3. You may verify that the PrivX server correctly authenticates the directory server (replace directory.example.com and 636 with the address and the port of the directory service):

    $ openssl s_client -connect directory.example.com:636

    With the correct certificate setup, you should get:

    Verify return code: 0 (ok).

  4. Restart PrivX to apply the changes:

    # systemctl restart privx

Adjusting User Matching

PrivX applies a default pre-filter for matching user records. You may adjust the pre-filter to affect what records are imported.

To override the pre-filter for a user directory, specify your custom User filter in the directory settings:

  1. On the Settings→Directories page, Edit your user directory.

  2. Under the Active directory settings section, specify a User filter for matching users on the user directory.

  3. Click Save to apply your changes. Your new User filter overrides the default pre-filter.

You can also change the default pre-filter globally from the Role Store configuration file, located under the following path on the PrivX machine:

/opt/privx/etc/rolestore.toml

Under the [ldap] section of the file, look for the settings default_user_filter and attributes. These settings respectively specify what objects are recognized as users, and what fields are fetched from matching records.

default_user_filter = \
"(|(objectClass=user)(objectClass=person)(objectClass=inetOrgPerson))"
attributes = "objectClass cn dn distinguishedName ... "

For default OpenLDAP setup you could specify, for example, the following line with inetOrgPerson and posixAccount:

default_user_filter = "(&(objectClass=inetOrgPerson)(objectClass=posixAccount))"

If you are using two directories with different schemas, you can combine them for example as follows:

default_user_filter = "(|(&(objectClass=user)(objectClass=person))(&(objectClass=inetOrgPerson)(objectClass=posixAccount)))"

Adjust these settings as necessary. Restart PrivX services to apply the changes.

# systemctl restart privx

Note

User filters may also be specified in directory settings. To modify directory settings, go to Settings→Directories and Edit your user directory.

When a User filter is specified in directory settings, only those records matching both the default_user_filter and User filter are imported as PrivX users.

Refreshing Directory Data

User-directory changes are updated to PrivX in the following ways:

  • By default, PrivX refreshes directory data every 15 minutes. To adjust the refresh interval of a directory, go to Settings→Directories and Edit the target directory. Shortening the interval allows PrivX to detect user changes faster, while lenghtening the interval reduces system load.

  • To immediately refresh directory data, go to Settings→Directories and perform a Refresh action on the target directory.

OpenID-Connect Configuration

This section describes the configurations for allowing users from an OpenID Connect (OIDC) provider to log into PrivX.

Users from added OIDC providers can log into PrivX, and furthermore to target hosts (as permitted by their roles). Furthermore, such users are authenticated against the OIDC provider.

To provide access for OIDC users, set up your OIDC and PrivX as follows:

  1. Configure your OIDC provider to provide role information in End-User Claims.

    End-User Claims from the OIDC provider must include tags that can be used to associate the End User to PrivX Roles. For example, in the following ID Token/Userinfo response, the groups Claim provides the required tags:

    {
    "sub": "248289761001",
    "name": "Jane Doe",
    "given_name": "Jane",
    "family_name": "Doe",
    "preferred_username": "j.doe",
    "email": "janedoe@example.com",
    "groups": ["Example Role 01", "Example Role 02"]
    }
  2. PrivX requires continued access to the OIDC provider for updated group and role information. Ensure your OIDC provider is configured to issue access and refresh tokens for PrivX.

  3. Add the OIDC provider to PrivX. To do this, go to the Settings→Directories page and click Add Directory.

  4. Set the directory Type to OpenID Connect. Provide any required settings, such as the OIDC issuer URL and client credentials.

    After you have provided the necessary settings, click Save to apply your changes.

    Note

    To allow OIDC users to login to personal accounts, you must define Source=Target attribute pairs. For example, to allow access to accounts specified in preferred_username, specify the following:

    preferred_username=windows_account
    preferred_username=unix_account
  5. Optional: You may test OIDC logins from the PrivX login page. All OIDC authentication methods are listed below the Login button.

    Any imported PrivX users can login to the PrivX GUI using their OIDC credentials. To further allow such users to log into target hosts, add them to roles as described in the section called “Granting Permissions for PrivX Users”.

Advanced Authentication for PrivX Users

This section describes additional authentication configurations that allow greater ease and security for PrivX users logging in.

Kerberos Authentication for PrivX Users

In PrivX you may enable Kerberos Single Sign On (SSO) for PrivX users belonging to one AD/LDAP user directory. Users from that directory can, after initial login to a Kerberos client, log into the PrivX GUI without having to retype their credentials.

Prerequisites

Ensure and perform the following before setting up Kerberos authentication for PrivX:

  • You need a functioning Kerberos Key Distribution Center (KDC) and admin server. These services may be run on the same server.

  • Kerberos servers must be able to resolve the host names of your PrivX servers.

  • Users must be part of a AD/LDAP user directory. The user directory must have been added to PrivX. Furthermore, users from that directory must have access to some Kerberos client for obtaining their Kerberos tickets (such as Windows login or kinit). Note that you may only enable Kerberos authentication for one user directory in PrivX at any time.

    For more information about adding user directories to PrivX, see the section called “Adding PrivX Users”.

PrivX Integration to Kerberos

To enable Kerberos authentication for PrivX users belonging to a user directory, repeat the following steps for each of your PrivX servers:

  1. To add PrivX as a service to Kerberos, create a unique service principal for the PrivX server. The principal name must follow the syntax:

    HTTP/privx.example.com@EXAMPLE.COM

    Replace the example values as follows:

    • privx.example.com - the PrivX server name.

    • EXAMPLE.COM - the name of your Kerberos realm.

  2. To allow the PrivX to authenticate against the KDC, obtain a keytab of the PrivX service principal. The keytab entries should be encrypted using algorithms supported by your Kerberos environment. If using Windows Kerberos, also ensure the keytab is mapped to the user account associated with the PrivX service principal.

    Caution

    Ensure that the keytab is never exposed to unauthorized personnel. Malicious users with access to the keytab may use it to impersonate services.

  3. On your PrivX server, add the keytab to /etc/krb5.keytab.

    Also ensure the keytab-file is readable by the local user privx. For example:

    # chown privx:privx /etc/krb5.keytab
    # chmod 0400 /etc/krb5.keytab
  4. Configure your PrivX server to connect to your KDC. To do this, add a similar configuration to /etc/krb5.conf on the PrivX server:

    [libdefaults]
    default_realm = EXAMPLE.COM
    
    # The following krb5.conf variables are only for MIT Kerberos.
    krb4_config = /etc/krb.conf
    krb4_realms = /etc/krb.realms
    kdc_timesync = 1
    ccache_type = 4
    forwardable = true
    proxiable = true
    
    
    [realms]
    EXAMPLE.COM = {
    kdc = dc.example.com
    admin_server = dc.example.com
    }
    
    [login]
    krb4_convert = true
    krb4_get_tickets = false

    Adjust the configuration according to your Kerberos environment. You will at least have to change default_realm to the actual name of your Kerberos realm, change the [realms] section to include the actual name of your Kerberos realm, and to specify the addresses of its KDC and Kerberos admin server.

    Save your changes to the file.

  5. On the PrivX server, adjust the PrivX settings in /opt/privx/etc/auth-default-config.toml. You will have to set the following:

    • kerberos_enabled - set to true

    • kerberos_service_name - set this equal to the PrivX service principal.

    • kerberos_directory_name - the name of the user directory for which Kerberos is enabled. For a list of directories and their names, see the Settings→Directories page in the PrivX GUI.

    • kerberos_realm_name - the name of your Kerberos realm.

    Example values for these settings:

    kerberos_enabled=true
    kerberos_service_name="HTTP/privx.example.com@EXAMPLE.COM"
    kerberos_directory_name="Example AD 01"
    kerberos_realm_name="EXAMPLE.COM"

    Save your changes to the file.

  6. On the PrivX server, restart PrivX services to apply the changes:

    # systemctl restart privx

    Once you have completed these steps on each PrivX server, Kerberos SSO is enabled.

Logging in with Kerberos

After you have set up kerberos SSO, PrivX users belonging to the configured user directory can log in as follows:

  1. Obtain your Kerberos ticket, for example, by logging into a machine with Kerberos authentication or by running kinit.

  2. Access the PrivX login page. You will be automatically logged into PrivX, without having to re-enter your credentials.

Multi-Factor Authentication for PrivX Users

When multi-factor authentication (MFA) is enabled for PrivX users, they are required to input a time-based PIN code (in addition to their account password) to log into PrivX.

Note

PrivX users must set up and use the Google Authenticator app to successfully log in with multi-factor authentication.

Enabling MFA for Directories

To enable/disable MFA for a user directory:

  1. On the Settings→Directories page, Edit a directory entry.

  2. Expand Advanced directory settings. Under the Multi-factor authentication settings section, set the MFA type. Set it to TOTP MFA (time-based) to enable MFA; Set it to Disabled to disable MFA.

  3. Click Save to apply the changes.

Logging in with MFA

When MFA is enabled, PrivX users can obtain their MFA code and log in as follows:

  1. Log into PrivX normally, using your user name and password.

  2. If you have not done so before, you will be asked to import your MFA code. This allows you to obtain PIN codes for MFA login.

    Scan or enter the code into your Google Authenticator app. After this, your Google Authenticator app should display 6-digit time-based PIN codes.

    Click Next to proceed.

  3. Enter the PIN code displayed in your authenticator app. After this you should be logged into the PrivX GUI.

Reobtaining MFA Codes

If a PrivX user has lost their MFA code, you can set PrivX to offer a new MFA code upon their next login:

  1. On the Settings→Users page, click the user who needs a new MFA code.

  2. Expand Advanced directory settings. Under Multi-factor authentication, perform a Reset MFA Pairing action. Also verify that the Multi-factor authentication status is updated to Enabled, not activated.

    The user is prompted to import a new MFA code upon their next PrivX login.

Chapter 7 Authentication Methods for Host Connections

PrivX allows password authentication by default. This chapter describes how you may allow other authentication methods (such as certificate or public-key) for connecting to target hosts.

Supported Authentication Methods

PrivX users can authenticate to target hosts using the following methods.

Table 7.1. Supported authentication methods

MethodSupported byNotes
Certificate (for SSH connections)SSHOnly for supported OpenSSH versions described in the section called “Requirements for Certificate Authentication Over SSH”.
Public keySSH
Stored passwordSSH, RDP
Certificate (for RDP connections)RDPTarget hosts must satisfy the prerequisites from the section called “Requirements for Certificate-Based Authentication Over RDP”.
User-provided passwordSSH, RDP

Certificate

Users are authenticated using just-in-time certificates. PrivX automatically issues certificates as needed; users do not need to input credentials when connecting.

Advantages: Automatically expiring credentials that are never exposed to users, making this method the most secure option.
Disadvantages: Allowed principals must be configured for target users, which is unwieldy in environments without automated configuration management. System times must be synchronized for certificate-based authentication to work correctly.
Public key

Users are authenticated using public keys provided by PrivX. Users do not need to input credentials when connecting.

Advantages: Public-key authentication is largely supported even on older and non-mainstream SSH servers.
Disadvantages: Public keys must be manually provisioned to target users on target servers. Public keys never expire, so they need to be manually renewed.
Stored password

Users are authenticated using passwords stored in PrivX. Users do not need to input credentials when connecting.

Advantages: Easy to set up.
Disadvantages: Weak passwords may compromise security.
User-provided password

Users are authenticated using passwords stored in PrivX.

Advantages: No additional target-host configuration required.
Disadvantages: Users must provide the target-user password when connecting. Weak passwords may compromise security.

Note

If a target host/target user supports multiple methods, the topmost supported method is used. User-provided password is enabled on all target hosts by default.

Enabling Certificate-Based Authentication for SSH Connections

You can enable certificate-based authentication on a target host with one of the following methods:

Requirements for Certificate Authentication Over SSH

To use certificate-based authentication for SSH connections, hosts serving as connection endpoints (target hosts) must use an SSH server that supports OpenSSH certificates. The exact required version depend on the chosen authorization method. For additional information about the supported authorization methods, see the section called “Supported Authentication Methods”.

Table 7.2. SSH version requirements for certificate-based authentication

Authorization methodRequired version
Role-based accessOpenSSH 5.6 or later
Login as selfOpenSSH 6.9 or later

Determine the PrivX roles that can access the host, and the target users as whom they are granted login.

Script-Based Certificate-Authentication Setup

PrivX provides a host-deployment script. It is a Python script that can be executed on target hosts to automatically set up certificate authentication.

The host-deployment script has the following system requirements:

  • Supported operating systems: CentOS, Fedora, Debian, Red Hat, Ubuntu.

  • Required Python version: 2.7.9 or later.

  • Required OpenSSH version: 6.9 or later.

  • Network: Connectivity to a PrivX server.

Note

On target hosts that do not support the host-deployment script, and on hosts that cannot connect to PrivX, you can set up certificate-authentication manually as per the section called “Manual Certificate-Authentication Setup”.

Note

For hosts that cannot be accessed directly by PrivX, you need to first set up a PrivX Extender for proxying host connections. For more information about PrivX Extender setup, see the section called “Proxying Connections to Hosts”.

To use the host-deployment script to set up certificate authentication on a target host, for connections between certain target accounts and PrivX users from certain roles:

  1. You need to define a trusted client before you can obtain deployment scripts. To create a trusted client, navigate to the Settings→Deployment→Trusted Clients page, then click Add Trusted Client. The trusted client must be given Host Provisioning permissions.

  2. In the trusted client, click , then click Deployment Script to download a deployment script.

  3. Execute the deployment script on the target host as root. You will at least need to provide the host type, and the principals (specifying which target accounts can be accessed, and by whom).

    To specify the host type, use one of the following options:

    --aws: The host runs on AWS.
    --google-cloud: The host runs on Google Cloud.
    --openstack: The host runs on OpenStack.
    --standalone: For non-cloud hosts.

    To specify principals, use any of the following options:

    --personal-account-roles: Allow members of certain roles to log in with their personal accounts (to target accounts whose names match their Windows/Unix username).
    --principals: Manually define target accounts and the roles that may access them.

    For example, using --personal-account-roles to allow members of the roles Example Role 01 and Example Role 02 to log in with their personal accounts, add:

    --personal-account-roles "Example Role 01,Example Role 02"

    You may also specify --principals to define target accounts and the roles that may access them. The general format is:

    --principals target_account1=role1,role2,…:target_account2=role3,role4,…:… 

    For example, to allow target account alice to be accessed by PrivX users belonging to the privx-admin role, set this option to:

    --principals alice=privx-admin

    As another example, to additionally allow accounts alice and bob to be accessed by members of Example Role:

    --principals alice=privx-admin,"Example Role":bob="Example Role"

    Full syntax example of running the host-deployment script:

    # /path/to/deploy.py --standalone \
    --personal-account-roles "Example Role 01, Example Role 02" \
    --principals alice="Example Role",privx-admin:bob=privx-admin

    For a full list of options supported by the host-deployment-script, run:

    $ /path/to/deploy.py help
  4. Certificates issued by PrivX are very time-sensitive. Even a clock skew of few minutes may prevent certificates from working correctly.

    Verify that the target-host time is correct. Adjust as necessary.

PrivX users belonging to one of the allowed roles should now see the target host on the Connections→New Connection page.

You may also verify that certificate-based authentication is used by checking the OpenSSH-server logs on the target server. Upon successful certificate-based authentication there should be a log message like the following:

Accepted publickey for alice from 192.0.2.26 port 50930 ssh2: RSA-CERT \
ID alice@127.0.0.1:53188 serial 4920619392583124720 \
(serial 4920619392583124720) \
CA RSA 98:16:36:bf:6e:c6:3f:e5:a1:5e:31:61:c1:37:ef:d8

Configuring Access Using Host Tags

For cloud-based hosts, PrivX can be configured to import allowed principals from host tags. This method simplifies host deployment as principals do not need to be provided for the host-deployment script.

Tip

Configuring access with host tags can be used for setting up hosts that mostly lack connection to PrivX: An initial instance must be able to connect to PrivX, but subsequent clones of this instance do not need PrivX connectivity.

To configure allowed principals for a cloud-based host using host tags:

  1. Add host tags to the host via your cloud-host-management interface (such as EC2 for AWS instances). Host tags must specify the access rules and SSH/RDP services related to the host.

    The list of supported host tags is provided later in this section.

  2. Configure PrivX to import host tags. To do this, navigate to Settings→Directories in the PrivX GUI and Edit the directory to which the target host belongs to. Enable the Import host instance tags from the directory setting. Click Save to apply your changes.

  3. Deploy the host using the host-deployment script, or manually.

    Users from PrivX roles are now able to access the host according to the principals defined in the host tags, with certificate-based authentication.

PrivX supports the following host tags:

privx-ssh-principals=<target>=<roles1>:<target2>=<roles2>:...

Allow target accounts to be accessed by specified PrivX roles using SSH connections.

Access to each target account is specified with <target>=<roles> syntax, where <target> is the account name and <roles> is the comma-separated names of PrivX roles allowed to access the account. Each such mapping must be separated with a colon (:).

For example, to allow target user alice to be accessed by PrivX roles privx-admin and Role 01, and to allow target user bob to be accessed by Role 02:

privx-ssh-principals=alice=Role 01,privx-admin:bob=Role 02
privx-rdp-principals=<target1>=<roles1>:<target2>=<roles2>:...

Allow target accounts to be accessed by specified PrivX roles using RDP connections.

Syntax is the same as with the privx-ssh-principals tag.

privx-ssh-personal-account-roles=<roles>

Allow members of certain role(s) to log in with their personal accounts (to target accounts whose names match their Windows/Unix username) using SSH connections. Any comma-separated PrivX-role names in <roles> are allowed login to personal accounts.

For example, to allow members of Role 01 and Role 02 to login to personal accounts:

privx-ssh-personal-account-roles=Role 01,Role 02
privx-rdp-personal-account-roles=<roles>

Allow members of certain role(s) to log in with their personal accounts (to target accounts whose names match their Windows/Unix username) using RDP connections. Syntax is similar to the privx-ssh-personal-account-roles tag.

privx-ssh-service-port=<port>

Specify the SSH-server port of the target host. By default SSH servers run on port 22.

Example:

privx-ssh-service-port=22
privx-rdp-service-port=<port>

Specify the RDP-server port of the target host. By default RDP servers run on port 3389.

Example:

privx-rdp-service-port=3389
privx-extender=<extender_name>

If connections to the host are relayed through a PrivX Extender, use this tag to specify the name of the associated trusted client.

Example:

privx-extender=Example Extender

For more information about PrivX Extender, see the section called “Proxying Connections to Hosts”.

Note

To obtain the tag in key-value format, split the syntax at the first = sign. For example, the previously-provided examples are as follows in key-value format:

KeyValue
privx-ssh-principalsalice=Role 01,privx-admin:bob=Role 02
privx-ssh-personal-account-rolesRole 01,Role 02
privx-ssh-service-port22
privx-rdp-service-port3389
privx-extenderExample Extender

Certificate-Authentication Setup via Chef

SSH Communications Security provides a public Chef cookbook privx-chef-cookbook. You can use it to set up nodes to trust PrivX certificates.

To obtain this cookbook, along with more information about its usage, visit:

https://github.com/SSHcom/privx-chef-cookbook

Manual Certificate-Authentication Setup

To manually enable certificate-based authentication, you must configure your target hosts as follows:

  1. Ensure the system clocks are synchronized (for example, using NTP). The certificates issued by PrivX have very short validity periods: clock skew may cause authentication to fail.

  2. The SSH server on the target host must be configured to trust certificates issued by PrivX (the section called “Trusting PrivX Certificates”).

  3. For target user accounts, specify the principals that are allowed to connect. Depending on the target-host OpenSSH version, you can do this in either of the following methods:

  4. To display the target hosts and accounts under known targets in PrivX, add the host to PrivX (the section called “Configure Known Targets in PrivX”).

Principals in PrivX-Issued Certificates

This section describes principals in the context of certificate-based authentication.

OpenSSH certificates contain principals indicating who is requesting access. OpenSSH certificates issued by PrivX contain at least the user name as a principal, and may have any number of other principals. For example, assume a PrivX user named alice belongs to roles having the principals:

bd5eab79-fe35-4f52-839a-05737075b152
b8b72199-689d-5a9b-782f-8e1069f7db19

When PrivX user alice connects to a target host using certificate authentication, PrivX issues them a certificate with the following principals:

bd5eab79-fe35-4f52-839a-05737075b152
b8b72199-689d-5a9b-782f-8e1069f7db19
alice

Authentication succeeds if the target account allows at least one of the principals.

Trusting PrivX Certificates

Target hosts using certificate-based authentication must be configured to trust the certificates issued by PrivX.

  1. Access the PrivX GUI. On the Settings→Deployment→SSH target hosts page, acquire the PrivX CA key.

    PrivX CA key

    Figure 7.1. PrivX CA key


    Copy the PrivX CA key. This key is later required for configuring the target host.

  2. On the target host, create the following file:

    /etc/ssh/privx_ca.pub

    Copy and save the PrivX CA key into this file.

    Ensure that the CA-key file is owned and readable by the user running the SSH server (typically root):

    # chown root:root /etc/ssh/privx_ca.pub
    # chmod 0400 /etc/ssh/privx_ca.pub
  3. In the SSH server configuration file (located at /etc/ssh/sshd_config by default), specify TrustedUserCAKeys to point to the PrivX CA key. To do this, add a line similar to the following into the SSH server configuration:

    TrustedUserCAKeys /etc/ssh/privx_ca.pub

    Restart the SSH server to apply the new settings.

  4. Certificates issued by PrivX are very time-sensitive. Even a clock skew of few minutes may prevent certificates from working correctly.

    Verify that the target-host time is correct. Adjust as necessary.

Allowing Login as Self and Role-Based Access

PrivX provides a principals-command script that enables login with personal accounts: PrivX users can log into the target accounts, the names of which match the PrivX user's Windows/Linux username.

Note

The principals-command script is only supported on target hosts running OpenSSH 6.9 or later.

The provided principals-command script is provided as an example. You may modify the script to suit your own needs.

To set up the principals-command script, enable login with personal accounts, and to configure role-based access:

  1. PrivX users who are to access the target host must belong to at least one PrivX role. If you have not done so already, assign users to roles as described in the section called “Managing Roles”.

    Also ensure that PrivX users are set with correct Windows username and Linux username. By default, AD users' Windows username and Linux username are set to match their User-Principal Name and sAMAccountName respectively.

  2. For security reasons we recommend creating a user specifically for running the principal-command script on the target host. This AuthorizedPrincipalsCommandUser should be an unprivileged user who only has permissions for performing the following:

    • Running the principals-command script.

    • Reading the principals that are allowed to log in with personal accounts, at /etc/ssh/personal_account_roles

    • Reading any user-specific authorization-principals files located at /etc/ssh/auth_principals/%u (replace %u with the name of the authenticated user).

    Some Unix distributions have a default nobody account, which can be used as the AuthorizedPrincipalsCommandUser.

  3. Obtain the AuthorizedPrincipalsCommand script from your PrivX server, at the following path:

    /opt/privx/scripts/principals_command.sh

    Copy the script to the target host. In this example, we assume the script is copied to

    /etc/ssh/principals_command.sh

    Both the script and the directory it is in must be owned by root. The script must also be readable and executable by the AuthorizedPrincipalsCommandUser (replace /etc/ssh/principals_command.sh with the path to which you copied the script):

    # chown root:root /etc/ssh
    # chown root:root /etc/ssh/principals_command.sh
    # chmod 0755 /etc/ssh/principals_command.sh
  4. Configure SSH server to run the principals-command script as the AuthorizedPrincipalsCommandUser. This is done by adding lines similar to the following into the SSH configuration (by default at /etc/ssh/sshd_config, replace authprincipalsuser with the name of your designated AuthorizedPrincipalsCommandUser, replace /etc/ssh/principals_command.sh with the path where you copied the script ):

    AuthorizedPrincipalsCommand /etc/ssh/principals_command.sh %u
    AuthorizedPrincipalsCommandUser authprincipalsuser

    Save your changes to the SSH server configuration file. Restart the SSH server to apply the changes.

  5. Next, specify who is allowed to access target accounts. Note that all access must be specified in a role-based fashion.

    1. To allow login with personal accounts for members of certain roles: On the target host, specify in /etc/ssh/personal_account_roles which PrivX-role members are allowed to log in with personal accounts. The file should specify one UUID per line, similar to the following:

      269eaef2-482e-5b44-5d0f-2ee4c37e2877 # Example Admins
      31f070c6-33ff-523f-4cea-d586ab25071a # Example Role
      8a0c0cbb-1417-4de2-8532-3eac1fb4c30b # Example Users
      ...

      Save your changes to the file.

      Note

      You can determine the UUIDs of PrivX roles from the Settings→Deployment→SSH target hosts page.

      Role principals in the PrivX GUI

      Figure 7.2. Role principals in the PrivX GUI


      Also ensure the file is readable by root and the AuthorizedPrincipalsCommandUser:

      # chown root:root /etc/ssh/personal_account_roles
      # chmod 0604 /etc/ssh/personal_account_roles

      PrivX users belonging to the specified roles may now log into the host as themselves. For example, a PrivX user belonging to the Example Admins role (with role UUID 269eaef2-482e-5b44-5d0f-2ee4c37e2877) with the Linux username alice may now log in to the target-account named alice (assuming the host is Unix/Linux-based).

    2. To grant custom role-based access to certain target accounts: Create the directory /etc/ssh/auth_principals/ for holding target-account-specific principals files (if not already done):

      # mkdir /etc/ssh/auth_principals
      # chown root:root /etc/ssh/auth_principals/
      # chmod 0755 /etc/ssh/auth_principals/

      For each target account requiring custom role-based access, create a principals file under /etc/ssh/auth_principals/. The principals file must have the same name as the target account. For example, when setting up custom role-based access for a target account named alice, the principals file is /etc/ssh/auth_principals/alice

      In the principals file, specify the roles that may access the account. The file should specify one UUID per line, similar to the following:

      269eaef2-482e-5b44-5d0f-2ee4c37e2877 # Example Admins
      31f070c6-33ff-523f-4cea-d586ab25071a # Example Role
      8a0c0cbb-1417-4de2-8532-3eac1fb4c30b # Example Users
      ...

      After saving your changes to the file, ensure it is readable and executable by both root and the AuthorizedPrincipalsCommandUser (replace /etc/ssh/auth_principals/alice with the path to the user's principals file):

      # chown root:root /etc/ssh/auth_principals/alice
      # chmod 0705 /etc/ssh/auth_principals/alice
  6. Certificates issued by PrivX are very time-sensitive. Even a clock skew of few minutes may prevent certificates from working correctly.

    Verify that the target-host time is correct. Adjust as necessary.

You may verify that certificate-authentication is used by checking the OpenSSH-server logs on the target server. Upon successful certificate authentication there should be a log message like the following:

Accepted publickey for alice from 192.0.2.26 port 50930 ssh2: RSA-CERT \
ID alice@127.0.0.1:53188 serial 4920619392583124720 \
(serial 4920619392583124720) \
CA RSA 98:16:36:bf:6e:c6:3f:e5:a1:5e:31:61:c1:37:ef:d8

Allowing Role-Based Access

PrivX roles have unique principals. When a target user allows a role principal, members of corresponding roles can connect to the target user.

To allow the members of a PrivX role to access a target user:

  1. On the target host, create a directory for storing principals files (if not already done).

    # mkdir /etc/ssh/auth_principals

    The permissions of the directory must be set so that individual target users are able to read their authorization-principals files, for example:

    # chown root:root /etc/ssh/auth_principals
    # chmod 0755 /etc/ssh/auth_principals
  2. On the target host, create a file for storing the user-specific allowed principals (replace %u with the account name of the target user on the target host):

    /etc/ssh/auth_principals/%u

    For example, if the target-user name is alice, their principals file is:

    /etc/ssh/auth_principals/alice

    Within the file, specify the UUIDs of the roles that are allowed access to the target-user account. Specify each UUID on its own line, similar to the following:

    269eaef2-482e-5b44-5d0f-2ee4c37e2877 # Example Admins
    31f070c6-33ff-523f-4cea-d586ab25071a # Example Role
    8a0c0cbb-1417-4de2-8532-3eac1fb4c30b # Example Users
    ...

    You can determine the principals of PrivX roles from the Settings→Deployment→SSH target hosts page.

    Role principals in the PrivX GUI

    Figure 7.3. Role principals in the PrivX GUI


  3. Ensure that the authorization-principals file is owned and readable by the target-user account (replace %u with the name of the target-user account):

    # chown %u:%u /etc/ssh/auth_principals/%u
    # chmod 0400 /etc/ssh/auth_principals/%u

    For example, if the target-user name is alice:

    # chown alice:alice /etc/ssh/auth_principals/alice
    # chmod 0400 /etc/ssh/auth_principals/alice
  4. If not already done, instruct the SSH server about where the authorization-principals files can be found from. This can be done by specifying the AuthorizedPrincipalsFile setting in the OpenSSH server configuration (by default at /etc/ssh/sshd_config):

    AuthorizedPrincipalsFile /etc/ssh/auth_principals/%u

    Save your changes to the OpenSSH server configuration. Restart the OpenSSH server to apply the changes. PrivX users belonging to one or more allowed principals (roles) are now authenticated to the target-user account using certificates.

  5. Certificates issued by PrivX are very time-sensitive. Even a clock skew of few minutes may prevent certificates from working correctly.

    Verify that the target-host time is correct. Adjust as necessary.

You may verify that certificate-authentication is used by checking the OpenSSH-server logs on the target server. Upon successful certificate authentication there should be a log message like the following:

Accepted publickey for alice from 192.0.2.26 port 50930 ssh2: RSA-CERT \
ID alice@127.0.0.1:53188 serial 4920619392583124720 \
(serial 4920619392583124720) \
CA RSA 98:16:36:bf:6e:c6:3f:e5:a1:5e:31:61:c1:37:ef:d8

Enabling Role-Based Public-Key Authentication

  1. Obtain the public key of the role you want to authorize. You can do this on the Settings→Deployment→SSH target hosts page.

  2. Authorize the public key to the target user on the target host. In OpenSSH for example, this is done by appending the public key to the authorized_keys file, typically located at:

    ~/.ssh/authorized_keys

    All the members of the role should now be able to connect to the target user with public-key authentication.

Enabling Authentication with Stored Passwords

You can store target-user passwords in PrivX, so PrivX users can connect to those target users without having to provide the password. The steps for enabling this authentication method are:

  1. For SSH only: Configure the target-host SSH server to allow password authentication. Note that allowing keyboard-interactive authentication does not enable using stored passwords in PrivX.

  2. Store the target-user passwords in PrivX:

    1. On the Settings→Hosts page, Edit the target host on which the target user is.

    2. Under the Accounts section, provide the Password for the target user(s). If not done already, also specify the Roles that may access the target user(s)

    3. Click Save to apply the changes.

    Connections to the target user should no longer prompt for password.

Enabling Certificate Authentication for RDP Connections

This section describes the procedures for enabling certificate authentication for RDP connections.

Before setting up certificate authentication for RDP connections, ensure the prerequisites described in the section called “Requirements for Certificate-Based Authentication Over RDP”.

Requirements for Certificate-Based Authentication Over RDP

Before enabling certificate authentication for RDP, check and execute the following:

  • Target hosts must belong to a Windows domain. The domain must include:

    • A domain controller with the server role Active Directory Domain Services, for handling authentication requests.

    • A Certificate Authority Server (CA server), with the server role Active Directory Certificate Services, including the role service Certificate authority.

      The CA server must also have a service for certificate-revocation-status checks, for example, HTTP CRL with Certificate Enrollment Web Service or Web Server IIS role, or alternatively OCSP with the Online Responder role service.

    • Ensure that users' group policy allows RDP login. When enabling login with personal accounts, also ensure target-host local policy allows users to log on locally.

  • Both the domain controller and the CA server must run on one of these supported platforms:

    • Windows Server 2008 R2 (with the latest service pack and updates)

    • Windows Server 2012 R2 (with the latest service pack and updates)

    • Windows Server 2016 (with the latest service pack and updates)

  • The domain policy must enable server certificate auto-enrollment. For instructions about enabling this, please refer to Microsoft documentation at https://docs.microsoft.com (search title: configure server certificate autoenrollment).

  • Firewalls for the domain must allow HTTP access to PrivX server port 80, for obtaining the Certificate Revocation List.

  • Hosts in the target domain must be able to resolve PrivX server FQDNs.

Steps for RDP Certificate-Authentication-Setup

After ensuring the prerequisites, enable certificate authentication for RDP by performing the following:

  1. For target hosts to trust PrivX certificates, you must publish the PrivX CA certificate in the Windows domain.

    To obtain the PrivX CA certificate, go to the PrivX GUI. On the Settings→Deployment→RDP Target Hosts page, click Download Certificate.

  2. Add the PrivX CA certificate to the Trusted Root Certification Authorities for the domain. For more information, please refer to Microsoft documentation at https://docs.microsoft.com (search title: distribute certificates to client computers by using group policy).

  3. Publish the PrivX CA certificate to the domain (replace privx_ca.crt with the path of the PrivX CA-certificate file):

    $ certutil -dspublish -f privx_ca.pem NTAuthCA

    Also ensure that the registry is updated by running:

    certutil -addstore -enterprise NTAuth privx_ca.pem
  4. On all target hosts, ensure that the host allows remote connections without Network Level Authentication.

  5. Define which roles are allowed to access the target hosts, and as which target accounts. For more information about mapping roles to target accounts, see the section called “Configure Known Targets in PrivX”.

  6. Certificates issued by PrivX are very time-sensitive. Even a clock skew of few minutes may prevent certificates from working correctly.

    Verify that the system times on the target hosts is correct. Adjust as necessary.

RDP connections to target hosts are now be authenticated by just-in-time certificates provided by PrivX, without needing to provide target-user passwords.

Configure Known Targets in PrivX

After setting up authentication manually, you need to expose known target hosts/accounts to PrivX users.

To add a host and its target accounts as known targets to PrivX, Go to the Settings→Hosts page and click Add Host. For each host you must at least specify:

  • Basic host information such as name and addresses.

  • The SSH and/or RDP services running on the host.

  • Account entries specifying which target accounts can be accessed, and by which roles. Account entries are also used for specifying which roles may log in with their personal accounts.

PrivX users who may access the host should now be able to see the target on the Connections page, under the Available hosts section.

Trusting Target-Host Identities

This section describes target-host authentication.

SSH Target-Host Authentication

For SSH connections, PrivX authenticates target hosts by their SSH host keys.

You can store SSH host keys when creating or editing a host entry via Settings→Hosts.

When connecting to a host, the key/certificate of which is not yet trusted by PrivX, the connection starts as follows:

  • If no other keys are stored for the host: PrivX administrators may accept the new host key for all subsequent connections. Regular PrivX user can accept a new host key if the Trust On First Use is enabled for the host.

  • If another key has been stored for the host: Regular PrivX users are prevented from connecting to the host. A PrivX administrator must explicitly accept the key for all subsequent connections.

You can store SSH host keys and set Trust on First Use behavior by editing host entries on the Settings→Hosts page.

RDP Target-Host Authentication

For RDP connections, PrivX authenticates target hosts by their RDP-server certificate.

By default, PrivX automatically accepts the certificate encountered upon the first RDP connection. Connections will fail if the RDP-server certificate changes, or is renewed prior to the start of the renewal period. The renewal period starts one month prior to the expiry date. Connection will automatically accept the new certificate during the renewal period.

If connections fails due to the RDP-server certificate changing, you can re-enable by deleting the stored RDP certificate:

  1. On the Settings→Hosts page, Edit the target RDP server.

  2. Under the RDP host certificate section, click

    Upon next RDP connection, PrivX automatically accepts the new RDP-server certificate for subsequent RDP connections.

You can adjust the time window during which the RDP-server certificate may be automatically renewed. To do this:

  1. Modify the RDP proxy settings, located at the following path on your PrivX servers:

    /opt/privx/etc/rdp-proxy.toml

    Locate and modify the following settings:

    • renewal_period_months: Allow RDP-server certificate to be renewed from this many months before the NotAfter field marked in the current RDP-server certificate.

    • renewal_period_days: Allow RDP-server certificate to be renewed from this many days before the NotAfter field marked in the current RDP-server certificate.

    These two settings are cumulative. For example, to allow the RDP-server certificate to be renewed from two months and 15 days before the current one expires:

    [certificates]
    update_automatically = true
    renewal_period_months = 2
    renewal_period_days = 15
  2. Save your changes to the RDP-proxy configuration.

    Restart the PrivX services to apply the new settings:

    # systemctl restart privx

Importing Hosts from Directories

You can set up PrivX to automatically add existing hosts on cloud platforms. Such hosts can later be connected to via PrivX.

For example, to add hosts from Amazon Web Services (AWS):

  1. In your AWS, add a policy to allow host scans. To do this, access your AWS and navigate to IAM→Policies, then create a policy with the following JSON:

    {
    "Version": "2012-10-17",
    "Statement": [
    {
    "Effect": "Allow",
    "Action": "ec2:Describe*",
    "Resource": "*"
    }
    ]
    }
  2. Create an IAM user with permissions to use the host-scan policy. This can be done on the IAM→Users page.

    The IAM user must have Programmatic access, and be attached with the host-scan policy.

    Note the Access key ID and the Secret access key of the user. These are required later for configuring PrivX against AWS.

  3. Configure PrivX to scan and add the AWS hosts.

    Log into PrivX as superuser (or other privx-admin user). On the Settings→Directories page, click Add Directory.

    Fill in the basic information of the directory. To allow PrivX to detect AWS hosts, add the Access key ID and the Secret access key of the IAM user.

    Save the directory settings. PrivX begins importing hosts from AWS.

    After a moment, you may verify the directory status back on the Settings→Directories page. The Connection should be in the OK state, and list the number of instances found on AWS.

    To list the imported hosts, click List Hosts.

    You may then Edit hosts to add services and account mappings to them, from Settings→Hosts page.

Chapter 8 Establishing and Managing Connections

This chapter describes the methods in which PrivX users can connect to target hosts:

Regardless of the used method, connections are authenticated according to the role-based rules and the authentication methods enabled for PrivX users.

Connecting via the PrivX GUI

To connect to target hosts via the PrivX GUI:

  1. Log into the PrivX GUI using your PrivX account.

  2. On the Connections→New connection page, specify where you want to connect to, and which connection type to use.

    • When Connection details is set to Search from known hosts, you can see the target hosts that your roles grant access to. Click a target host to display the available target accounts, then click a target account to connect to it.

    • If the desired target host and/or target account is not displayed in the GUI, you can manually specify a connection target by switching Connection details to Enter details manually.

    You may need to provide the target-account password (depending on the available authentication methods). After successful authentication, you should be logged into the target account on the target host.

    Note

    In addition to remote terminal/desktop sessions, PrivX offers additional features for interacting with the target host (such as file transfer). Also, you may need to adjust locale settings for keyboard commands to be transferred correctly.

    For more information about connection features and settings, see sections the section called “SSH GUI Features” and the section called “RDP GUI Features” for SSH and RDP respectively.

    Tip

    To quickly connect to a host you have accessed previously, Go to the Home page of the PrivX GUI and click a connection listed under Recent connections. Your recent connections are also listed on the Connections→History page.

SSH GUI Features

Open multiple terminals

On the tab bar, click + to open additional terminals.

Copy-paste
  • On a Mac, you can select text and use command-c and command-v to copy-paste, or right-click and use the context menu.

  • On a Windows or Linux you can select text and right-click to use the context menu. Alternatively you can select some text, pres ctrl on its own and then press ctrl-c or ctrl-v within the next second.

  • The left Alt (option on a Mac) key also functions as the Meta key (for example in Emacs).

Transfer files

You can upload, download, and remove files from the File Transfers tab.

To change directory, click a directory or . You can perform additional actions on files via their menus.

  • To download a file: Double-click the file, or perform a Download action via its menu.

  • To upload a file: Drag-and-drop the file to the file-transfer view. Alternatively, click Upload next to the file-transfer view and select the local file to upload.

Change text, locale and theme

From the Settings tab, you can set the font size, character encoding, and the locale used for the connection. You can also switch between a dark and a light theme.

Open URLs

To open HTTP/HTTPS links in a new tab on Windows or Linux, hold Ctrl and double-click the link. To open links on Mac, hold command and double-click.

RDP GUI Features

Copy-paste

To copy-paste text to the target host, place the text into the Clipboard tab, then paste normally on the target host. Text copied on the target host is automatically made available in the Clipboard.

Transfer files

Upon connecting, PrivX automatically mounts a network drive called Transfers on PrivX to the target host. File downloads and uploads must be performed via this network drive.

You can copy files from the target host to Transfers on PrivX, then download them from the Files tab. Similarly, you can upload files by placing them to Transfers on PrivX on the Files tab, then move the file to another location on the target host.

  • To download a file: Double-click the file, or perform a Download action via its menu.

  • To upload a file: Drag-and-drop the file to the file-transfer view. Alternatively, click Upload next to the file-transfer view and select the local file to upload.

Set keyboard layout

To change your keyboard layout, go to the Settings tab, select your layout, then restart the connection to apply the changes. Set this to match the keyboard layout defined for the server (not the client-side layout).

Fullscreen view

To toggle fullscreen view, click

Note

Toggling fullscreen mode also re-establishes the RDP connection.

Connecting with Native Clients (SSH Only)

This section describes how you can configure native clients to authenticate using permissions provided by PrivX.

In this configuration, users can connect to target hosts/accounts using the SSH clients installed on their workstations, without needing to use the PrivX GUI. Connections are authenticated against PrivX. For example, if PrivX allows you to access a target account with certificate authentication, your native clients will also connect using certificate authentication without prompting you for target-account credentials.

This configuration requires a PrivX to be installed on the user's workstation.

Native-Client Setup Usage (on Unix)

To set up native clients against PrivX for a user on a Unix workstation:

  1. Obtain the following, required for configuring native clients:

  2. Extract and install the PrivX agents to the workstation. For example (replace PrivX-Agents-*.zip with the path to the agent-software package):

    # unzip -j PrivX-Agents-*.zip linux-amd64/* -d /usr/local/bin/

    The example command installs the PrivX agent and the PrivX agent utility to:

    /usr/local/bin/privx-agent-unix
    /usr/local/bin/privx-agent-ctl

    The following steps assume the PrivX agent and the agent utility to be in these locations.

  3. Enable PrivX agent to start automatically when the user logs into the workstation. You can do this by appending the following to the users' .profile file:

    # Start PrivX Agent unless there is already an ssh-agent running
    START_PRIVX_AGENT="yes"
    PRIVX_AGENT_UNIX="/usr/local/bin/privx-agent-unix"
    if [ -n "$START_PRIVX_AGENT" ] && [ -z "$SSH_AUTH_SOCK" ] && \
    [ -x "$PRIVX_AGENT_UNIX" ]; then
    export SSH_AUTH_SOCK=$( \
    mktemp -d /tmp/ssh-XXXXXXXXXX 2>/dev/null || \
    mktemp -d -t 'mytmpdir')"/agent.$$"
    nohup $PRIVX_AGENT_UNIX -a $SSH_AUTH_SOCK \
    -config $HOME/.privx/agent.json > /dev/null 2>&1 &
    export SSH_AGENT_PID=$!
    trap 'test -n "$SSH_AGENT_PID" && kill $SSH_AGENT_PID' 0
    fi

    Note

    The provided example commands for agent startup are not run if another application sets the SSH_AUTH_SOCK variable (such as a default ssh agent), nor if the PrivX agent is installed to a custom location. You may have to adjust the agent-startup conditions to suit your environment.

    The temporary-directory path /tmp/ssh-XXXXXXXXXX is used by the agent. Do not change this path.

  4. Add PrivX servers to the agent. To do this, log in to the workstation as the user who will be using native clients (in order to start the agent), then run the following (replace https://privx.example.com with the address of your PrivX server):

    $ privx-agent-ctl server probe https://privx.example.com

    Unless the PrivX server certificate is trusted on the workstation, you will be presented with additional information, such as the SHA checksums of the certificate.

    PrivX server 'https://privx.example.com' certificate is untrusted
    Server TLS certificate:
    Issuer        DC=com, DC=ssh, DC=fi, DC=hel, OU=QA, CN=MSCA-PKI-TEST2-ROOT-CA
    Subject       OU=PrivX Web Server, CN=privx.hel.fi.ssh.com
    Serial        2453081971937566630710942289116460769316175891
    Not Before    2018-03-28 09:00:15 +0000 UTC
    Not After     2028-03-28 09:10:15 +0000 UTC
    Fingerprints
    SHA1        B5 F3 70 E2 DB 61 56 D9 AC AE 03 4D AE DC 01 4C FB D2 AB C0
    SHA256      17 22 63 69 D1 AA 77 34 96 BD B7 90 69 83 E7 30 97 A2 78 10 \
    73 5C 93 D0 D6 01 99 5C 04 C5 55 B2
    
    Would you like to add this server to trusted servers? Y/N:

    You may ensure that these match to the checksums of the PrivX server certificate, which you can obtain by running the following on the PrivX server:

    # openssl x509 -noout -fingerprint -sha1 -in /etc/nginx/ssl/nginx.crt
    # openssl x509 -noout -fingerprint -sha256 -in /etc/nginx/ssl/nginx.crt

    Once you have confirmed the server identity, enter Y to add the PrivX server.

The native clients have now been set up against PrivX. You can now use the native clients on the workstation as follows:

  1. Log into the workstation as the user for whom native clients have been set up.

    Verify that the agent is running with:

    $ privx-agent-ctl status

    The command should return a message similar to the following:

    PrivX SSH Agent Status
    PrivX Server          https://privx.example.com
    Login status          logged out
  2. Via the terminal, authenticate against PrivX using your PrivX credentials. For example (replace username with your PrivX user name):

    $ privx-agent-ctl login username

    You may verify your login status with:

    $ privx-agent-ctl status

    After entering your PrivX credentials correctly, your native SSH clients (such as ssh) will authenticate connections via PrivX. For a list of valid connection targets, run:

    $ privx-agent-ctl target list

Native-Client Setup Usage (on MacOS)

To set up native clients against PrivX for a user on a MacOS workstation:

  1. Obtain the following, required for configuring native clients:

  2. Extract and install the PrivX agents to the workstation. For example (replace PrivX-Agents-*.zip with the path to the agent-software package):

    # unzip PrivX-Agents-*.zip darwin-amd64/*
    # cp darwin-amd64/privx-agent-unix /usr/local/bin/
    # cp darwin-amd64/privx-agent-ctl /usr/local/bin/
    # cp darwin-amd64/privx-agent-start.sh /usr/local/bin/

    The example command installs the PrivX agent, the agent utility, and the agent-startup script to:

    /usr/local/bin/privx-agent-unix
    /usr/local/bin/privx-agent-ctl
    /usr/local/bin/privx-agent-start.sh

    The following steps assume the PrivX agent, the agent utility, and the agent-startup script to be in these locations.

  3. Enable PrivX agent to start automatically when the user logs into the workstation. To do this, first install the agent launcher with:

    # cp darwin-amd64/com.privxagent.plist ~/Library/LaunchAgents/
    # launchctl load -w ~/Library/LaunchAgents/com.privxagent.plist
    # launchctl start ~/Library/LaunchAgents/com.privxagent.plist

    Also append the following to the users' .bash_profile file:

    # Register SSH_AUTH_SOCK & SSH_AGENT_PID to local environment
    # if started by Launchd
    if sock=$(launchctl getenv SSH_AUTH_SOCK); then
    export SSH_AUTH_SOCK=$sock
    fi
    
    if pid=$(launchctl getenv SSH_AGENT_PID); then
    export SSH_AGENT_PID=$pid
    fi
  4. Add PrivX servers to the agent. To do this, log in to the workstation as the user who will be using native clients (in order to start the agent), then run the following (replace https://privx.example.com with the address of your PrivX server):

    $ privx-agent-ctl server probe https://privx.example.com

    Unless the PrivX server certificate is trusted on the workstation, you will be presented with additional information, such as the SHA checksums of the certificate.

    PrivX server 'https://privx.example.com' certificate is untrusted
    Server TLS certificate:
    Issuer        DC=com, DC=ssh, DC=fi, DC=hel, OU=QA, CN=MSCA-PKI-TEST2-ROOT-CA
    Subject       OU=PrivX Web Server, CN=privx.hel.fi.ssh.com
    Serial        2453081971937566630710942289116460769316175891
    Not Before    2018-03-28 09:00:15 +0000 UTC
    Not After     2028-03-28 09:10:15 +0000 UTC
    Fingerprints
    SHA1        B5 F3 70 E2 DB 61 56 D9 AC AE 03 4D AE DC 01 4C FB D2 AB C0
    SHA256      17 22 63 69 D1 AA 77 34 96 BD B7 90 69 83 E7 30 97 A2 78 10 \
    73 5C 93 D0 D6 01 99 5C 04 C5 55 B2
    
    Would you like to add this server to trusted servers? Y/N:

    You may ensure that these match to the checksums of the PrivX server certificate, which you can obtain by running the following on the PrivX server:

    # openssl x509 -noout -fingerprint -sha1 -in /etc/nginx/ssl/nginx.crt
    # openssl x509 -noout -fingerprint -sha256 -in /etc/nginx/ssl/nginx.crt

    Enter Y to add the PrivX server.

The native clients have now been set up against PrivX. You can now use the native clients on the workstation as follows:

  1. Log into the workstation as the user for whom native clients have been set up.

    Verify that the agent is running with:

    $ privx-agent-ctl status

    The command should return a message similar to the following:

    PrivX SSH Agent Status
    PrivX Server          https://privx.example.com
    Login status          logged out
  2. Via the terminal, authenticate against PrivX using your PrivX credentials. For example (replace username with your PrivX user name):

    $ privx-agent-ctl login username

    You may verify your login status with:

    $ privx-agent-ctl status

    After entering your PrivX credentials correctly, your native SSH clients (such as ssh) will authenticate connections via PrivX. For a list of valid connection targets, run:

    $ privx-agent-ctl target list

Setting up Known Hosts

Setting up known hosts allows users to see what they can connect to. You can add or edit known hosts on the Settings→Hosts page. Each known-host entry may specify:

  • Connection information: such as host name, addresses, and PrivX configuration.

  • Options: in case of SSH, by enabling Trust on first use you can allow PrivX to store host public identity on first connection.

  • Services: specify the SSH and RDP servers that should be accessible.

  • Accounts: the target accounts on the host to which PrivX users can connect to. Associate allowed roles to target accounts to control which PrivX users may connect to them. For more information about associating Roles to accounts, see the section called “Managing Roles”.

  • SSH host keys: when the Trust on first use option is not checked, the SSH host key must be added here. In this case PrivX will only allow connections to the host if the host key matches one of the provided values.

    Note

    PrivX administrators may accept or deny the connection even when the host key is missing or incorrect.

Monitoring and Managing Connections

You can monitor ongoing and prior connections on the Monitor page. The page allows you to:

  • See which user is currently connecting or has connected to which destination via SSH or RDP. Note that the page does not show agent-based connections.

  • Filter connections by their status and search words.

  • Terminate a connection.

Proxying Connections to Hosts

A PrivX Extender relays host connections, allowing connections to target hosts that are not directly accessible by PrivX.

PrivX Extender can be set up on any host that satisfies the following requirements (Extender host):

  • The host must be able to connect to PrivX and to target host(s).

  • The host must have one of the supported operating systems: CentOS 7.4 or later, Red Hat version 7.4 or later.

To set up PrivX Extender on a host:

  1. Add the PrivX Extender as a trusted client: Navigate to the Settings→Deployment→Trusted clients page in the PrivX GUI, click Add Trusted Client. Give the trusted client PrivX Extender permissions. Leave the network settings with default values unless specified otherwise. Click Save to finalize the new trusted client.

    Click next to the trusted client, then click Extender Config to download the configuration.

  2. Install the PrivX Extender software on the Extender host in either of the following ways:

    • Install from the SSH product repository. To do this, set up the repository and install the software package:

      # rpm --import https://product-repository.ssh.com/info.fi-ssh.com-pubkey.asc
      # wget https://product-repository.ssh.com/ssh-products.repo \
      -O /etc/yum.repos.d/ssh-products.repo
      # yum install PrivX-Extender
    • If the Extender host lacks Internet connectivity, you may obtain the software package from software downloads.

      Then copy the package to the Extender host and install it with (replace /path/to/PrivX-Extender.*.rpm with the path to which you placed the Extender package):

      # yum install /path/to/PrivX-Extender-*.rpm
  3. Save the Extender configuration to the following path on the Extender host:

    /opt/privx/etc/extender-config.toml
  4. Restart the PrivX Extender service to apply the configuration:

    # systemctl restart privx-extender

    The PrivX Extender is now set up. You may verify back on the Settings→Deployment→Trusted clients page that the trusted-client Status is Registered.

  5. Configure the target host(s) that are to be accessed via a PrivX Extender. The procedure is different for existing hosts, and for hosts that are to be deployed.

    Extender Configuration for Host-Deployment Script

    When using the host-deployment script to deploy target hosts, provide the --api-hostname option to specify the PrivX-Extender address and port (comma-separated). Example syntax for host deployment:

    # /path/to/deploy.py --standalone \
    --personal-account-roles "Example Role 01" \
    --api-hostname "extender.example.com:8443"

    You may check the addresses (subject-alternative names) of your PrivX Extender from its TLS certificate:

    # openssl x509 -text -noout -in /opt/privx/extender/extender.crt \
    | grep -A 1 "Subject Alternative Name"

    The PrivX Extender port is 8443 by default. You may verify the port from the extender configuration file, where it is specified by the host_deployment_listen_address variable.

    For more information about deploying hosts with the host-deployment script, see the section called “Script-Based Certificate-Authentication Setup”.

    Extender Configuration for Existing and Manually-Deployed Hosts

    For every target host that is to be accessed via the PrivX Extender, go to the Settings→Hosts page and Edit the host. Then under the Services section, prepend the Client name of the PrivX Extender to the Address of each SSH and RDP service. Separate the Client name from the addresses with a forward slash.

    Example Address syntax in IPv4 and IPv6 format:

    Example Extender/192.0.2.100
    Example Extender/2001:DB8::64

    Save your host changes. Subsequent connections to the host are proxied via the PrivX Extender.

Chapter 9 Auditing

This chapter describes how to use and configure PrivX auditing features.

Viewing Audit Data

In the PrivX GUI, you can find audit data from the following locations:

  • For connections-specific audit events, go to Monitor→Connections and click one of the connection entries.

  • For global audit events, see Monitor→Events.

Note

To obtain video playback about user's sessions, you need to enable session recording as described in the section called “Session Recording Setup”.

PrivX microservices generate logs to /var/log/messages. These may be useful in troubleshooting scenarios.

Session Recording Setup

This section describes the procedures for setting up session recording.

When session recording is enabled, you can view a video playback and any transferred files of your users' sessions. To enable session recording for connections to a host:

  1. On the Settings→Hosts page, Edit the host.

  2. Under Options, enable the setting Session Recording. Click Save to apply your changes.

    Subsequent sessions to the host are recorded. You can view the playback and transferred files from the connection-specific audit events, available from Monitor→Connections.

Session recordings should not be stored on PrivX servers as they may consume lots of disk space; you should configure PrivX to store session recordings on an external share instead (such as NFS). To set up external storage share for PrivX session recordings:

  1. On your external storage server, create a share for storing PrivX session recordings. The share must be a directory that satisifies the following:

    • The share must be mountable by all PrivX servers.

    • The share must be readable and writable by the privx system user of every PrivX server.

  2. On each PrivX server, install any extensions required for mounting the external-storage share. For example, to mount NFS shares you will likely need to install nfs-utils; for SMB shares you will likely need cifs-utils. These extension packages are available from the RHEL/CentOS public repositories.

  3. On each PrivX server, mount the external share to a local directory. To enable mounting the share on system startup, we recommend adding the mount directive to /etc/fstab.

    To allow the GUI to display other connection logs when the NFS server is unavailable, mount the share with options like the following:

    soft
    timeo=10
    retry=1
  4. On each PrivX server, configure PrivX to store session recordings to the mounted share. To do this, edit the data_folder setting in /opt/privx/etc/shared-config.toml (replace /path/to/privx-trails with the local directory to which the external share is mounted):

    data_folder="/path/to/privx-trails"

    Save your changes, then restart PrivX services to apply the changes:

    # systemctl restart privx

Audit Events in PrivX

This section lists the audit events raised by the PrivX system. Note that some of the listed audit-event types are not used by the current PrivX version.

PrivX uses syslog facilities to write audit events. Audit events are stored to the system's default syslog location. On RHEL/CentOS 7 the default location is /var/log/messages.

The debug logs for each microservice are in the following locations:

  • /var/log/privx/auth.log - Logs for the OAuth2 microservice.

  • /var/log/privx/authorizer.log - Logs for the authorizer microservice.

  • /var/log/privx/connectionmanager.log - Logs for the connection manager microservice.

  • /var/log/privx/hoststore.log - Logs for the hoststore microservice.

  • /var/log/privx/keyvault.log - Logs for the keyvault microservice.

  • /var/log/privx/rdpproxy.log - Logs for the RDP proxy microservice.

  • /var/log/privx/rolestore.log - Logs for the role store microservice.

  • /var/log/privx/sshproxy.log - Logs for the SSH proxy microservice.

  • /var/log/privx/userstore.log - Logs for the user store microservice.

  • /var/log/privx/workflowengine.log - Logs for the workflow engine microservice.

License-error

Code: 0

Description: The system license does not allow operation.

Configuration-error

Code: 1

Description: The system configuration is invalid.

Service-starting

Code: 10

Description: The service is starting.

Service-running

Code: 11

Description: The service is running.

Service-stopped

Code: 12

Description: The service has been stopped.

User-logged-in

Code: 100

Description: User has logged in to the system.

User-login-failed

Code: 102

Description: User login operation failed.

User-MFA-challenge-sent

Code: 103

Description: User tried to log in without MFA pin code.

User-MFA-challenge-accepted

Code: 104

Description: User successfully authenticated with MFA pin code.

User-MFA-challenge-setup-sent

Code: 105

Description: User was MFA setup information.

Access-token-granted

Code: 106

Description: Access token granted

User-access-token-refreshed

Code: 110

Description: User refreshed the access token

User-access-token-refresh-failed

Code: 111

Description: User access token refresh failed.

OAuth-client-authenticated

Code: 121

Description: OAuth client authenticated

OAuth-client-authentication-failed

Code: 122

Description: OAuth client authentication failed

Role-added

Code: 201

Description: New role added to the system.

Role-modified

Code: 202

Description: Role has been modified.

Role-removed

Code: 203

Description: Role has been removed.

Directory-added

Code: 210

Description: New directory added to the system.

Directory-modified

Code: 211

Description: Directory has been modified.

Directory-removed

Code: 212

Description: Directory has been removed.

Directory-authentication-failed

Code: 213

Description: Directory authentication failed.

User-roles-modified

Code: 220

Description: The user's role associations were changed

AWS-token-was-granted

Code: 230

Description: A AWS token was granted to a user

AWS-token-was-not-granted

Code: 231

Description: AWS token grant failed

Connection-requested

Code: 300

Description: Connection was requested.

Connection-authenticated

Code: 301

Description: Connection was authenticated.

Connection-rejected

Code: 302

Description: Connection was rejected.

Connection-closed

Code: 303

Description: Connection was closed.

Session-added

Code: 310

Description: A session was added to a connection.

Session-removed

Code: 311

Description: A session was removed from a connection.

File-upload

Code: 320

Description: File upload performed.

File-download

Code: 321

Description: File download performed.

Host-key-matched

Code: 324

Description: Host key matched

Host-key-denied

Code: 325

Description: Host key denied

Host-key-accepted

Code: 326

Description: Host key accepted

Host-key-saved

Code: 327

Description: Host key saved

Extender-connected

Code: 328

Description: Extender connected

Extender-disconnected

Code: 329

Description: Extender disconnected

File-removed

Code: 330

Description: File removed.

Folder-removed

Code: 331

Description: Folder removed.

File-moved

Code: 332

Description: File moved.

Folder-created

Code: 333

Description: Folder created.

Connection-audit-started

Code: 334

Description: Connection audit started

Connection-audit-failed

Code: 335

Description: Connection audit failed

Authorization-requested

Code: 400

Description: A client requested an authorization.

Authorization-certificate-granted

Code: 401

Description: An authorization certificate granted.

Authorization-role-key-granted

Code: 402

Description: An authorization role key granted.

Authorization-role-key-sign-operation-rejected

Code: 403

Description: An authorization role key sign operation was rejected.

Authorization-role-key-sign-operation-accepted

Code: 404

Description: An authorization role key sign operation was accepted.

Authorization-rejected

Code: 405

Description: An authorization was rejected.

Authorization-certificate-warning

Code: 406

Description: Authorization certificate creation generated warnings.

Authorization-Passphrase-returned

Code: 407

Description: Authorization passphrase was returned

Principal-added

Code: 410

Description: A principal was added.

Trusted-client-added

Code: 420

Description: A trusted client was added.

Trusted-client-modified

Code: 421

Description: A trusted client was modified.

Trusted-client-removed

Code: 423

Description: A trusted client was removed.

License-updated

Code: 430

Description: The service license was updated.

CA-Certificate-Created

Code: 440

Description: CA certificate was created.

CA-Certificate-Deleted

Code: 441

Description: CA certificate was deleted.

EE-Certificate-Enrolled

Code: 442

Description: End entity certificate was enrolled

EE-Certificate-Revoked

Code: 443

Description: End entity certificate was revoked

User-added

Code: 500

Description: New user added to the system.

User-modified

Code: 501

Description: User has been modified.

User-removed

Code: 502

Description: User has been removed.

User-password-modified

Code: 510

Description: User password has been modified.

User-authenticated

Code: 520

Description: User has been authenticated.

User-authentication-failed

Code: 521

Description: User authentication has failed.

Workflow-added

Code: 600

Description: A workflow was added.

Workflow-modified

Code: 601

Description: A workflow was modified.

Workflow-removed

Code: 602

Description: A workflow was removed.

Request-added

Code: 610

Description: A request was added.

Request-modified

Code: 611

Description: A request was modified.

Request-removed

Code: 612

Description: A request was removed.

Decision-made

Code: 620

Description: A decision has been made on a request.

Email-sent

Code: 630

Description: A email notification has been sent.

Email-configuration-Modified

Code: 631

Description: Email configuration has been modified.

DB-Schema-Updated

Code: 641

Description: Database Schema updated

Log-downloaded

Code: 700

Description: Log files have been downloaded.

Log-level-modified

Code: 710

Description: The log level was modified.

Host-added

Code: 801

Description: A host was added.

Host-modified

Code: 802

Description: A host was modified.

Host-removed

Code: 803

Description: A host was removed.

Scope-added

Code: 810

Description: A scope was added.

Scope-modified

Code: 811

Description: A scope was modified.

Scope-removed

Code: 812

Description: A scope was removed.

Connection-terminated

Code: 900

Description: Connection terminated.

Connection-terminated-for-host

Code: 901

Description: Connection terminated for host.

Connection-terminated-for-user

Code: 902

Description: Connection terminated for user.

Trail-opened

Code: 1000

Description: Trail opened.

Trail-open-failed

Code: 1001

Description: Failed to open trail.

Trail-file-open-failed

Code: 1002

Description: Failed to open trail file.

Trail-file-read-failed

Code: 1003

Description: Failed to read trail file.

Chapter 10 Troubleshooting

This section describes the usual solutions to fixing issues related to, for example, setup, initial login, and services being unavailable. Also restarting PrivX and accessing debug logs are instructed.

Reading Debug Logs

Messages in syslog /var/log/messages and /var/log/privx/*.log may provide additional information about issues in the setup and in client connections.

  • /var/log/privx/auth.log - Logs for the OAuth2 microservice.

  • /var/log/privx/authorizer.log - Logs for the authorizer microservice.

  • /var/log/privx/connectionmanager.log - Logs for the connection manager microservice.

  • /var/log/privx/hoststore.log - Logs for the hoststore microservice.

  • /var/log/privx/keyvault.log - Logs for the keyvault microservice.

  • /var/log/privx/rdpproxy.log - Logs for the RDP proxy microservice.

  • /var/log/privx/rolestore.log - Logs for the role store microservice.

  • /var/log/privx/sshproxy.log - Logs for the SSH proxy microservice.

  • /var/log/privx/userstore.log - Logs for the user store microservice.

  • /var/log/privx/workflowengine.log - Logs for the workflow engine microservice.

For more details about what each microservice does, see Appendix B.

For more information about enabling debug logging, see the section called “PrivX Log Settings”.

Checking microservice statuses

You can verify the microservice statuses on the status page, available at (replace https://privx.example.com with the address of your PrivX server:

https://privx.example.com/status.html

Restarting PrivX

Some issues may be fixed by restarting the PrivX service. You can do this by running the following command on your PrivX servers:

# systemctl restart privx

Services Are Down

If microservices report 502 errors, check the database connectivity. Make sure the pg_hba.conf on the PostgreSQL server allows PrivX servers to connect to the PrivX database with md5 authentication.

More information about the error may be provided by the microservice logs.

Connections fail with error Too many Authentication Failures

PrivX connects using all the available credentials (such as certificate, public key, and stored credentials). For target users who allow many roles, the OpenSSH MaxAuthTries may be exceeded before PrivX offers the correct authentication method.

To fix the error, increase the MaxAuthTries in the target-host OpenSSH configuration, restart the target-host OpenSSH server, then try connecting again.

Problems Related to Authentication

More information about authentication issues may be found from syslog messages.

Since PrivX uses short-term certificates for user authentication, deviations in system times (minutes or more) will easily result in failing authentications. It is extremely important to synchronize the clocks between all the involved systems:

  • PrivX servers

  • Hosts serving as connection endpoints.

We strongly recommend using authenticated NTP clock synchronization on all the involved systems.

Directory Users Are Not Listed

PrivX applies a default pre-filter for matching user records. The pre-filter may need to be adjusted depending on your user-directory structure. For more information about adjusting how users are matched, see the section called “Adjusting User Matching”.

List Users View Does Not Display All Attributes

Sometimes in List users view some of the columns show Anonymous, or are empty. In this case it is possible you may need to adjust the attribute mapping in your directory settings. For example in default OpenLDAP setup you could have the following attribute mappings:

  • sn=full_name

  • uid=principal

Contacting Support

You can request technical support and let us know about PrivX issues on the SSH Communications Security support site at https://help.ssh.com/

When submitting a support ticket, please attach PrivX troubleshooting data. To generate troubleshooting data, run the following on your PrivX server:

# /opt/privx/scripts/troubleshoot.sh info

And attach the generated troubleshooting-data package to the support ticket. By default the package is generated to the current working directory, with the name:

Privx-troubleshoot-data-<host>-<timestamp>.tar.gz

Caution

Troubleshooting data may contain security critical data, and must be distributed with appropriate care.

For additional usage instructions related to the troublehsooting script, you may run:

# /opt/privx/scripts/troubleshoot.sh -h

Appendix A Example Nginx Load-Balancer Configuration

This chapter provides an example configuration for an Nginx load balancer, used for distributing connections to PrivX servers.

 # PrivX NGINX Load-balancer example configuration.
# Requests are distributed between servers based on client IP addresses.
# The upstream module contains the IP addresses of the PrivX servers.
# In this example two instances of PrivX are running
# with private IP addresses 172.12.1.3 and 172.12.1.5.
# All HTTP requests are redirected to HTTPS.

events {
worker_connections 1024;
}

http {
upstream privx {
ip_hash;
server 172.12.1.3:443;
server 172.12.1.5:443;
}

client_max_body_size 50M;

server {
listen 80 default_server;
listen [::]:80 default_server;
return 301 https://$host$request_uri;
}

server {
listen 443 ssl http2 default_server;
listen [::]:443 ssl http2 default_server;
ssl_certificate "/etc/nginx/server.crt";
ssl_certificate_key "/etc/nginx/server.key";

location / {
proxy_set_header X-Forwarded-Host $http_host;
proxy_pass https://privx;
}

location ~ ^/(ssh-proxy|rdp-proxy)/ {
proxy_pass https://privx;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade";
}
}
}

Note

To change Nginx load balancer configuration to use sticky sessions, change the line

ip_hash;

to

sticky;

Note that sticky sessions require Nginx to be built with the sticky module. For more information about the sticky module and its installation, see https://bitbucket.org/nginx-goodies/nginx-sticky-module-ng/src

Appendix B PrivX Microservices

PrivX is based on microservice architecture, where different microservices communicate with each other over HTTPS using REST. End-user authentication is provided using OAuth2. OAuth2 service can integrate against user’s identity providers, or the PrivX Local User Directory can be used. Role Store integrates against Local User Directories, and identity providers such as LDAP and AD. Authorizer creates certificates attached to roles for users connecting to target hosts.

See the following sections for more information on the PrivX microservices.

Authentication Service

Authentication services implement OAuth2 to verify user credentials against identities stored in role stores. Also, the PrivX microservices authenticate to each other via authentication services.

Authorizer

Authorizers create role-based certificates for authenticating users to target hosts.

Connection Manager

Connection manager collects metadata for connections going through SSH and RDP proxies. It also forwards connection termination requests made through the UI.

Host Store

Host stores save host information, such as addresses, SSH/RDP services, and target-user-to-role mappings. Host stores also import hosts from existing directories.

Keyvault

Key vaults encrypt and store PrivX secrets, such as stored credentials for target hosts, the database-field-encryption key, and JSON-web-token signing keys.

Local User Store

Local user stores can be used in environments without existing user directories, and for easily setting up users in test environments.

Monitor Service

The Monitor Service indexes all the audit events raised by PrivX microservices. The monitor service is also responsible for processing audit-event-related searches.

Role Store

Role stores associate local and directory users to roles (by checking the rules and the requests of each role). Role stores integrate against user directories and dynamically evaluate users' roles as needed.

SSH/RDP client

The SSH and RDP clients allow PrivX users to connect to target hosts via the PrivX web-based GUI.

Workflow Engine

Workflow engines allow you to define workflows for granting/revoking role memberships, and propagate requests along their workflows (in accordance to the received approvals/denials). Workflow engines send emails to approvers about new requests.

Appendix C PrivX Analytics

The PrivX analytics feature is used to gather data about the operating system, CPU, memory, device name, geographical location, and the version of PrivX running on your installation. After first use, PrivX servers track these parameters and periodically send the data to SSH Communications Security Corporation.

Upon license activation, PrivX servers uniquely identify the node on which the installation exists. This interaction is not related to any individual user and hence completely anonymous. This data is used to understand usage patterns, and to improve the product to better serve our customers.

Analytics data is sent on every license refresh operation, which is scheduled to run automatically every 12 hours. Please note that the data is also sent if you manually refresh or update the license information, which is done by clicking Update on the Settings→License→License page.

Analytics are enabled by default upon license activation. You can opt out of sending analytics at any time by going to the Settings→License page and setting Send analytics data data to No.

Index

A

accessing target hosts, Granting Access to Target Hosts
Accounts (host configuration), Granting Access to Target Hosts
Active Directory, Adding PrivX Users
admin rights, Granting Administrator Permissions
all attributes are not listed
troubleshooting, List Users View Does Not Display All Attributes
approvals, Requesting and Approving Memberships
audit events (list), Audit Events in PrivX
authentication, Advanced Authentication for PrivX Users
troubleshooting, Problems Related to Authentication
authentication service, Authentication Service
authorizer, Terminology, Authorizer

D

debug logs
troubleshooting, Reading Debug Logs
deployment, Authentication Methods for Host Connections
SSH target host configuration, Manual Certificate-Authentication Setup
trusted clients, Script-Based Certificate-Authentication Setup
directory (in UI), Terminology
documentation conventions, Documentation Conventions

E

email-notification setup, Enabling Email Notifications

H

host store, Terminology, Host Store

I

Import host instance tags from the directory (directory setting), Script-Based Certificate-Authentication Setup
installation, Setting Up PrivX

K

kerberos authentication for PrivX users, Kerberos Authentication for PrivX Users
keyvault, Keyvault
known host, Terminology

O

OAuth2 service, Terminology
online licensing, Online Licensing

R

refresh (directory action), Refreshing Directory Data
refresh interval, Refreshing Directory Data
requests, Requesting and Approving Memberships, Managing Workflows
email notifications, Enabling Email Notifications
reset MFA pairing, Reobtaining MFA Codes
restarting PrivX
troubleshooting, Restarting PrivX
role, Terminology
role store, Terminology, Role Store
roles, Granting Permissions for PrivX Users

S

securing directory connections, Secure-Connection Setup
server setup, PrivX Server Setup
server upgrade, Upgrading PrivX
services are down
troubleshooting, Services Are Down
set up server, PrivX Server Setup
SSH extensions, Role Restrictions
SSH host keys, Trusting Target-Host Identities
SSH options, Role Restrictions
SSH Target Host Configuration
principal, Allowing Role-Based Access
public key, Enabling Role-Based Public-Key Authentication
SSH/RDP Client, SSH/RDP client
STARTTLS setup, Secure-Connection Setup
stored password, Enabling Authentication with Stored Passwords
system upgrade, Upgrading PrivX

T

target host, Terminology
target user, Terminology
terminating connections, Monitoring and Managing Connections
TOFU, Trusting Target-Host Identities
too many authentication failures
troubleshooting, Connections fail with error Too many Authentication Failures
troubleshooting, Troubleshooting
all attributes are not listed, List Users View Does Not Display All Attributes
authentication, Problems Related to Authentication
debug logs, Reading Debug Logs
restarting PrivX, Restarting PrivX
services are down, Services Are Down
too many authentication failures, Connections fail with error Too many Authentication Failures
users are not listed, Directory Users Are Not Listed
trust on first use, Trusting Target-Host Identities
two-factor authentication, Multi-Factor Authentication for PrivX Users