Skip to content

SSO Tool

Introduction

About this Document

This manual serves as a reference source for technical personnel and / or system administrators. It explains the installation and configuration of the AXS Guard Single Sign-On (SSO) Tool.

An in-depth description of the AXS Guard Authentication concepts is available in a separate document, the AXS Guard Authentication How To, which is accessible by clicking on the permanently available Documentation button in the Administrator Tool.

Examples used in this Guide

All setups and configuration examples in this guide are executed as an advanced administrator. Some options are not available if you log in as a full administrator or a user with lower access privileges.

As software development and documentation are ongoing processes, the screenshots shown in this guide may slightly deviate from the current user interface.

Concepts and Features

Overview

The AXS Guard Single Sign-On (SSO) Tool is designed to securely and transparently authenticate users with an AXS Guard from a client PC in the LAN. After successful authentication, the users are granted Firewall and Web Access rights based on the provided credentials. Topics covered in this section include:

  • Supported Operating Systems

  • The features and advantages of the SSO Tool

  • The SSO purpose and concept

  • Possible installation modes

  • Special cases involving Terminal Servers

Supported Operating Systems

The AXS Guard SSO Tool can be installed on the following platforms:

  • Microsoft: Windows 7 or later (32-bit and 64-bit versions). Vista is no longer supported by Microsoft.

  • Linux: All 32-bit distributions and 64-bit versions with multilib support (32-bit libraries).

  • Mac: Yosemite or later.

SSO Tool Features

  • Seamless, strong, and secure two-factor authentication

  • Quick and easy installation

  • Can be used in Domain or Workgroup mode

  • Support for user profiles

  • Automatic configuration of client browser settings in Windows environments

  • Integrated software update notifications

  • Secure communication over SSL

Seamless Authentication

The purpose of the SSO Tool is to allow users to authenticate seamlessly and securely for firewall and web access (see the linked authentication concept explained in the Authentication How To). When successfully authenticated, users are granted firewall and web access rights in accordance with their AXS Guard profile configuration. For detailed information about the AXS Guard firewall and web access modules, see the relevant AXS Guard documentation.

Seamless Authentication with an Active Directory DC

Installation Modes

The SSO Tool can be installed either in:

  • Domain Mode: to support Windows clients in a domain where a domain controller is present.

  • Workgroup Mode: use this mode for Windows computers that are not in a domain or non-Windows machines (Linux and Mac users).

Domain Mode

Select this mode when installing the AXS Guard SSO Tool on Windows clients that are members of a Microsoft Windows Domain. In Domain Mode, the user is automatically authenticated with the AXS Guard after successfully logging on to the domain and AXS Guard firewall and web access rights are applied. The Windows Domain must be registered under the AXS Guard’s allowed domains.

Important

This mode is only supported on Windows clients. The AXS Guard username must match the Active Directory username, otherwise authentication will fail.

Workgroup Mode

Select this mode to install the AXS Guard SSO Tool on computers that are not connected to a Microsoft Domain Controller. This mode supports user profiles, e.g. you can set up a default user profile, which is automatically activated after logging in to the PC, and any additional profiles for other users or locations. It also offers the following possibilities:

  • The user credentials can be stored in a user profile, which allows the user to be automatically authenticated against the AXS Guard after logging in to his/her PC. The password field can also be left blank for additional security.

  • This mode supports two-factor authentication. Classic passwords are often poorly chosen. One-time passwords generated by a DIGIPASS token offer a strong and more secure alternative for firewall and web access authentication. See the AXS Guard Authentication How To for additional information.

  • This mode is supported by Windows, Linux and Mac.

Important

Do not store passwords in a profile when using DIGIPASS authentication for firewall and web access.

SSL Connection

The Secure Sockets Layer (SSL) is a commonly-used protocol to secure communications between hosts in a network.

The SSO Tool uses SSL to communicate with the AXS Guard appliance. The aim is to prevent sensitive information, such as user credentials, from being intercepted when they are transmitted over the local network between the user’s client PC and the AXS Guard appliance. SSL is enabled by default when installing the SSO Tool.

img

Automated Adjustment of Proxy Settings

The SSO Tool offers the possibility to automatically adjust the user’s proxy settings after authentication. When the user logs out, uses suspend mode or closes his / her laptop without logging out, the proxy settings are cleared. This is a major convenience for users as well as the system administrator(s), as the browser settings don’t have to be manually adjusted.

Important

This feature is only supported on Windows clients.

Automated Updates

The SSO Tool periodically connects to the AXS Guard appliance to check whether a new version is available and will notify the user as shown below.

Example of SSO Tool Update Notification

User Profiles

A user profile contains a user’s SSO configuration. You can define multiple profiles on a single computer (to allow users to share the computer) or to allow authentication in different office locations, where other firewall and web access policies may apply to the same user.

SSO User Profiles

Important

Profiles are not supported on Mac clients.

Particular Cases with Terminal Servers

Overview

In this section, we explain the use of the SSO Tool in combination with Terminal Servers:

  • Terminal Servers without Virtual IP address support.

  • Terminal Server with Virtual IP address support.

Without Virtual IP Support

The SSO Tool cannot be used to authenticate via a terminal server which does not support Virtual IP addresses. Each user / IP pair needs to be unique. This scenario applies to older versions of the Citrix Metaframe Presentation Server.

For more detailed information, see the AXS Guard Authentication How To, which is accessible via the Documentation button in the AXS Guard administrator tool.

img

With Virtual IP Support

When users log in to a thin client, which is linked to a central server such as a Citrix Presentation Server or an MS Terminal Server, any outgoing traffic generated by the thin client shows the Terminal Server’s IP address as the source IP address. In that case, the SSO utility cannot be used.

As of version 4.0 and above, the Citrix Metaframe Presentation Server offers a Virtual IP feature where it can assign a unique virtual IP address to each user who logs in. As such, it is possible to differentiate each user’s traffic based on their Virtual IP address; each user / IP pair is unique.

The Virtual IP Addresses are bound to the Citrix Presentation Server NIC and can be viewed with the ipconfig command.

img

Installation and Configuration

Configuration and Installation Overview

  1. Allow and link firewall and web access authentication.

  2. Register your Windows domain on the AXS Guard appliance.

  3. Configure the authentication policy for the SSO tool.

  4. Download, install and configure the SSO utility for your OS.

Authentication and Windows Domain Settings

Skip the following steps if the client is not part of a Microsoft domain.

  1. Navigate to Authentication > General.

  2. Allow and link firewall and web access authentication.

    Server-Side Authentication Settings

  3. Select the SSO Tool tab to add your Windows domain(s).

  4. Save your configuration.

    Windows Domain Settings on the AXS Guard Appliance

Field Description

Windows domains used in your network

Enter the same domain string that is used by users when they log in to your Windows domain, e.g. if mydomain.local is your Windows domain, enter mydomain to allow authentications from that domain. Authentications from non-registered domains will be rejected.

Configuring the SSO Authentication Policy

  1. Go to Authentication > Services.

  2. Select Firewall and Web Access.

  3. Select the desired authentication policy.

    title="Web Access Authentication Policy

Field Description

Service

The AXS Guard service to be configured. This field cannot be edited.

Authentication Policy

The authentication policy determines how users must authenticate to access the service. Go to Authentication > Advanced > Policy for an overview of policies configured on your system.

Brute Force Attack Protection

Enable to protect the selected service against brute force attacks as configured under Authentication > General.

Downloading the SSO Tool

  1. Log on to the AXS Guard appliance.

  2. Go to Add-ons.

  3. Select the appropriate file for your OS.

    Downloading the SSO Tool

Users can also download the SSO tool via the Web Access login page. Their browser must be configured to use the AXS Guard proxy server.

Downloading the SSO Tool

Windows Installation

Upgrading an existing Installation

Important

  • If you are upgrading from version 1.0 to version 2.0 or later, you must uninstall the old version before upgrading. If you are upgrading from version 2.13 to 2.14, administrator credentials are always required to install the SSO tool, even for a per-user installation.
  • Ensure to fully exit the SSO tool prior to an upgrade or removal.
  • As of version 2.0, the SSO tool automatically attempts to remove previous versions when you start the installation procedure.

Available software upgrades are announced via the release notes and automated messages in the Windows system tray.

Supported Installation Methods

There are several methods to install the SSO Tool:

  • Silent installation: Deploy the SSO tool with Active Directory (by creating an mst transform file for the msi installer) or by using the msi installer in a Windows login script. Additionally, the SSO tool offers an alternative installation method through Microsoft Intune. For comprehensive guidance on this automated deployment option, please consult the relevant Microsoft documentation.

  • Local, system-wide installation: Requires administrator privileges on the local machine and installs the SSO Tool for all users on the system.

  • Local, non-privileged user installation: Does not require administrator privileges on the local machine and installs the SSO Tool only for the user who is logged in to the system.

Silent Installation

With Active Directory

To deploy the SSO tool via a Group Policy, you have to create a customized msi installer. You also have to option to create an .mst (msi transform) file for the .msi installer. See the knowledge base section on this site for step-by-step instructions.

A customized msi installer can be created with the included msi configuration tool for the SSO installer. This program automatically creates an msi installer adapted to your network environment based on the configured settings. As an alternative, you can create an mst transform file with Orca, a database table editor for creating and editing Windows Installer packages and merging modules.

  1. Extract the SSO zip file.

  2. Run the configureMsi executable.

  3. Configure the correct settings for your network environment.

  4. Click on `Configure Installer when finished.

  5. Deploy the resulting msi file via a Group Policy.

    SSO msi Configuration Tool

Property Values

ALLUSERS

Set this value to 1 for a system-wide installation, i.e. ALLUSERS=1 (install for all users, requires elevation). If unspecified or set to "", i.e. ALLUSERS="" (program default), the SSO tool will be installed for the current user only (stored in the registry under HKLM or HKCU). See msdn.microsoft.com for additional information about this property.

NAM

Create a new profile with this name.

DESC

Create a new profile with this description.

IP

Create a new profile with this AXS Guard IP. Use the IP address of the primary secure LAN device of the AXS Guard appliance, e.g. 192.0.2.1 (required for domain mode).

DOM

The windows domain, e.g. example.com (required for domain mode).

USR

Create a default profile with this username (optional for domain mode).

PWD

The password to be set in the default profile (optional for domain mode).

Example of an mst Propterty Table (Orca)

With a Login Script

Administrators can install the SSO tool silently by adding the following line to the Windows login script of a client:

msiexec /i "\\\\<server>\\<path>\\<to>\\<SSO>\\sso_setup.msi" /q USR=%username% DOM=<domainname> IP=<ip-axsguard> ALLUSERS=""

Local System-wide Installation

  1. Log in to the Windows client with administrator privileges.

  2. Extract the SSO zip file to the location of your choice.

  3. Double-click on the msi installer to start the installation.

  4. Read and accept the terms in the license agreement.

  5. Check Install for all users of this machine as shown in the image below.

  6. Configure the default profile settings.

    logo

Important

You will be asked to create a default user profile. If you have profiles from a previous installation, select No.

Local Non-privileged User Installation

Non-privileged users can only install the SSO Tool for their own Windows account. The installation procedure is identical to the System-wide installation. Select Install just for you when prompted.

Important

The msi installer will ask for administrator credentials if it detects a previous version of the SSO Tool on your system. Administrative privileges are required to uninstall versions prior to 2.14.

Mac Installation

  1. Download the SSO utility for Mac from the AXS Guard appliance.

  2. Extract the zip file.

  3. Install the dmg file.

Linux Installation

To install the SSO Tool in Linux:

  1. Download the SSO tool for Linux from the AXS Guard appliance.

  2. Extract the Linux binary from the tgz archive to your home folder.

  3. Start the SSO tool from a terminal, e.g. ./AXSGUARDSSOv2.

Important

The Linux binary is compiled with gcc 4.9 and requires wxWidgets (version 3.0 or later) to run. Check the documentation of your Linux distribution for installation instructions.

Ubuntu example: sudo apt-get install libwxgtk3.0-dev

Basic Configuration

User Profiles

Right-clicking on the tray icon will show a context menu allowing a user to activate, create, delete or edit a user profile. Other menu options include logging off from the AXS Guard and stopping the SSO Tool. A user can create different user profiles (see User Profiles).

  1. Right-click on the tray icon.

  2. Select Create new profile.

    logo

  3. Enter the profile settings and save.

    logo

There are three scenarios in which the password field should be left blank, i.e.

  • In Windows Domain Mode, the username and password fields cannot be edited by the user, as they authenticate against the Windows Domain server.

  • In Workgroup Mode: If your company policy forbids the storage of AXS Guard passwords, users will be prompted to enter their password whenever required.

  • When using DIGIPASS authentication: For AXS Guard systems which enforce DIGIPASS authentication for firewall and web access, a password window will appear whenever the user is required to enter a one-time password.

SSO Password Window

Field

Description

Use Windows Domain Mode for this profile

  • Check this option if the client is part of a Windows Domain. The username and password fields will be grayed out, since the Windows Domain credentials are used to authenticate the user against the AXS GUARD.

  • Uncheck this option if the client is not part of a Windows Domain Controller (Workgroup Mode).

Name

The label of the user profile.

Description

An optional description for the user profile.

Hostname

The secure LAN IP address of the AXS GUARD appliance. The SSO tool will try to auto-complete the AXS GUARD LAN IP address by attempting to resolve the default name axsguard. If this name does not resolve, the hostname field must be completed manually.

Username (Workgroup Mode only)

The AXS GUARD account of the user.

Password (Workgroup Mode only)

The AXS GUARD password of the user. Leave blank if you are using DIGIPASS authentication for firewall and web access.

Use AXS GUARD as proxy server

Check to automatically adjust the proxy configuration of your Windows system. If checked, the user’s browser will connect to the Internet through the AXS GUARD proxy server. The Windows 10 and Windows 8 proxy settings can be verified by going to PC Settings > Network > Proxy.

Use this profile as your default profile

The default profile will automatically be activated whenever the SSO tool is started.

Choosing a Default User Profile

See User Profiles.

Activating a User Profile

To manually log in with a specific profile, a user has to select Activate profile from the tray icon menu. A list with the available profiles will appear. The profile currently in use will be marked as active (also see the image below).

  1. Right-click on the tray icon to display the context menu.

  2. Select Activate profile.

  3. Click on the desired user profile.

    Activating a User Profile

Editing and Deleting User Profiles

The Edit/Delete profiles option allows you to modify or delete a user profile. To edit or delete a user profile:

  1. Right-click on the tray icon.

  2. Select Edit/Delete profiles.

  3. Select the desired profile.

  4. Modify the settings and click on Save or click on Delete to remove the user profile.

    logo

Linux-Specific Configuration

On Linux systems, the configuration settings for the SSO Tool are stored in the user’s home directory in the .aXsguardSSOv2 file. The file can be edited with a standard text editor. Caution is advised when editing the file. The SSO utility configuration in Linux is the same as in Windows, except that domain mode is not supported.

Mac-Specific Configuration

On Mac systems, profiles are not supported. Users can only enter their credentials and select to start the SSO tool automatically when logging in to their system ("launch at login" option).

logo

Advanced Configuration Options

  1. Right-click on the tray icon.

  2. Click on Settings.

  3. Click on OK to save the settings.

    Advanced Settings

Field Description

Notify user when new versions becomes available

If enabled, users are automatically notified via the system tray when a new version of the SSO tool is available. This option is enabled by default.

Enable Debug output

Enables debug output to a logfile named axsguard.log. The file is located in %AppData%\AXSGUARDSSOv2. See the official Microsoft documentation for information about the %AppData% path. The debug logging option is disabled by default, but can be useful for troubleshooting and support.

Troubleshooting

I cannot install the SSO Tool in Windows Vista

Windows Vista is no longer supported by Microsoft. To install the SSO Tool in Windows Vista, the msi installer must be unblocked before you can run it. Please note that only a per-machine installation context is supported.

  1. Copy the msi executable to your desktop.

  2. Right-click the msi executable on your desktop and select properties.

  3. Unblock the msi installer.

    logo

Connection to server fails

If you encounter the following error message:

logo

Verify the following:

  1. Is the AXS Guard LAN IP address correctly entered in the given user profile? Right-click the system tray icon and edit the profile to verify this.

  2. Is it possible to ping the AXS Guard LAN IP address? If it cannot be pinged, the network connectivity must be checked: is the computer still physically connected to the LAN ? Verify whether the network cables are still connected, replace the network cable if necessary.

  3. Check the AXS Guard Firewall to verify whether the sec-auth Firewall Rule is present and activated in the stat-sec static Firewall Policy (Firewall > Policies > Static > stat-sec, as shown below).

    stat-sec Firewall Policy

If the error occurs because of a temporary network outage, the SSO Tool displays a message as soon as the connection is restored.

logo

Unknown user or password invalid

If the following error message appears when logging in:

Invalid User or Password

Verify the following:

  1. Check the allowed Microsoft domains in the AXS Guard Administrator Tool. This field must be left empty if no domains are used in your network.

  2. Is the username/password combination entered correctly and valid in the AXS Guard user list?

  3. Edit the user profile to make sure that the correct username has been entered and re-enter the according password. Save and reactivate the profile.

Login not allowed from domain or computer

If the following error message appears when signing on:

logo

Verify the following:

  1. Check the Microsoft domain settings on the AXS Guard appliance and make sure they match the domain as configured in your profile.

  2. Make sure you are logged on to the Windows domain and not locally (see image below). When using Workgroup mode, no domain must be specified in the AXS Guard Administrator Tool.

    logo

  3. Make sure you did not store a password in the user profile.

  4. Test the DIGIPASS using the test function in the AXS Guard Administrator Tool.

  5. Check if the DIGIPASS is correctly assigned to the user.

  6. Check the user’s Web Access and Firewall Policy settings.

Detailed information about Authentication and DIGIPASS configuration settings is available in the AXS Guard Authentication How To, which can be accessed by clicking on the permanently available Documentation button in the Administrator Tool.

Running the SSO Tool in Linux throws an error

./AXSGUARDSSOv2_64: error while loading shared libraries: libwx_gtk2u_adv-3.0.so.0: cannot open shared object file: No such file or directory
(1.9.3)[~] user@linux: $ ldd ./AXSGUARDSSOv2_64
        linux-vdso.so.1 =>  (0x00007ffc7dd9a000)
        libssl.so.1.0.0 => /lib/x86_64-linux-gnu/libssl.so.1.0.0 (0x00007fdd4a74b000)
        libcrypto.so.1.0.0 => /lib/x86_64-linux-gnu/libcrypto.so.1.0.0 (0x00007fdd4a36f000)
        libwx_gtk2u_adv-3.0.so.0 => not found
        libwx_gtk2u_html-3.0.so.0 => not found
        libwx_gtk2u_core-3.0.so.0 => not found
        libwx_baseu-3.0.so.0 => not found
        libwx_baseu_net-3.0.so.0 => not found
        libstdc++.so.6 => /usr/lib/x86_64-linux-gnu/libstdc++.so.6 (0x00007fdd4a068000)
        libm.so.6 => /lib/x86_64-linux-gnu/libm.so.6 (0x00007fdd49d62000)
        libgcc_s.so.1 => /lib/x86_64-linux-gnu/libgcc_s.so.1 (0x00007fdd49b4c000)
        libpthread.so.0 => /lib/x86_64-linux-gnu/libpthread.so.0 (0x00007fdd4992d000)
        libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007fdd49568000)
        libdl.so.2 => /lib/x86_64-linux-gnu/libdl.so.2 (0x00007fdd49364000)
        /lib64/ld-linux-x86-64.so.2 (0x000055e7d3c1c000)

The Linux binary requires wxWidgets (version 3.0 or later) to run. Check the documentation of your Linux distribution for installation intructions.

The Linux binary is compiled with gcc 4.9 and will not work with wxWidgets libraries that have been compiled with gcc 5.

Support

If you encounter a problem

If you encounter a problem with AXS Guard, follow the steps below:

  1. Check the troubleshooting section of the feature-specific manual.

  2. Check the knowledge base on this site for information about special configurations.

  3. If no solution is available in any of the above sources, contact your AXS Guard vendor.

Contact Information

(+32) 15-504-400
support@axsguard.com