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 on-premises Active Directory domain.

    If you plan to manage only Azure AD domains via Adaxes, you still have to install Adaxes on a domain-joined computer. It can be any on-premises domain, even a placeholder domain created purely for management purposes.

  • 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: 3 GB or more recommended. See details below.
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

Log records stored in the SQLite database on the computer where Adaxes service is installed may take a significant amount of disk space. This amount depends on the average number of recorded events per day and the log record retention period, which is 30 days by default. It is recommended to allocate at least 1 GB for each month worth of log records.

Generally, 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

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

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

Installation

As a best practice, it is not recommended to install the Adaxes service on a domain controller because you will not be able to install it unless you select the built-in Administrator account as the Adaxes service account.

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.

      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 a 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. However, this right can get revoked by a domain-based Group Policy. In this case, you will need to explicitly grant the Log on as a service right to the Adaxes service account in a domain-based Group Policy. For details, see How do I grant Log on as a service right.

    • 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

If you are installing Adaxes for the first time or installing it on a new computer, you need to perform post-installation steps.

Multi-server deployment

You can set up multiple Adaxes services that share common configuration (managed 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.

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.

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.

    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.

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.

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. For example:

     Application Request Routing Module {id=app-request-routing}
    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) {id=f5-big-ip}
    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 {id=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 password or search the 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 from outside the internal network.

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.

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

To avoid any compatibility issues, it is recommended to upgrade all Adaxes components (e.g. Adaxes service, Administration console, Web interface) to the same version. This is particularly important when upgrading to Adaxes 2023, as its components are completely incompatible with components from older versions.

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

Have your license key (license.admlic) at hand, as you will need to reactivate your license right after the upgrade.

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 the latest version, and then restore the configuration.

To upgrade, perform the following steps:

  1. Back up the Adaxes configuration.

  2. Uninstall the old version of Adaxes.

  3. If you have Adaxes 2017.2 and older, you need to do an intermediate update to Adaxes 2021.1. Otherwise, skip this step.

     Upgrade from Adaxes 2017.2 and older
    1. Download and install Adaxes 2021.1.

    2. Restore the Adaxes configuration.

    3. Navigate to the folder where Adaxes Web interface is installed. By default, the folder is C:\Program Files\Softerra\Adaxes 3\Web Interface.

    4. Migrate the old configuration of your Web interface using the Softerra.Adaxes.Web.Migration.UI.exe tool.

    5. Back up the Adaxes configuration once again.

    6. Uninstall Adaxes 2021.1.

  4. Install the latest version.

  5. Restore the Adaxes configuration.

  6. 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 latest version. During the installation, join the new Adaxes service to your configuration set.

 Upgrade from Adaxes 2017.2 and older

To upgrade from 2017.2 and older, you need to do an intermediate upgrade of one Adaxes service instance to Adaxes 2021.1, and then upgrade all instances to the latest version.

  1. Back up the Adaxes configuration.

  2. Uninstall one Adaxes service instance from your configuration set.

  3. Download and install Adaxes 2021.1. During the installation, join the new instance to your configuration set.

  4. On the computer where you have just installed Adaxes 2021.1:

    • Restore the Adaxes configuration.

    • 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 3\Web Interface by default.

  5. Upgrade all Adaxes services one by one by following the standard two-step multi-server upgrade process described above. The 2021.1 service should be reinstalled last.

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 {id=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 {id=install-from-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 {id=install-with-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

    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 {id=transfer-pending-approval-requests}

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

  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.

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

 How do I grant Log on as a service right {id=grant-logon-as-service}

When Adaxes service is installed on a workstation rather than on a domain controller, the Log on as service right is granted locally on the workstation via the Local Policy settings. If there is a conflicting domain-based Group Policy Object that grants such a right to other accounts, it will override the Local Policy during Group Policy refresh and will revoke the local right granted during the installation process. As a result, the Adaxes service will no longer be able to start. In this case, you need to grant the Log on as a service right to the Adaxes service account in a precedent domain-based Group Policy.

  1. Launch the Group Policy Management Console.

  2. Select the precedent Group Policy Object (GPO) effective for the computer where Adaxes service is installed.

  3. Right click the GPO and then click Edit.

  4. Navigate to Computer Configuration / Policies / Windows Settings / Security Settings / Local Policies and click User Rights Assignment.

  5. Add the Adaxes service account to the Log on as a service policy.