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 PrivX Administrator Manual > PrivX Users and Permissions > AD/LDAP Directory Configuration.

For additional information about OpenID Connect (OIDC) configuration, see PrivX Administrator Manual > PrivX Users and Permissions > OpenID-Connect Configuration.

Granting Permissions for PrivX Users

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

  • Access target hosts.

  • Approve/deny requests.

  • Manage connections.

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

  • The user is included in the role via rules (mapped users). For more information about configuring rules for roles, see PrivX Administrator Manual > PrivX Users and Permissions > Granting Permissions for PrivX Users > Managing Roles.

  • The user has been approved as a member of the role (approved users). For more information about approval mechanisms, see PrivX Administrator Manual > PrivX Users and Permissions > Granting Permissions for PrivX Users > Requesting and Approving Memberships.

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.

For more information about granting access to target hosts, see PrivX Administrator Manual > PrivX Users and Permissions > Granting Permissions for PrivX Users > Granting Access to Target Hosts.

Note

Role changes take effect within 1 - 5 minutes.

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 PrivX Administrator Manual > PrivX Users and Permissions > 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→New Connection page.

    For more information about connecting to target hosts see PrivX Administrator Manual > Establishing and Managing Connections.

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.

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 PrivX Administrator Manual > PrivX Users and Permissions > Granting Permissions for PrivX Users > 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"

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.

    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 PrivX Administrator Manual > PrivX Users and Permissions > 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 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. 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 PrivX Administrator Manual > PrivX Users and Permissions > 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 PrivX Administrator Manual > PrivX Users and Permissions > 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.

    mfa_00.png

    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.