Installation Guide for Adaxes 2018.1

This document contains requirements and instructions on how to install Softerra Adaxes 2018.1.

System Requirements

The tables below outline software and hardware requirements for different Softerra Adaxes components.

Supported Operating Systems

* It's highly recommended to install Web Interface and SPML Web Service on the server editions of Windows, because when installed on a workstation, IIS has a limitation on the number of simultaneous connections. The connection limit can be reached when only two or three people are using the Web Interface at the same time.

Hardware Requirements

The minimum hardware required to install and run Softerra Adaxes components:

Installation Prerequisites

• All Adaxes components require Microsoft .NET Framework 4.5.2 or higher.
• To install Adaxes Service on Windows 7, you need to install Active Directory Lightweight Directory Services (AD LDS) first.
• Adaxes PowerShell Module requires Windows PowerShell 3.0 or higher.

Installation

All Adaxes components (Adaxes Service, Web Interface, Administration Console, PowerShell Module, etc.) are installed using a single installation package. It is not necessary to install all the components on a single computer. In case you need to install different components on different computers, install the Adaxes service first, because to install other components you will need to specify the network location of the Adaxes service.

Installation Instructions

1. Log on to the operating system using an Active Directory domain account that has local administrator permissions on the computer.
2. Install Microsoft .NET Framework 4.5.2 or higher, if not installed.
3. Launch the Softerra Adaxes installation package (.msi) for the language and OS architecture you want.
4. Read the information provided on the Welcome screen and click Next.
5. Accept the license agreement and click Next.
6. Select the Adaxes components you want to install and click Next.
   
   If you select none of the Adaxes components, only Adaxes ADSI Provider will be installed.
7. If you have selected the Adaxes Service component, do the following:
   
   • On the Adaxes Service Account page, specify the credentials of the user account under which the Adaxes service will run.
     • It is recommended to have a dedicated account to run the Adaxes service.
     • To change the account you'll need to reinstall the Adaxes service.
     • The Windows service for Adaxes will use the account to log in to the system.
     • The account will have full access to Adaxes configuration and all Active Directory domains managed by Adaxes.
     • The AD domain where the Adaxes service account is located will be automatically registered to be managed by Adaxes.
     Service Account Permissions
     
     The Adaxes service account can be used as the service account for a managed Active Directory domain. Since all operations within a domain are performed using a service account, it must have sufficient rights in the domain. If you want to use the Adaxes service account as the service account for a domain, you need to add it to the domain Administrators group.
     
     

     ---

     
     If the Adaxes service account doesn't have administrator rights, it should have the rights necessary to publish and unpublish the Adaxes service in Active Directory (create/delete a Service Connection Point). For information on how to grant the necessary permissions, see Grant Permissions to Publish Adaxes Service.
     
     
     Log On As Service Right
     
     Since Adaxes service uses the Adaxes service account to log on to the system, the Log on as service right is granted to the account.
     
     When the Adaxes service is installed on a workstation rather than on a domain controller, the right is granted locally on the workstation via the Local Policy settings. If there is a conflicting domain-based Group Policy object that grants the Log on as service right to other accounts, the local right granted during the installation process will be removed on Group Policy refresh, because the domain-based Group Policy settings override the Local Policy settings. If it happens, the Adaxes service will not start, and the Log on as service right will need to be granted to the Adaxes service account in a precedent domain-based Group Policy.
     Click Next.
   • On the Service Configuration page, to achieve fault tolerance and load balancing, you can join the new Adaxes service to an existing Adaxes configuration set. For more details, see Multi-Server Deployment for High Availability.
     To join the Adaxes service to a configuration set, select the Shared configuration option, specify the DNS host name of any Adaxes service from the configuration set, and then provide the credentials of the service account of any Adaxes service contained in the configuration set.
     Click Next.
   • On the Ready to Install page, you can specify whether to open the Windows Firewall port that is used for communication between Adaxes clients (e.g. Adaxes Administration Console or Adaxes Web interface) and the Adaxes service. If the Open port 54782 in Windows Firewall option is selected, an inbound rule for port 54782 will be added in Windows Firewall. If you uninstall Adaxes, the rule will be deleted automatically.
8. If you have selected the Web Interface component, do the following:
   • On the Web Interface Configuration page, configure IIS web site parameters for the Web Interface and Web Interface Configurator.
     Available Web Interface Types
     
     The list of Web Interface types available on a specific web server is determined by the configuration of each Web Interface type. For example, if you don't want the Web Interface for Administrators to be available from the outside, you can disable it on all web servers located in the DMZ. For more details, see Disable Web Interface on Specific Web Servers.
     Click Next.
   • On the Service for Web Interface step, specify the DNS host name of the Adaxes service the Web Interface will connect to. The step is only available if you install the Adaxes Service and Web Interface components separately. When both components are installed simultaneously, Web Interface will connect to the Adaxes service installed during the current installation.
     
     If the Adaxes service shares its configuration with other Adaxes services, the Web Interface will connect to the nearest available Adaxes service contained in the configuration set.
     
     Click Next.
9. If you have selected the SPML Web Service component, do the following:
   • On the SPML Web Service page, configure IIS parameters for the SPML web service and click Next.
   • On the AD Access for SPML Web Service page, specify how you want Adaxes SPML Provider to access Active Directory. The page is only available if you install the Adaxes Service and SPML Web Service components separately. When both components are installed simultaneously, SPML Provider will use the Adaxes service installed during the current installation.
     
     Adaxes SPML Provider can access Active Directory directly or via an Adaxes service. Accessing Active Directory via Adaxes allows you to benefit from the Adaxes features like Business Rules, Security Roles and Property Patterns.
     
     If SPML Provider connects to Active Directory through an Adaxes service and the service shares its configuration with other Adaxes services, SPML Provider will connect to the nearest available Adaxes service contained in the configuration set.
     
     Click Next.
10. On the Ready to Install page, click Install to begin the installation.
    Depending on the features you've selected, additional components can be installed on the system. For details, see Additional Components.

Multi-Server Deployment for High Availability

You can set up multiple Adaxes services that share common configuration (managed AD domains, Security Roles, Business Rules, Scheduled Tasks, Web Interface configuration, etc.). In a multi-server environment, if one of the Adaxes services goes down, users are automatically redirected to the nearest service available. It enables fault tolerance and provides more efficient load distribution on your system.

Adaxes services that share common configuration form a logical grouping called a configuration set. When the configuration of an Adaxes service is modified, the configuration of other services in the configuration set becomes inconsistent with the most up-to-date configuration. As the changes get replicated through the configuration set, all service configurations become identical once again. Adaxes uses a type of replication called multimaster replication.

Consider a multi-server deployment if you have a geographically distributed environment, there is a heavy load on your Adaxes service, or you want to achieve extra availability and improve the failover.

To setup a multi-server configuration:

1. Install the first instance of Adaxes service. This will create a configuration set with only one Adaxes service.
2. During installation of subsequent instances of Adaxes service, join each new service to the configuration set. For this purpose, on the Service Configuration page of the installation wizard, select the Shared configuration option and specify the DNS host name of any Adaxes service from the configuration set. To join a service to a configuration set you will need to provide the credentials of the Adaxes service account of any Adaxes service contained in the configuration set.

Database for Log Records

By default, Adaxes log records are stored in a SQLite database located on the computer where Adaxes service is running. Since SQLite databases are not replicated, each instance of Adaxes service will have access to its own log records only. In a multi-server environment it is highly recommended to use Microsoft SQL Server as an external database for log records. In such a configuration, all records will be merged in a single database and each Adaxes service will have access to all log records generated within the configuration set.

For instructions on how to configure Adaxes to use an external database for logging, see Enable Logging to External MS SQL Database.

Deploying Web Interface to a Web Farm

You can install Adaxes Web Interface in a web farm if you want to share the web-site traffic across multiple servers, improve site availability, and balance load among sites.

To install Adaxes Web Interface in a web farm:

1. Install Adaxes Web Interface on each web server in the web farm.
   

   Command line

   To install Adaxes Web Interface in an unattended mode, run the following command line:

   msiexec /quiet /i "adaxes_x64_en.msi" ADDLOCAL=AppWebUIFeature ADMWEBSERVICECONFIGSET="<CONFIG-SET-ID>"

   <CONFIG-SET-ID> is the identifier of the Adaxes service configuration set. For details, see Get the Configuration Set ID.

   To install Adaxes Web Interface and Web Interface Configurator, use the following command line:

   msiexec /quiet /i "adaxes_x64_en.msi" ADDLOCAL=AppWebUIFeature,AppConfigWebUIFeature ADMWEBSERVICECONFIGSET="<CONFIG-SET-ID>"

   Important: In order to upgrade the Web Interface, the update must be applied on each web server in the farm.
2. Configure client affinity for the web farm. Since Adaxes Web Interface requires all client requests to be routed to the same web server during a client session, you need to configure load balancing to map a client to a Web Interface. The load balancing algorithm must be applied only for the very first request from the client. From that point on, all subsequent requests from the same client must be routed to the same Web Interface for the duration of the client session.
   
   To configure client affinity:
   
   Application Request Routing Module
   
   

   1. Launch Internet Information Services (IIS) Manager.
   2. Select the server farm and double-click Server Affinity.
   3. Enable the Client affinity option and click Apply.

   
   F5 BIG-IP Local Traffic Manager (LTM)
   
   

   1. Go to the F5 BIG-IP LTM configuration page.
   2. Expand Local Traffic in the navigation panel and select Profiles.
   3. Open the Persistence tab and then click Create.
   4. In the General Properties section type the desired name of the profile you are creating.
   5. Select Source Address Affinity in the Persistence type drop-down list.
   6. Customize other settings of the profile according to your requirements and click Finished.
   7. Open the virtual server(s) that hosts Adaxes Web Interface and open its Resources tab.
   8. In the Default Persistence Profile drop-down list, select the name of the persistence profile you have created.
   9. Save the changes.

   
   Citrix NetScaler
   
   

   1. Go to the Citrix NetScaler VPX configuration page.
   2. Navigate to Traffic Management > Load Balancing > Virtual Servers.
   3. Select the virtual server you use for load balancing and click Edit.
   4. In the Persistence list, select the SOURCEIP option.
   5. Save the changes.

Installing Web Interface and Administration Console in DMZ

To make Adaxes Web Interface and Administration Console available from outside, they can be installed in the DMZ (also known as perimeter network or extranet). Web Interface can be exposed to the Internet to allow users to perform tasks like password reset and directory search when they are not on the internal network (e.g. users working from home, users on a business trip, external users). If you install Adaxes Administration Console on a computer in the DMZ, Administrators will be able to connect to the computer using Remote Desktop and manage Adaxes and Active Directory from outside the internal network.

To deploy Adaxes clients in the DMZ:

• Install a Read-Only Domain Controller in the DMZ. Adaxes Web Interface and Administration Console can be installed only on a computer that is joined to an Active Directory domain. Since DMZ is usually a highly restricted piece of network, it is recommended to use Read-Only Domain Controllers. Read-Only Domain Controllers provide a one-way replication from your internal network to the DMZ and thus decrease the risks when a DMZ machine gets compromised. For details on how to deploy read-only DCs in the DMZ, see Active Directory Domain Services in the Perimeter Network.
• Open port 54782 in the firewall. Adaxes Web Interface and Adaxes Administration Console use port 54782 for communication with the Adaxes service. The port number can be changed if required.
  

  How to change the port

  • Open the folder where Adaxes service is installed, typically C:\Program Files\Softerra\Adaxes N\Service.
  • Open the Softerra.Adaxes.Service.exe.Config file in a text editor.
  • Change the port attribute of the following XML element:

     <configuration>
       ...
        <system.runtime.remoting>
          <customErrors mode="Off" />
          <application>
            <channels>
              <channel ref="tcp" port="54782" priority="2" secure="true">

• Configure which Web Interface types will be available in the DMZ. For example, if you don't want Web Interfaces for Administrators and Help Desk to be available from the outside, you can allow them only on the web servers located inside your local network. For more details, see Disable Web Interface on Specific Web Servers.

Deploying Web Interface to Windows Azure Pack

To deploy Adaxes Web Interface to Windows Azure Pack:

1. Open Azure Management Portal.
2. Create a website for Adaxes Web Interface using Quick Create.
3. Select the new website and switch to the Configure tab.
4. Make sure .NET Framework Version is set to V4.5.
5. Set Managed Pipeline Mode to Integrated.
6. Set Custom Application Pool Identity to Allow.

7. Provide the username and password of an Active Directory account that the website will run under.

   It is recommended to use a low-privileged domain account for the application pool identity.

8. Upload Web Interface files to the site\wwwroot directory of the new website (e.g. using FTP).

   The Web Interface files are located in the C:\Program Files\Softerra\Adaxes N\Web Interface\App folder on a computer where Adaxes Web Interface is installed.

   Important:
   
   If Adaxes Web Interface and Adaxes Service are installed on the same computer, you need to install Web Interface on a separate computer and get the files from there.

Uninstallation

To uninstall Softerra Adaxes:

1. If you want to uninstall the Adaxes Service component, make sure that the service is running. It is necessary to correctly unregister the service from your system (remove the service connection points and clean up the configuration set metadata).
2. Open Add or Remove Programs and select the Softerra Adaxes product.
3. Click Remove and follow the steps provided.

Upgrade

Upgrade Multi-Server Configuration

1. Uninstall the old version of Adaxes service.
2. If you are moving an Adaxes service that shares its configuration with other Adaxes services from one computer to another, you need to manually transfer the information on pending Approval Requests.
   

   How to transfer information on pending Approval Requests

   • On the computer, where the previous instance of Adaxes service was installed, go to the common application data folder used by Adaxes. It is typically located at C:\ProgramData\Softerra\Adaxes N\.
   • Locate the AdaxesCommandQueueBackup folder that holds information on pending Approval Requests.
   • Copy the folder to a similar location on the computer to which you are transferring Adaxes service.
3. Install the new version. During the installation, join the new Adaxes service to your configuration set.
4. Wait until the configuration is replicated. To make sure that the replication is complete, launch Adaxes Administration Console, connect to the newly installed Adaxes service and wait until the connection is established.

Upgrade Single Server Configuration

If you have a single Adaxes service that does not share its configuration with any other Adaxes services, you need to back up your configuration, upgrade to a new version, and then restore the configuration. To do this, perform the following steps:

1. Back up the configuration of your Adaxes service using the Softerra.Adaxes.BackupRestore.exe tool. The tool is located in the folder where Adaxes service is installed, which is C:\Program Files\Softerra\Adaxes N\Service by default.
2. When upgrading from 2017.2 and earlier, you need to back up the configuration of your Web Interface using the Softerra.Adaxes.Web.UI.Configuration.exe tool. The tool is located in the folder where Adaxes Web Interface is installed, which is C:\Program Files\Softerra\Adaxes 3\Web Interface by default.
   
   Starting from 2018.1, the Web Interface configuration is a part of Adaxes service configuration and you don't need to back up and restore it separately.
3. Uninstall the old version of Adaxes.
4. Install the new version.
5. Restore the Adaxes service configuration using the Softerra.Adaxes.BackupRestore.exe tool.
6. When upgrading from 2017.2 and earlier, migrate the old configuration of your Web Interface using the Softerra.Adaxes.Web.Migration.UI.exe tool. The tool is located in the folder where Adaxes Web Interface is installed, which is C:\Program Files\Softerra\Adaxes N\Web Interface by default.
   
   If you have different Web Interface configurations installed on different web servers, migrate each configuration one after another, and then specify which Web Interface configuration will be available on which web server. For details, see Disable Web Interface on Specific Web Servers.

Additional Components

Some of the Adaxes components require additional software to be installed. All the software is installed automatically during Adaxes installation. The software components that are going to be installed are listed on the Ready to Install page that is shown right before the installation process starts.

Additional software components installed automatically:

How Do I

Grant Permissions to Publish Adaxes Service

1. Open Active Directory Users and Computers on a domain controller.
2. Connect to the domain of the computer on which you want to install Adaxes.
   • In the console tree, right-click Active Directory Users and Computers, and then click Connect to Domain.
   • Type the domain name and click OK.
3. On the View menu, select Advanced Features.
4. Right-click the computer on which you want to install Adaxes, and then click Properties.
5. On the Security tab, click Add.
6. Type the name of the user account to which you want to grant the permissions and click OK.
7. Select the Allow check boxes for the Create All Child Objects and Delete All Child Objects permissions.
8. Click OK.

Install Microsoft Active Directory Lightweight Directory Services (AD LDS) on Windows 7

1. Visit http://www.microsoft.com/downloads/details.aspx?familyid=A45059AF-47A8-4C96-AFE3-93DAB7B5B658.
2. Follow the instructions to download and install Microsoft Active Directory Lightweight Directory Services.

© Softerra 2018. All rights reserved.