EasyAccess 4.3 Getting Started Guide

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:

Starting the EasyAccess Server on Windows

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

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.

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

Installation steps are given for the following:

Installation on LINUX using the X Window Interface

Installation on LINUX using the CLI

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

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:

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.

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

Incoming Traffic

HTTP 8443 for:

RADIUS (UDP), common ports 1645/1812.

Hazelcast, if clustering has been configured.

Outgoing Traffic

HTTPS 443 against:

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.

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:

Note the following about the above changes:

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:

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

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

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.

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.

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

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

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

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

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.

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.

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.

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.

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.

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.

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

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

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

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

In the next guide step, select Create to save the 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:

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

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

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.

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

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

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.

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.

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

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.

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.

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.

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.

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

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.

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.

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

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.

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.

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

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.

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.

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>

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.

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.

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/

In the final guide step, select Create to save the 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:

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.

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.

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:

The above valves will now be described in detail:

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.

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.

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:

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

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.

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.

Redirection setup is now complete.

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:

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:

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.

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.

This guide step will also require the following:

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

In the final guide step, select Create to save the 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.

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.

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

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

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:

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.

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

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

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.

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.

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.

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:

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.

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

Change the "name" parameter to SAMLUidOneTouch.

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).

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).

Use the following steps to configure the EasyAccess service:

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>

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.

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.