Managing API access via OAuth2
You can configure the Pexip Infinity platform to use OAuth2 to authenticate and authorize administrator accounts connecting to the Pexip Infinity management API.
Using OAuth2 for management API authentication is an alternative to access using LDAP for environments that make frequent API requests, as it can significantly reduce the number of requests sent to the LDAP server. Using LDAP, every management API request is preceded by an authentication request to the LDAP server. Using OAuth2, the API client authenticates once with the Management Node to obtain a token that is then valid for a specified amount of time (1 hour by default).
When configured, OAuth2 applies to management API access only. It can not be used to access the Pexip Infinity web-based Administrator interface; access to this will always use the specified administrator Authentication source (as configured under ).
The steps required to enable management API access via OAuth2 are:
-
Creating a management API OAuth2 client and assigning the new administrator role to it.
This topic also includes information on:
All usernames and passwords are case sensitive.
Creating an administrator role
Administrator roles control the actions that administrators can perform after they have been authenticated. You create one or more administrator roles, and then
To add, edit or delete administrator roles, go to . For full details of the options that are available, see Managing administrator roles.
Creating an OAuth2 client
To create OAuth2 client credentials that can be used to access the management API, go to and select . Enter the following:
This process will generate a private key that you must copy before navigating away from the page.
| Option | Description |
|---|---|
| Client name |
Enter a name for this particular OAuth client and role combination. |
| Role | Select the Administrator role to assign to the management API when it is authenticated using this client. |
Select . Additional Client ID and Private key information appears. These are the credentials that the OAuth2 client must use in order to access the management API.
You must copy the private key before you navigate away from the page as it will not be available afterwards.
Configuring management API authentication
To configure management API access using OAuth2, go to and scroll down to the Management API Oauth2 settings section. The options are:
| Option | Description |
|---|---|
| Management API Oauth2 settings | |
| Access token expiration |
The length of time (in seconds) after which the management API OAuth2 client must re-authenticate. Default: 3600 (1 hour) |
| Disable Basic authentication |
When selected, basic authentication is not available to management API users; they can only authenticate using OAuth2. When this option is not selected, management API users can authenticate using either OAuth2 (if configured) or basic authentication — which includes the local admin username and password, or a valid LDAP username and password. |
| Allow all permissions | When enabled, management API clients authenticated using OAuth2 can use all permissions specified in the assigned role. When this option is disabled, these API clients cannot modify authentication configuration even if "may modify authentication configuration" is specified in the role. |
Using OAuth2 to access the management API
When management API access using OAuth2 has been enabled as described above, users can access the management API by configuring their OAuth2 client with the Client ID and Private key credentials, and then directing the client to https://<management_node_fqdn>/oauth/token/
Viewing active management API clients
To view all OAuth2 clients with a currently active token, go to . Select a client to view details of the permissions assigned to the client, and its token expiry.
