Table of Contents

 Adding PrivX Users
 Granting Permissions for PrivX Users
 Managing Roles
 Requesting and Approving Memberships
 Granting Access to Target Hosts
 Granting Administrator Permissions
 Host-Specific Management Permissions
 Managing Workflows
 Enabling Email Notifications
 User Configuration
 Automatic Logout
 Require Password Change
 Limiting Login Rate
 AD/LDAP Directory Configuration
 Secure-Connection Setup
 Adjusting User Matching
 Refreshing Directory Data
 Advanced Authentication for PrivX Users
 Kerberos Authentication for PrivX Users
 Multi-Factor Authentication for PrivX Users
 Client-Certificate Authentication for PrivX Users
 OpenID-Connect Authentication for PrivX Users

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.

  • User-related configurations, such as directory setup and methods for authenticating to PrivX.

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 Authentication for PrivX Users”.

Granting Permissions for PrivX Users

PrivX users gain permissions from roles. Roles may allow users to:

  • Access target hosts.

  • Approve/deny requests.

  • Manage connections.

  • View/Manage secrets.

  • Perform PrivX administration.

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

All users automatically start as members of the privx-user role.

Note

For active PrivX users, permission changes take effect when their access token is refreshed. The interval is specified in /opt/privx/etc/oauth-shared-config.toml, by the setting access_token_validity.

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

  • Rules: LDAP filters for specifying the members of the role.

  • Permissions: Allow specific management and viewing options.

  • SSH Options: Allow SSH options.

  • Context Restrictions: Restrict role validity by time and client address.

For more information about granting access to target hosts, see the section called “Granting Access to Target Hosts”.

Note

Role changes take effect within 1 - 5 minutes.

Settings pages in the GUI require both view- and manage- permissions. For example, a PrivX user needs roles-view and roles-manage to access Settings→Roles.

Before restricting the Allowed remote addresses, ensure that meaningful user addresses are included in the X-Forwarded-For header. If the header includes multiple addresses, select one of them by configuring strip_how_many_x_forwarded_for_client_ips in /opt/privx/etc/shared-config.toml

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.

Users granted membership by the rules of the role can only be removed by adjusting the rules.

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

OpenID Connect users can not request memberships for roles.

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→Available Hosts page.

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

Granting Administrator Permissions

You can grant PrivX administrator permissions 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, sessions, and workflows.

  • Connect to any target host.

Host-Specific Management Permissions

You can use access groups to provide roles with management permissions over certain hosts. This can be useful when you want to delegate management of certain hosts to specific roles.

The high-level steps for delegating host management involve:

  1. Create an access group.

  2. Put roles into the access group, and set management permissions.

  3. Deploy hosts into the access group.

To create an access group:

  • On the Settings→Access groups page of the PrivX GUI, click Add Access Group. Provide the required information and click Save.

To put roles into access groups, and to set management permissions within the access group:

  1. On the Settings→Roles page, Edit a role to display its settings.

  2. Expand Permissions, then set the following:

    • Set the Access group for this role.

    • Select permissions this role has in the access group. Note that only host-management (hosts-*) and connection-management permissions (connections-* ) are access-group-specific.

Deploy hosts into the access group:

Note

To change the access group of an already-deployed host, run the host-deployment script with the correct access group on the 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

User Configuration

This section describes the configuration topics related to PrivX users.

Automatic Logout

Settings for automatically logging out PrivX users are in /opt/privx/etc/oauth-shared-config.toml. You can set PrivX to automatically log out users for one or more of the following reasons:

  • Inactivity - Set with refresh_token_valid.

  • Time since login (optional) - Set with session_valid. If this is not set, refresh_token_valid effectively specifies the maximum session validity.

For example, to automatically log out PrivX users after 30 minutes of inactivity, or after 8 hours from initial login:

refresh_token_valid="30m"
session_valid="8h"

To automatically log out PrivX users after a certain duration regardless of activity, uncomment session_valid and set the duration in refresh_token_valid:

refresh_token_valid="30m"
# session_valid="8h"

Require Password Change

You can require a PrivX local user to change their password on next login. This may be useful in scenarios where PrivX administrators hand out PrivX accounts to end users.

To require a target user to change their password:

  1. On the Settings→Users page, Edit the target user to display their settings.

  2. Under Additional options, select Require password change.

    Click Save to apply your changes. Next time the target user logs in they will be prompted to change their password, before being allowed to do anything else.

Limiting Login Rate

After a user and/or IP address repeatedly fails to log into PrivX, you can temporarily prevent them from making further login attempts to PrivX. This can help secure your PrivX against brute-force-access attempts.

To set limits for failed logins, perform the following on each PrivX server:

  1. Modify the settings under the [loginratelimit] section in the configuration file:

    /opt/privx/etc/auth-default-config.toml

  2. Restart the PrivX services to apply:

    # systemctl restart privx

AD/LDAP Directory Configuration

This section describes configuration topics for AD and LDAP directories. For instructions about setting up other user-directory types, see the Advanced Deployment topics at help.ssh.com

Users from 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.

    Note

    By default, PrivX allows directory users to log in with userPrincipalName (typically given in username@domain format) as username.

    You may set User DN pattern to use another field as the user name. For example, to allow directory users to log in using their uid as username, change the setting to:

    (uid=%s)

    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.

  • Obtain the CA chain of your directory server.

To enable secure connections to user directories:

  1. Ensure the directory-server certificate specifies the server DNS and/or IP addresses in the SubjectAltName field. You may do this with a test connection like the following (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

    Verify that the output contains the DNS and/or IP address(es) of the server, similar to the following:

    X509v3 Subject Alternative Name:
    DNS:directory.example.com, IP Address:192.0.2.10

  2. On the Settings→Directories page, Edit the directory for which you want to set up secure connections.

    Expand Advanced directory settings, then under Server authentication settings configure the following:

    • Add the CA chain of your directory server to Trust Anchors.

    • Deselect Skip server certificate validation.

    Click Save to apply your changes. Subsequent connections to the directory server are TLS-secured.

    After the changes you may verify the directory status back on the Settings→Directories page.

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)))"

To allow rules in PrivX roles to match nested groups, you must enable enable_nested_groups in the Role Store configuration file /opt/privx/etc/rolestore.toml

Restart PrivX services to apply any 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.

Advanced Authentication for PrivX Users

This section describes additional ways for logging into PrivX, and methods for further securing PrivX login.

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 authenticator app (such as Authy or Google Authenticator). After this, your 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. Under Multi-factor authentication, click and select Reset MFA Pairing. 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.

Client-Certificate Authentication for PrivX Users

Users imported from AD and LDAP directories can log in to PrivX using SSL certificates. Such certificates may be for example from users' smart cards, or from client certificates imported to browsers.

Enabling Certificate Authentication

To enable certificate authentication for users from a certain directory:

  1. In the PrivX GUI on the Settings→Directories page, Edit a AD or LDAP directory to display its settings.

  2. Expand Advanced directory settings. Then under Multi-Factor authentication settings, enable Client certificate authentication. You must also provide Trust anchors: the certificates of those CAs who issued the users' certificates.

    Click Save to apply the new settings. Certificate authentication is enabled for users belonging to the directory.

Logging In with Certificate Authentication

After certificate authentication is enabled, users can log into PrivX as follows:

  1. Ensure that your client certificate is available. For example, that your smart card is inserted and read properly, or your certificate is imported to the browser.

  2. Access the PrivX-login page. If prompted by your browser, provide your client certificate.

    For successful login, the Subject Alternative Name in your client certificate must specify your User Principal Name.

    After providing a valid client certificate you will be logged into PrivX.

OpenID-Connect Authentication for PrivX Users

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 via the PrivX GUI, and furthermore to target hosts (as permitted by their roles). 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. Provide the following redirect URI to the OIDC provider:

    https://privx.example.com/auth/api/v1/oidc-cb

  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.

    Note

    To allow OIDC users to log into personal accounts, specify the claim(s) containing the users' personal-account names. Then in Source=Target attribute pairs, map these claims to unix_account or windows_account for SSH and RDP connections respectively.

    For example, if the users' Windows logon names are in their email claim, specify the following:

    email=windows_account

    As another example, if the users' preferred_username claim matches both their Unix- and Windows-account names, specify the following:

    preferred_username=unix_account,windows_account

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

  5. Optional: You may test OIDC logins from the PrivX login page. You can log in using either of the following methods:

    • Via the PrivX login page, click the OIDC authentication method listed below the Login button.

    • Go directly to the OIDC login page. To display the link to the OIDC login page, go to Settings→Directories and click your OIDC directory. The link is in The Direct Login URL, under the OpenID connect settings section.

    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”.