HomeDocumentationAPI Reference
Log In
These docs are for v17. Click to read the latest docs for v33.

Setting up Hosts

This section describes manually setting up hosts and connection targets on them. For information about importing hosts automatically using cloud host tags or deploy script, see Script-Based Certificate-Authentication Setup.

You can add connection targets to PrivX by adding hosts. To do this, go to ​Administration→Hosts​ and click ​Add Host​​. PrivX host entries are used for specifying, among other things:

  • ​​Basic host information​​ - Such as the host name and address(es).

  • ​​Services​​ - Available methods for accessing the host: SSH, RDP, and Web.

  • ​​Accounts​ - Who can access the host, and as what identity. For example, allow members of ​Example Role 01​ to log in as ​exampleuser​​ on the host.

Connection targets offer the following benefits:

  • To see and connect to known targets, PrivX users can go to the ​Connections​ page and select ​Search from known hosts​​. PrivX users will only see those connection targets that they are authorized to.

  • Connection targets support additional authentication methods (instead of just user-provided password). For more information about the configurations required for additional authentication methods, see Supported Authentication Methods.

  • Allow auditing connections. If auditing is enabled for the host, administrators are able to view recordings of completed connections.

  • PrivX can periodically check the status of known targets and indicate when targets are unreachable. Settings related to status checks are under the ​[health-check-options]​ section in the Hoststore configuration ​/opt/privx/etc/hoststore.toml​​.

📘

Note

All known targets must have unique machine IDs: If you need to add cloned machines to PrivX, ensure the uniqueness of the machine's ID and regenerate it if necessary.

Proxying Connections

For target hosts that are inaccessible from PrivX servers (such as hosts in protected networks), you may use PrivX Extenders for relaying connections.

To proxy connections to the host via Extenders, go to the Settings add either of the following to the host ​Address​​:

  • An ​Extender name​​: Connections to the host are proxied via the named Extender.
  • A ​Routing prefix​​: Connections to the host are proxied via any Extender with the specified ​Routing prefix​​.

Example Address syntax in IPv4 and IPv6 format:

exampleextender/192.0.2.100
exampleextender/2001:DB8::64

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

For more information about PrivX-Extender requirements and setup, see PrivX components and Setting up PrivX components respectively.

SSH Targets

📘

Note

You can use the PrivX host-deployment script to automatically add SSH targets (while also enabling certificate-based authentication). For more information about using the host-deployment script, see Script-Based Certificate-Authentication Setup.

To allow connections to SSH hosts, add a host entry with the following considerations in mind:

  • Add a ​Service​ with the type ​SSH​​, specifying the address and the port of the SSH server on the host.

    When the ​Trust on first use​​ option is disabled, SSH host keys must also be added here. In this case regular PrivX users can connect only if the host key matches one of the provided values. PrivX administrators can establish connections even if the host key is missing or incorrect.

  • Add ​Accounts​​ specifying which PrivX roles may access the host, and which target accounts they are given access as.

    The access options of the accounts can be limited under ​Allowed Service Options​​

    By default all​​ Allowed Service Options​​ are enabled. The default values can be changed in Administration→Settings, under the Hoststore category.

RDP Targets

To allow connections to RDP hosts, add a host entry with the following considerations in mind:

  • Add a ​Service​ with the type ​RDP​​, specifying the address and the port of the RDP server on the host.

  • Add ​Accounts​​ specifying which PrivX roles may access the host, and which target accounts they are given access as.

    The access options of the accounts may be limited under ​Allowed Service Options.​​

    By default all​​ Allowed Service Options​​ are enabled. The default values can be edited in the Hoststore configuration file, located at /opt/privx/etc/hoststore.toml on PrivX servers.

    You may also provide ​Windows application restrictions​​, for limiting users to certain applications. Note that the target Windows host must be configured to allow the listed applications to be used over RDP.

Web Targets

You can use PrivX to connect to websites. To allow connections to websites, add a host entry with the following considerations in mind:

  • Add a ​Service​ with the type ​Web​​, specifying the address of the website.

    📘

    Note

    Since connections to web targets are provided via a PrivX Web Proxy, you need to provide the address in proxy format. For example (replace ​exampleproxy​ with your Web access gateway name, and ​https://www.example.com/​​ with the address of the website):

    ​​​exampleproxy​​/​https://www.example.com/​​​

    Replace the example values as follows:

    • exampleproxy​​​: The ​Name​ or the ​Routing prefix​​ of the web-access gateway(s) used for proxying the connection.
    • ​​​https://www.example.com/​​​: The address of the website.

    If you want PrivX to automatically fill in login credentials for the website, also provide the following ​Additional settings​​:

    • ​​Login-request address​​: The verified address of the login request. For example, in form logins this may be the URL of the webpage plus the URL specified by the ​action​​ attribute of the form. Recommended for improved security.

    • ​​Password property​​: The verified id​​ of the password field in the login form. Recommended for improved security.

    • ​​Login-page address​​: The login-page address. Only needed if the login page is not under the ​Address​ of this web service. For example, while you could have an AWS service with the ​Address​​:

      ​​exampleproxy/https://example.signin.aws.amazon.com/console​​

      That website may redirect you to a different address for login:

      ​​https://us-east-1.signin.aws.amazon.com​​

    • ​​Authentication type​​: Set to ​Automatic​ for most websites, such as websites using forms for authentication. Set to ​Basic​ for websites using the ​Basic HTTP Authentication Scheme​​ (defined in RFC 7617).

    • ​​Username-field name​​: The ​name​​ of the username field in the login form. Only required if PrivX is unable to automatically detect this field.

    • ​​Password-field name​​: The ​name​​ of the password field in the login form. Only required if PrivX is unable to automatically detect this field.

  • Add ​Accounts​ specifying which PrivX roles may access the website. If you want PrivX to automatically fill in login credentials for the website, also provide ​Usernames​ and ​Passwords​​ in the account mappings.

    The access options of the accounts can be limited under the ​Allowed Service Options​​

    By default all​​ Allowed Service Options​​ are enabled. The default values can be edited in the Hoststore configuration file, located at /opt/privx/etc/hoststore.toml on PrivX servers.

📘

Note

When set up to do so, PrivX automatically fills up login credentials, but will not actually log into the web service. Users must manually click any ​Login​​ buttons to log in.

For HTTPS targets, by default PrivX only allows connections using TLSv1.2 and later.

To prevent users from accessing websites other than the intended web targets, configure additional access rules, as described in Access Restrictions for Web Connections.

Account Types

The following account types are available for granting access to target hosts:

  • ​​Explicit​​ - Allow access to a certain user. Choose this option when defining a web target.
    Choose this option when defining a web target.

  • ​​Directory​ - Allow access to the users' ​Windows username​ or ​Linux username​​. For PrivX directory users these default to their ​userPrincipalName​ and ​sAMAccountName​​ respectively.

  • ​​User-defined​ - Allow users to input the username when connecting. Similar to ​manual connections​​, except restricted to the target host.

📘

Note

If the provided user name matches other Account entries, then the most-preferred authentication method among matching Accounts is used for login. Otherwise the user is prompted for password.

For example, if a host has the following Accounts:

  • Explicit: ​Example role 01​ to ​alice​​ with certificate authentication.

  • User-defined: any role to any account with user-provided passphrase.

Then if a member of Example role 01 connects with the user-defined rule and provides ​alice​​ as the user name, the explicit rule is considered matching, and certificate authentication is used since it is preferred over user-provided password.

For more information about the preference order of authentication methods, see Supported Authentication Methods.