Skip to main content
Version: 16.1

Migrate System Users

In ADONIS 15.0 and earlier, Windows users could be manually imported from Microsoft Active Directory via the desktop application Administration Toolkit. These so-called "system users" were authenticated directly against Active Directory and could be used for secure authentication with ADONIS and the Administration Toolkit.

With the release of ADONIS 16.0, support for logging in with "system users" was phased out. To continue authenticating users against Active Directory in ADONIS 16.1 with relatively little configuration effort, LDAP authentication can be configured. Alternatively, the authentication mechanisms IDM, SAML, or OIDC can be used.

Set Up LDAP Authentication for "System Users"

To configure LDAP authentication so that "system users" can authenticate against Active Directory, you need to complete the following steps:

  1. Adapt LDAP Settings

  2. Adapt Connector-Specific Settings

  3. Start Authenticating Users

note

This guide covers only the essential parameters needed to enable authentication for former "system users" in ADONIS 16.1. For information on additional parameters, see the LDAP section in the Administration Help.

Adapt LDAP Settings

To migrate "system users", you need to configure general LDAP settings and domain-specific parameters:

The configuration parameters that have to be adapted are listed below.

General LDAP Settings

First, you need to configure general LDAP settings that apply to all domains:

  • Edit the LDAP Settings in the right pane.

Adapt the following parameters:

  • Enabled

    Select this option to enable the LDAP mechanism globally.

  • Properties

    Define the LDAP properties that should be available for all users. The property sAMAccountName must be included as it is used to uniquely identify users and serves as the login name within ADONIS. Other properties are optional.

Example

Add the following property:

  • Name: sAMAccountName, Recursive node lookup: no

    Specifies the LDAP property "sAMAccountName", which corresponds to the Active Directory attribute "Security Account Manager (SAM) Account Name".

Usually, it should not be necessary to change the other general LDAP parameters.

Domain-Specific LDAP Parameters

Now set the domain-specific parameters:

  • In the left pane, under LDAP Domains, click Create to add a new domain.

Once you have added the domain, you can start working on the configuration right away. Adapt the following parameters:

  • Precedence

    Represents the order in which domains are tried during an authentication request. Ensure that the new domain is given the highest priority by setting its precedence value to "1".

  • Name

    Represents the identifier of this domain. You can choose any name.

  • Provider URL

    Specifies the URL for the LDAP directory server. This value takes the form ldap://host:port. Note that it is recommended to use IP addresses instead of domain names to avoid the DNS lookup.

  • Principal

    Represents the login name of the principal user used to look up all other users. This user MUST have read access to all parts of the directory service that are used in ADONIS.

  • Principal domain

    Represents the domain of the principal user.

  • Principal format

    This field defines how to compose the principal's username and domain to authenticate with the directory. For Microsoft Active Directory, set this value to %principal%@%principaldomain%.

  • Password

    Represents the password of the principal user. Will be stored in encrypted form.

  • Login base DN

    Represents the starting point in your directory structure from which the LDAP server begins searching for user objects during the authentication process. Replace company with your actual company or domain name, and com with the appropriate top-level domain (TLD) for your organisation.

  • Login filter

    This mandatory filter option includes a placeholder for the username, used to precisely identify the relevant user object in the LDAP directory. Set this value to (&(objectClass=user)(sAMAccountName=%username%)). When a user attempts to log in, ADONIS automatically replaces %username% with the entered username. The filter then searches the LDAP directory for a user object with an sAMAccountName attribute matching the provided username. If a corresponding entry is found, ADONIS confirms that the login credentials belong to a valid user in the directory.

  • Default connector

    Represents the connector with LDAP coupling that should be used to determine the user mapping when LDAP is used outside of a specific connector context (e.g., when synchronising users via a scheduled task). Select the standard connector ("Standard Login").

Usually, it should not be necessary to change the other domain-specific parameters.

Adapt Connector-Specific Settings

Next, you need to configure LDAP coupling for the standard connector ("Standard Login") to fetch additional user data and allow authenticating users against Active Directory.

  • In the ADONIS Administration, go to Authentication > Connectors.

  • Hover over the Standard Login connector, click More, and then select Edit. Now you can configure the connector.

When this connector is applied, the standard login page will be displayed in which the user can enter their username and password. If no LDAP coupling is configured, these credentials are used to authenticate the user against the available data in the database. If LDAP coupling is configured, the provided credentials will be used to authenticate the user against the configured directory service.

Adapt the following parameter on page 3 LDAP Coupling:

  • Enable/Disable LDAP coupling

    Select this option to enable LDAP coupling for this connector.

Next, Adapt the following parameters on page 4 User mapping in the Synchronize users section:

  • Create user automatically

    Select this option to have users who log in to ADONIS for the first time created "on-the-fly" in the ADONIS database.

  • Synchronize automatically

    Select this option to update user data according to the information retrieved from the directory service every time the user logs in. Manual changes to the user by the ADONIS administrator are overwritten in this case.

    What user data is synchronised can be defined in the child properties of this parameter (only activate Synchronize attributes for now):

  • Synchronize attributes: Specifies whether user attributes should be automatically synchronised between LDAP and ADONIS. Enable this option.

  • Synchronize roles: Specifies whether the assignment of system roles should be updated every time the user data is synchronised. Disable this option so "false" so existing system role assignments are not overwritten.

  • Synchronize groups: Specifies whether the assignment of user groups updated every time the user data is synchronised. Disable this option so existing group assignments are not overwritten.

  • Synchronize repositories: Specifies whether the assignment of repositories should be updated every time the user data is synchronised. Disable this option so existing repository assignments are not overwritten.

  • Synchronize named use: Specifies whether the assignment of named users for scenarios should be updated every time the user data is synchronised. Disable this option so existing scenario assignments are not overwritten.

Usually, it should not be necessary to change the other connector-specific parameters.

Start Authenticating Users

Save your changes in the ADONIS Administration. All users that can log in to the configured domain should also be able to log in to ADONIS now.

Furthermore, if users do not yet exist in the database, they are created automatically when they log in to ADONIS for the first time. However, such new users will still need to be manually assigned user groups, system roles, repositories, etc. – additional configuration steps are necessary to enable an automatic assignment of these elements based on LDAP data (see the User Mapping section in the Administration Help for more details).

(Optional) Tracking Errors

Logging output is written to the files "<Tomcat installation>/logs/ADONIS16_1.log" and "<ADONIS installation/*_aworker.log>".