Inhalt/Content
Introduction
iAGENT comes with integrated user management. However, it is possible to set up authentication via an external identity management system. This requires a few configuration steps that are described in this tutorial.
Short Description of Configuration in iAGENT
Via system parameters (Administration –> System –> System Settings –> System Parameters tab) the following parameters have to be added / adjusted and the values have to be set according to the environment. Alternatively, the Routing.conf file on the file system of the iAGENT web server can also be adjusted.
external.auth.enabled = true external.auth.agent.enabled = true external.auth.routing.enabled = true external.auth.user.auth.class = com.novomind.ecom.common.auth.ldap.ADLDAPAuthenticator external.auth.ldap.enabled = true external.auth.ldap.servers = [{url:"ldaps://xxx.novomind.com", domains:[novomind.com], pagesize.max: 234, timeout.connect: 1000 , timeout.read: 2000},{url:"ldaps://xxx2.novomind.com", domains:[novomind.com], pagesize.max: 234, timeout.connect: 1000 , timeout.read: 2000},{url:"ldaps://xxx3.novomind.com", domains:[novomind.com], pagesize.max: 234, timeout.connect: 1000 , timeout.read: 2000}] external.auth.ldap.user.properties.read = false
If these parameters are configured accordingly, the entered user name and password are used to authenticate against the external system when logging in.
For accesses with system users (such as from apps or REST API), one of the following keys must be set to the value DB on the corresponding user (Individual Settings tab in User Settings):
- auth.type (for login on Supervisor and Desk)
- auth.type.agent (for login on Desk)
- auth.type.user (for login on Supervisor)
Authentication with an Active Directory server
Functioning
The authentication uses an Active Directory server to authenticate a user when they log in.
To do this, the AD is addressed via LDAP/LDAPS and a connect/bind with the corresponding user is attempted. If the connect is successful, the user is considered authenticated. If desired, it is also possible to check whether the user is stored in one or more groups in the AD. If a check is carried out and the user is not present in a configured group, the user is considered to be unauthenticated.
Furthermore, it is possible to read properties of the user from the AD and to store these with the user.
However, this requires a ‘search’ user that has the appropriate rights in the AD.
Multiple AD servers can be used for authentication, so that a fallback scenario, for example, can be configured. It is also possible to support registration in multiple domains.
All configuration changes take effect immediately or shortly after at runtime.
Installation
A customer-specific authentication filter must be stored for the customer so that the one authentication class can be stored.
Configuration
The configuration of the authentication is stored in the central configuration file ‘Routing.conf’.
The following configuration parameters are relevant:
Parameter ‘external.auth.enabled’ -> Activates the AuthFilter so that external authentication can be used.
Should be set to the following value:external.auth.enabled = true
– ‘external.auth.agent.enabled’ parameter -> Enables/disables (true/false) registration with the agent through external authentication.
external.auth.agent.enabled = true
– ‘external.auth.agent.enabled’ -> Enables/disables (true/false) the login to the supervisor through external authentication.
external.auth.routing.enabled = true
– ‘external.auth.user.auth.class’-> Sets the class to be used for authentication. In the case of AD authentication:
external.auth.user.auth.class = com.novomind.ecom.common.auth.ldap.ADLDAPAuthenticator
– ‘external.auth.ldap.enabled’ -> Activates/deactivates AD LDAP authentication.
external.auth.ldap.enabled = true
– ‘external.auth.ldap.servers’ -> This parameter can be used to configure the servers to be used. The configuration is done in JSON notation. The individual parameters are explained in more detail below. As an example, the configuration for two AD servers looks like this:
external.auth.ldap.servers = [{url:‘ldap://10.22.102.77’, domains:[novomind.de, novomind.com], username: ‘administrator’, password: ‘xxx’, pagesize.max: 234, timeout.connect: 234 , timeout. read: 234},{url:\‘ldap://10.21.102.77\’, domains:[products.novomind.com], username: ‘administrator’, password: ‘xxx’, pagesize.max: 234, timeout.connect: 234 , timeout.read: 234}]
– ‘external.auth.ldap.user.properties.read’ -> This parameter determines whether the user properties should be read from the LDAP server after authentication.
The default value is ‘false’. These properties are required, for example, when creating or updating users (keyword UserModifyClone).
external.auth.ldap.user.properties.read = true
– ‘external.auth.ldap.groups.routing’ -> Group names (LDAP NameInNameSpace cn=<group name>…) can be stored, in which a user must be in order to be allowed to log on to the supervisor. If the parameter is not set or is empty, no group check is performed.
external.auth.ldap.groups.routing = [Group1, Supervisors, Group2]
– ‘external.auth.ldap.groups.agent’ -> Group names (LDAP name in name space cn=<group name>…) can be stored in which a user must be in order to be allowed to log in to the agent. If the parameter is not set or is empty, no group check is carried out.
external.auth.ldap.groups.agent = [agent group 1, ‘agent group 2’]
– ‘external.auth.ldap.user.domain.preserve’ -> This parameter can be used to control whether the domain used during a login (e.g. User@example.com) should be discarded or whether it corresponds to the username. By default, the domain is discarded after a login and only serves to determine the AD server. This prevents all AD servers from being ‘tried out’ during a login. In this case, the username of the logged-in user would be ‘User’. If the parameter is set to true, the entire username used during login is used.
external.auth.ldap.user.domain.preserve = false
LDAP server configuration
The configuration of the logon servers is done via the ‘external.auth.ldap.servers’ parameter. Multiple servers can be defined there in JSON notation, which
are used depending on the logon. The following parameters can be stored for each server configuration:
– Parameter ‘url’ (required) -> The URL used to access the LDAP server is stored here. A port can also be specified if the port differs from the standard port for the corresponding protocol. Examples:
url:"ldaps://ad.example.com"url:"ldap://ad.example.com"url:"ldaps://ad.example.com:965"
– ‘domains’ parameter (required) -> Specifies the domains managed by the AD server. During the login attempts, the corresponding domain is appended to the username if the login was made without a domain.
domains:[rz.example.com, intern.example.com]
– ‘username’ parameter (optional) -> Defines the username of the AD user that can be used for a search in the LDAP (e.g. reading the user properties).
username: ‘search-ad’
– ‘password’ parameter (optional) -> Defines the password for the AD user that can be used for a search in the LDAP (e.g. reading the user properties).
The password can be stored encrypted or unencrypted.
password: ‘xxx’
– ‘pagesize.max’ parameter: this defines the maximum value that a search is allowed to return. For larger values, paging is used. Normally, an LDAP server can return 1000 results for a single request. This is also the default value.
pagesize.max: 500
– ‘timeout.connect’ parameter -> Determines how long the system waits for a connection to a server (in milliseconds). The default is 500 ms.
timeout.connect: 500
– ‘timeout.read’ parameter -> Determines how long to wait for a search result (e.g. group search, search for user properties). The default is 30000 ms.
timeout.read: 30000
Server configuration for a fallback scenario for the domain ‘example.com’
The LDAP logon can be configured so that, for example, two servers are used for authentication at a domain.
In this case, the user would first log in to the first server and then, in the event of a network error (e.g. ConnectTimeout), to the second server.
If the first server can be accessed and user authentication fails, the second server will not be accessed.
In this case, a simple configuration would look like this:
external.auth.ldap.servers= [{url:‘ldap://ad1.example.com’, domains:[example.com]}, {url:‘ldap://ad2.example.com’, domains:[example.com]}}
Server configuration for a scenario with multiple domains
If the login is made to multiple domains and multiple AD servers, the domain can be appended to the username in the login mask, for example (see also the ‘external.auth.ldap.user.domain.preserve’ parameter), if the username does not already contain it. When selecting the the authentication server to be used, the transferred domain is taken into account so that no unnecessary logins to other AD servers occur.
Please note:
Please note that if no domain is specified in the user name (user name instead of user name@domain), the login will be attempted with this user on all domains one after the other. If the login fails on the first domain, the login will be attempted on the next domain. This will inevitably result in failed login attempts, which could attract the attention of your internal IT security team.
A simple configuration with two domains and no fallback server would look like this:
external.auth.ldap.servers= [{url:‘ldap://ad1.example.com’, domains:[ad1.example.com]}, {url:‘ldap://ad2.example.com’, domains:[ad2.example.com]}}
Automatic user creation in iAGENT
After a successful login using an LDAP user that does not yet exist in iAGENT, the following setting can be used to ensure that the user is then also automatically created in the iAGENT system. This is done without assigning roles and rights. It is therefore not possible for the user to log in yet, but the supervisor sees the user and only needs to assign the appropriate roles.
ldap.autoCreateUser = true
UserModifyClone
General
The UserModifyClone class can be used to create/change a user when an external authentication is used (e.g. LDAP or SAML). The user to be used for cloning and the data to be stored
can be configured. For example, if the name and email address are passed during authentication, these can be updated during registration. It is also possible to store/update user-specific properties (UserProperties).
Prerequisites
To use the UserModifyClone class, you need to use external authentication and the associated customer-specific authentication filter.
The following implementations of external authentication are currently available:
– com.novomind.ecom.common.auth.ldap.ADLDAPAuthenticator (login via LDAP to an ActiveDirectory server)
– com.novomind.ecom.saml.Authenticator (logging in to an IdentityProvider using the SAML protocol – SSO)
How it works
If external authentication is successful, a user (agent/supervisor) is created if configured.
It is possible to configure different default template users for creating an agent and a supervisor.
If a client is also transferred by the registration, this can also be used to use a different template user for each client.
Properties obtained from the registration (name, email, cost centre, first name, last name) can be used to update the user in the iMail system. The configuration determines which properties are updated.
Configuration Creating a user
The configuration is done in the ‘Routing.conf’ configuration file. The following parameters play a role here:
– ‘external.auth.user.modify.class’ -> This parameter defines the class to be used to create/modify a user. By default, this is the following class:external.auth.user.modify.class = com.novomind.ecom.auth.modify.UserModifyClone
– ‘external.auth.user.modify.clone.enabled’ -> Can be set to activate/deactivate (true/false) cloning/modifying.
If the parameter is not set, cloning/modifying is not active. The following value should be set:external.auth.user.modify.clone.enabled = true
– ‘external.auth.user.modify.clone.routing.enabled’ -> Can be used to activate/deactivate (true/false) cloning/modifying for a supervisor login. If the parameter is not set, cloning/modifying is not active. The following value should be set:external.auth.user.modify.clone.routing.enabled = true
– ‘external.auth.user.modify.clone.routing.user’ -> Defines the user that is used as a template for creating a supervisor user.
The user name of a user configured in the iAGENT system is stored.external.auth.user.modify.clone.routing.user = svcloneuser
– ‘external.auth.user.modify.clone.routing.mandator.mapping’ -> If a client in the iMail system could be determined by the login/authentication
(normally no client is available after login), this can be used to determine the template user for cloning. Either the name of the client or the ID in the iAGENT system can be used. If no user can be determined here, the user defined by the parameter ‘external.auth.user.modify.clone.routing.user’ is used.
external.auth.user.modify.clone.routing.mandator.mapping = {Mandator1:svuser1, 21:svuser2}
– ‘external.auth.user.modify.clone.agent.enabled’ -> Can be set to activate/deactivate (true/false) cloning/modifying during agent login. If the parameter is not set, cloning/modifying is not active when an agent logs on. The following value should be set:external.auth.user.modify.clone.agent.enabled = true
– ‘external.auth.user.modify.clone.agent.user’ -> Defines the user that is used as a template for creating an agent user.
The user name of a user configured in the iAGENT system is stored.external.auth.user.modify.clone.agent.user = agentcloneuser
– ‘external.auth.user.modify.clone.agent.mandator.mapping’ -> If a client in the iAGENT system could be determined by the login/authentication (usually no client is available after login), this can be used to determine the template user for cloning. Either the client name or the ID in the iAGENT system can be used.
If no user can be determined here, the user defined by the ‘external.auth.user.modify.clone.agent.user’ parameter is used.
external.auth.user.modify.clone.agent.mandator.mapping = {Mandator1:agentuser1, 21:agentuser2}
– ‘external.auth.user.modify.email.generate’ -> If the creation of a user fails because an email address is already in use, setting this parameter will trigger the generation of a random email address.
These are email addresses from the non-existent domain ‘example.com’. This feature is not active by default.external.auth.user.modify.email.generate = false
Configuration: Changing/updating a user
– ‘external.auth.user.modify.properties.enabled’ -> Switches changing/updating a user off/on (false/true).
If not set, the feature is disabled. The following value should be set:external.auth.user.modify.properties.enabled = true
– ‘external.auth.user.modify.properties.mapping’ -> This parameter can be used to store a mapping for parameters obtained through authentication. This allows parameters obtained through authentication to be found under a different name. A mapping is required for parameters that are to be set later under a different name as user property. The mapping can also be used, for example, to determine the e-mail address (key ‘email’). The value of the parameter is in JSON notation.
external.auth.user.modify.properties.mapping = {email: ‘mail’, displayname: ‘displayName’, AD_FirstName:‘givenName’, AD_LastName:‘sn’, AD_Surname:‘sn’, AD_Surname:‘sn’, AD_UserPrincipalName‘ , AD_DisplayName:’displayName‘ , AD_CostCenter:’costCenter"}
– ‘external.auth.user.modify.properties.names’ -> Defines the parameters that are to be stored as properties for the user.
These properties must be obtained under this name either directly through the authentication or by mapping to another parameter that was obtained through the authentication.
external.auth.user.modify.properties.names = [AD_First name, AD_Last name, AD_User ID, AD_Display name, AD_Cost centre]
– ‘external.auth.user.modify.update.email’ -> Determines whether the user’s email address should be updated.
The ‘email’ property is used for this. This may need to be provided by the mapping.external.auth.user.modify.update.email = true
– ‘external.auth.user.modify.update.name’ -> Determines whether the name (not the user name) of the user should be updated.
The ‘displayname’ property is used for this. This may need to be provided by the mapping.
If the ‘displayname’ property is not available, an attempt will be made to use the ‘firstname’ and ‘lastname’ properties.external.auth.user.modify.update.name = true