User API Key Authentication
The main API key authentication method has been available since we added the first API function. It's a relatively simple methods but has some limitations that the User API Key authentication aims to improve on. Namely:
- Enabling Expiration for API Keys
- Enabling support for strong two-factor authentication (2FA).
What is User API Key Authentication?
The User API Key authentication enables retrieval of an API key using a web browser.
If we take the Outlook plugin as an example, when you click authenticate, a web browser window will popup with a login prompt. You complete the authentication and at the end of it the browser window there will be a Authenticated Successful message and also a hidden div that looks like the following:
<div class="d-none" id="api_key">3noyMlZyGuQFkZjgzhU4jzAQHXMtBT725GQhAZsm313k</div>
The upshot is that as we're using a web browser it's possible to match the normal web browser login, so if you enable Strong 2-Factor Authentication, users will be prompted to perform 2-Factor Authentication before authentication completes and the API key is generated and presents it.
How To Use
If you want to use the User API key authentication in your own API integration, it's easy to start the authentication process. You simply open a web browser window the relative URL /session/api, i.e. https://liquidfiles.company.com/session/api if your LiquidFiles installation is https://liquidfiles.company.com. The tricky bit will be to capture the browser window when the authentication is completed.
To make it easier to grab the API key when the authentication has completed, you can use a couple of additional parameters.
| Parameter | Type | Description |
|---|---|---|
| agent_port | Integer | (optional) An Agent Port that when set will trigger a HTTP POST to http://localhost:agent_port with the API key when the user has successfully authenticated. |
| agent_name | String | (Optional) a name for the client that will be used when logging in for logging purposes. |
| agent_version | String | (Optional) a version number for the client that will be used when logging in for logging purposes. |
Agent Port
Lets begin with the Agent Port. The way to use the agent port is that you will need to open a TCP listener on the system that initiates the login. This should be a random port for security reasons. You can then add the agent_port parameter to the login URL, i.e. https://liquidfiles.company.com/session/api?agent_port=12345.
In this example, once a user successfully authenticates, a HTTP POST will be made to https://localhost:12345. This is localhost from the browsers perspective, i.e. the system that the user is logging in from. The response will be sent in parameter format, api_key=3noyMlZyGuQFkZjgzhU4jzAQHXMtBT725GQhAZsm313k. Once you have retrieved the API key from the listener you can close the listener and the browser window.
Security Concerns
It's possible to imagine that an attacker could open their own listener and somehow capture the api key during authentication, but they can't. First, if you've implemented this correctly on the client side, the listener port will be random so the attacker would have to guess the random port and they shouldn't be able to. And secondly the operating system will prevent a process from opening a listener on a port that's already open.
Agent Name & Agent Version
You can send Agent Name and Agent Version and it will be used for logging in Admin → Activity Log when a user logs in.
API web SAML Authentication
In addition to the relative /session/api URL, there's also a /saml/api URL that is used for direct authentication with SAML. If you open a browser window to /saml/api, the browser will be redirected to the SAML server for the user to complete the authentication. Once successfully authenticated the user will be redirected back to the LiquidFiles system and the same "Authentication Successful" page will be shown, together with the optional agent_port callback.