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, Amazon Linux.
• ​​Required Python version​​: 2.7.9+ or 3.6.5+
• ​​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 described in Manual Certificate-Authentication Setup.

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 Setting up 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. To create a host-deployment script, navigate to the ​Administration→Deployment→Deploy and configure SSH target hosts​ page, select ​Configure using a deployment script​​.

   If you need to granularly delegate host and connection-management permissions, also select the ​Access group​ the host is to be deployed to. For more information about access groups, see Host-Specific Management Permissions​​.

   Click ​Add Script​​. Download the ​deploy.py​​ script when prompted to.

2. Execute the deployment script on the target host as root. You will at least need to provide the host type, and the accounts (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.
   ​​--azure​​: The host runs on Microsoft Azure.
   ​​--google-cloud​​: The host runs on Google Cloud.
   ​​--openstack​​: The host runs on OpenStack.
   ​​--standalone​​: For non-cloud hosts.

   For allowing PrivX users access to target accounts, 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). Corresponds to a ​Directory​​ account.

   ​​--principals​​: Manually define target accounts and the roles that may access them. Corresponds to an ​Explicit​​ account.
   NOTE: If you run deploy script again with different principal, the new run does not remove the principal file in /etc/ssh/auth_principals/ created by the previous execution.

   ​​--user-defined-account-roles​​: Allow members of certain roles to input the target account when connecting (similarly to manual connections). Corresponds to a ​User-Defined​​ account. Note that this option does not enable certificate-based authentication for the specified roles.

   --delegated-principals: Delegate role configuration to PrivX for the given principal. Allows creating new roles on PrivX side, which can access this principal without a need to reconfigure the host.

   --delegated-personal-account-roles: Delegate role configuration to PrivX for all target principals. Allows creating new roles on PrivX side, which can access this host without a need to reconfigure the host.

   --configure-only: Configures the target host, but does not register the host to PrivX. Can be used to modify existing configuration, if you don't want to override the settings in PrivX.
   NOTE: even if target host has been configured to allow access, PrivX needs to still know about it either via host tags or via manual/scripted config.
   When deploy script is being run, it will overwrite the PrivX host configuration with the actual config on the target host. This flag is useful, If you have done manual changes to host on PrivX side and do not wish to overwrite those settings.

   --show-config: Show which PrivX roles and principals SSHD allows to connect to the host. Verifies the role configs on the target host. This shows only the host SSHD configuration and does not verify PrivX configuration for the host.

   For more information about account types, see Account Types.

   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:

   Bash

   --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:

   Bash

   --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:

   Bash

   --principals alice=privx-admin
   

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

   Bash

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

   ​​--user-defined-account-roles​​ allow members of selected roles to freely input the target-account name. However, access defined with this option defaults to password authentication unless paired with another account option.

   In the following example, members of ​Example Role 01​ and ​Example Role 02​ may access any target account with password authentication, but if a member of ​Example Role 01​ inputs ​alice​​ they are authenticated using certificates:

   Bash

   --user-defined-account-roles "Example Role 01,Example Role 02"
   --principals alice="Example Role 01"
   

   Full syntax example of running the host-deployment script:

   Bash

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

   Finally, you may use --show-config to verify the results:

   Bash

   [root@localhost ~]# python deploy.py --show-config
   deploy script version 17.0-0
   Access group ID 0bbbc3ef-4771-4292-78af-684151b64428
   usepam yes
   permitrootlogin yes
   PrivX CA certificate path OK
   AuthorizedPrincipalsCommand OK
   authorizedprincipalscommanduser nobody
   
   Accepted CA certificates:
   ssh-rsa
   AAAAB3NzaC1yc2EAAAADAQABAAACAQClupyy3sMlpHP4hQ3qGLxi7TUFmr0EeL7jfcVr1PvaYgP4UCZpYyQ2
   Je+MIHNFdnqSBxsuCip8Tr7h033qJmxabjdFVw2B0qnGRsYwAm3PKYbgxwZnolGPbszQfScPuAtdTvo3kOWd
   IbSL5JYS034bHZ5L5mWCVpyOGIZqP9+Z+RdVM/gyzdCRNX7xU3xWlD5Tw/eVl26oRrrvOHdKSNyPB2QdjQCZ
   fBcgxPLXMF9tQxqIbwLkjHH70BRdySBdFvWaGCKLL7qI6FQOAcA0HvQF+L1n0oeH1xi7H1up7oPGJ9xe6Zuf
   rr1wF5jgvkgS2ky5afUI1d0EYjR7Lq1FQmeqfPD9EzvDjjkjpHxqeGUvtjGENJLuFlG8UFIN5S1u9/jWjAse
   fLUJ+NI4lhmPnqPkj68MMthzGGOdoQFKTrYYms/o+wxyuf5rTEU9ey4nDHzdObKPT9WlXCZhv0Vy5tty2Ql+
   0B06aktqojGY9sE1DT3x9BVUU+2GQdPmCIxvUS4yCJbJle0FtE5QXfHwFoB3kpyfZkglBuzmZi8kEPnqk6FB
   TSJUWfZwbuflMm3K0DeTBfXy+mbWXc/6YRS+kCZjhVduZCbt5j+Jh8ZJZmVIAOV02aC5jGOd1zQe7+W25+Cf
   THN6gtbOOJUkIlmkSTVbSpQAyrird8rE9kdoeaPnbw== 
   
   
   Certificate login with principal 'centos' allowed for these roles:
       delegated-roles # All PrivX roles                                  
   
   Certificate login with principal 'root' allowed for these roles:
       44985f40-5c68-433d-9604-9b493589feb1 # privx-admin                 OK - verified by privx.local.com
       e0844e38-460b-5762-4190-b7db71682533 # delegate_test               OK - verified by privx.local.com
       12312312-1233-1233-1233-123123123123 # mystery role long tex..     Failed to verify - privx.local.com
   
   Certificate login with principal 'test' allowed for these roles:
       44985f40-5c68-433d-9604-9b493589feb1 # privx-admin                 OK - verified by privx.local.com
       12312312-1234-1234-1234-123123123123 # delegate_test               Role id does not match the name - privx.local.com
   
   Certificate login with any principal except 'centos,root,test' when using Directory account type, allowed for these roles:
       delegated-roles # All PrivX roles
   

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

   Bash

   $ /path/to/deploy.py --help
   

   For more examples about deployment options, see Configuring SSH target host to accept PrivX connections.
   

📘

Note

If connections to the target host are relayed via a PrivX Extender, use the ​--api-hostname​​ option to specify the Extender's address and port, similarly to the following:

Bash

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

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

Bash

# 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's configuration file, where it is specified by the ​host_deployment_listen_address​​ variable.

3. Certificates issued by PrivX are very time-sensitive. Even a clock skew of just 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→Available Hosts​​ 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 [email protected]: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.

📘

Note

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.

📘

Note

When specifying tags for cloud hosts, do not include double-quotation marks in the value.

2. Configure PrivX to import host tags. To do this, navigate to ​Administration→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. Corresponds to an ​Explicit​​ account.

  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. Corresponds to an ​Explicit​​ account.
  ​
  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. Corresponds to a ​Directory​​ account.
  ​
  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. Corresponds to a ​Directory​​ account.

  Syntax is similar to the ​privx-ssh-personal-account-roles tag.

​​privx-ssh-user-defined-account-roles=<roles>​​

• Allow members of certain role(s) to freely specify the target account when connecting with SSH. Corresponds to a ​User-Defined​​ account. Note that access defined with this option does not grant certificate-based authentication to the specified roles.
  ​
  Syntax is similar to the ​privx-ssh-personal-account-roles​​ tag.

privx-rdp-user-defined-account-roles=<roles>​​

• Allow members of certain role(s) to freely specify the target account when connecting with RDP. Corresponds to a ​User-Defined​​ account. Note that access defined with this option does not grant certificate-based authentication to the specified roles.
  ​
  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=<extendername>​​

• If connections to the host are relayed through a PrivX Extender, use this tag to specify the name of the Extender.
  ​
  Example:

  privx-extender=exampleExtender
  

  For more information about PrivX Extender, see ​[ XXX →Proxying Connections to Hosts]​

​​privx-carrier=<carriername>​​

• Specify the name of the carrier that should be used as the default carrier for this host's web connections.
  ​
  Example:

  privx-carrier=exampleCarrier
  

​​privx-enable-auditing=<yes|no>​​

• Toggle auditing for the host. Defaults to ​no.​​
  ​
  Example:

  privx-enable-auditing=yes
  

privx-use-private-ips-only=<yes|no>​​

• Enabling this prevents using scanned public IP addresses as connection addresses for cloud hosts. This can be used to enforce connecting to hosts via private IP addresses only.
  ​
  Example:

  privx-use-private-ips-only=no
  

​​privx-trust-on-first-use=<yes|no>​​

• Enable/disable ​Trust on First Use​​, allowing regular users to connect to targets without known host keys. If disabled, superuser needs to accept host keys for unknown hosts on the first connection.
  ​
  Example:

  privx-trust-on-first-use=yes
  

  For more information about ​Trust on First Use​​, see ​[ XXX →Trusting Target-Host Identities]​​.

privx-access-group=<access_group_name>

• Deploy the host to the named access group. If unspecified, the host is deployed to the ​Default​​ access group.
  ​
  Example:

  privx-access-group=examplegroup01
  

  For more information about access groups, see ​[ XXX →Host-Specific Management Permissions]​​.

`privx-access-group-id=<access_group_id>

• Deploy the host to the access group with the specified ID. If unspecified, the host is deployed to the ​Default​​ access group.
  ​
  Example:

  privx-access-group-id=0bbbc3ef-4771-4292-78af-684151b64428
  

📘

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: