Skip to main content

User Authentication

User sessions can be created using the API. This is handy for machine to machine authentication, and is where knocknoc-client authentication requests are also configured.

As an Admin, create a local user, selecting API Key as the authentication method:

Screenshot 2025-06-09 at 14.06.15.png

Visit the API keys section and choose"User Authentication", selecting the user who has been permitted API access.

Screenshot 2025-06-09 at 14.06.01.png

Note the IP restrictions.

Knocknoc client

This is utilized for machine to machine authentication, such as during scripted authentication grant/revocation as part of SCP/Rsync transfers or ephemeral/scripted SSH access.

The client knocknoc-client is packaged with the Knocknoc Agent, and requires the following configuration:

  • Knocknoc server URL;
  • Username; and
  • API key

A template can be created by running knocknoc-client -newconfig <configfile>

To create a session, the user runs knocknoc-client -config <file>. This will contact the knocknoc server at the specified URL, and attempt to login as the specified user with the given API key. If that login is successful, then a regular user session will be created, with the ACLs granted in the usual fashion, for the session duration specified for the user, and then exit. If the operation (eg: file transfer) takes longer than the Knocknoc session, it will be terminated as access is removed in most cases. For IPSets, if the blocklist is not utilized, the established TCP connection will continue without disruption, however new (tcp syn) sessions will be blocked. This is naturally firewall configuration dependent. 

If the -persist command-line option is passed to knocknoc-client, then rather than exiting, the client will enter a loop, which behaves similarly to the user home/webpage view. It polls the "user status" endpoint every 30 seconds, which handles IP address changes automatically. 

Back to top