MFA With the Agent

The command-line interface of the Pro Custodibus agent can be use to check the multi-factor authentication state of each of the WireGuard connections managed by the agent, as well as to perform the interactive portion of multi-factor authentication itself.

List Connections

To list the WireGuard connections managed by Pro Custodibus on the host, and view the state of multi-factor authentication for each, run the following command:

$ sudo /opt/venvs/procustodibus-agent/bin/procustodibus-mfa
Interface    Endpoint       ID           State
-----------  -------------  -----------  ------------------------------
wg-prod      Prod Server 1  ZSp2TSWJ6Ge  EXPIRED
wg-prod      Prod Server 2  63Wa7kQ68oH  OK until 01/01/20 01:00:00 PST
wg-dev       Test Server    USBiuu8PBZw  -

  • The Interface column shows the name of the connection’s WireGuard interface on this host.

  • The Endpoint column shows the name of the connection’s remote endpoint.

  • The ID column shows the ID of the connection’s remote endpoint.

  • The State column shows the MFA state of the connection.

    • The EXPIRED state means the connection requires multi-factor authentication to use.

    • The OK state means the previous multi-factor authentication for the connection is still valid.

    • The - (blank) state means the connection does not require multi-factor authentication.

This command usually requires admin privileges on the host to run (eg via sudo), as it uses the agent’s own credentials to query the Pro Custodibus servers.

(To run this command on Windows, from the Start menu, right-click the Pro Custodibus Agent > Pro Custodibus MFA Status menu item, and select Run as Administrator.)

Check a Connection

To check the MFA state for an individual WireGuard connection, run the following command, with the remote endpoint’s ID as the argument to the --endpoint flag:

$ /opt/venvs/procustodibus-agent/bin/procustodibus-mfa --check --endpoint=ZSp2TSWJ6Ge
EXPIRED

This command outputs one of the following:

EXPIRED

The connection requires multi-factor authentication to use.

OK

The connection does not require multi-factor authentication, or the previous multi-factor authentication for the connection is still valid.

UPDATING

The connection is in the process of being updated.

UNKNOWN

The connection state is unknown.

This command does not require admin privileges on the host to run, as it does not require authentication.

Authenticate for a Connection

To perform the interactive portion of multi-factor authentication for a WireGuard connection, run the following command, using your Pro Custodibus user ID as the argument to the --auth flag, and the remote endpoint’s ID as the argument to the --endpoint flag:

$ sudo /opt/venvs/procustodibus-agent/bin/procustodibus-mfa --auth=Ahg1opVcGX --endpoint=ZSp2TSWJ6Ge
Password:

Enter your Pro Custodibus password at the prompt. If authentication succeeds, the command will output the duration for which the authentication will remain valid:

OK until 01/01/20 08:00:00 PST

This command usually requires admin privileges on the host to run (eg via sudo), as after it performs the multi-factor authentication, it then uses the agent’s own credentials to immediately update the connection’s preshared key.