Managing administrator access via OIDC

You can configure the Pexip Infinity platform to authenticate and authorize administrator login accounts for the Pexip Infinity Administrator interface via the OpenID Connect (OIDC) protocol. Integration with an OIDC Identity Provider allows you to make use of the provider's single sign-on (SSO) and multi-factor authentication (MFA) capabilities and 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 OIDC allows multiple users to administer the platform. These users log in with their OIDC credentials to an OpenID provider such as Microsoft Azure. When using OIDC:

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

In addition to OIDC, you can authenticate and authorize administrator login accounts using a centrally managed LDAP-accessible server. For more information, see Managing administrator access via LDAP.

The configuration described here applies to all administrator accounts connecting to the Pexip Infinity Administrator interface. It does not apply to connections to the Pexip Infinity management API, or SSH connections.

The following sections describe:

• Configuration summary for OIDC authentication
• Configuring Azure as an OIDC provider
• Configuring Pexip Infinity
• Configuring administrator roles
• Configuring OIDC role mappings
• Reinstating the local admin account

Configuration summary for OIDC authentication

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

The OpenID provider must already be configured with:

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

The Pexip Infinity platform must then be configured with:

• an Administrator Authentication source setting that uses an OIDC provider (i.e. includes OpenID Connect service)
• connection details for the OIDC provider; 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
• role mappings that map OIDC groups to administrator roles.

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

• The OIDC provider address is specified as an FQDN (so that it matches the name on the certificate presented by the OIDC provider, which is typically created for the host name rather than the IP address).

• The Management Node trusts the certificate presented by the OIDC provider; typically this means that the OIDC provider server certificate has to be uploaded to the Management Node as a trusted CA certificate (as the OIDC provider 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 OIDC provider (unless the OIDC provider has been explicitly configured to demand a client certificate).

The steps for configuring Azure as an OIDC provider, and configuring the Pexip Infinity platform to use Azure as an OIDC authentication source, are described in more detail in the following sections. For information about installing server and trusted CA certificates, see Managing TLS and trusted CA certificates.

Configuring Azure as an OIDC provider

1. Log in to the Azure portal and select Microsoft Entra ID. From the panel on the left select App registrations and then select New registration:

   

2. On the Register an application page:

   • Enter an appropriate Name

   • In the Redirect URI section, from the drop-down options select Web and enter a redirect URI in the format https://<Management Node FQDN>/oidc/auth/

     The Redirect URI is the page on the Administrator interface to which the Pexip Infinity administrator will be returned after they have successfully signed in to the OIDC provider. Because it is a page on the Management Node, this URI is internal to your deployment and only needs to be accessible from the administrator's web browser; you do not need to make it externally accessible.

   • Select Register:

   

3. Note the Application (client) ID. You must enter this as the Client ID when configuring Pexip Infinity:

   

4. Select the Endpoints tab, and copy the OpenID Connect metadata document (this ends in openid-configuration). You must enter this as the Metadata URL when configuring Pexip Infinity:

   

5. From the panel on the left, select Authentication and scroll down to Implicit grant and hybrid flows. Select ID tokens and then select Save:

   

6. From the panel on the left, select Token configuration. Select Add groups claim, select All groups..., and then select Add:

   

7. From the panel on the left, select Certificates & secrets. Select New client secret, complete the fields, and then select Add:

   

8. Copy the new client secret Value. You must enter this as the Client secret when configuring Pexip Infinity:

   

Configuring Pexip Infinity

The next step to allow administrators to use OIDC authentication when they log in to the Pexip Infinity Administrator interface is to configure Pexip Infinity with information about the OIDC provider. To do this, go to Users & Devices > Administrator authentication. The relevant 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 can only 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 management 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. Open ID Connect service: administrators can only log in using an account configured on the OpenID Connect provider and obtain privileges according to the groups and roles associated with that account. Note that if this option is selected and the OpenID Connect provider is inaccessible for any reason, administrators will not be able to log in to the Pexip Infinity web-based Administrator interface or management API. Open ID Connect service and local database: administrators can log in using either the default local admin account or via an account configured on the OpenID Connect provider. LDAP database, Open ID Connect service and local database: administrators can log in using the default local admin account, via an account configured on the LDAP database, or via an account configured on the OpenID connect provider. When using OIDC either on its own or in combination with another authentication source, you must configure the items in the OpenID Connect configuration section. Default: Local database.
Require client certificate	This option is only applicable if using LDAP as an authentication source. For more information, see Certificate-based authentication.
Management API Oauth2 settings
The settings in this section apply to management API access via OAuth only. They do not affect local, LDAP or OpenID Connect access. For more information, see Managing API access via OAuth2.
LDAP configuration and Advanced LDAP configuration
The settings in these sections apply to LDAP access only. They do not affect local or OpenID Connect access. For more information, see Managing administrator access via LDAP.
OpenID Connect configuration
Metadata URL	Enter the URL of the OpenID Connect metadata document, copied from your OIDC provider. This ends with openid-configuration To obtain the metadata information, the Management Node must have a connection to the OpenID Connect provider. Alternatively, you can leave this field blank; the Configuration metadata, Authorization URL and Token endpoint URL fields appear and you can instead paste the information from Azure into the relevant fields.
Configuration metadata	(Available if Metadata URL is blank) The OpenID Connect configuration metadata, copied from your OIDC provider.
Authorization URL	(Available if Metadata URL is blank) The OpenID Connect authorization URL, copied from your OIDC provider.
Token endpoint URL	(Available if Metadata URL is blank) The OpenID Connect token endpoint URL, copied from your OIDC provider.
Client ID	The Application (client) ID, copied from your OIDC provider.
Authentication method	The OpenID Connect authentication method. For Azure, select Client secret.
Client secret	Enter the Value of the client secret, copied from your OIDC provider.
Scope	The OpenID Connect OAuth2 scope to request.
Username field	The field in the authentication token response to use as the username.
Groups field	The field in the authentication token response to use as the list of groups. You apply role mappings to one or more of these groups by referencing the group in the Value field. If this field is left blank, all users authenticated using OIDC will have the combined access rights of all role mappings that specify a Authentication source of OpenID Connect.
Required key	If there is a field in the authentication token response which must be present, enter the name of the field here.
Required value	If you have specified that there is a Required key, enter the value of the required key here.
Login button text	The text to use for the OpenID Connect button on the login page of the Pexip Infinity Administrator interface. Defaults to OpenID Connect. Maximum length: 128 characters.

If authentication against an OpenID Connect provider is configured, you can save the settings only if Pexip Infinity can successfully contact the specified OpenID Connect provider.

Configuring administrator roles

Administrator roles control the actions that administrators can perform after they have been authenticated. You create one or more administrator roles, and then map them to your OIDC groups, allowing you to grant different privileges to different sets of administrator users.

To add, edit or delete administrator roles, go to Users & Devices > Administrator roles. For full details of the options that are available, see Managing administrator roles.

Configuring OIDC role mappings

Role mappings are used to map the list of groups obtained from Azure to the Pexip Infinity administrator roles. You must configure a separate role mapping for each group for which you want to map one or more Pexip Infinity administrator roles.

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

Option	Description
Name	A descriptive name of the role mapping, e.g. "domain administrator with full privileges".
Source	The authentication source to which this role mapping applies. Select OpenID Connect.
Value	The group to which this mapping applies. For Azure, enter the Object ID; for Okta, enter the group name. This group must be included in the list that is returned in the specified Groups field field of the authentication token response. If the Groups field is blank, this Value will be ignored.
Roles	Select from the list of Available roles the administrator roles to associate with the OIDC 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.

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 admin account with full administrator privileges. You may need to do this if, for example, the Authentication source is configured as OpenID Connect service only and your connectivity to the Azure goes down or your credentials become invalid.

For full instructions, see Reinstating the local admin account.