Skip to main content

Tutorial: Add iVALT Two-Factor Authentication to Access Server

Abstract

Integrate Access Server with iVALT 2FA for a layer of biometric authentication security.

Overview

Add iVALT two-factor authentication (2FA) to Access Server to enhance VPN security with iVALT's biometric authentication system. This integration provides remote, encrypted connections for users and more secure authentication.

Access Server also has built-in TOTP MFA support.

Important

You can't turn on Access Server's built-in TOTP MFA and add iVALT 2FA. This will cause user authentication problems.

When you integrate iVALT 2FA, your user logins include biometric verification. The diagram shows how the authentication flows with the setup.

ivalt.png

  1. User attempts VPN connection.

  2. Initial authentication (local/PAM/LDAP/RADIUS) succeeds.

  3. Access Server notifies iVALT via HTTPS API to begin the 2FA procedure.

  4. The post-auth script retrieves the user's mobile number from iVALT.

  5. A biometric authentication request is sent to the user's mobile device.

  6. The user confirms via biometric verification.

  7. The script validates geofencing and timezone.

  8. VPN access is granted or denied based on the result.

Prerequisites

  • An iVALT account.

  • An installed Access Server.

  • Console (SSH) access with root privileges.

Step 1: Set up the post-auth script

  1. Connect to the Access Server console and get root privileges.

  2. Clone the iVALT repository:

    git clone https://github.com/iVALT-Inc/openvpn-ivalt-2fa.git

  3. Open the main.py script for editing:

    nano openvpn-ivalt-2fa/main.py

  4. Find and update the following line with your iVALT secret key:

    IVALT_SECRET_KEY = "<ivalt_secret_key>"

  5. Save and exit the file (Ctrl + x, then y, then press Enter).

  6. Load the script and restart Access Server:

    cd /usr/local/openvpn_as/scripts/
./sacli --key "auth.module.post_auth_script" --value_file="openvpn-ivalt-2fa/main.py" ConfigPut
./sacli start

  7. Test your setup by signing in as a VPN user.

    Tip

    Test with one user already enrolled in iVALT and another who hasn’t yet enrolled.

Remove iVALT authentication

If you stop using iVALT, remove the integration:

  1. Connect to your Access Server console and get root privileges.

  2. Remove the iVALT setup:

    cd /usr/local/openvpn_as/scripts/
./sacli --key "auth.module.post_auth_script" ConfigDel

  3. Reload the service to commit the changes:

    ./sacli start

Troubleshooting

Error: The email provided (brandonqa@access-server.com) was not found

This means the email address isn't registered or enrolled with the iVALT app.

Solution: Register and enroll all VPN user email addresses in the iVALT app before using this integration.

Error: AUTHENTICATION_FAILED

The FaceID verification failed, or the iVALT 2FA request timed out after 60 seconds.

Solution: Complete the FaceID verification within the 60-second window.

Error: INVALID_TIMEZONE

The user's Time Windows doesn't match the settings in the iVALT Admin Panel.

Solution: Ensure the Time Windows (timezone, start time, and end time) and access window align with the user's actual location and login time.

Example: If the user brandonqa has:

  • Timezone: UTC-05:00

  • Start: 08:00 AM

  • End: 04:00 PM

They must sign in within that window to avoid this error.

Error: INVALID_GEOFENCE

The user's VPN location is outside their iVALT-configured geofence.

Solution: Ensure the location configured in the iVALT Admin Panel matches the user's real location.

Example: If brandonqa's geofence is set to California, but they attempt to sign in from Montana, Access Server returns INVALID_GEOFENCE.

In this section:
See also: