Adaxes installation guide

All Adaxes components (Adaxes service, Web interface, Administration console, etc.) are installed using a single installation package. You can install all components on a single computer or install different components on different computers. If you are going to install Adaxes components on different computers, install Adaxes service first, because to install other components you will need to specify the network location of the Adaxes service.

Also, you can set up Adaxes as a multi-server deployment with several Adaxes service instances that share common configuration – for high availability and fault tolerance.

Prerequisites

  • To install Adaxes, the computer must be joined to an Active Directory domain.
  • All Adaxes components require Microsoft .NET Framework 4.8 or higher.

Hardware requirements

Component Hardware requirements
Adaxes service
  • CPU: 2 GHz or higher recommended
  • RAM: 1 GB or more recommended
  • HDD: 2 GB or more recommended
Administration console
  • CPU: 1.6 GHz or higher recommended
  • RAM: 1 GB or more recommended
Web interface
  • CPU: 2 GHz or higher recommended
  • RAM: 1 GB or more recommended
REST API
  • CPU: 2 GHz or higher recommended
  • RAM: 1 GB or more recommended

Tip

Hardware requirements depend on Adaxes configuration complexity and the number of managed objects. The more complicated your configuration is and the more objects you manage, the more processing power and RAM is recommended to allocate to the computer where Adaxes will be installed.

Software requirements

Component Supported operating systems
Adaxes service
  • Windows 8 and higher
  • Windows Server 2012 R2 and higher
Administration console
  • Windows 7 and higher
  • Windows Server 2008 R2 and higher
Web interface
  • Windows 7 and higher
  • Windows Server 2008 R2 and higher
REST API
  • Windows 7 and higher
  • Windows Server 2008 R2 and higher
PowerShell module
  • Windows 8 and higher
  • Windows Server 2012 and higher
SPML Web service
  • Windows 7 and higher
  • Windows Server 2008 R2 and higher

Tip

It's highly recommended to install Web interface, REST API, and SPML Web service on server editions of Windows, because on a workstation, IIS has a limitation on the number of simultaneous connections. The connection limit can be reached with only two or three concurrent connections to any of these components.

Additional software

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

Adaxes component Additional software installed
Adaxes service Microsoft AD LDS
Web interface Microsoft IIS
REST API Microsoft IIS
SPML Web service Microsoft IIS

Note

After Adaxes is uninstalled, the additional software components installed automatically remain in the system.

Installation

Follow the steps below to install Adaxes:

  1. Log on to the operating system using an Active Directory domain account that has local administrator permissions on the computer.

  2. Launch the Adaxes installation package (.msi). Alternatively, install Adaxes from the command line.

  3. Read the information provided on the Welcome screen and click Next.

  4. Accept the license agreement and click Next.

  5. Select Adaxes components you want to install and click Next.

     If you selected the Adaxes service component
    • On the Adaxes service account page, specify the credentials of the user account under which the Adaxes service will run. 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 should have the rights necessary to publish and unpublish the Adaxes service in Active Directory (create/delete service connection points). For information on how to grant the permissions, see Grant permissions to publish Adaxes service.

      Tip

      The Adaxes service account can also be used as the service account to manage an Active Directory domain. Since all operations within a domain are performed using a service account, it must have sufficient rights in the domain.

      Log on as service right

      Since Adaxes service uses the service account to log on to the system, the Log on as service right will be granted to the account during the installation.

      Note

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

      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 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 to Windows Firewall. If you uninstall Adaxes, the rule will be deleted automatically.

     If you selected the Web interface component
    • On the Web interface configuration page, configure IIS web site parameters for the Web interface and Web interface configurator.

      Available Web interfaces

      The list of Web interfaces available on a specific web server is determined by the configuration of each Web interface. For example, if you don't want the Web interface for administrators to be available from outside, you can disable it on all web servers located in the DMZ. For more details, see Disable a Web interface on specific web servers.

    • Click Next.

    • On the Adaxes service for Web interface page, 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.

     If you selected the REST API component
    • On the REST API configuration page, configure IIS web site parameters for REST API and click Next.

    • On the Adaxes service for REST API page, specify the DNS host name of the Adaxes service REST API will connect to. The step is only available if you install the Adaxes service and REST API components separately. When both components are installed simultaneously, REST API will connect to the Adaxes service installed during the current installation.

      If the Adaxes service shares its configuration with other Adaxes services, REST API will connect to the nearest available Adaxes service contained in the configuration set.

    • Click Next.

     If you selected the SPML Web service component
    • On the SPML service configuration 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 in the configuration set.

    • Click Next.

     If you didn't select any of the Adaxes components

    Only Adaxes ADSI provider will be installed.

    Adaxes ADSI Provider is an API layer that lets you use ADSI interfaces to connect to and communicate with Adaxes service. You can use the ADSI Provider in custom client applications, standalone scripts, and scripts executed by business rules, scheduled tasks and custom commands.

  6. On the Ready to install page, click Install.

Depending on the features you've selected, additional components can be installed on the system. For details, see Additional software.

Post-installation tasks

After Adaxes is installed, you need to perform post-installation steps.

Multi-server deployment

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 a more efficient load distribution on your system.

Load balance / Failover Users (Web interface, scripts, etc.) Configuration set Adaxes service 1 Adaxes service 2 Adaxes service 3

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 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 multi-master replication.

Replication Replication Replication Domain A Adaxes service Domain B Adaxes service Adaxes service

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 set up 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 the installation of subsequent instances of Adaxes service, join each new service to the configuration set.

     How to join a new service to a configuration set
    1. On the Adaxes service configuration page of the installation wizard, select the Shared configuration option.
    2. Specify the DNS host name of any Adaxes service from the configuration set.
    3. Provide the credentials of the service account of any Adaxes service contained in the set.

    Important

    To join a new service from another domain to a configuration set, the domains must have two-way trust relationships.

Log record database in a multi-server deployment

By default, Adaxes log records are stored in an SQLite database located on the computer where the 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.

Log records Log records Log records Microsoft SQL Server (On-premises / Azure) Adaxes service 1 Adaxes service 2 Adaxes service 3

For instructions on how to configure Adaxes to use an external database for logging, see Enable logging to an 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.

Load balance / Failover (Adaxes) User AD LDS (Web interfaceconfiguration) Adaxes service Web farm (Client affinity enabled) Adaxes Web interface Web server (IIS) Adaxes Web interface Web server (IIS) Adaxes Web interface Web server (IIS) Load balance / Failover

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 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 from the command line, run the following command:

    msiexec /quiet /i "<path>adaxes.msi" ADDLOCAL=AppWebUIFeature ADMWEBSERVICECONFIGSET="<config-set-id>"
    

    where:

    • <path> - the path to the Adaxes installation file (adaxes.msi or adaxes_x86.msi).
    • <config-set-id> - 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, run the following command:

    msiexec /quiet /i "<path>adaxes.msi" ADDLOCAL=AppWebUIFeature,AppConfigWebUIFeature ADMWEBSERVICECONFIGSET="<config-set-id>"
    

    where:

    • <path> - the path to the Adaxes installation file (adaxes.msi or adaxes_x86.msi).
    • <config-set-id> - the identifier of the Adaxes service configuration set.
  2. Configure client affinity for the web farm.

     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.

Exposing Web interface to the Internet

To make Adaxes Web interface and Administration console available from the outside of your network, 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 self-reset their AD password or search directory when they are not on the internal network (e.g. users working from home, users on business trips, 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.

DMZ Adaxesadministration console Adaxes Web interface Read-onlydomain controller Internet Web browser Client for passwordself-service HTTP Port 54782 Local network Adaxesadministration console Adaxes Web interface Adaxes service

To make Adaxes components available from the Internet:

  1. Install a read-only domain controller (RODC) 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. RODCs 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 RODCs in the DMZ, see Active Directory Domain Services in the Perimeter Network.

  2. Open port 54782 in the firewall.

    By default, Adaxes Web interface and Adaxes Administration console use port 54782 for communication with the Adaxes service. You can select a different port during the installation or change it later if required.

     How to change the port after installation
    • Open the folder where Adaxes service is installed which is C:\Program Files\Softerra\Adaxes 3\Service by default.
    • Open the Softerra.Adaxes.Service.exe.config file with a text editor.
    • Locate XML element configuration\system.runtime.remoting\application\channels\channel.
    • Change the value of the port parameter.
      <configuration>
          ...
          <system.runtime.remoting>
              <customErrors mode="Off" />
              <application>
                  <channels>
                      <channel ref="tcp" port="54782" priority="2" secure="true">
      
    • In a multi-server environment, repeat the above steps for each Adaxes service in the configuration set.
  3. Configure which Web interfaces will be available in the DMZ. For example, if you don't want the Web Interface for administrators and Help Desk to be available from 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.

If you do not want to install a read-only domain controller and Adaxes Web interface in the DMZ, but still need to make the Web interface accessible from outside, you can use an application delivery controller (e.g. Citrix NetScaler, Nginx, CloudFlare, etc.). For example, the controller can be placed in the DMZ to accept requests from outside and pass them to the Adaxes Web interface installed in your local network.

HTTP HTTP Internet Web browser DMZ Application delivery controller Adaxes Web interface Local network

Uninstallation

Configuration backup

Before uninstalling Adaxes service, you may want to back up Adaxes configuration, or it will be permanently lost after uninstalling the last instance of Adaxes service in the configuration set.

To uninstall 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 Softerra Adaxes.
  3. Click Remove and follow the steps provided.

Upgrade

Important

Before upgrading, make sure that your license key can be used with the latest version of Adaxes. For details, see Check for updates.

Upgrade single-server configuration

If you have a single Adaxes service that doesn't share common 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 Adaxes configuration.
  2. Uninstall the old version of Adaxes.
  3. Install the new version.
  4. Restore the Adaxes configuration.
  5. Activate your license key.

Upgrade multi-server configuration

If you have multiple Adaxes services sharing common configuration, you need to reinstall them one after another by performing the following steps:

  1. Uninstall the old version of Adaxes service.
  2. Install the new version. During the installation, join the new Adaxes service to your configuration set.

Moving Adaxes service to another computer

If you need to move a 2020.1 or older Adaxes service instance to another computer, you need to transfer pending approval requests.

How do I

How do I grant permissions to publish Adaxes service

The Adaxes service account should have the permissions necessary to publish and unpublish the Adaxes service in Active Directory (create/delete a Service Connection Point). To grant the permissions:

  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 checkboxes for the Create All Child Objects and Delete All Child Objects permissions.
  8. Click OK.

How do I install Adaxes from the command line

To install Adaxes components from the command line, use the following commands:

Adaxes service

msiexec /quiet /i "<path>adaxes.msi" ADDLOCAL=ServiceFeature ADMCFGTYPE=0 ADMADMINNAME="<adminUsername>" ADMADMINPWD="<adminPwd>" ADMSERVICEADMINSID="<adminSID>" OPENADAXESPORTINFIREWALL=1 

where:

  • <path> - the path to the Adaxes installation file (adaxes.msi or adaxes_x86.msi).
  • <adminUsername> - the username of the account that will be used as the Adaxes service account (e.g. admin@company.com).
  • <adminPwd> - the password of the account that will be used as the Adaxes service account.
  • <adminSID> - the SID of the account that will be used for the service installation (e.g. S-1-5-21-2718492785-1413807572-3629993048-500).

Adaxes Web interface

msiexec /quiet /i "<path>adaxes.msi" ADDLOCAL=AppWebUIFeature ADMWEBSERVICECONFIGSET="<config-set-id>"

where:

  • <path> - the path to the Adaxes installation file (adaxes.msi).
  • <config-set-id> - the identifier of the Adaxes service configuration set. For details on how to get the identifier, see Get the configuration set ID. If you are installing the Web interface and the Adaxes service on the same computer, and want the Web interface to always connect to this Adaxes service, don't specify this parameter.

Adaxes Web interface and Web interface configurator

msiexec /quiet /i "<path>adaxes.msi" ADDLOCAL=AppWebUIFeature,AppConfigWebUIFeature ADMWEBSERVICECONFIGSET="<config-set-id>"

where:

  • <path> - the path to the Adaxes installation file (adaxes.msi or adaxes_x86.msi).
  • <config-set-id> - the configuration set identifier of the Adaxes service the Web interface will be connected to. For details on how to get the identifier, see Get the configuration set ID. If you are installing the Web interface and the Adaxes service on the same computer, and want the Web interface to always connect to this Adaxes service, don't specify this parameter.

Adaxes REST API component

msiexec /quiet /i "<path>adaxes.msi" ADDLOCAL=RestApiFeature ADMWEBSERVICECONFIGSET="<config-set-id>"

where:

  • <path> - the path to the Adaxes installation file (adaxes.msi or adaxes_x86.msi).
  • <config-set-id> - the identifier of the Adaxes service configuration set. For details on how to get the identifier, see Get the configuration set ID. If you are installing the REST API component and the Adaxes service on the same computer, and want the REST API to always connect to this Adaxes service, don't specify this parameter.

Adaxes Administration console

msiexec /quiet /i "<path>adaxes.msi" ADDLOCAL=AdminConsoleFeature

where <path> specifies the path to the Adaxes installation file (adaxes.msi or adaxes_x86.msi).

Adaxes PowerShell module

msiexec /quiet /i "<path>adaxes.msi" ADDLOCAL=PowerShellFeature

where <path> specifies the path to the Adaxes installation file (adaxes.msi or adaxes_x86.msi).

How do I install Adaxes service with a specific language

By default, when installing Adaxes service, the language is automatically selected based on the locale set in the operating system. To install Adaxes service with a specific language, you need to launch the installation package from the command prompt:

  1. On the computer where you want to install Adaxes service, launch the command prompt.

  2. Type the following command and press Enter:

    msiexec /i "<path>adaxes.msi" ADMSERVICEINITCULTURE="<lang>"
    

    where:

    • <path> - the path to the Adaxes installation file (adaxes.msi or adaxes_x86.msi);
    • <lang> - the language for Adaxes service installation. Possible values:
      • en-US - English
      • fr-FR - French
      • de-DE - German

    Note

    Adaxes service is available in English, German and French. If a different language is specified, English language will be used.

    Example:

    msiexec /i "C:\adaxes.msi" ADMSERVICEINITCULTURE="de-DE"
    
  3. Follow the instructions in the wizard that opens.

How do I transfer pending approval requests

In Adaxes 2020.1 and older, pending approval requests are not replicated, which means if you are moving an Adaxes service instance to another computer, you need to manually transfer pending approval requests.

  1. Uninstall the Adaxes service instance which you want to move to another computer.
  2. Install the new Adaxes service instance and join it to your configuration set.
  3. On the computer where the old Adaxes service instance was installed, navigate to the common application data folder used by Adaxes. It is typically located at C:\ProgramData\Softerra\Adaxes 3\.
  4. Copy the AdaxesCommandQueueBackup folder to the computer where you installed the new Adaxes service, preserving the folder structure. If any folder doesn't exist, create it.

Tip

In Adaxes 2021.1 and newer, pending approval requests are replicated between Adaxes services, so the above actions are not necessary.