Managing administrator access via LDAP

You can configure the Pexip Infinity platform to authenticate and authorize administrator login accounts via a centrally managed LDAP-accessible server. Integration with LDAP provides increased security, better auditing of changes and more control and flexibility as you can assign different privileges to specific groups of users.

By default, Pexip Infinity only has a single local administrator account. Integration with an LDAP directory service allows multiple users to administer the platform. These users log in with their directory credentials, which is generally a Windows AD domain. When using LDAP:

  • Instead of authenticating the supplied username and password credentials against its own internal database, Pexip Infinity contacts the LDAP server to authenticate the administrator's user account.
  • It uses the account's LDAP group attributes in combination with role mappings defined in Pexip Infinity to determine which Pexip Infinity features the administrator is authorized to access.

You can also configure the Pexip Infinity platform for client certificate authentication. This means that instead of logging in to the Pexip Infinity Administrator interface via the standard login page, or providing an authorization header when accessing the management API, administrators present (via their browser) a client certificate containing their user identification details. The validation of the presented certificate acts as the authentication phase and the username attributes in the certificate are used to determine which features the administrator is authorized to access.

The configuration described here applies to all administrator accounts connecting to the Pexip Infinity Administrator interface or the Pexip Infinity API. It does not apply to SSH connections. When using LDAP authentication, Pexip Infinity is configured by default to work with a Windows Active Directory LDAP server, but it can also be configured to work with other LDAP-accessible databases.

You can also allow administrator accounts connecting to the Pexip Infinity API to use OAuth instead of, or in addition to, LDAP. For more information, see Managing API access via OAuth2.

All usernames and passwords are case sensitive.

The following sections describe:

Configuration summary for LDAP authentication

To enable authentication and authorization via LDAP, you need to configure both the LDAP database (if it is not already configured with user details) and the Pexip Infinity platform.

The LDAP database must be configured with:

  • administrators' user credentials
  • groups that define the capabilities of the users.

The Pexip Infinity platform must be configured with:

  • an authentication source setting that uses an LDAP database
  • connection details for the LDAP server; if the server address is an FQDN, ensure that it is resolvable over the DNS server configured for the Management Node
  • administrator roles to control the actions that administrators can perform
  • LDAP role mappings that map LDAP groups to administrator roles.

If a secure TLS connection between the LDAP server and the Management Node is required, ensure that:

  • The LDAP server address is specified as an FQDN (so that it matches the name on the certificate presented by the LDAP server, which is typically created for the host name rather than the IP address).
  • The Management Node trusts the certificate presented by the LDAP server; typically this means that the LDAP server certificate has to be uploaded to the Management Node as a trusted CA certificate (as the LDAP server's certificate is often generated by an internal authority which would not be included in Pexip's inbuilt list of trusted CA certificates).

    Note that the Management Node's server certificate does not have to be trusted by the LDAP server (unless the LDAP server has been explicitly configured to demand a client certificate).

The Pexip Infinity platform configuration steps for specifying an LDAP authentication source, and configuring administrator and LDAP role mappings are described in more detail in the following sections, and there is an example that shows how to configure permissions for an AD group. For information about installing server and trusted CA certificates, see Managing TLS and trusted CA certificates.

Configuring how administrators are authenticated

To configure how administrators are authenticated when they log in to the Pexip Infinity Administrator interface or API, go to Users & Devices > Administrator authentication. The options are:

Option Description
Authentication source

The database to query for administrator authentication and authorization.

Local database: uses the Pexip Infinity local on-box database. Administrators can only log in via the default account (typically admin) and will have full administrator privileges.

LDAP database: administrators log in using an account configured on the LDAP database and obtain privileges according to the groups and roles associated with that account. Note that if this option is selected and the LDAP server is inaccessible for any reason, administrators will not be able to log in to the Pexip Infinity web-based Administrator interface or API.

LDAP database and local database: administrators can log in using either the default local admin account or via an account configured on the LDAP database.

When using an LDAP database, you must configure the items in the LDAP configuration section. By default, Pexip Infinity checks the entered username against the Active Directory sAMAccountName attribute (as configured in the LDAP user search filter advanced setting below).

Default: Local database.

Require client certificate

Controls whether administrators are authenticated via a client certificate. By default, administrators log in to the Pexip Infinity Administrator interface via the standard login page, and provide an authorization header when accessing the management API. Instead, users can be required to present (via their browser) a client certificate containing their user identification details. The options are:

Not required: Client certificates are not required. Administrators log in via the standard login page and provide a password which is authenticated against the selected Authentication source. Management API requests require an authorization header.

Required (user identity in subject CN): administrators identify themselves via the identity contained in the subject CN (common name) of the client certificate presented by their browser.

Required (user identity in subjectAltName userPrincipalName): administrators identify themselves via the identity contained in the subjectAltName userPrincipalName attribute of the client certificate presented by their browser.

Default: Not required.

When a client certificate is required, the standard login page is no longer presented. Administrators will not be able to access the Pexip Infinity Administrator interface or the management API if their browser does not present a valid certificate that contains a user identity which exists in the selected Authentication source.

API Oauth2 settings

The settings in this section apply to API access only. They do not affect LDAP access. For more information, see Managing API access via OAuth2.

LDAP configuration
LDAP server address

The domain name (for DNS SRV lookup), FQDN (for DNS A/AAAA lookup) or IP address of the LDAP server. If using a domain or an FQDN, ensure that it is resolvable over DNS.

You must also ensure that Pexip Infinity has trusted CA certificates for the authority that signed the LDAP server’s certificate (if a TLS connection is required).

We strongly recommend that you do not use an IP address. If an IP address is used, and a TLS connection is required, this will only work if the IP address is specified as the common name in the LDAP server's certificate.

See Troubleshooting LDAP server connections for more information about how the system establishes a connection to the LDAP server and how to troubleshoot connection issues.

Allow insecure transport

By default the system will attempt to establish a secure TLS connection with the LDAP server. Select this option if you want to allow the system to fall back to a TCP connection (using SASL DIGEST-MD5). You cannot specify the LDAP server by IP address if this option is selected.

LDAP bind username and password

The username and password of the bind account on the LDAP server. This should be a domain user service account, not the Administrator account.

LDAP base DN

The base DN (distinguished name) of the LDAP forest to query (e.g. dc=example,dc=com).

Advanced LDAP configuration

By default the advanced LDAP configuration settings are preconfigured for Windows Active Directory, and may also be appropriate for other LDAP databases such as OpenLDAP.

Search global catalog

Select this option to expand the scope of the search to the entire Active Directory Global Catalog instead of traditional LDAP. Note that this uses ports 3268 (TCP) and 3269 (TLS).

LDAP user search DN The DN relative to the LDAP base DN to query for user records (e.g. ou=people). If blank, the LDAP base DN is used. In deployments with large user bases, you may want to configure this to optimize the LDAP user queries.
LDAP user filter

The LDAP filter used to match user records in the directory.

Default: (&(objectclass=person)(!(objectclass=computer)))

LDAP user search filter

The LDAP filter used to find user records when given the user name. The filter must contain {username} to indicate locations into which the username is substituted. This filter is applied in conjunction with the LDAP user filter and must contain at least one substitution.

If client certificate-based authentication is used, this filter usually must include 'userPrincipalName={username})' either in addition to, or instead of, the default value; for example '(|(uid={username})(sAMAccountName={username})(userPrincipalName={username}))'.

To log in using an email address, you can use '(|(uid={username})(sAMAccountName={username})(mail={username}))' — note that this requires the use of LDAPS.

Default: (|(uid={username})(sAMAccountName={username}))

LDAP group attributes

A comma-separated list of attributes in the LDAP user record to examine for group membership information. The attribute value must contain the DN of each group the user is a member of. If no attributes are specified, or none of the specified attributes are present in the LDAP user record, an LDAP group search (using the remaining advanced configuration options below) is performed instead.

Default: memberOf

LDAP group search DN The DN relative to the LDAP base DN to query for group records (e.g. ou=groups) when no group attributes are present in the LDAP user record. If blank, the LDAP base DN is used. In deployments with large user bases, you may want to configure this to optimize the LDAP group queries.
LDAP group filter

The LDAP filter used to match group records in the directory.

Default: (|(objectclass=group)(objectclass=groupOfNames)(objectclass=groupOfUniqueNames)(objectclass=posixGroup))

LDAP group membership filter

The LDAP filter used to search for group membership of a user. The filter may contain {userdn} to indicate locations into which the user DN is substituted. The filter may contain {useruid} to indicate locations into which the user UID is substituted. This filter is applied in conjunction with the LDAP group filter and must contain at least one substitution.

Default: (|(member={userdn})(uniquemember={userdn})(memberuid={useruid}))

If authentication against an LDAP database is configured, you can save the settings only if Pexip Infinity can successfully contact the specified LDAP server.

Note that all LDAP distinguished names must be entered as per the LDAP standard (RFC 4514). LDAP configuration is case insensitive.

Supporting nested security groups in Windows Active Directory

The default LDAP configuration does not support nested security groups in Windows Active Directory. For example, if group A is allowed to log in via LDAP, and if group B is a member of group A, then any user who is only a member of group B will not be allowed to log in.

To allow members of a nested Active Directory security group to log in over LDAP:

  1. Go to Users & Devices > User authentication and expand the Advanced LDAP configuration section.
  2. Ensure that LDAP group attributes is empty (i.e. remove the default "memberOf" content).
  3. Change LDAP group membership filter to "(member:1.2.840.113556.1.4.1941:={userdn})"
  4. Select Save.

(This configuration uses the LDAP_MATCHING_RULE_IN_CHAIN OID. More information on this can be found at https://msdn.microsoft.com/en-us/library/aa746475%28VS.85%29.aspx.)

Configuring administrator roles

Administrator roles control the actions that administrators can perform in the web-based Administrator interface or management API after they have been authenticated. For example, you can configure a role that allows an administrator to only view (and not modify) specific items of configuration data or status information via the Administrator interface.

When an administrator has restricted permissions, all navigation menu options are still displayed, but they are given an Access denied message if they try to select a menu option that they are not authorized to use. For read-only restrictions, the relevant Add <item> options are not displayed.

Two roles are present by default:

  • Read-only: allows read-only access to all configuration settings and status information when accessing the system via the web-based Administrator interface or the API. An administrator with this role can also take diagnostic snapshots and backups, view logs, and make packet captures. Note that this role has full read access to sensitive information — you can create more restricted roles if necessary.
  • Read-write: allows full administrative access when accessing the system via the web-based Administrator interface or the API.

To add, edit or delete administrator roles, go to Users & Devices > Administrator roles. When configuring roles, the options are:

Option Description
Name A descriptive name of the role, e.g. "auditor" or "management system".
Permissions

Select from the list of Available permissions the set of permitted actions for the role and then use the right arrow to move the selected actions into the Chosen permissions list. For more information on each permission, see Descriptions of all available administrator permissions.

All roles must include the Is an administrator permission for access to the system. In addition, the May use web interface and May use API permissions must be included for access via the web-based Administrator interface and API respectively. You must then also add all of the other permissions, such as May modify system configuration and so on, that you want to apply to the role — if a role has, for example, only the Is an administrator and May use web interface permissions, an administrator with that role will be able to log in via the web-based Administrator interface but will not be able to perform any actions.

When creating an OAuth2 client for admin API access, the permissions Is an administrator and May use API are assumed and do not need to be set explicitly.

The permissions that are applied to the default Read-only role are shown below:

Configuring LDAP role mappings

LDAP role mappings are used to map the LDAP groups associated with LDAP user records to the Pexip Infinity administrator roles. You must configure a separate LDAP role mapping for each LDAP group for which you want to map one or more Pexip Infinity administrator roles.

To add, edit or delete LDAP role mappings, go to Users & Devices > LDAP role mappings. When configuring LDAP role mappings, the options are:

Option Description
Name A descriptive name of the role mapping, e.g. "domain administrator with full privileges".
LDAP group DN

Select the LDAP group against which you want to map one or more administrator roles.

The list of LDAP groups is only populated when there is an active connection to an LDAP server (Users & Devices > Administrator authentication).

Note that the LDAP groups used for role mappings cannot be the pre-defined AD groups such as Domain Users etc. but need to be explicitly configured custom groups.

Roles

Select from the list of Available roles the administrator roles to associate with the LDAP group and then use the right arrow to move the selected roles into the Chosen Roles list.

All of the underlying permissions within a role are "positive" permissions, i.e. they allow the administrator to do something. If more than one role is selected, all of the permissions associated with each role are combined and granted to the relevant administrator.

Note that you can select which opens a new window from where you can configure a new administrator role. When you save the role it is automatically added to the set of Chosen Roles.

Examples: configuring permissions for an AD group

These examples show how you can configure the specific actions (permissions) that all members of an AD group are allowed to perform when administering Pexip Infinity, and provide methods to filter the groups that are displayed.

The filtering options are not mandatory but they do make it easier to select the appropriate LDAP groups, and can optimize system performance.

Let's assume that you have the following set of groups already configured in Windows Active Directory:

In both of the examples below you need to ensure that you have configured an LDAP authentication source (Users & Devices > Administrator authentication) that can access your AD server, for example:

Reinstating the local admin account

If necessary you can reinstate access via the Pexip Infinity local on-box database, so that administrators can log in via the default account (typically admin) and will have full administrator privileges. You may need to do this if, for example, the Authentication source is configured as LDAP database and your connectivity to the LDAP server goes down or your credentials become invalid.

To reactivate your local admin account:

  1. Log in to the Management Node over SSH.
  2. For local admin access only, run the command:

    authset LDAP LOCAL

    or, for LDAP and local admin access, run the command:

    authset LDAP BOTH

You can also disable client certificate authentication so that you can log in to the Pexip Infinity Administrator interface via the standard login page.

To disable certificate-based authentication:

  1. Log in to the Management Node over SSH.
  2. Run the command:

    authset CBA OFF

If you forget the password for the Pexip Infinity Administrator interface, you can re-run the installation wizard, being sure to change only the Web administration password setting.