Microsoft Active Directory

The Axon Ivy Engine connects to the traditional Microsoft Active Directory via LDAP. In most cases, it is sufficient to copy the template below and adjust the values. However, there are many detailed settings that you can find in the reference. The Engine Cockpit offers a detailed configuration page to connect Microsoft Active Directory.

Template

 1# Microsoft Active Directory as an Identity Provider for the 'default' Security System
 2# [engineDir]/configuration/ivy.yaml 
 3SecuritySystems:
 4  default:
 5    IdentityProvider:
 6    Name: "microsoft-active-directory"
 7    Config:
 8      Connection:
 9        Url: ldap://localhost:389
10        UserName: Administrator@axonivy.com
11        Password: "${encrypt:1234}"
12      Binding:
13        DefaultContext: ou=ivyteam,dc=axonivy,dc=com
14
15      # Role mappings
16      Roles:
17        Manager: cn=manager,ou=ivyteam,dc=axonivy,dc=com
18        Employee: cn=employee,ou=ivyteam,dc=axonivy,dc=com
19
20      # User property mappings
21      UserAttribute:
22        Properties:
23          phoneNumber: phone

Reference

  1Connection:
  2  # Url to the Identity Provider
  3  # - LDAP:  ldap://<hostname>:<port>   - port can be omitted if it is default port 389
  4  # - LDAPS: ldaps://<hostname>:<port>  - port can be omitted if it is default port 636
  5  # NOTE: security protocol needs to be set to "ssl" for LDAPS (Environment.java.naming.security.protocol, see below).
  6  Url: ldap://localhost:389
  7        
  8  # Ivy access to the Identity Provider
  9  # -------------------------------------
 10  #
 11  # provide a technical user for Ivy to access AD
 12  # none = no authentication (default if UserName/Password NOT configured)
 13  # simple = user name and password is used (default if UserName/Password is configured)
 14  # [enum: none, simple]
 15  AuthenticationKind: simple
 16
 17  # User name to authenticate to the Identity Provider (java.naming.security.principal).
 18  # Valid formats are... 
 19  # - LDAP Distinguished Name (RFC 4514) like cn=Administrator,dc=axonivy,dc=com
 20  # - Active Directory user name like Administrator@axonivy.com
 21  UserName: ""
 22
 23  # Password to authenticate (java.naming.security.credentials).
 24  # [password]
 25  Password: ""
 26
 27  # Use a connection pool to store established LDAP connections?
 28  #
 29  # This can speed up access to the AD since the connections are established once and re-used instead of established, used, closed.
 30  # N.B. Further configuration options for the pool have to be set in jvm.options.
 31  # The settings are documented in https://docs.oracle.com/javase/jndi/tutorial/ldap/connect/config.html
 32  #
 33  UseLdapConnectionPool: false
 34  
 35  # Are insecure SSL connections allowed(no server certificate verification)?
 36  #
 37  # NOTE: Setting EnableInsecureSSL to true will turn off server certificate verification.
 38  #       Whenever possible the LDAP server certificate (or its root certificate)
 39  #       should be added to the Ivy Engine trust store.
 40  #       See SSL.Client.TrustStore in the @engine.guide.url@/configuration/files/ivy-yaml.html
 41  #       on how to configure the engine truststore.
 42  #
 43  EnableInsecureSSL: false
 44
 45  Retry:
 46    # After a failure, how many times shall a call be retried?
 47    Count: 3
 48
 49    # Delay in milliseconds before the next retry call, after a failure.
 50    # With each retry the delay time doubles.
 51    Delay: 500
 52
 53  # Here you can configure additional environment properties for the LDAP context.
 54  Environment:
 55    # How to handle LDAP aliases. 
 56    # https://docs.oracle.com/javase/jndi/tutorial/ldap/misc/aliases.html
 57    # [enum: always, never, finding, searching]
 58    "java.naming.ldap.derefAliases": always
 59
 60    # Specify connection security
 61    #
 62    # If this property is unspecified, the behavior is determined by the service provider. 
 63    # https://docs.oracle.com/javase/jndi/tutorial/ldap/security/ssl.html
 64    # [enum: , ssl]
 65    "java.naming.security.protocol": ""
 66
 67    # Specify how referrals received from the Identity Provider are to be processed.
 68    # https://docs.oracle.com/javase/jndi/tutorial/ldap/referral/index.html
 69    # follow is the default setting, but may cause slow reading from the AD
 70    # ignore does not follow the referral
 71    # throw throws an error if a referral is found. It is intended mostly for identifying and debugging LDAP problems.
 72    #
 73    # [enum: follow, ignore, throw]
 74    "java.naming.referral": follow
 75    
 76    # LDAP Attributes binary 
 77    "java.naming.ldap.attributes.binary": "objectSid objectGUID"
 78
 79Binding:
 80  #
 81  # Default Context to import from. 
 82  # The security system only sees and can import objects below the default context. 
 83  # If you want to see and import all users of an Identity Provider, then set the default context to the root object/domain.
 84  # If you want to import only users from a certain department or location, then you can set the default context to 
 85  # the appropriate organization unit or location.
 86  # See also EverybodyUserGroupName and UserFilter to control/filter the users that are imported.
 87  # Format = LDAP Distinguished Name (RFC 4514) like dc=axonivy,dc=com or ou=ivyteam,dc=axonivy,dc=com
 88  # [directoryBrowser]
 89  DefaultContext: ""
 90        
 91  # If configured, the security system imports only the users that are members of this user group.
 92  # See also DefaultContext and UserFilter to control/filter the users that are imported.
 93  # Format = LDAP Distinguished Name (RFC 4514) of a user group like cn=AxonIvyUser,ou=ivyteam,dc=axonivy,dc=com
 94  # [directoryBrowser]
 95  ImportUsersOfGroup: ""
 96        
 97  # The security system only imports users that match the given filter.
 98  # See also DefaultContext and EverybodyUserGroupName to control/filter the users that are imported.
 99  # Format = LDAP Search Filter (RFC 4515)
100  UserFilter: "(&(objectClass=user)(!(objectClass=computer)))"
101
102UserAttribute:
103  # The LDAP attribute that stores the unique identifier of a user
104  # This identifier is used during synchronization to identify a renamed user 
105  Id: objectGUID
106
107  # The LDAP attribute that stores the name of a user
108  Name: sAMAccountName
109
110  # The LDAP attribute that stores the full name of a user
111  FullName: displayName
112
113  # The LDAP attribute that stores the mail address of a user
114  EMail: mail
115
116  # The LDAP attribute that stores the language of a user
117  Language: ""
118
119  # Here, you can specify a list of additional LDAP attributes that are imported and available as user properties (IUser.getProperty)
120  # [keyvalue:Name,LDAP Attribute]
121  Properties:
122    # Maps a user property to an LDAP attribute
123    # In the example below 'phoneNumber' is the name of the user property. 
124    # The value of the property is imported from the LDAP attribute 'phone' of the user.
125    #phoneNumber: phone
126
127Membership:
128  # 
129  # The LDAP attribute that stores the groups a user is a member of, i.e.
130  # the LDAP object of a user contains one of these attributes for each group the user is a member of.
131  #
132  UserMemberOfAttribute: memberOf
133  
134  # Can the security system use the LDAP attribute configured in UserMemberOfAttribute (memberOf, groupMembership) to import user role membership?
135  # Sometimes, this LDAP attribute is not available because of security concerns. 
136  # If you set this to false, then the security system will import the user role membership with an alternative but slower mechanism.
137  UserMemberOfLookupAllowed: true
138 
139  # The LDAP attribute that stores the groups a group is a member of, i.e.
140  # the LDAP object of a group contains one of these attributes for each group that the group is a member of.
141  #
142  UserGroupMemberOfAttribute: memberOf
143
144  # The LDAP attribute that stores the members (user, groups) of a group
145  #
146  UserGroupMembersAttribute: member
147
148  # This property defines how the synchronization find all users that are a member of a user group.
149  # The default should be fine for most situations.
150  # Only if you have strict security settings in your directory, you may need to switch to TRAVERSE.
151  # The setting TRAVERSE has a big impact on your synchronization speed if you use 'ImportUsersOfGroup'.
152  #
153  # [enum: MATCHING_RULE, DIRECT, TRAVERSE]
154  NestedGroupsLookup: MATCHING_RULE
155
156# The number of objects the security system can read in one LDAP request
157PageSize: 500
158
159# Role mapping that is considered by the user synchronization.
160# Users are added to the roles to which they are assigned in.
161#Roles:
162  # The left side, e.g. Manager, specifies the unique name of the role defined in Axon Ivy.
163  # On the right side, e.g. cn=manager,ou=ivyteam,dc=axonivy,dc=com the external name of the role is set.
164  # The synchronization adds all users to Manager respectively Employee that are assigned to cn=manager,ou=ivyteam,dc=axonivy,dc=com
165  # respectively cn=employee,ou=ivyteam,dc=axonivy,dc=com.
166  #Manager: cn=manager,ou=ivyteam,dc=axonivy,dc=com
167  #Employee: cn=employee,ou=ivyteam,dc=axonivy,dc=com