EasyAccess 4.3 Getting Started Guide


Table of Contents

1. Overview
2. Server Installation
2.1. Windows Installation
2.2. Linux Installation
2.3. Licenses
2.4. Server Protocols and Ports
2.5. External Database Setup
3. Management Access
4. LDAP Server Setup
5. RADIUS Setup
5.1. Basic RADIUS Scenario Setup
5.2. RADIUS with Token Scenario Setup
5.3. RADIUS with OneTouch Scenario Setup
5.4. Passwordless RADIUS Authentication
6. Federation (SAML) Setup
6.1. Basic Federation Scenario Setup
6.2. SSO Setup
6.3. Redirecting SAML Requests
6.4. Customizing SAML Assertions
6.5. MyApps Setup
6.6. SSO with OneConnect Setup
6.7. Passwordless Federation Authentication
7. MS-CHAPv2 Proxy Setup
8. Self Service Setup
9. Cluster Setup
9.1. EasyAccess Service Setup
9.2. Cluster Database Service Setup
9.3. Cluster Management
10. Knowledge Base Articles

Chapter 1: Overview

[Note] Note: This document is also available in other formats

A PDF version of this document along with all current and older documentation in PDF format can be found at https://my.clavister.com.

It also available in a framed HTML version.

Introduction

The Clavister EasyAccess product is a server based, on-premises software product that provides multi-factor authentication services. This guide will go through both installation of the product as well as describing some of the basic setup procedures for different scenarios once the EasyAccess server is running.

The topics covered will include the following:

  • Installing the EasyAccess server.

  • Accessing the EasyAccess configuration manager web interface.

  • Setting up access to a user store (in other words, access to a database of users).

  • Setting up RADIUS authentication servicing, optionally with different kinds of multifactor authentication.

  • Setting up different types of federation (SAML) scenarios.

  • Enabling authentication management by users themselves through the self service feature.

Note that this guide only covers setup of the EasyAccess server. It does not cover setup of a client device or how to make use of the self service feature.

Compatible Hardware Platforms

The EasyAccess server software can be installed on any of the following platforms:

  • Linux™ (64 bit).

  • Windows™ 10 or 11 (64 bit).

  • Windows Server™ 2008, 2012, 2016 (64 bit).

Resource Requirements

The following are the minimum hardware resource requirements for the EasyAccess server running on all platforms:

  • RAM memory requirements:

    1. A minimum of 2 GBytes RAM for installations with up to 10,000 users.

    2. A minimum of 4 GBytes RAM for installations with between 10,000 and 100,000 users.

    3. For greater user numbers, consult with support personnel.

  • A minimum of 5 GBytes free disk space.

  • The EasyAccess server is not highly CPU intensive so a hardware platform providing a single CPU can be sufficient in many scenarios. However, a dual core CPU is recommended.

Virtual Environment Support

Virtual environments such as VMware and Microsoft Hyper-V are supported.

Using a Reverse HTTP Proxy is Recommended

After installation, the EasyAccess server is best protected from the Internet by being on a DMZ type network with a private IP address. This means that there must be some means of SAT address translation from a public IP for incoming connections.

The recommendation is to place a reverse proxy between the Internet and the EasyAccess server and to configure the proxy to allow the expected external client access to the server. This may also include installing the appropriate SSL certificate on the proxy which clients can accept, instead of configuring this in EasyAccess.

The selection and detailed setup of reverse proxy software is outside the scope of this publication. However, below is a list of the recommended proxy translations, where the first parameter is the URI of the incoming connection and the second parameter is the translated URL, where EA_SERVER represents the private IP address of the EasyAccess server.

  • "/config" => "https://EA_SERVER:8443/config"

  • "/mfaadmin" => "https://EA_SERVER:8443/mfaadmin"

  • "/selfservice" => "https://EA_SERVER:8443/selfservice"

  • "/authenticate" => "https://EA_SERVER:8443/authenticate"

  • "/saml" => "https://EA_SERVER:8443/saml"

  • "/oidc" => "https://EA_SERVER:8443/oidc"

  • "/pki" => "https://EA_SERVER:8443/pki"

  • "/push" => "https://EA_SERVER:8443/push"

  • "/activateonetouch" => "https://EA_SERVER:8443/activateonetouch"

  • "/myapps" => "https://EA_SERVER:8443/myapps"

  • "/pss" => "https://EA_SERVER:8443/pss"

If preferred, the protocol used could be HTTP with the port number 8080.

Chapter 2: Server Installation

This section describes the installation of the EasyAccess server software on one of the supported computing platforms. The supported platforms and minimum resource requirements are described in Chapter 1, Overview.

The following steps are required to install the software:

  1. Download the installation package from the MyClavister section of the Clavister website. This can be found under the Downloads section of MyClavister. A MyClavister user account will need to be created if one does not already exist.

  2. Download a valid license file from the Licenses section of the relevant MyClavister account. The license file will be required during the installation procedure and the EasyAccess server will not start if it is not present. The server can start with an expired license file but connection attempts to it will fail.

    Downloading a license is described further in Section 2.3, Licenses.

  3. Next, use the installation instructions that follow in this section for the relevant computing platform.

[Note] Note: Upgrading from a Pre-4.0 version

This section should not be used if upgrading from a version before 4.0. The Release Notes PDF for the 4.0.2 version contains a section which describes how to upgrade. Pre-4.0 versions use a different internal database so an export of old data followed by an import into the new version may be required.

The EasyAccess Folder Structure

Installation on either a Windows or a Linux based computer will create a similar folder structure under the root file path specified during installation. Under Windows, for example, the default path will be the Windows Program Files folder. The top folder in the structure is called EasyAccess under which is a Server folder. Under the Server folder will be the following key folders:

  • bin - Contains executable files, including files for starting the EasyAccess server.

  • config - Contains JSON files which define the configuration. The file phenix-store.json is the main configuration file.

  • license - Contains the current license file. The license file must be placed here if it was not specified during installation otherwise the EasyAccess server will not start.

  • logs - Contains the log files server.log and events.log for different event types. The server.log file is an important tool for troubleshooting.

An Internal or External Database Can Be Used

Note that the standard installation includes installation of the default EasyAccess internal HSQLDB database. However, from EasyAccess version 4.0 onwards, the possibility exists to use an external database server instead which can be either a MySQL or an MSSQL database. An external database can be running on a separate computer or the same computer as the associated EasyAccess installation. If the EasyAccess installation is to be part of a cluster then an external database server must be used instead of the internal database.

The additional setup steps required for using an external database can be found in Section 2.5, External Database Setup.

2.1. Windows Installation

This section describes the installation of the EasyAccess server software on a Windows based computer.

First, execute the Windows .exe installer file on the computer after downloading it from MyClavister (link: https://my.clavister.com). This will run an installation wizard which will go through the following steps:

  1. A welcome message is presented in the first wizard step. Click Next to continue.

  2. Accept the license agreement.

  3. Select an installation location for the server file or accept the default. For example: C:\Program Files\EasyAccess\Server.

  4. Locate and select a valid license file. Downloading a license is described in Section 2.3, Licenses.

  5. Enter the default system administrator username and password. These credentials will be used to access the EasyAccess configuration manager WebUI. Note that only the characters A-Z, a-z and 0-9 should be used.

  6. Set an encryption key which will be used as a seed for encrypting persistent data such as token keys. If this is a single standalone EasyAccess node or the first node in a cluster then the encryption key can be anything. If this node is to be joined into an already existing cluster the key given MUST be the same as the other nodes. Note that only the characters A-Z, a-z and 0-9 should be used.

  7. Enter the HTTP port used for accessing the EasyAccess configuration manager WebUI. For example, 8443.

  8. Select Finish to close the wizard.

Starting the EasyAccess Server on Windows

The server is started in one of the following two ways:

  • If it is desirable to have a console window open to show server activity, open the EasyAccess/server/bin folder and then start the EasyAccess server executable file. This file will have a name of the form EasyAccess_<vernum>.exe.

  • If a console is not needed, the service called EasyAccess should be started. On Windows, this is done by opening the service list and then right clicking the EasyAccess service before selecting the Start option. This is shown below. The service will not need to be started again after a Windows restart as it will start automatically.

Starting the EasyAccess Service

Figure 2.1. Starting the EasyAccess Service

Note that the server will take a short amount of time to initialize and start up completely. The startup phase can be monitored by viewing the CPU load in the Windows task manager. Alternatively, use the following Windows console command:

C:\> netstat -aon | findstr :8443

This will show the server is listening on the management port (in this case 8443) if the server has started. The server.log file should also contain a log that indicates successful startup.

2.2. Linux Installation

This section describes the installation of the EasyAccess server software on a Linux based computer.

Installation steps are given for the following:

  • Using the X Window interface.

  • Using the CLI.

Installation on LINUX using the X Window Interface

  1. Open a console.

  2. Enter:

    > chmod +x easy_server_linux_x64_<version>.sh

  3. To start installation, enter:

    > sudo ./easy_server_linux_x64_<version>.sh
  4. The wizard welcome screen will display. Click Next.

  5. Accept the license agreement.

  6. Select the installation location or accept the default destination.

  7. Select the license file. Downloading a license is described in Section 2.3, Licenses.

  8. Enter the administrator username and password. These credentials will be used for accessing the EasyAccess configuration manager WebUI. Note that no other characters than A-Z, a-z and 0-9 are recommended.

  9. Enter an encryption key seed used for encrypting persistent data such as token keys. Note that if this is a single node or the first node in a cluster then the encryption key can be anything. However, if this node is to be joined into an already existing cluster, the key MUST be the same on all nodes. Note that no other characters than A-Z, a-z and 0-9 are recommended.

  10. Enter the HTTP port that access to the configuration manager WebUI will use. For example, 8443. If the installation is being done in a virtual environment, check the box I am installing on a virtual machine.

  11. Click Finish to end the Setup.

Installation on LINUX using the CLI

  1. Open a console.

  2. Enter:

    > chmod +x easy_server_linux_x64_<version>.sh

  3. To start installation, enter:

    > sudo ./easy_server_linux_x64_<version>.sh** -c

  4. Press the Enter key to continue.

  5. Accept the license agreement.

  6. Select the installation location.

  7. Select the license file.

  8. Enter the default system administrator username for access to the configuration application.

  9. Enter a password for the system administrator that was set in the previous step. Note that no other characters than A-Z, a-z and 0-9 are recommended.

  10. Enter an encryption key seed used for encrypting persistent data such as token keys. Note that if this is a single node or the first node in a cluster then the encryption key can be anything. However, if this node is to be joined into an already existing cluster, the key MUST be the same on all nodes. Note that no other characters than A-Z, a-z and 0-9 are recommended.

  11. Enter the HTTP port the management WebUI will use. For example, 8443.

  12. If the installation is being done in a virtual environment, answer yes and press Enter. If not, just press Enter.

  13. Indicate if this installation is part of a cluster.

  14. Indicate if this installation is on an appliance.

  15. Installation is complete.

Starting the EasyAccess Server on Linux

The server is started using the bash script called start-PhenixID.sh which is located in the EasyAccess/Server/bin/ folder. The console command would therefore be:

> sudo  [install-path]/EasyAccess/Server/bin/start-PhenixID.sh

There must be a valid license file in the license folder for the server to start successfully. Note that the server will take a short amount of time to initialize and start up completely. The startup phase can be monitored using the following Linux console command:

> netstat -nlap|grep :8443

When the server is operational, the command output will show a Java process listening on the specified port. The server.log file should also contain a log that indicates successful startup.

The "No fonts found" Error Message

When running EasyAccess under Linux, a potential problem that could arise when the EasyAccess server starts is that the relevant dejavu fonts required by EasyAccess are not installed. This problem results in the following error appearing:
	java.lang.Error: Probable fatal error:No fonts found.

The issue can be resolved by installing the required fonts and doing this is described for different Linux distributions in a Clavister Knowledge Base article at the following link:

https://kb.clavister.com/332435040

2.3. Licenses

License Location and Replacement

The local EasyAccess server license is stored as the file called license.p12 which can be found in the folder EasyAccess/Server/license. A running EasyAccess server will not respond to HTTP requests to open the management WebUI if this license file is invalid. After the server starts, a message in the log file events.log will indicate if the server found the file to be invalid.

To install a valid license.p12 license file, it needs to be first downloaded to the local management computer from the relevant MyClavister account. The file can then be uploaded to the server in one of the wizard steps during EasyAccess installation. Alternatively, the file can be manually placed in the folder EasyAccess/Server/license and then the EasyAccess server is restarted to read it.

License upgrades can only be done by manually replacing the old license.p12 file with a new license file with the exact same name and then restarting the server.

Downloading a License File from MyClavister

A license file is downloaded with the following steps:

  1. Log into the relevant MyClavister account at https://my.clavister.com.

  2. Select the Register License option from the Licenses menu.

    Licenses Menu

    Figure 2.2.  Licenses Menu

  3. Select EasyAccess from the product choices.

    EasyAccess Product Selection

    Figure 2.3. EasyAccess Product Selection

  4. Enter the License Number and EasyAccess ID codes. This will be supplied by your Clavister sales office. Note that the codes shown below are examples only.

    EasyAccess License Codes

    Figure 2.4. EasyAccess License Codes

  5. After confirming the dialog, the system will indicate the codes have been accepted. Press View License to get to the license download page.

    License Codes Accepted Confirmation

    Figure 2.5. License Codes Accepted Confirmation

  6. A summary of the license will now be displayed and pressing the EasyAccess Certificate button will download the license file.

    License View Page

    Figure 2.6. License View Page

License Checking After Expiry

When the EasyAccess server starts, it checks for the local license in the license folder. If this license has expired it will check the external PCS license validation server for permission to continue. If the PCS server denies this, relevant log messages are written and the server will not continue with full functionality.

If the PCS server cannot be contacted, this will be logged by the EasyAccess server which will continue normal operation. Every 24 hours the EasyAccess server will retry contacting the PCS server and after 7 failed attempts, EasyAccess server functions will become restricted.

To then restore normal EasyAccess server operation, either the local license file must be replaced followed by a restart or the PCS server must be updated so the existing license will be validated.

It is not possible to turn off external license validation against the PCS server.

2.4. Server Protocols and Ports

Below is a description of the protocols and ports used for traffic to and from the EasyAccess server.

Incoming Traffic

HTTP 8443 for:

  • Configuration Manager (/config).

  • MFA Admin (/mfaadmin).

  • Self Service (/selfservice).

  • MyApps (/myapps).

  • OnePass, if "Online key provisioning" is enabled.

  • One Touch authentication.

  • SAML.

  • HTTP API.

RADIUS (UDP), common ports 1645/1812.

Hazelcast, if clustering has been configured.

Outgoing Traffic

HTTPS 443 against:

  • PhenixID Message Gateway, if configured:
    msggweu.phenixidentity.com, msggweu1.phenixidentity.com.

  • PCS, used for licensing and "One Touch Push notifications": pcs.phenixidentity.com.

  • BankID, if configured: appapi2.bankid.com/rp/v4, appapi2.test.bankid.com/rp/v4.

LDAP, common ports 389/636.

JDBC, common ports 3306/1433.

SMTP, common ports 25/465/587.

Hazelcast, if clustering has been configured.

Internal Traffic

PhenixID Server default port: HTTPS 8443.

Hazelcast, 5701-5702 and 47000.

OrientDB, 2424.

2.5. External Database Setup

From EasyAccess version 4.0 onwards, the possibility exists to use an external database server which can be either a MySQL or an MSSQL database (details for HSQLDB are also included in this section but this is usually only the default internal database). These databases can be running on a separate computer or the same computer as an EasyAccess server. If an EasyAccess installation is to be part of a cluster then an external database server must be used instead of the internal database.

This section will not discuss setting up these external databases in depth. The documentation related to each database product should be referenced for the setup procedure. However, this section will describe the changes to EasyAccess that must be made in order to get the EasyAccess server to use an external database instead of its internal database.

Configuring EasyAccess to use an External Database

To change the EasyAccess server configuration to use an external database, go to the EasyAccess/Server/config folder and open the boot.json file in a suitable text editor.

Locate the following section:

{
	"name": "com.phenixidentity~phenix-store-mpl",
	"config": {
				"
				"
	}
},

Replace the above section with one of the following, depending on the type of database used:

  • For the default internal HSQLDB database:

    {
    	"name": "com.phenixidentity~phenix-store-mpl",
    	"config": {
    	"user": "phenixid",
    	"password": "<password>",
    		"encryption.key": "<encryptionkey>",
    		  "export_start": "15:00",
    		  "driver_class": "org.hsqldb.jdbc.JDBCDriver",
    		  "dataretention": "60",
    		  "is_server": "true",
    		  "server.address": "0.0.0.0",
    		  "url": "jdbc:hsqldb:hsql://localhost:9001/phenixid"
    	}
    }
  • For an external MySQL database:

    {
    	"name": "com.phenixidentity~phenix-store-mpl",
    	"config": {
    	"user": "<user_name>",
    		"password": "<password>",
    			"encryption.key": "<encryptionkey>",
    			  "export_start": "15:00",
    			  "driver_class": "com.mysql.cj.jdbc.Driver",
    			  "dataretention": "60",
    			  "is_server": "false",
    			  "url": "jdbc:mysql://172.24.0.3:3306/phenixid"
    	}
    }
  • For an external MSSQL database:

    {
    	"name": "com.phenixidentity~phenix-store-mpl",
    	"config": {
    	"user": "dummy",
    	"password": "dummy",
    	"encryption.key": "<encryptionkey>",
    	  "export_start": "15:00",
    	  "driver_class": "com.microsoft.sqlserver.jdbc.SQLServerDriver",
    	  "dataretention": "60",
    	  "is_server": "false",
    	  "url": "jdbc:sqlserver://172.24.0.3:1433;instance=sqlexpress;
    		       databaseName=phenixid;integratedSecurity=true;"
    	}
    }

Note the following about the above changes:

  • For MySQL and MSSQL, the parameter "url" will be dependent on the database of choice. This value should be provided by the person(s) responsible for the database configuration.

  • The default database name, "phenixid", can be changed for MySQL and MSSQL but NOT for the EasyAccess internal HSQLDB database. For HSQLDB, the SQLConnector class must be changed and instructions for doing this can be found in the file Changedatabasename.zip which can be downloaded from the following link:

https://media.screensteps.com/attachment_assets/assets/004/134/741/original/Changedatabasename.zip

Initializing External Databases

Before restarting the modified EasyAccess so it tries to connect to an external database, the external databases themselves should be set up be available over a network to the EasyAccess server (this is not needed with the internal HSQLDB database). For details on installing the various external database options, each product's own documentation should be referred to. However, the following should be noted about the initial configuration for each database:

  • For an external MySQL database:

    The file mysql_phenixid.sql from the downloadable SQLImport.zip tools archive should be used to create the initial MySQL database structure.

  • For an external MSSQL database:

    The file mssql_phenixid.sql from the downloadable SQLImport.zip tools archive should be used to create the initial MSSQL database structure.

The SQLImport.zip file can be downloaded from the following link:

https://media.screensteps.com/attachment_assets/assets/004/005/043/original/SQLImport.zip

Chapter 3: Management Access

This section describes the EasyAccess configuration manager interface

Once the EasyAccess server is running, the administrator can connect to its configuration manager web interface (WebUI) using a standard web browser. The IP address of the server along with the port number specified during installation should be entered into the browser's address field using the following format:

 https://<IP-address>:8443

If the browser is running on the same computer as the server then the localhost address can be used, as shown below.

Browser Navigation to the EasyAccess Server

Figure 3.1. Browser Navigation to the EasyAccess Server

The browser will then require that a security exception is granted by the administrator before continuing. This is because the EasyAccess server uses a self-signed certificate for HTTPS. Select the Advanced option in the browser and confirm the exception.

If connection to the server fails then check the following:

  • The EasyAccess server is running.

  • The correct port number is being used for connection.

  • The license is still valid. An invalid license will be indicated by a log message in the server.log file which can be found in the EasyAccess/Server/Logs folder of the installation.

After successful connection to the server, the administrator login screen will appear. The credentials entered must match the credentials that were specified during the installation process.

Administrator Login to the Configuration Manager WebUI

Figure 3.2. Administrator Login to the Configuration Manager WebUI

After successful login, the Start page of the EasyAccess interface will appear.

The Configuration Manager Start Page

Figure 3.3. The Configuration Manager Start Page

The initial Start page of the interface contains the following elements:

  • The Connection Overview

    This displays a summary of the current EasyAccess connections, both incoming and outgoing. After initial installation this will be empty except for the default management HTTP connection. This display will change as new connections are added.

Configuration Manager WebUI - Connection Overview

Figure 3.4. Configuration Manager WebUI - Connection Overview

  • Latest Events

    This is a list of the latest server events.

Configuration Manager WebUI - Latest Events

Figure 3.5. Configuration Manager WebUI - Latest Events

The sections that follow will explain how to use this interface to set up some basic EasyAccess features.

Chapter 4: LDAP Server Setup

After successfully connecting to the EasyAccess server and logging in to the configuration manager WebUI, one of the first basic tasks to perform will be to set up an EasyAccess connection to a user store that holds the credentials of authenticating users. Connections define the way EasyAccess communicates with external devices and servers. They can be either outgoing (LDAP, JDBC, HTTP), incoming (RADIUS) or the HTTP management connection (one of which is already predefined).

In this section, it is assumed that a connection is required to a user store which is an LDAP server. This LDAP server connection will be used later in Section 5.2, RADIUS with Token Scenario Setup.

First, the EasyAccess guide for new connections must be started. The term guide is used in EasyAccess to refer to what Windows would call a wizard. Each guide consists of a sequence of steps which ask for the required input data. Forward and back links at the bottom of each step are used for navigation.

Start the guide for a new connection by going to Scenarios > Connections and selecting the plus button on the LDAP option.

Add an LDAP Connection

Figure 4.1. Add an LDAP Connection

The initial step in the guide asks for a name for this connection.

LDAP Connection Name

Figure 4.2. LDAP Connection Name

Next, specify how to connect to the server. The value localhost is used if the LDAP server is on the same computer. Otherwise, an IP address or FQDN can be specified. Multiple servers for failovers can be specified as a comma separated list.

LDAP Host Connection

Figure 4.3. LDAP Host Connection

In the next step, specify the distinguished name (DN) of the account performing the lookup along with the server password. The account must have read/write access.

LDAP Host Connection

Figure 4.4. LDAP Host Connection

The final step in defining the LDAP server is to specify if the connection should be encrypted and use SSL/TLS. If enabled, SSL/TLS must also be enabled on the LDAP server. To establish trust between the EasyAccess and the LDAP server, the LDAP server SSL certificate chain must be added to the EasyAccess server trust store (doing this is not described here).

Enable Trust all to skip trust checking.

LDAP SSL/TLS Encryption

Figure 4.5. LDAP SSL/TLS Encryption

Before leaving the guide to finish setup, the connection to the LDAP server can be tested. If the connection fails, the previous steps in the guide can be reviewed for errors.

LDAP Connection Test

Figure 4.6. LDAP Connection Test

If communication with the server is successful then the next step will summarize this connection's parameters and the Create option at the bottom can be selected to save the connection.

LDAP Connection Create

Figure 4.7. LDAP Connection Create

The saved connection now appears in the navigation menu under Scenarios > Connections.

Display Saved LDAP Connections

Figure 4.8. Display Saved LDAP Connections

This saved LDAP connection will be used in later scenarios, such as Section 5.2, RADIUS with Token Scenario Setup, where a simple OTP scenario is set up.

Chapter 5: RADIUS Setup

RADIUS scenarios are used in EasyAccess to handle incoming RADIUS connections. The EasyAccess server can act as a RADIUS server and respond to incoming RADIUS authentication requests. The response may be the simple authentication of username and password credentials against a user database, or authentication may include one of the many multifactor authentication options that EasyAccess provides.

Setting up various types of example RADIUS scenarios will be described in the subsections that follow.

5.1. Basic RADIUS Scenario Setup

This section discusses setting up EasyAccess to do basic RADIUS authentication of username and password credentials, without any form of additional multifactor authentication.

To set up a basic RADIUS connection, go to Scenarios > Connections in the configuration manager WebUI and select the plus button on the RADIUS option.

Add a RADIUS Connection

Figure 5.1. Add a RADIUS Connection

A guide will now begin which prompts for the information required.

The guide prompts for the IP address and port to listen on for RADIUS requests. A value of 0.0.0.0.0 means that listening will be for all IP addresses.

Specify the RADIUS Connection Listening Addresses

Figure 5.2. Specify the RADIUS Connection Listening Addresses

The next step in the guide shows a summary of the RADIUS connection.

RADIUS Connection Summary

Figure 5.3. RADIUS Connection Summary

Select the Create option at the bottom to save the connection.

Create RADIUS Connection

Figure 5.4. Create RADIUS Connection

The saved connection now appears in the navigation menu under Scenarios > Connections.

Display Saved RADIUS Connections

Figure 5.5. Display Saved RADIUS Connections

This saved RADIUS connection will now be used in the next section where a simple OTP scenario is set up.

5.2. RADIUS with Token Scenario Setup

This section describes how a typical multi-factor authentication scenario is configured. In this case, the scenario of RADIUS with username/password and token will be configured where a generated one time password (OTP) will be used as the additional authentication factor.

The first step is to go to Scenarios > RADIUS and then press the plus button on the scenario called Username, password and token.

Add RADIUS with Token Scenario

Figure 5.6. Add RADIUS with Token Scenario

A guide will now open to gather the required data for this scenario. In the first guide step, specify a suitable name for this scenario along with an optional description.

RADIUS with Token Scenario - Name and Description

Figure 5.7. RADIUS with Token Scenario - Name and Description

In the next guide step, select a user store. In this example, the LDAP store created in Chapter 4, LDAP Server Setup will be selected. It is also possible to select the Create new option to create a user store connection on the fly.

RADIUS with Token Scenario - User Store Selection

Figure 5.8. RADIUS with Token Scenario - User Store Selection

Now, specify a filter to find the user. In this case, it is enough to use the username. The Search base defines the root on the LDAP server where the users are found.

RADIUS with Token Scenario - LDAP User Filter

Figure 5.9. RADIUS with Token Scenario - LDAP User Filter

The RADIUS connection to use is now specified next. This determines the RADIUS requests that EasyAccess will listen for. In this example, the connection specified in Section 5.1, Basic RADIUS Scenario Setup is selected. Alternatively, a new RADIUS connection could be specified on the fly by selecting Create new.

RADIUS with Token Scenario - RADIUS Selection

Figure 5.10. RADIUS with Token Scenario - RADIUS Selection

The next guide step allows the acceptable IP addresses of connecting RADIUS clients to be specified. In addition the shared secret password that the client needs can be specified along with an optional Attribute Selector. The attribute selector is used if different authentication methods can be chosen. For example, a valid value might be 44=SMS.

RADIUS with Token Scenario - RADIUS Client Filter

Figure 5.11. RADIUS with Token Scenario - RADIUS Client Filter

Optionally specify that a PIN must appear either before or after the OTP, along with the user store attribute that will contain the code.

RADIUS with Token Scenario - PIN Code

Figure 5.12. RADIUS with Token Scenario - PIN Code

In the final guide step, select Create to save the scenario.

Create RADIUS Token Scenario

Figure 5.13. Create RADIUS Token Scenario

The EasyAccess server is now ready to accept authenticating RADIUS connections.

5.3. RADIUS with OneTouch Scenario Setup

This section describes how a OneTouch authentication scenario is configured. The Clavister OneTouch product is a downloadable app that allows authentication of a connection to a NetWall firewall as an additional factor to username and password credentials. Authentication with username and OneTouch only, without a password, is possible and is discussed separately in Section 6.7, Passwordless Federation Authentication.

A link is established once between the OneTouch app and the EasyAccess server. When the user then needs to be authenticated later, EasyAccess pushes a message to the app asking for confirmation of the login. The user sends a confirming message back to EasyAccess with a single button press. EasyAccess then completes authentication of the connection.

The setting up of the OneTouch scenario involves the following steps:

A. Create the global OneTouch configuration object in Easy Access.

B. Create a RADIUS OneTouch scenario.

C. Enroll users for OneTouch. This is done by the administrator using the WebUI or by the users themselves through self service.

The steps in the above list will now be described in detail.

A. Create the global OneTouch configuration object

A OneTouch object needs to be created. There can only be a single global OneTouch object created for each EasyAccess installation and this will be automatically associated with any OneTouch scenario that is created. Go to Scenarios > System and select the add button next to One Touch.

Create the Global OneTouch object

Figure 5.14. Create the Global OneTouch object

An EasyAccess guide now opens that will collect the required data for OneTouch in a series of steps. The first guide step allows the issuer name to be specified. This name will be displayed by the OneTouch client.

Specify the OneTouch Issuer

Figure 5.15. Specify the OneTouch Issuer

The next guide step allows the external URL to be specified. This will be used as a prefix for building callback URLs for use by the One Touch client for both activation and fetching assignments. The URL may be the actual endpoint of the EasyAccess server but can also be a logical endpoint redirected to the actual server by a firewall or reverse proxy. Using such redirection is recommended.

The URL prefix should be chosen with care since this value cannot be changed for activated clients. HTTPS should be used as the URL protocol.

Specify the External URL Prefix

Figure 5.16. Specify the External URL Prefix

The next guide step asks if push notifications should be enabled. This would normally by activated. If it is not activated then OneTouch will work but the client device will not receive notifications that the OneTouch app has received an assignment. If the feature is not activated here it cannot be switched on later by the administrator or in the self service function.

Enable Push Notifications

Figure 5.17. Enable Push Notifications

In the final guide step, select Create to save the scenario.

Save the OneTouch Configuration

Figure 5.18. Save the OneTouch Configuration

B. Create a RADIUS OnTouch scenario

To create the scenario go to Scenarios > RADIUS and then press the plus button on the scenario called Username, password and OneTouch.

Add RADIUS with OneTouch Scenario

Figure 5.19. Add RADIUS with OneTouch Scenario

A guide will now open to gather the required data for this scenario. In the first guide step, specify a suitable name for this scenario along with an optional description.

RADIUS with OneTouch Scenario - Name and Description

Figure 5.20. RADIUS with OneTouch Scenario - Name and Description

In the next guide step, select a user store. In this example, the LDAP store created in Chapter 4, LDAP Server Setup will be selected. It is also possible to select the Create new option to create a user store connection on the fly.

RADIUS with OneTouch Scenario - User Store Selection

Figure 5.21. RADIUS with OneTouch Scenario - User Store Selection

Now, specify a filter to find the user. In this case, it is enough to use the username. The Search base defines the root on the LDAP server where the users are found.

RADIUS with OneTouch Scenario - LDAP User Filter

Figure 5.22. RADIUS with OneTouch Scenario - LDAP User Filter

The RADIUS connection to use is now specified next. This determines the RADIUS requests that EasyAccess will listen for. In this example, the connection defined in Section 5.1, Basic RADIUS Scenario Setup is selected. Alternatively, a new RADIUS connection could be specified on the fly by selecting Create new.

RADIUS with OneTouch Scenario - RADIUS Selection

Figure 5.23. RADIUS with OneTouch Scenario - RADIUS Selection

The next guide step allows the acceptable IP addresses of connecting RADIUS clients to be specified. In addition the shared secret password that the client needs can be specified along with an optional Attribute Selector. The attribute selector is used if different authentication methods can be chosen. For example, a valid value might be 44=SMS.

RADIUS with OneTouch Scenario - RADIUS Client Filter

Figure 5.24. RADIUS with OneTouch Scenario - RADIUS Client Filter

In the next guide step, select Create to save the scenario.

Create RADIUS Token Scenario

Figure 5.25. Create RADIUS Token Scenario

The EasyAccess server is now ready to accept authenticating RADIUS connections. It will be automatically associated with the OneTouch configuration that was created in step A.

C. Enroll users for OneTouch

Enrolling users for OneTouch can be done in one of the following ways:

  • Users can enroll themselves using the self service function. The self service function must be enabled for this and this is discussed further in Chapter 8, Self Service Setup.
  • The administrator can enroll users through the EasyAccess WebUI. This is discussed next.

To enroll users in the EasyAccess WebUI, go to Scenarios > Applications > One Touch Enrollment and press the plus button.

OneTouch User Enrollment

Figure 5.26. OneTouch User Enrollment

An EasyAccess guide will open to collect the data required. The first step asks for a user store that contains users.

OneTouch Enrollment - User Store Selection

Figure 5.27. OneTouch Enrollment - User Store Selection

Specify the search settings for the user store. The search base is the search starting point in the directory tree. It can be entered manually or selected by using the Choose option. Searching is done using the scope "SUB". This value is mandatory, with LDAP DN as the required syntax.

The attribute used to identify users (such as uid, email or samaccountname) must also be specified.

OneTouch Enrollment - User Search Settings

Figure 5.28. OneTouch Enrollment - User Search Settings

Specify if push notifications are to be enabled. These are used for notifying users of pending assignments and are normally enabled.

OneTouch Enrollment - Enable Push Notifications

Figure 5.29. OneTouch Enrollment - Enable Push Notifications

In the final guide step, select Create to save the enrollments.

OneTouch Enrollment - Saving

Figure 5.30. OneTouch Enrollment - Saving

After saving the OneTouch configuration, the object parameters are presented and can be edited. Some parameters can be changed that could not be set in the guide. For example, the OneTouch connection URI value can be changed.

OneTouch Enrollment - URI Value

Figure 5.31. OneTouch Enrollment - URI Value

Regardless how enrollment is done, users themselves must still create a link between their tOneTouch app installation and EasyAccess. If the OneTouch URI is left as the default value of activateonetouch then this is done by the user opening the following URL in a web browser.

	https://<EasyAccess-server-DNS-name>:8443/activateonetouch

Note that the URI must begin with the "/" character and it must be unique within the EasyAccess instance.

Under the Tokens tab, the maximum number of allowed tokens for a user can be specified. Leaving this field blank means the number is unlimited.

OneTouch Enrollment - Maximum Tokens

Figure 5.32. OneTouch Enrollment - Maximum Tokens

When all changes are complete, press the Save link and the EasyAccess server will restart with the changes applied.

OneTouch Enrollment - Save Configuration

Figure 5.33. OneTouch Enrollment - Save Configuration

After installing the OneTouch app and either being enrolled by the administrator or enrolling through self service, the user can now initiate connection to the OneTouch URI and link the app to EasyAccess.

5.4. Passwordless RADIUS Authentication

It is possible to configure RADIUS scenarios so that only a username is required during authentication and not a password. This is done by editing the scenario after it is first set up in the WebUI.

However, it should be noted that other forms of multi-factor authentication might still be used with such RADIUS scenarios, for example OTP, even though the password is not required.

Removing Password Checking from the Execution Flow

With RADIUS scenarios, EasyAccess cannot change the way that the client displays the request for access credentials so the password field will still be displayed, unless the client can be somehow modified. However, password authentication processing can be skipped in EasyAccess by removing the LDAPBindValve from the scenario's execution flow.

For example, assume that a RADIUS Username, Password and OneTouch has been created. Select Scenarios > RADIUS > Username, Password and OneTouch and open the scenario. Select the Execution Flow tab and then delete the valve called LDAPBindValve.

Passwordless RADIUS - Delete LDAPBindValve

Figure 5.34. Passwordless RADIUS - Delete LDAPBindValve

The scenario can now be saved and authentication will execute as normal (usually with some other authentication factor such as OneTouch) but without the password being checked.

Chapter 6: Federation (SAML) Setup

Introduction

Identity Federation allows a separate Identity Provider (IdP) to act as an identity authenticator for users accessing a Service Provider (SP). Typically, service providers are HTTP server applications. These applications may be within a single organization or provided by different organizations. A single identity provider might provide authentication for several service providers.

Security Authentication Markup Language (SAML) is used to pass authentication information via a web browser between an IdP and an SP. Service providers must be set up to trust the SAML Assertions that are provided by a specific IdP. These assertions verify that a user has been authenticated by the IdP so the service provider does not need to perform further authentication.

Identity Federation with EasyAccess

EasyAccess provides a set of Federation scenarios. Each scenario might use either simple username and password authentication, or multi-factor authentication, such as Username, Password and OneTouch. When federation scenarios are created, an identity provider is also created which can generate SAML assertions for access to service providers. In other words, EasyAccess acts as an IdP.

Authentication Flow

The detailed flow of authentication in a typical federation scenario is the following:

  1. The user connects to a service provider by navigating a web browser to an HTTP server URL.

  2. The web browser is redirected by the server to the EasyAccess server for authentication.

  3. EasyAccess presents one or more webpages to authenticate the user. Depending on the federation scenario chosen, this may involve one of the EasyAccess multi-factor authentication methods, such as OneTouch.

  4. When successfully authenticated, EasyAccess provides a SAML assertion to the browser.

  5. The browser is redirected back to the original HTTP server.

  6. The HTTP server now uses the SAML assertion to verify that the user is authenticated.

  7. The user is allowed access to the application at the original URL by the HTTP server.

The subsections that follow describe the setup required for various types of federation scenarios.

6.1. Basic Federation Scenario Setup

Creating a basic federation scenario in the EasyAccess WebUI will now be described in detail. The scenario created will rely on simple username and password authentication but any of the available multi-factor authentication options could be included. In addition, it is assumed the scenario will be for connection to a single external service provider.

Authenticating with multiple service providers using Single Sign On (SSO) is a special case of identity federation and setting this up in EasyAccess is discussed separately in Section 6.2, SSO Setup. However, this section should be reviewed first before looking at more complex scenarios.

A. Add Keystore

A PKCS12 file with a filetype of .p12 containing a single cryptographic key pair must be uploaded to EasyAccess to create a Keystore. This is a signed certificate which will be used by EasyAccess when it creates the SAML IdP Metadata XML file that will be used by a service provider to read generated SAML assertions. Once uploaded, a keystore can be shared across many EasyAccess scenarios.

EasyAccess provides the option to use a predefined EasyAccess self-signed keystore but this option should be selected for testing purposes only since it provides minimal security.

Uploading a new keystore is done by selecting Scenarios > Federation and pressing the plus button next to the Keystore option.

Federation Scenario - Add KeyStore

Figure 6.1. Federation Scenario - Add KeyStore

A guide will now open and the first guide step is to enter a name and optional description for the keystore.

Federation Scenario - Specify KeyStore Name

Figure 6.2. Federation Scenario - Specify KeyStore Name

In the next step, drag and drop a PKCS12 file into the box provided and enter the private key password to unlock the file. The password must be specified and must be correct in order to continue to the next step. The Verify and show link can be selected to check that the password matches and to show a verified summary of the uploaded file's contents.

Federation Scenario - Specify File and Password

Figure 6.3. Federation Scenario - Specify File and Password

Press Next and then Create to save the keystore.

B. Specify Service Provider's SAML Metadata

Specifying the metadata by selecting Scenarios > Federation > SAML metadata upload and pressing the plus button next to SAML metadata upload.

Federation Scenario - Upload Service Provider's Metadata

Figure 6.4. Federation Scenario - Upload Service Provider's Metadata

A guide will now open and the first guide step is to enter a name and optional description for the metadata.

Federation Scenario - SAML SP Metadata Name

Figure 6.5. Federation Scenario - SAML SP Metadata Name

In the next step, drag and drop the metadata XML file into the box provided. Alternatively, specify a URL where the metadata can be found if the service provider makes it available in this way. The Verify and show link can be selected to show a verified summary of the metadata and is also useful to check if a specified SP URL works for fetching the SP metadata.

Federation Scenario - SAML SP Metadata Upload

Figure 6.6. Federation Scenario - SAML SP Metadata Upload

Press Next and then Create to save the metadata source.

C. Define a Federation Scenario

In the EasyAccess WebUI, go to Scenarios > Federation and create a new scenario with the desired type of authentication by pressing the relevant plus button. In this example, the simplest type of scenario will be used which is Username and Password only, without any multifactor authentication. The SAML related setup steps will be the same for any of the other federation scenarios.

Federation Scenario - Add Scenario

Figure 6.7. Federation Scenario - Add Scenario

A guide will now open and the first guide step is to enter a name and optional description for the scenario.

Federation Scenario - Specify Scenario Name

Figure 6.8. Federation Scenario - Specify Scenario Name

In the next guide step, select a user store. In this example, the LDAP store created in Chapter 4, LDAP Server Setup will be selected. It is also possible to select the Create new option to create a user store connection on the fly.

Federation Scenario - User Store Selection

Figure 6.9. Federation Scenario - User Store Selection

Now, specify a filter to find the user. In this case, it is enough to use the username. The Search base defines the root on the LDAP server where the users are found.

Federation Scenario - LDAP User Filter

Figure 6.10. Federation Scenario - LDAP User Filter

In the next step, specify an entity ID. This can be any string with no spaces but it must be unique within the SAML federation. Also, specify the post SSO URL, which must be reachable by devices using the federation. This is the URL which the service provider will redirect to for authentication. This URL can also be used by the service provider for downloading the IdP SAML metadata.

The URL specified must have the following form:

	<http/https>://<host>/saml/authenticate/<unique_identifier>
Federation Scenario - Entity ID and URL

Figure 6.11. Federation Scenario - Entity ID and URL

Next, select the keystore that was previously uploaded for this scenario. It is possible to select EasyAccess generated keystores but these are self-signed and should be used for testing purposes only.

Federation Scenario - Select Keystore

Figure 6.12. Federation Scenario - Select Keystore

Enter the attribute used as the user identifier. This is the attribute the user will enter at login. This is also the value that will be marked as the nameid in the assertion token. Any additional attributes incorporated in the assertion (SAML Attribute statement) are entered in the Additional attributes field. Multiple attributes are separated by commas.

Federation Scenario - Specify User Attribute

Figure 6.13. Federation Scenario - Specify User Attribute

Specify a default service provider URL to be used with unsolicited SAML requests. Instead of trying to access the service provider first, a user could navigate their web browser directly to the EasyAccess server and this is the meaning of "unsolicited requests". If the Default SP value is left as the value Select default SP then such unsolicited requests will be ignored by EasyAccess.

Alternatively, if the Default SP is set to a particular service provider's URL then this is the URL the browser will be redirected to with the SAML assertion that EasyAccess generates when an unsolicited SAML request arrives (assuming that the user is successfully authenticated first).

For convenience, a selection is also provided in the WebUI to use the test SAML site samltest.id as the default SP. This can be useful for testing purposes and more information about this test site can be found at the following link:

https://samltest.id/

Federation Scenario - Default SP

Figure 6.14. Federation Scenario - Default SP

In the final guide step, select Create to save the scenario.

Create Federation Scenario

Figure 6.15. Create Federation Scenario

After a short delay, the scenario will be available to process traffic.

E. Configure the Service Provider

The service provider must be correctly configured with the SAML Metadata of the IdP (in this case EasyAccess). The metadata is supplied in one of the following ways:

  • As a URL on the EasyAccess server. This URL is specified by the Post SSO URL.

  • As an XML file. This file must be created by opening the post SSO URL in a browser and manually copying the XML data into a file. The data can be found by opening the scenario for editing in the EasyAccess WebUI, selecting the Identity Provider tab and selecting the link View SAML Metadata.

    The metadata link can be manually constructed in a browser navigation field by appending the string "?getIDPMeta" to the post SSO URL. For example, if EasyAccess is running as the local host, the URL to display the IdP metadata might be the following:

     https://localhost:8443/saml/authenticate/samlauth?getIDPMeta

Service providers often have unique requirements for how they are set up to operate with SAML and it is not possible for this section to document this for every possible provider. Usually, the service provider themselves will supply a description of what is required.

Customizing the SAML assertions that EasyAccess generates for a service provider is described in Section 6.4, Customizing SAML Assertions.

6.2. SSO Setup

This section describes how to set up a Single Sign On (SSO) capability in EasyAccess. SSO is a special type of federation scenario. The initial authentication of a user is the same as for a normal federation scenario wih a single service provider. However, the user can then change to a another service provider (often within the same organization) within the same browser session, without having to authenticate again.

The sequence of processing steps for SSO is the same as those described at the beginning of Section 6.1, Basic Federation Scenario Setup for a standard federation scenario with a single service provider. However, the following additional steps will occur when the user tries to access additional service providers during the same browser session.

  1. The new service provider redirects the browser back to EasyAccess for authentication.

  2. The browser's old SAML assertion for the first service provider tells EasyAccess that the user has already been authenticated so EasyAccess provides a new SAML assertion to the browser for the new service provider without further authentication.

  3. The browser is redirected back to the new service provider with the new SAML assertion.

  4. The service provider accepts the SAML assertion and allows access.

The detailed setup steps for SSO are the following:

A. Set up a Federation Scenario

Set up a federation scenario as normal. Doing this is described in Section 6.1, Basic Federation Scenario Setup. The scenario could use simple username and password authentication or could use one of the multi-factor authentication options.

Note that, instead of the metadata for just a single service provider being uploaded to EasyAccess in the scenario, the metadata for all the potential service providers should be uploaded.

B. Modify the Scenario's Execution Flow

Changes are required to the valves in the scenario's execution flow. The list of valves that will be required in this particular example are the following and in the following order:

  • LockoutCheckValve
  • InputParameterExistValidatorValve
  • LDAPSearchValve
  • LDAPBindValve
  • AuthnRequestDecoder
  • AssertionProvider (one for each service provider)

The above valves will now be described in detail:

  • The default LockoutCheckValve should be left as it is. This checks if the user is locked out for any reason such as too many authentication attempts. This valve could be left out while testing the setup but should be included in a production environment.

  • The default InputParameterExistValidatorValve can also be left as it is. This checks that the user has entered a password.

  • The LDAPSearchValve is needed to retrieve the user's data based on username. The attributes property specifies which user data will be available to subsequent valves. This property may need to be changed to include data required in the SAML assertion sent to particular service providers. Below is a JSON example which shows some typical values.

    {
      "name": "LDAPSearchValve",
      "enabled": "true",
      "config": {
        "connection_ref": "bbd7198c-0a6c-43aa-b62b-cd7552c8b4cf",
        "base_dn": "DC=maso,DC=lan",
        "scope": "SUB",
        "size_limit": "0",
        "filter_template": "samAccountName=",
        "attributes": "objectGUID,samAccountName,sn,mail,givenName",
        "binary_attrs": "objectGUID"
      }
    },

    Note that the connection_ref value is automatically set when the connection is selected during scenario creation in the WebUI.

  • The default LDAPBindValve can be left as it is. This authenticates the entered password against the stored LDAP value.

  • Insert an AuthnRequestDecoder. This must be included before multiple AssertionProvider instances (which is the case with SSO) when each instance is testing the issuer property. This valve needs no customization and its default values are listed below.

    {
      "name": "AuthnRequestDecoder",
      "enabled": "true",
      "config": {
        "proceed_on_error": "false"
       }
     },
  • Ensure there is an AssertionProvider valve for each service provider so that the required values for the additionalAttributes property are specified for the SAML assertion created. The following AssertionProvider example would only be used if the service provider name is MyExampleSP.

    {
      "name": "AssertionProvider",
      "enabled": "true",
      "config": {
        "targetEntityID": "f1dab3a5-02a0-43c6-afef-9d8e39323eb3",
        "nameIDAttribute": "sAMAccountName",
        "additionalAttributes": "userid,mail,givenName",
        "exec_if_expr": "flow.property('issuer').equals('MyExampleSP')"
      }
    },

    Note that the targetEntityValue for all assertions must be the same ID value of the scenario identity provider. Also note that the additionalAttributes can include any items in the list specified in the attributes property of the LDAPSearchValve specified earlier.

    Some service providers may require specific user data be included in the SAML assertion with specific property names. Customizing SAML data is discussed further Section 6.4, Customizing SAML Assertions.

C. Configure the SAML Metadata on the Service Provider

The SAML IdP Metadata for this scenario must be configured on the service provider. The metadata can be configured either in a file or as a URL on the EasyAccess server. This is described further in Section 6.1, Basic Federation Scenario Setup.

D. Set Up EasyAccess Redirection Without Authentication

When a user tries to connect to another service provider after being initially authenticated for the first provider, EasyAccess must be set up so it does not ask the user to authenticate again. Instead, EasyAccess will read the old SAML assertion from the browser and give the browser a new assertion before redirecting it back to the requesting service provider. Setting up this redirection in Easy Access requires the creation of a second, secondary federation scenario and doing this is described in Section 6.3, Redirecting SAML Requests.

6.3. Redirecting SAML Requests

This section describes how to set up EasyAccess to redirect SAML authentication requests when a user is already authenticated for a browser session. This is needed, for example, by the SSO setup described in Section 6.2, SSO Setup and when using the MyApps feature described in Section 6.5, MyApps Setup. It is assumed that a first federation scenario has already been created and redirection is required for that scenario. That first scenario will be referred to in this section as the primary scenario.

The setup steps for redirection are the following:

A. Get the ID of the Primary Scenario's Identity Provider

The id property value of the primary scenario's identity provider will be needed in this setup so this must first be retrieved by opening the advanced editor in the WebUI and selecting the pen next to the SAML 2 Identity providers option.

Edit SAML 2 IdP

Figure 6.16. Edit SAML 2 IdP

The primary identity provider can now be located and the id property value noted. An example of how the primary identity provider will appear in the editor is shown below.

{
  "id": "f1dab3a5-02a0-43c6-afef-9d8e39323eb3",
  "alias": "",
  "name": "SAML IDP",
  "keystore": "714e6ce2-31ca-49cc-baae-ce134d9ea2ad",
  "entityID": "my-federation-scenario",
  "requireSigned": "false",
  "postSSOURL": "https://example.com/saml/authenticate/samldispatch",
  "created": "2019-11-15T11:20:18.983Z",
  "modified": "2019-11-18T12:48:13.510Z"
}

In addition, the postSSOURL value must be changed to a special URL, as in the above, which has the form:

 https://<server-url>/saml/authenticate/<dispatch-alias>

When service providers redirect to this URL, EasyAccess processing will be performed by a special SAML Dispatch authenticator which will be defined later in this section. The <dispatch-alias> in the above URL is the alias name of this authenticator.

B. Set up a New Federation Scenario

Set up a new federation scenario with basic username and password authentication. This will be referred to as the secondary scenario and its purpose is to provide a new authenticator that will only be used when a user is already authenticated. The Entity ID and Post SSO URL values in this new scenario should both be different from the primary scenario.

Any key store can be configured in this new scenario since its identity provider will not be used. All SAML metadata is also the same as for the primary scenario so this too needs no further action.

C. Modify the Execution Flow of the Secondary Scenario

The initial valve list for this secondary scenario should be configured like the primary scenario and will include the same AuthnRequestDecoder and the same multiple AssertionProvider valves as the primary. However, there are some differences in the execution flow, which are described next:

  • Remove the InputParameterExistValidatorValve and LDAPBindValve in order to turn off password checking.

  • Insert a FlowFailValve after the initial LockoutCheckValve so that the flow will fail if the user is not already authenticated. The JSON for the default FlowFailValve is the following:

    {
      "name": "FlowFailValve",
      "config": {
        "message":"User does not exist",
        "skip_if_expr":"request.get('authenticatedrequest').equals('true')"
      }
    }
  • For each AssertionProvider, change the targetEntityID property to be the ID value of the primary scenario identity provider, which was obtained in step A. Below is the JSON for an example AssertionProvider.

    {
      "name": "AssertionProvider",
      "enabled": "true",
      "config": {
        "targetEntityID": "f1dab3a5-02a0-43c6-afef-9d8e39323eb3",
        "nameIDAttribute": "sAMAccountName",
        "additionalAttributes": "userid,mail,givenName",
        "exec_if_expr": "flow.property('issuer').equals('MyExampleSP')"
      }
    },

The resulting execution flow for the secondary scenario should now be the following:

  • LockoutCheckValve
  • FlowFailValve
  • LDAPSearchValve
  • AuthnRequestDecoder
  • AssertionProvider (one for each service provider)

B. Add a SAML Dispatcher

An entry point must be created for all SAML requests. There is a specific EasyAccess authenticator type for this purpose called Dispatch. This type is not part of any scenario so it must be created separately. This object must exist to redirect processing to the correct authenticator depending on if the user is already authenticated or not.

To create this, select the Advanced tab and click the pen icon besides the Authentication - HTTP option.

Choosing a New Valve

Figure 6.17. Choosing a New Valve

Next, add the following authenticator JSON definition anywhere. The idpID value must be set to the ID of the primary scenario's identity provider, obtained in step A. Note that the alias value (in this example, "samldispatch") needs to be appended to the authenticator's postSSOURL property, and this is also discussed in step A.

{
  "alias": "samldispatch",
  "name": "Dispatch",
  "configuration": {
    "idpID": "f1dab3a5-02a0-43c6-afef-9d8e39323eb3",
    "mapping": [
      {
        "!request.getParameter('authenticatedrequest').equals('true')",
        "authenticator": "1eacbcd4-29d8-4f60-b532-4bc9a91f14c2"
      },
      {
        "request.getParameter('authenticatedrequest').equals('true')",
        "authenticator": "c07e52b9-67e0-481b-948e-6a867962ab2b"
      }
    ]
  }
}

The respective authenticator properties in the above JSON must be set to the ID or alias for the primary scenario authenticator and secondary scenario authenticator. These values can also be found by opening the advanced editor, choosing the Authentication - HTTP option and then finding the authenticator.

D. Change the idpID Property of the Secondary Scenario Authenticator

The idpID value of the secondary scenario authenticator needs to be the same as the primary scenario authenticator so they point to the same identity provider (the identity provider created with the secondary scenario will not be used).

To do this, go to the advanced editor and click the pen icon next to Authentication - HTTP. Search for the secondary scenario's authenticator and change the idpID value to be the primary scenario's identity provider ID (this was obtained in step A). Below, is an example of doing this, with the idpID line highlighted.

Changing the idpID

Figure 6.18. Changing the idpID

Redirection setup is now complete.

6.4. Customizing SAML Assertions

In federation scenarios, each service provider may expect specific user data to be included in the SAML assertion created by EasyAccess and the included data may also need a specific attribute name in the assertion. The data itself may also need to be processed in some way, for instance converted from binary to a string, or possibly changed to all uppercase.

Such specific requirements can be met by including a set of custom valves in the execution flow for a scenario.

Below is a an example of such a customization:

  • An LDAPSearchValve will always be used to retrieve data for a specific user. The attributes property of the valve must specify all the data items that will be used later when creating assertions for different service providers.

    {
      "name": "LDAPSearchValve",
      "enabled": "true",
      "config": {
        "connection_ref": "bbd7198c-0a6c-43aa-b62b-cd7552c8b4cf",
        "base_dn": "DC=maso,DC=lan",
        "scope": "SUB",
        "size_limit": "0",
        "filter_template": "samAccountName=",
        "attributes": "objectGUID,samAccountName,sn,mail,givenName",
        "binary_attrs": "objectGUID"
      }
    },
  • One or more subsequent PropertyCopyValve instances can now be used in the scenario's execution flow to copy over user data to new attribute names that are required by the service provider in the SAML assertion. For example, the following valve will copy the sn attribute value fetched by the LDAPSearchValve above into a new attribute called last_name.

    {
      "name": "PropertyCopyValve",
      "enabled": "true",
      "config": {
        "proceed_on_error": "false",
        "source": "sn",
        "dest": "last_name"
      }
    },
  • Similarly, the givenName can be copied into a new attribute called first_name.

    {
      "name": "PropertyCopyValve",
      "enabled": "true",
      "config": {
        "proceed_on_error": "false",
        "source": "givenName",
        "dest": "first_name"
      }
    },
  • Various other valve types are available to perform a variety of data conversions where the service provider expects user data in a given form. For example, the following GUIDBinaryToStringValve will convert the binary objectGUID value to a string that is assigned to the assertion property called userid.

    {
      "name": "PropertyGUIDBinaryToStringValve",
      "enabled": "true",
      "config": {
        "proceed_on_error": "false",
        "source": "objectGUID",
        "dest": "userid"
      }
    },

    Note that the objectGUID can be a very useful object to pass in an assertion because it will not change, even if the username does.

  • The valve called PropertyToUpperValve could then be used to make sure that the new string property called userid is all uppercase.

    {
      "name": "PropertyToUpperValve",
      "enabled": "true",
      "config": {
        "proceed_on_error": "false",
        "source": "userid"
      }
    },
  • An AuthnRequestDecoder will need to be included if there are multiple service providers and therefore multiple AssertionProvider valves when each valve is testing the issuer property. No customization of this valve is required and its default values are listed below.

    {
      "name": "AuthnRequestDecoder",
      "enabled": "true",
      "config": {
        "proceed_on_error": "false"
       }
     },
  • Add an AssertionProvider for each service provider so that different values for the additionalAttributes property can be specified in the SAML assertion created for that provider.

    For example, the following assertion would only be used in the execution flow if the service provider is called MyExampleSP. This provider requires the additional properties of userid, mail and givenName in the SAML assertion given to it.

    {
      "name": "AssertionProvider",
      "enabled": "true",
      "config": {
        "targetEntityID": "f1dab3a5-02a0-43c6-afef-9d8e39323eb3",
        "nameIDAttribute": "sAMAccountName",
        "additionalAttributes": "userid,mail,givenName",
        "exec_if_expr": "flow.property('issuer').equals('MyExampleSP')"
      }
    },

    Note that the targetEntityValue for all assertions must be the ID value of the scenario's identity provider.

  • A second AssertionProvider can now be added for a second service provider called MyOtherExampleSP that requires the last_name and first_name data.

    {
      "name": "AssertionProvider",
      "enabled": "true",
      "config": {
        "exec_if_expr": "flow.property('issuer').equals('myOtherEaxampleSP')",
        "targetEntityID": "f1dab3a5-02a0-43c6-afef-9d8e39323eb3",
        "nameIDAttribute": "sAMAccountName",
        "additionalAttributes": "last_name,first_name,mail",
      }
    },

6.5. MyApps Setup

Introduction

It is possible to configure EasyAccess to act as a federation service provider. As a service provider, EasyAccess becomes an HTTP server which makes available a MyApps webpage. This webpage will contain HTML links to multiple HTTP applications found on other, external service provider servers. Typically, a MyApps page is used as a landing page for single sign on (SSO) access to various applications.

A MyApps webpage is set up in EasyAccess by creating a MyApps Scenario, which can be found under Scenarios > Applications in the EasyAccess WebUI. Multiple such MyApps scenarios can be created, each providing a different webpage with different sets of external service provider links.

When a user tries to access a MyApps webpage for the first time, EasyAccess acts like a normal SAML service provider and redirects the browser back to an identity provider within EasyAccess itself to generate a SAML assertion for the MyApps page. Following successful authentication, the user can then select any of the external services linked to by the webpage. However, if those external service providers are to also accept the initial authentication, they must have also been correctly configured to redirect back to the same EasyAccess identity provider for a new SAML assertion.

The identity provider to which a MyApps scenario points should already exist in EasyAccess so this may involve setting up a new federation scenario, possibly with a multifactor method. Setting up a basic federation scenario is described in Section 6.1, Basic Federation Scenario Setup. A key difference with MyApps as the service provider is that MyApps already has access to all the SAML metadata for any EasyAccess federation scenario. Similarly, federation scenarios do not need MyApps metadata uploaded. In addition, the same keystore is easily shared between MyApps scenarios and federation scenarios.

Note that it is also possible for the administrator to set up similar MyApps webpage functionality using a non-EasyAccess web server, but that will not be discussed further in this publication.

MyApps Usage with cOS Core and OneConnect

With Clavister NetWall devices, the MyApps feature can be used with the Clavister OneConnect app when it sets up an SSL VPN connection to the firewall. cOS Core acts as a RADIUS client and will connect to an EasyAccess RADIUS scenario to authenticate the OneConnect user. The RADIUS scenario can be set up with the URL of a webpage which cOS Core forwards back to OneConnect during authentication. OneConnect will automatically open this URL in the default web browser. The URL can be a MyApps webpage, with no further authentication required.

Setting up EasyAccess with OneConnect is described further in Section 6.6, SSO with OneConnect Setup. This section will discuss the general case for MyApps usage.

The MyApps Processing Sequence

The typical processing sequence with MyApps for SSO of several websites is as follows:

  1. The user is authenticated using a scenario in EasyAccess and tries to open a MyApps webpage on the same EasyAccess server. As mentioned above, this might occur because the user has used Clavister OneConnect to open an SSL VPN tunnel, and OneConnect has then opened the MyApps URL in the user's browser following successful authentication.

  2. The MyApps page acts like a normal service provider and redirects the user to the configured EasyAccess identity provider. An EasyAccess federation scenario should therefore already exist which contains the identity provider that supplies this assertion. This scenario may perform user authentication, however, it might get the authentication status from another scenario such as a RADIUS scenario (this is the case with the OneConnect client).

  3. EasyAccess supplies the assertion and the MyApps page appears in the user's browser.

  4. The user selects one of the service provider HTML links on the MyApps page.

  5. The browser tries to open the HTML link on the chosen service provider's server.

  6. The service provider's server redirects the browser back to EasyAccess, asking for a new SAML assertion, customized for that provider.

  7. Providing a federation scenario is correctly configured for that service provider, EasyAccess creates the new SAML assertion and redirects the browser back to the provider.

  8. The service provider allows browser access based on the new assertion.

  9. The user can later select another link on the MyApps page and and the same cycle of the new service provider redirecting back to EasyAccess to request another SAML assertion will repeat.

From the user's perspective, the flow described above means that they could be only authenticated once and then have access to any of the service providers on a MyApps webpage.

Setting Up a MyApps Scenario

The following steps are required to set up an EasyAccess MyApps scenario.

A. Create a MyApps scenario

The first step is to go to Scenarios > Applications and then press the plus button next to the MyApps option in order to begin creating a new MyApps scenario.

Create MyApps Scenario

Figure 6.19. Create MyApps Scenario

A guide will now open to gather the required data for this scenario. In the first guide step, specify a suitable name for this scenario along with an optional description. The guide defaults to the name MyApps but this could be different and should be unique within all MyApps scenarios created in the EasyAccess instance. The description is only used within EasyAccess itself and is not visible on the final MyApps webpage.

Create MyApps - Name and Description

Figure 6.20. Create MyApps - Name and Description

This guide step will also require the following:

  • The URI of the MyApps webpage. This string will be appended to the base URL of the EasyAccess server to get the full URL of this MyApps webpage. For example, if the URI is the default value of /myapps and the EasyAccess server URL is https://www.example.com, the MyApps page will be available at https://www.example.com/myapps.

  • The service provider identifier. This is the entityID of the service provider that EasyAccess will act as for this MyApps page. This string should be unique among all MyApps scenarios in the EasyAccess instance and among the service providers which this MyApps page will link to.

Create MyApps - URI and Service Provider

Figure 6.21. Create MyApps - URI and Service Provider

In addition, this guide step will also require the following:

  • A keystore must be selected which will be the same keystore used for the SAML assertions that this service provider will receive from an EasyAccess federation scenario. Uploading keystores is discussed in Section 6.1, Basic Federation Scenario Setup.

  • A pre-existing EasyAccess connection instance must be selected. This defines the HTTP port on which this MyApps page will be available. Normally, the predefined EasyAccess connection on port 8443 (HTTPS) would be selected.

  • The EntityID of the identity provider in EasyAccess which will generate a SAML assertion for this MyApps page. Usually, this will be the identity provider of a pre-existing federation scenario which will authenticate the user. If one does not exist, it will first need to be created.

Create MyApps - Keystore, Connection and IdP

Figure 6.22. Create MyApps - Keystore, Connection and IdP

In the final guide step, select Create to save the scenario.

Save MyApps Scenario

Figure 6.23. Save MyApps Scenario

The new MyApps webpage will be available to browsers which navigate to the URL specified for the scenario.

B. Add service provider URLs to the MyApps scenario

The next step is to edit the MyApps scenario that has been saved and to add a link for each service provider to the MyApps HTML page. The word application is used synonymously here with the SAML concept of service provider.

Go to Scenarios > Applications, select the MyApps scenario that was created in step A. Select the Applications tab and then select the Show link. This will display the MyApps Application List Pipe. Each CreateApplicationValve contained by this pipe corresponds to an HTML link to a service provider on this MyApps webpage.

Edit MyApps - Applications List

Figure 6.24. Edit MyApps - Applications List

By default, two example CreateApplicationValve instances are included in the pipe as examples. These can be deleted.

Next, add a new CreateApplicationValve by choosing the Add Valve option and selecting that valve from the drop-down list. This displays a dialog for entering a textual description and URL for the service provider. This will appear as one of the links on the MyApps webpage.

Edit MyApps - Application Definition

Figure 6.25. Edit MyApps - Application Definition

In addition, the following can also be optionally specified in a CreateApplicationValve:

  • SORT ORDER

    This is an integer which represents the position of the link on the webpage.

  • IMAGE

    An image can be specified for the webpage link.

  • CATEGORY

    A category can be specified so the application belongs to that category. Applications with the same category will be grouped together on the MyApps webpage.

After specifying all the applications required, the edits can be saved. The MyApps page URL is now accessible on the EasyAccess server.

6.6. SSO with OneConnect Setup

This section describes setting up Single Sign On (SSO) in EasyAccess when connecting to resources behind a NetWall firewall through the Clavister OneConnect SSL VPN client. Usually, the target web page after successful OneConnect connection will be an EasyAccess MyApps web page. However, an external landing webpage could be used instead. The aim is to have the user land on the target webpage after successful OneConnect connection and then be able to open any of the service providers on the webpage without further authentication.

A Summary of authentication processing steps with OneConnect

The processing sequence with OneConnect would be the following:

  1. A user starts the OneConnect SSL VPN app on their device and tries to connect to a Netwall firewall using their username and password.
  2. cOS Core is set up to authenticate the user by sending a RADIUS authentication request to an EasyAccess RADIUS scenario. Successful authentication could be based only on username/password credentials but EasyAccess may be configured to use a multifactor RADIUS authentication option, such as using OneTouch. The multifactor authentication option can be added as required to the EasyAccess scenario but will not be discussed further in this section.

    Note that once OneConnect is started, all the traffic from the client will go through the SSL VPN tunnel so cOS Core must be configured to allow this traffic to flow between the VPN tunnel and EasyAccess server. The server might be located locally to the NetWall device or it could be located remotely across the Internet.

  3. The EasyAccess server performs normal RADIUS authentication on the user. The RADIUS scenario that handles authentication is configured to creates a unique UUID which is bound to a persistent user session so the user need not authenticate again later.

  4. The EasyAccess server sends a URL back to cOS Core as part its RADIUS response with the UUID added to it. This URL is preconfigured as part of the RADIUS scenario setup and it points to the identity provider of a federation scenario on the EasyAccess server. Pointing directly back to the identity provider in this way simplifies the setup steps.

  5. The URL is forwarded back to the OneConnect client by cOS Core as part of the successful authentication response. This is standard cOS Core behavior and does not need to be configured.

  6. The URL is automatically opened by the OneConnect client in the user's default web browser.

  7. The browser connects to the EasyAccess server and the target identity provider give the browser a SAML assertion based on the UUID in the URL without further authentication being needed. This exchange will not be visible to the user.

  8. Once it has the SAML assertion, the client browser is redirected to the default service provider URL that has been set for the identity provider. This is typically a MyApps webpage on the EasyAccess server that provides access to different service providers. However, it could be a specific external service provider.

  9. The target webpage accepts the user as authenticated based on the SAML assertion in the browser.

  10. Authentication for the target webpage will persist throughout the browser session. If the browser is closed, this is lost.

Below are the detailed steps for setting up EasyAccess with OnConnect.

A. Set Up cOS Core for RADIUS Authentication of OneConnect

It will be assumed in this section that cOS Core has been correctly configured to authenticate incoming connections from OneConnect clients using RADIUS and that the RADIUS server used is the EasyAccess server.

Configuring cOS Core to do this is described in the SSL VPN section of the separate cOS Core Administration Guide..

B. Create a RADIUS Scenario

A new RADIUS scenario must be created to authenticate the OneConnect client. Creating a basic senario is described in Section 5.1, Basic RADIUS Scenario Setup. The RADIUS scenario could use one of the multi-factor authentication options, such as that described in Section 5.2, RADIUS with Token Scenario Setup

C. Change the list of RADIUS scenario valves

Particular valves nust be set up in the RADIUS scenario in a specific order.

First, open the scenario for editing in the EasyAccess WebUI and select the Execution Flow tab. By selecting the Show link, the default list of valves will be displayed. The typical RADIUS scenario list valve is shown below.

RADIUS Scenario Valve List

Figure 6.26. RADIUS Scenario Valve List

This list must be modified to contain the following valve types and in the following order:

  • LockoutCheckValve
  • SessionCreateValve
  • LDAPSearchValve
  • LDAPBindValve
  • UUIDCreateValve
  • SessionBindValve
  • PropertySetValve
  • SessionBindToUidValve
  • SessionPersistValve

To create the above valve list, the following steps are required:

  • A SessionCreateValve is needed because RADIUS does not include the concept of a session. No changes are required to the default values of the SessionCreateValve shown below.

    {
      "name": "SessionCreateValve",
      "enabled": "true",
      "config": {
        "proceed_on_error": "false"
      }
    }
  • Modify the LDAPSearchValve to have the values required. The following JSON lists example values:

    {
      "name": "LDAPSearchValve",
      "enabled": "true",
      "config": {
        "connection_ref": "bbd7198c-0a6c-43aa-b62b-cd7552c8b4cf",
        "base_dn": "dc=your,dc=base,dc=change,dc=com",
        "scope": "SUB",
        "size_limit": "0",
        "filter_template": "uid=",
        "attributes": "*"
      }
    }
  • Modify the LDAPBindValve as required. For example:

    {
      "name": "LDAPBindValve",
      "config": {
        "connection_ref":"bbd7198c-0a6c-43aa-b62b-cd7552c8b4cf",
        "password_param_name":"User-Password",
        "userid_param_name":"User-Name"
      }
    }
  • Add an UUIDCreateValve to create and store a random UUID. For example:

    {
      "name": "UUIDCreateValve",
      "enabled": "true",
      "config": {
        "proceed_on_error": "false",
        "name": "alias_value"
      }
    }
  • Create a SessionBindValve to bind the session to the UUID. This means that the session can be loaded later using the "Alias" or UUID string.

    {
      "name": "SessionBindValve",
      "enabled": "true",
      "config": {
        "alias": "",
        "proceed_on_error": "false"
      }
    }
  • Create a PropertySetValve that creates a property which contains the URL which is to opened by the OneConnect app. In this case, the UUID will be also passed as a parameter with the URL. For example:

    {
      "name": "PropertySetValve",
      "enabled": "true",
      "config": {
        "proceed_on_error": "false",
        "name": "clavister-url",
        "value": "https://www.example.com/saml/authenticate/samldispatch/?accesstoken="
      }
    }

    Note that the example-url will be referenced by the vendor specific attribute in the RADIUS scenario. This attribute will be set in step D.

  • Create a SessionBindToUidValve to bind the session to the user ID received from the LDAPSearchValve. This will be used in the SAML Assertion.

    {
      "name": "SessionBindToUidValve",
      "enabled": "true",
      "config": {
        "proceed_on_error": "false",
        "userid": ""
      }
    }
  • Now create a SessionPersist Valve to make the session persistent otherwise it will disappear after each authentication.

    {
      "name": "SessionPersistValve",
      "enabled": "true",
      "config": {
        "proceed_on_error": "false"
      }
    }

D. Specify the vendor specific attribute

Using the scenario editor in the WebUI, select the Advanced tab for the RADIUS scenario and set the vendor specific attribute. This specifies where to find the URL that will be sent to the OneConnect client after successful authentication. In the screenshot below the value "clavister-url" refers to the value parameter string in the PropertySetValve created previously. The value 5089 is the vendor ID for Clavister and the type value 4 must be used with OneConnect.

Setting the Vendor Specific Attribute

Figure 6.27. Setting the Vendor Specific Attribute

E. If not MyApps, create a new Federation Scenario

If the target webpage for SSO is not a MyApps page, create a simple federation scenario as described in Section 6.1, Basic Federation Scenario Setup and also upload into EasyAccess the SAML SP Metadata for the service provider.

If the target webpage is an EasyAccess MyApps page, no metadata upload is required but the MyApps scenario will have to be set up. Doing this is described in Section 6.5, MyApps Setup.

F. Add the SAML authenticator

A SAML authenticator must be defined that the OneConnect client redirects to. This is done in the WebUI by selecting the Advanced tab and clicking the pen icon next to the Authentication - HTTP option, as shown below.

Defining a SAML Authenticator

Figure 6.28. Defining a SAML Authenticator

Define a HeaderSAML authenticator by adding the following JSON anywhere.

{
  "alias": "samldispatch",
  "name": "HeaderSAML",
  "configuration": {
    "idpID": "f1dab3a5-02a0-43c6-afef-9d8e39323eb3",
    "pipeID":"tokenPipe"
  }
},

Note that the idpID value must be a SAML identity provider. Another federation scenario might have to be created in order to get this SAML identity provider.

F. Add the tokenPipe

To add the new pipe referred to by the HeaderSAML authenticator created above. click the pen next to Pipes in the Advanced options.

Edit Pipes

Figure 6.29. Edit Pipes

Enter the following JSON anywhere to define the new pipe called tokenPipe.

{
  "id": "tokenPipe",
  "valves": [
    {
      "name": "SessionLoadByAliasValve",
      "config": {
        "aliasid": "",
        "require_session": "true",
        "require_auth_session": "false"
      }
    },
	{
      "name": "LDAPSearchValve",
      "enabled": "true",
      "config": {
        "connection_ref": "bbd7198c-0a6c-43aa-b62b-cd7552c8b4cf",
        "base_dn": "dc=your,dc=base,dc=change,dc=com",
        "scope": "SUB",
        "size_limit": "0",
         "filter_template": "uid="
      }
    },
    {
      "name": "AssertionProvider",
      "config": {
        "targetEntityID": ""f1dab3a5-02a0-43c6-afef-9d8e39323eb3",
        "nameIDAttribute": "uid",
        "sourceID": "myapps",
      }
    },
    {
      "name": "SessionClearAllAliasValve",
      "config": {}
    }
  ]
},

The pipe tokenPipe contains the following valves:

  • SessionLoadAliasValve

    This loads the previous session that was made persistent in the RADIUS scenario in step A using the user's UUID. The UUID is part of the URL that the OneConnect client opens in the browser. To retrieve the session, the aliasID property is set to this UUID using .

    Note that the require_session parameter is set to true so that if there is no session with the specified alias, flow execution will fail. This makes it impossible to connect using a random UUID.

  • LDAPSearchValve

    A valve is required that creates an item instance in EasyAccess memory. An ItemCreateValve could be used for this. Alternatively, an LDAPSearchValve will also perform the task and will additionally retrieve user data based on the user ID bound to the session.

  • AssertionProvider

    This is an assertion provider for the target webpage. The targetEntityID is the ID of an identity provider and this must have the same value as the idpID used in the HeaderSAML authenticator created earlier.

    The sourceID will be the same as the entityID value in the MyApps scenario if MyApps is being used.

    Other values would be added as required by the service provider. For a MyApps page, the JSON values listed above would be sufficient.

    The nameIDAttribute could also be set to .

  • SessionClearAllAliasValve

    This clears all aliases from the session. This is done to avoid the remote possibility that an attacker might successfully replicate an alias.

6.7. Passwordless Federation Authentication

It is possible to configure federation scenarios so that only a username is required during authentication and not a password. This is done by editing the scenario after it is set up in the WebUI.

It should be noted that other forms of multi-factor authentication might still be used with such scenarios, such as OTP or Onetouch, even though a password is not required.

Passwordless Federation Scenario Setup

With a federation scenario, the SAML authenticator first needs to have its name changed using the advanced editor. In this description, a federation Username, Password and OneTouch scenario will be taken as the example scenario. Setting up federation scenarios is discussed in Section 6.1, Basic Federation Scenario Setup and it may be useful to review that section before continuing.

After the federation scenario is created, the authenticator name first needs to be changed from SAMLUidPasswordOneTouch to SAMLUidOneTouch. To do this, select the Advanced tab to display the advanced editor and select the pen icon next to Authentication - HTTP.

Passwordless OneTouch - Edit Authenticator

Figure 6.30. Passwordless OneTouch - Edit Authenticator

Find the SAML authenticator with the "name" parameter value of SAMLUidPasswordOneTouch.

Passwordless OneTouch - Original Authenticator Name

Figure 6.31. Passwordless OneTouch - Original Authenticator Name

Change the "name" parameter to SAMLUidOneTouch.

Passwordless OneTouch - New Authenticator Name

Figure 6.32. Passwordless OneTouch - New Authenticator Name

Next, some valves now need to be removed from the relevant federation Username, Password and OneTouch scenario.

Select Scenarios > Federation > Username, Password and OneTouch in the WebUI and open the scenario. Select the Execution Flow tab and remove the two valves called InputParameterExistsValidatorValve (this requires that a password be entered) and LDAPBindValve (this requires that the entered password matches the user's LDAP entry).

Passwordless OneTouch - Removing Valves

Figure 6.33. Passwordless OneTouch - Removing Valves

When the user now tries to authenticate, the password field will be removed from the dialog presented. Below is an example of this (the Swedish language version is shown).

Passwordless OneTouch - Authentication Dialog

Figure 6.34. Passwordless OneTouch - Authentication Dialog

Chapter 7: MS-CHAPv2 Proxy Setup

The EasyAccess server can act as a proxy between a RADIUS client and an NFS server in order to perform MS-CHAPv2 authentication.

The steps for setting up EasyAccess as an MS-CHAPv2 proxy are the following:

A. Deploy the RADIUS Proxy Module

The first step is to add the RADIUS proxy module to EasyAccess. To do this, open the EasyAccess WebUI, select the Advanced tab and then select the Modules option.

Editing Modules

Figure 7.1. Editing Modules

The following JSON block can now be inserted at any suitable location.

{
  "id":"mschap-radius-proxy-module",
  "name":"com.phenixidentity~phenix-radius-proxy",
  "enabled":"true",
  "config":
  {
  }
}

The above module now needs a reference to it in the default EasyAccess node group. From the Advanced tab menu, select Node_Groups.

Editing Node Groups

Figure 7.2. Editing Node Groups

Add the value the module id value of mschap-radius-proxy-module to the module_refs list, as shown below.

Adding the Module to the Node Group

Figure 7.3. Adding the Module to the Node Group

B. Add the Proxy Connection

The connection to the NFS server providing MS-CHAPv2 authentication will now be defined. From the Advanced tab menu, select RADIUS proxy connections.

Edit RADIUS Proxy Connections

Figure 7.4. Edit RADIUS Proxy Connections

Now, add the following JSON within the square brackets, substituting in the relevant values for the IP address and port numbers.

{
  "id":"my-mschap-radius-connection",
  "description":"My RADIUS proxy connection",
  "config": {
    "port":"1820",
    "server_host":"192.168.98.165",
    "server_port":"1812"
  }
}

The properties specified in the JSON above have the following meanings:

  • id - A logical name for this connection.
  • description - A description of the connection.
  • port - The UDP port number on the EasyAccess server that listens for connections.
  • server_host - The IP address of the NFS server.
  • server_port - The UDP port that the NFS server listens on.

C. Add the RADIUS Authenticator

From the Advanced tab menu, select Authentication - RADIUS proxy.

Edit RADIUS Proxy Authentication

Figure 7.5. Edit RADIUS Proxy Authentication

Now add the following JSON within the square brackets.

{
  "id":"my-auth-radius-proxy",
  "name":"OneTouchAuthenticator",
  "description":"My RADIUS proxy authenticator",
  "config": {
    "radius_proxy_config":"my-mschap-radius-connection",
    "pipeID":"MyUserLookupWithLDAP",
    "selector":""
  }
}

The properties specified in the JSON above have the following meanings:

  • id - A logical name for this authenticator.

  • name - The authenticator type. Only OneTouch is supported.

  • description - A description of this authenticator.

  • radius_proxy_config - The ID of the connection added in B.

  • pipeID - The ID of the execution pipe that will be defined in the next step.

  • selector - This is optional and specifies any selectors to be sent as attributes. For example: 44=onetouch. Selectors are not relevant to NetWall devices since cOS Core does not send them.

D. Add the Execution Pipe for Authentication

From the Advanced tab menu, select Pipes.

Edit Pipes

Figure 7.6. Edit Pipes

Now, add the following JSON in any suitable location.

{
  "id": "MyUserLookupWithLDAP",
  "description": "Verify that user exists in LDAP",
  "valves": [
    {
      "name": "LDAPSearchValve",
      "config": {
        "connection_ref": "Your connection LDAP connection REF",
        "base_dn": "dc=Your,dc=domain",
        "scope": "SUB",
        "size_limit": "0",
        "filter_template": "sAMAccountName="
      }
    },
    {
      "name": "FlowFailValve",
      "config": {
        "message":"User does not exist",
        "exec_if_expr":"flow.items().isEmpty()"
      }
    }
  ]
}

The FlowFailValve could stop execution based on any suitable condition. In the above, execution fails if the user is not found. However, this could also be set up so execution fails if, for example, the user has a specific attribute value.

Chapter 8: Self Service Setup

The self-service feature in EasyAccess allows individual users access to the EasyAccess server so they can manage aspects of their own authentication. This section describes how the self service feature can be enabled by the EasyAccess administrator.

To set up a self service, go to Scenarios > Applications in the configuration manager WebUI and select the plus button on the Self Service option. This will open a guide which will take the administrator through the steps to configure self service.

Adding Self Service

Figure 8.1. Adding Self Service

The first guide step will ask for a user store. In the example below, the LDAP server created in Chapter 4, LDAP Server Setup will be selected.

Self Service - Specify User Store

Figure 8.2. Self Service - Specify User Store

The guide will then ask where the search in the LDAP server should begin. The value User Identifier Attribute specifies the attribute which contains the username in the user search. Note that in the case of Active Directory, this attribute would be sAMAccountName.

Self Service - LDAP Search Settings

Figure 8.3. Self Service - LDAP Search Settings

The next guide step will allow the attribute names to be specified for other user data and will also allow the administrator to determine which will be visible/editable for the self service user. Note that only a single value can be specified for any field.

This value of the User Identifier Attribute field specified in the previous step is always visible to the self service user but never editable.

Self Service - Attributes Settings

Figure 8.4. Self Service - Attributes Settings

Now, enable any application features that are required. The optional features are:

  • PIN: - Enable PIN enrollment.

  • Prefetch OTP - Enable creation and download of one time passwords.

  • Pocket Pass - Enable enrollment for OATH based Pocket Pass app.

  • Hardware tokens - Enable hardware token enrollment. This requires the hardware token module to be enabled.

  • One Touch - Enable enrollment for PKI based One Touch app.

Note that enabling the self service One Touch feature is only possible if the One Touch feature has already been configured in EasyAccess. Doing this is described in Section 5.3, RADIUS with OneTouch Scenario Setup.

Self Service - Features

Figure 8.5. Self Service - Features

The next sequence of steps depends on which features in the previous step have been selected. Each feature will require an additional configuration step in the guide (these steps are not shown here).

If the One Touch feature has been selected or if the Online key provisioning option has been enabled in the Pocket Pass feature, the URL of an external server must be specified. This server will be used to construct the URL that points back to the application used by Pocket Pass and One Touch clients.

Self Service - Network Settings

Figure 8.6. Self Service - Network Settings

The final step in the guide is to click the Create option to save the self service setup.

Create Self Service Application

Figure 8.7. Create Self Service Application

Once the self service feature is configured and available, each end user will then need to download the relevant app to their device and then log into the self service feature to configure the service they want to use.

Chapter 9: Cluster Setup

For EasyAccess version 4.0 and later, cluster setup is not part of the standard EasyAccess installation wizard. This means that the cluster configuration must be performed manually.

When to Use a Cluster

Clustering is typically used when high availability is required. However, it may also be used when traffic needs to be spread across multiple nodes using an external load balancer. Clustering can also facilitate software upgrades with zero downtime since one node can be taken offline while a second processes traffic.

Cluster Architecture

The EasyAccess cluster architecture consists of three components: two standalone EasyAccess installations on separate computers and an external database server. The two EasyAccess servers communicate with each other so they are synchronized. Both servers can communicate independently with the database. This setup is illustrated in the diagram below.

The EasyAccess Cluster Architecture

Figure 9.1. The EasyAccess Cluster Architecture

With a cluster, an external database must be installed and can be either a MySQL or an MSSQL server. The database can run on the same computer as one of the EasyAccess installations but placing it on a separate, third computer is recommended. The external database itself can be configured to be fault tolerant.

The sections that follow explain how to configure each of these components when setting up a cluster.

9.1. EasyAccess Service Setup

Use the following steps to configure the EasyAccess service:

  1. Open the file /classes/cluster.xml in a suitable text editor.

  2. Enable tcp-ip:

    <tcp-ip enabled="true">
  3. Enable interfaces:

    <interfaces enabled="true">
  4. Add the subsection member-list to the tcp-ip section and add the IP address of the second cluster node as a member in this new section (this is shown in the example at the end of this section).

  5. Assign the local IP address to the properties public-address, interface in tcp-ip as well to interfaces.

  6. Save the changes.

  7. Repeat the above procedure on the other node, reversing the IP addresses of the nodes.

  8. Restart the service on both nodes.

  9. Check the system log on either node to check the two systems are communicating correctly.

Below is an example of a configured cluster.xml file where is 192.168.0.12 is the IP address of the other node:

<network>
	<public-address>192.168.0.11</public-address>
	<port auto-increment="false" port-count="1">5701</port>
	<outbound-ports>
		<!--
		Allowed port range when connecting to other nodes.
		0 or * means use system provided port.
		-->
		<ports>0</ports>
	</outbound-ports>
	<join>
		<tcp-ip enabled="true">
			<interface>192.168.0.11</interface>
			<member-list>
				<member>192.168.0.12</member>
			</member-list>
		</tcp-ip>
		<multicast enabled="false"/>
		<aws enabled="false"/>
	</join>
	<interfaces enabled="true">
		<interface>192.168.0.11</interface>
	</interfaces>
</network>

9.2. Cluster Database Service Setup

Starting with EasyAccess version 4.0, the cluster database must be a separate external database server running either MySQL or MSSQL. The database server could be installed on the same computer as one of the EasyAccess server nodes but is best located on a separate computer. Both EasyAccess servers in a cluster will communicate with the database based on the parameters set in their /config/boot.json configuration file.

Setting up an external database for either a standalone or cluster EasyAccess installation is described in Section 2.5, External Database Setup.

9.3. Cluster Management

When operating an EasyAccess cluster, it is important that services, nodes and external dependencies are maintained and monitored closely. The aspects described below should be considered.

Node Communication

The ports required by the cluster nodes should be opened at all times and should not blocked by firewalls. Latency between cluster nodes should be kept as low as possible. Since the cluster nodes are constantly kept synchronized, the lower latency the better.

Brief network disturbances should not be a problem but consistent interference in communications between nodes can cause performance problems and in some cases system failure.

Time Synchronization Servers

It is essential that both nodes are using the same time synchronization servers so they have the same system time.

Restarting Node Services

Restarting of services or the entire node should not be done without monitoring. In cases where nodes need to be restarted, perhaps due to software updates, ensure that the nodes have time to re-establish cluster connections.

Verifying Logs

It is recommended to regularly verify that the cluster is operating correctly by looking at the system logs of either node. This can help identify any anomalies at an early stage.

Chapter 10: Knowledge Base Articles

The Clavister Knowledge Base (KB) provides an online collection of articles that cover all Clavister products, including EasyAccess. The following is a list of links to some useful articles that can supplement the information found in the rest of this publication: