Set Up Web Client Login with LDAP Coupling
During login to the ADOIT web client using the LDAP mechanism, ADOIT users are authenticated directly against a directory service (e.g. Active Directory or eDirectory).
Depending on the configuration, users that log in to the ADOIT web client for the first time will be created "on-the-fly" in the ADOIT database. They will be assigned to preconfigured system roles/user groups. 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:
This authentication mechanism is based on the LDAPv3 standard. Therefore a general compatibility to LDAP v3-compliant directory services is given. The authentication mechanism has been successfully tested with Microsoft Active Directory 2003/2008 R2 and eDirectory 8.8.6. Any other directory service requires a prior evaluation.
To configure this authentication mechanism, you need experience with JSON. If you need help, contact your ADOIT consultant.
Adapt Global LDAP Settings
The setup of this authentication mechanism requires the configuration of certain connection parameters and directory service specific properties:
- Open the Admin Page. On the toolbar at the top of the screen, click More , point to Authentication, and then click LDAP.
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”.
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".
default_domain
The identifier of the domain which should be used as default domain. The default domain is used whenever no domain was specified.
Domain-Specific LDAP Parameters
Now domain-specific parameters need to be set.
Under Authentication > LDAP, click the Add button to add a new domain.
Click the 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 synchronizing 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 on the Admin Page). 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 the ADOIT web client.
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. Examples are included in the Help file which you can download from the Admin Page.
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 Client\03 Tools\02 Password Encryption Tool" on the installation medium.
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.
On the Admin Page, on the toolbar at the top of the screen, click More , and then click Authentication.
Edit the Standard Login 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, ADOIT 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 if it doesn't exist yet or which system roles or user groups to assign to the user. Examples are included in the Help file which you can download from the Admin Page.
array "properties" (properties: {name, attr})
Mapping of LDAP properties to ADOIT attributes. Each property is an object.
Example"properties": [ { "name": "sn", "attr": "SURNAME" } ]
The value of the LDAP property "sn" is assigned to the ADOIT attribute "SURNAME" .
autoCreateUser
Specify whether users that log in to the ADOIT web client for the first time will be created "on-the-fly" in the ADOIT 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 synchronization task is performed. Manual changes to the user by the ADOIT administrator are overwritten in this case.
What user data is synchronized 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 synchronized. 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 synchronized. 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 synchronized. Possible values are ”true” or ”false”.
auto_sync_repos
Specify whether the assignment of repositories should be updated every time the user data is synchronized. 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 synchronized. 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 synchronization.
deleteNotFoundUsers
Specify whether users which are not found during synchronization should be deleted. Possible values are ”true” or ”false”.
moveUndeletableUsersToGroup
Specify whether users which cannot be deleted during synchronization 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.
userGroupForUndeletableUsers
Set this property to point to the name of the user group to which users which could not be deleted during synchronization 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 the web client. 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 ADOIT (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 ADOIT 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 ADOIT 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 ADOIT (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 ADOIT 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 ADOIT user group "Designer".
noteTo define the language of the user group names, select the language you want to use via the Language button on the Authentication 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 ADOIT 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 ADOIT (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 ADOIT database and also cannot be created.
To assign EA workflow roles to users, you must also define the property mfbID="{63868638-23DC-482A-95E1-CA20A445F306}".
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.
noteTo define the language of the user group names, select the language you want to use via the Language button on the Authentication 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 EA workflow roles to users, you must define the property mfbID="{63868638-23DC-482A-95E1-CA20A445F306}".
repositories [{properties: name, type, match, targetType, targetName, additionalConfig {object-group} [optional]}]
Repositories is an array of objects that can be used to specify that users are shared with a specific repository. 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.
noteYou can use the Copy the ID to the clipboard functionality in the Administration Toolkit to find out the ID of a repository. 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 ADOIT 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.
The scenarios have the following IDs:
Design & Document: {452D9152-E300-4FFF-9A15-2DC2529B009F}
Control & Release: {0426D2A9-E01C-4938-AA65-15FAA0B47FC3}
Explore & Contribute (ArchiMate Library only): {0689AC37-8150-487B-B500-D99201AAAD6D}
Govern & Manage (Standard Library only): {C047C45B-1A5C-4F03-8EB4-70E17859A7DC}
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 on the Admin Page. Once the changes are saved, they take effect immediately. A restart is not required.
All users that can log in to the configured domain(s) should also be able to log in to the ADOIT web client. Furthermore, if a user does not yet exist in the database, it is created and also assigned to the corresponding user groups/system roles according to the mapping definition within the configuration.
(Optional) Tracking Errors
Logging output is written to the files ”<Tomcat installation>/logs/ADOIT13_0.log” and ”<ADOIT installation/*_aworker.log>”.