Skip to main content
Version: 16.0

Set Up Login with LDAP Coupling

During login to ADONIS using the LDAP mechanism, ADONIS users are authenticated directly against a directory service (e.g. Active Directory or eDirectory).

Depending on the configuration, users that log in to ADONIS for the first time will be created "on-the-fly" in the ADONIS database. They will be assigned to preconfigured user groups and system roles. Optionally, specific repositories will be assigned to them as their working place and they will be shared with these repositories to make them available as objects in modelling.

The following steps have to be taken to configure this authentication mechanism:

  1. Adapt Global LDAP Settings

  2. Adapt Connector-Specific Settings

  3. Start Authenticating Users

note

This authentication mechanism is based on the LDAPv3 standard. Therefore a general compatibility to LDAP v3-compliant directory services is given.

caution

To configure this authentication mechanism, you need experience with JSON. If you need help, contact your ADONIS consultant.

info

The Apache Tomcat web server has to be restarted if these settings are changed. Otherwise the changes will not become effective.

Adapt Global LDAP Settings​

The setup of this authentication mechanism requires the configuration of certain connection parameters and directory service specific properties:

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

General LDAP Parameters​

First, general parameters that apply to all domains need to be set.

  • Edit the LDAP Settings.

Adapt the following parameters:

  • enabled

    Specifies whether using the LDAP mechanism is enabled globally or not. Possible values are ”true” or ”false”.

  • default_domain

    The identifier of the domain which should be used as default domain. The default domain is used whenever no domain was specified.

  • array "properties" (properties: name etc.)

    Here some LDAP properties which should be available for all users can be specified.

    Example

    "properties": [ { "name": "cn" }]

    Specifies the LDAP property "cn" which refers to the Active Directory attribute "Common Name".

Domain-Specific LDAP Parameters​

Now domain-specific parameters need to be set.

  • Under Domains, click the New connector button to add a new domain.

  • Click the Edit connector button to edit your new domain.

The new domain will already include a number of properties. Adapt the following parameters:

  • name

    name represents the identifier of this domain. This value must be unique among the domains.

  • defaultConnector

    defaultConnector is an optional property. It is used to determine the user mapping when LDAP is used outside the context of a specific authentication mechanism (= connector) , e.g. when synchronising users via a scheduled task.

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

  • security_protocol

    In case you are using LDAPS, specify an SSL compatible protocol here (e.g. 'SSL').

  • ssl_certificate

    ssl_certificate must be added in case you are using LDAPS. You can specify the SSL (X509) certificate to use (just the file name if you have uploaded it in the ADONIS Administration). Alternatively, you can install a trusted certificate globally in the trust store.

  • principal

    principal must be added to the domain configuration. This property represents the login name of the principle 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

    principal_domain must be added to the domain configuration. This property represents the domain of the principle user.

  • principal_format

    principal_format must be added to the domain configuration. This property represents the format in which the principal name and domain are composed for the initial context creation.

note

Examples are included in the template with all authentication parameters explained. You can download this template from the LDAP page by clicking Download Template.

  • password

    password must be added to the domain configuration. This property represents the password of the principal user in encrypted form. The password must be encrypted with an encryption tool which can be found in the directory "03 Web Application\02 Tools\02 Password Encryption Tool" in the installation package.

  • array "unique_identifier"

    An array of strings to serve as a unique identifier of the user for internal use. To define multiple identifiers, add them to the array (separated by commas):

    Example

    "unique_identifier": [ "cn", "distinguishedName" ]

    Specifies the LDAP properties "cn" and "distinguishedName" as unique identifiers.

    The different unique identifiers will be tried sequentially and the first one which is found will be used.

  • login_base_dn

    The base domain specification where the user objects are located.

  • login_filter

    A mandatory filter option including a username placeholder to retrieve exactly the required user object.

Adapt Connector-Specific LDAP Settings​

Each authentication mechanism (= connector) can be configured to use LDAP coupling to fetch additional user data. However, authentication against a directory service using the LDAP coupling will only take place if LDAP coupling is configured for the Standard connector.

  • In the ADONIS Administration, go to Home > More options, and then click General Settings.

  • On the right side of the Standard Login connector, click the Edit connector button .

This configuration represents the Standard connector. When this connector is applied, the standard login page will be displayed in which the user can enter his user name 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.

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

LDAP Coupling​

The following parameters allow you to enable and configure LDAP coupling for this connector.

  • ldap (property: enabled)

    Specifies whether LDAP coupling for this connector is enabled or not. Possible values are ”true” or ”false”.

  • ldap (property: domains) [optional]

    The property domains is an array of identifier(s) of the domain(s) which should be used for authentication. The name of the domain must match the name of a domain configured in the global LDAP settings. If no domain is specified, ADONIS tries to authenticate a user against all domains from the global LDAP settings sequentially until first success.

User Mapping​

The following parameters allow you to control how the authentication process deals with the user that logs in, e.g. if a user should be created when it doesn't exist yet or which system roles or user groups to assign to the user.

note

Examples are included in the template with all authentication parameters explained. You can download this template from the General Settings page by clicking Download Template.

  • array "properties" (properties: {name, attr})

    Mapping of LDAP properties to ADONIS attributes. Each property is an object.

    Example

    "properties": [ { "name": "sn", "attr": "SURNAME" } ]

    The value of the LDAP property "sn" is assigned to the ADONIS attribute "SURNAME" .

  • autoCreateUser

    Specify whether users that log in to ADONIS for the first time will be created "on-the-fly" in the ADONIS database. Possible values are ”true” or ”false”.

auto_sync_user (properties: enabled etc.)

Specify whether user data should be updated according to the information retrieved from the directory service every time the user logs in and/or every time a periodic synchronisation task is performed. 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:

  • enabled

    Specify whether this setting is enabled or disabled. Possible values are ”true” or ”false”.

  • auto_sync_attributes

    Specify whether the assignment of user attributes should be updated every time the user data is synchronised. Possible values are ”true” or ”false”.

  • auto_sync_roles

    Specify whether the assignment of system roles should be updated every time the user data is synchronised. Possible values are ”true” or ”false”.

  • auto_sync_groups

    Specify whether the assignment of user groups should be updated every time the user data is synchronised. Possible values are ”true” or ”false”.

  • auto_sync_repos

    Specify whether the assignment of repositories should be updated every time the user data is synchronised. Possible values are ”true” or ”false”.

  • auto_sync_nameduse

    Specify whether the assignment of named users for scenarios should be updated every time the user data is synchronised. Possible values are ”true” or ”false”.

The child properties are evaluated only if enabled is set to ”true”.

user_deletion_handling

In the child properties of this parameter, specify what should happen with users which are not found during synchronisation.

  • deleteNotFoundUsers

    Specify whether users which are not found during synchronisation should be deleted. Possible values are ”true” or ”false”.

  • moveUndeletableUsersToGroup

    Specify whether users which cannot be deleted during synchronisation should be moved to a specific user group. Note that you have to set userGroupForUndeletableUsers to point to the name of the user group. Otherwise, the users will not be moved.

note

Which users are undeletable?

  • Users who are logged in.

  • Users that have been shared with a repository (= to make them available as objects in modelling) when they are being used in a model or have incoming references.

  • userGroupForUndeletableUsers

    Set this property to point to the name of the user group to which users which could not be deleted during synchronisation should be moved. This parameter is only evaluated if moveUndeletableUsersToGroup is set to ”true”.

mapped_user_handling

In the child properties of this parameter, specify how to map authenticated users to alias users.

  • mappings [{properties: name, type, match, mappeduser, mapexistingusers [optional]}]

    mappings is an array of objects that can be used to specify cases where already authenticated users should be mapped to (= treated as) alias users. These alias users will represent the authenticated user when they log in to ADONIS. An example of this might be mapping a specific group of users to a user with access to the Organisation Portal.

    One array consists of one or more mapping objects with the following properties: name represents the property from the directory service. type can either be equals, equalsIgnoreCase or contains. match represents the (partial) match of type. mappeduser represents the alias user in ADONIS (must exist, must have trusted login enabled). mapexistingusers is an optional property to specify which users are affected. Set to ”true” to specify that the authenticated user should always be represented by the alias user if the mapping applies. Set to "false" if this should only be done if the authenticated user does not exist yet in the ADONIS database and also cannot be created.

    Example

    "mappings": [ { "name" : "memberOf", "type" : "contains", "match" : "Quality Management", "mappeduser" : "Reader2" }]

    The value(s) of the property "memberOf" (property with multiple values) must contain "Quality Management", then the user is mapped to the alias user "Reader2".

  • default_mapping [optional]

    The default alias user that users should get assigned to in case none of the mappings defined via the mappings array applies.

The following parameters determine how to process user data concerning the assignment of system roles, user groups and repositories.

  • groups [{properties: name, type, match, targetType, targetName, mapexistingusers [optional]}]

    groups is an array of objects that can be used to specify the mapping of LDAP properties to ADONIS user groups. Multiple mappings can be provided in order to assign a user to different user groups.

    One mapping consists of the following properties: name represents the property from the directory service. type can either be equals, equalsIgnoreCase or contains. match represents the (partial) match of type. targettype must be set to group. targetname represents the user group in ADONIS (must exist). mapexistingusers is an optional property to specify which users are affected. Set to ”true” to specify that the authenticated user should always be represented by the alias user if the mapping applies. Set to "false" if this should only be done if the authenticated user does not exist yet in the ADONIS database and also cannot be created.

    Example

    "groups": [ { "name": "claim_group", "type": "contains", "match": "Designer", "targetType": "group", "targetName": "Designer", } ]

    The value(s) of the property "claim_group" must contain "Designer", then the user is assigned to the ADONIS user group "Designer".

    note

    To define the language of the user group names, select the language you want to use via the Language button on the General Settings page.

  • roles [{properties: name, type, match, targetType, targetName, mapexistingusers [optional], mfbID [optional]}]

    roles is an array of objects that can be used to specify the mapping of LDAP properties to ADONIS system roles. Multiple mappings can be provided in order to assign a user to different system roles.

    One mapping consists of the following properties: name represents the property from the directory service. type can either be equals, equalsIgnoreCase or contains. match represents the (partial) match of type. targettype must be set to role. targetname represents the language independent name of the system role in ADONIS (must exist). mapexistingusers is an optional property to specify which users are affected. Set to ”true” to specify that the authenticated user should always be represented by the alias user if the mapping applies. Set to "false" if this should only be done if the authenticated user does not exist yet in the ADONIS database and also cannot be created.

    To assign model release workflow roles to users, you must also define the property mfbID="{3AD30848-5A75-484C-B27C-5AB621932DC9}".

    To assign document release workflow roles to users, you must also define the property mfbID="{C2B15753-7357-4F3C-AF70-BFF38A70D4F2}".

  • default_groups [optional]

    default_groups is an array of strings that define the default user groups the users should get assigned to in case none of the mappings defined via the groups array applies. If this groups do not exist, users are assigned to the standard group.

    note

    To define the language of the user group names, select the language you want to use via the Language button on the General Settings page.

  • default_roles [optional] {properties: name, mfbID}

    default_roles is an array of objects that define the default system roles the users should get assigned to in case none of the mappings defined via the roles array applies. Define any number of objects.

    name represents the property from the directory service.

    To assign model release workflow roles to users, you must define the property mfbID="{3AD30848-5A75-484C-B27C-5AB621932DC9}".

    To assign document release workflow roles to users, you must define the property mfbID="{C2B15753-7357-4F3C-AF70-BFF38A70D4F2}".

  • repositories [{properties: name, type, match, targetType, targetName, additionalConfig {objectgroup} [optional]}]

    repositories is an array of objects that allows you to assign a specific repository to users as their working place. Simultaneously, the users will be made available as objects in modelling.

    Define any number of objects to assign a user to different repositories. If no repository is configured, users will be shared with all repositories. Additionally, you can define an object group per repository where the shared user objects should be located.

    To perform a static assignment, the targettype must be set to repository and the targetName property (= the ID of a repository) must be specified. Users will be unconditionally shared with a specific repository.

    A dynamic assignment is possible by mapping LDAP properties to repositories. Such a mapping consists of the following attributes: name represents the property from the directory service. type can either be equals, equalsIgnoreCase or contains. match represents the (partial) match of type. targettype must be set to repository. targetName is the ID of the repository.

    note

    Set the targetName property to * to explicitly assign users to all repositories.

    note

    To find out the ID of a repository, go to ADONIS Administration > Repositories. To the right of the repository you want, click More, and then click Copy the ID to the clipboard. If you want to define an object group per repository where the shared user objects should be located, please do not hesitate to contact your ADONIS consultant.

  • nameduse [{properties: name, type, match, targetType, targetName}]

    nameduse is an array of objects that can be used to assign named users for specific scenarios based on LDAP properties.

    The array consists of one or more mapping objects with the following properties: name represents the property from the directory service. type can either be equals, equalsIgnoreCase or contains. match represents the (partial) match of type. targettype must be set to nameduse. targetname is the ID of the scenario.

note

The scenarios have the following IDs:

  • Design & Document: {A09B203E-0333-462B-A7E7-635F962D40CA}

  • Control & Release: {14B604D1-EFDE-4E34-A789-46FD6CA4E9C7}

  • Read & Explore: {9C822D49-B1D7-4EB7-A519-DEF5509E5FBD}

  • Organisation Portal: {54467D33-89F0-4F4B-9276-E45B34B5D5FC}

Constraints​

The applicability and availability of a connector can be constrained, to e.g. only allow certain connectors for requests coming from certain IP addresses.

  • constraint [{properties: type, mode, logic [optional], values}]

    All constraints must be of type client-ip which means that if a client's IP falls in the specified pattern, the connector is either applied or not applied (depending on the used logic). Two different modes can be defined for the type client-ip : match or subnet. values is an array of strings representing the IP addresses.

Start Authenticating Users​

Save your changes in the ADONIS Administration. In order to start authenticating users, the Apache Tomcat web server has to be restarted for the configuration changes to become effective.

All users that can log in to the configured domain(s) should also be able to log in to ADONIS. Furthermore, if a user does not yet exist in the database, it is created and also assigned to the corresponding user groups and system roles according to the mapping definition within the configuration.

(Optional) Tracking Errors​

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