← Back to plugin index

Active Directory Connector

Description
Microsoft Active Directory Connector

General Information
If a Microsoft Active Directory is used to manage the users, only this Plugin needs to be configured to handle the different user-related directory tasks. This MS AD connector implements the Airlock IAM Plugin interfaces: Authenticator, UserIterator, LicenseUserCounter, UserPersister, CredentialPersister, PasswordService, PasswordPolicy, and PasswordAuthenticator

  • Only standard Active Directory user attributes are used. Therefore its not necessary to extend the schema.
  • Active Directory features like recursive group membership, password policies and password histories are supported.
  • Changing passwords is possible when the connection to the AD is secured using SSL/TLS.
  • Multiple AD servers can be configured for failover or load balancing.
  • Multiple "User Search Bases" and "Group Search Bases" can be specified.

This plugin works best with Microsoft Active Directory server 2008R2 and later.

Note on Stealth-Mode (Zero-Information Leakage)
This plugin provides "stealth" in the sense that it does not reveal information about the factor that prevented the successful login but it does not provide protection against denial of service attacks based on locking user accounts.
If used in conjunction with the "Stealth Mode" (see "Main Authenticator" plugin), it is strongly recommended to enable the "soft account lock" feature of this plugin (see property below).

Note on using this plugin only for password checks
When only using this plugin to check the user's password, additional features like role lookup or context data retrieval may not work as expected.

Type name
ActiveDirectoryConnector
Class
com.airlock.iam.core.misc.impl.activedirectory.ActiveDirectoryConnector
May be used by
Persister Password Service Persister Password Service Combining Extended User Persister Password Settings Password Settings Export Users Task Export Users Task Client Certificate (X.509) Request Authentication Selection Authenticator Has Email Address Active Directory Password Repository User-based Authenticator Selector Email User Profile Item Set Password Step Email Notification Task Email Notification Task Authenticator-based One-Shot Target Application Composite Password Service Composite Password Service Composite Password Service Mandatory Password Change Step Email Notifier Airlock 2FA Activation Letter Task User Persister Configuration User Persister Configuration User Persister Configuration Pattern-based Random String Generator Credential Secret Batch Task User-based Password Service Selector Self Reg Users Clean Up Task HTTP Basic Authentication Step Destroy Last User Session Service Container Credential Data mTAN Handler Credential Data mTAN Handler Transaction Approval Delete Users Task Delete Users Task Admin SSO Ticket Request Authentication OAuth 2.0/OIDC Authorization Server Primary Key Lookup Lock Inactive Accounts Task Lock Inactive Accounts Task Token Authenticator Administrators Configuration Administrators Configuration Administrators Configuration Vasco Letter Generator Combining User Persister Fallback Authenticator Token Activation On Delivery Strategy New Email Clean-up Strategy Credential-based Generic Token Repository Extended String User Profile Item Certificate Token Authenticator String User Profile Item Data Sources Legacy Email OTP Authentication Step Custom User Persister-based User Store Provider Password Batch Task Password Batch Task Password User Item XML File Importer Task Cipher Credential Persister Vasco Token Report Strategy Secret Questions Token Controller User Persister-based User Store Certificate Data Extractor Task OAuth 2.0 Token Request Authentication Basic Auth Request Authentication Basic Auth Request Authentication Lookup and Accept Authenticator Voluntary Password Change Step Username Password Authentication Step User Store Configuration User Store Configuration Context Data Username Transformer Password Reset Step Administrators Management Integer User Profile Item Credential Data Certificate Matcher Token Data mTAN Handler Meta Authenticator Meta Authenticator Meta Authenticator Meta Authenticator Password-only Authentication Step Persister IAK Verifier Password Change Self-Service Step Auth Method-based Authenticator Selector Role-based Authenticator Selector User to Password Service Mapping User to Password Service Mapping Airlock 2FA Authenticator SMS Notifier mTAN IAK Token Report Strategy Lock Expired Initial Passwords Task Lock Expired Initial Passwords Task Username Password with FIDO Authentication Step Self Reg Users Reminder Task Password Token Controller Password Authenticator Email Otp Authenticator OATH OTP Settings Radius Authentication Service Radius Authentication Service User Sync Task User Sync Task Static Request Authentication User to Authenticator Mapping SSO Ticket Request Authentication User Persister Email Certificate Provider Cronto Report Strategy Main Authenticator Main Authenticator Loginapp Certificate Authenticator Certificate Authenticator Credential Report Task HTTP Password Service
Properties
Connection Settings (connectionPool)
Description
The connection settings for communicating with one or more Microsoft Active Directory servers.
Attributes
Plugin-Link
Mandatory
Assignable plugins
Is Read Only (isReadOnly)
Description

If enabled, the Active Connector plugin does not write any data to the AD except for new passwords (changing and setting passwords can be disabled in the global password settings).
This allows using a service account user with only few privileges.

If enabled, the following data is not written to the AD (and therefore some features may not work as expected):

  • Context data (e.g. changes to user's postal address)
  • Credential data (e.g. change of mobile phone number)
  • User unlocking (after password change or from the Adminapp)
  • Enforcing password change (after setting a new password in the Adminapp)

Note that individual context attributes can be made read-only using the configuration property "Read-Only Attributes".

Attributes
Boolean
Optional
Default value
false
Username Attribute (userIdAttributeName)
Description
The name of the attribute that holds the user ID. Usually the default value 'sAMAccountName' should not be changed.
Attributes
String
Optional
Default value
sAMAccountName
Suggested values
cn, sAMAccountName, userPrincipalName
Credential Data Attribute (credentialDataAttribute)
Description

The LDAP attribute with credential data (e.g. mobile phone number for mTAN/SMS authentication or email address for certificate validation).
If the same attribute is listed in the property "Binary Attributes", it will be treated as binary data, otherwise it is assumed to be UTF-8 string data.

This property is only required when an additional credential should be checked besides the password.

Attributes
String
Optional
Default value
mobile
Suggested values
mobile, mail, cn, userPrincipalName
User Search Bases (userSearchBases)
Description
Specifies the LDAP tree node(s) for users. If multiple nodes are defined, all are considered in the defined order when finding users.

The separate property "User Search Scope" controls whether users are only searched in the nodes defined by this property or in its subtrees as well.

Attributes
String-List
Mandatory
User Search Scope (userSearchScope)
Description
Specifies whether the search should consider the complete subtree of the search base "User Search Bases" or only its direct child nodes.
  • ONE_LEVEL: Search users only in the specified "User Search Bases" - the subtree is ignored.
  • SUBTREE: Search users recursively in the specified "User Search Bases" - considers the complete subtree.
  • SUBORDINATE_SUBTREE: Search users recursively in the specified "User Search Bases" - considers the complete subtree from one level below the specified "User Search Bases" and ignores users directly in it.
  • BASE: Only the exact entries in the specified "User Search Bases" are considered.
Attributes
Enum
Optional
Default value
SUBTREE
User Search Filter (userSearchFilter)
Description

LDAP search filter expression applied when searching for users.
Note that this filter is automatically combined (logical AND) with a username filter based on the "Username Attribute".
The format and interpretation of filter follow RFC 2254.

Example 1 - Consider only entries with object class user: (objectCategory=user)
Example 2 - Consider only entries with object class person: (objectClass=person)
Example 3 - Consider only users in a specific group (no nested groups): (&(objectCategory=Person)(memberOf=cn=snakeOilDepartment,ou=groups,dc=company,dc=com))
Example 4 - Same as example 1 but considering nested groups: (&(objectCategory=Person)(memberOf:1.2.840.113556.1.4.1941:=cn=snakeOilDepartment,ou=groups,dc=company,dc=com))

Attributes
String
Optional
Multi-line-text
Default value
(objectCategory=user)
Example
(objectCategory=user)
Example
(objectClass=person)
Username Conversion Pattern (usernameConversionPattern)
Description

Regular expression pattern containing a group (a region embraced by parentheses) that can be used in conjunction with property "Username Conversion Replacement" in order to transform the username before it is used for searching the user in the directory. If the username does not match the pattern at all, no transformation is performed.

Example: The pattern "(.*)" and the replacement pattern "user.$1" will transform the username "jdoe" to "user.jdoe" before it is used in the directory.

Example: The pattern "user\.(.*)" and the replacement pattern "$1" will transform the username "user.jdoe" to "jdoe" before it is used in the directory.

Attributes
RegEx
Optional
Username Conversion Replacement (usernameConversionReplacement)
Description
The replacement string used in conjunction with property "Username Conversion Pattern" in order to transform the username. The token "$1" is used to reference the string matching the group in the pattern. See property "Username Conversion Pattern" for examples.
Attributes
String
Optional
Example
user.$1
Example
$1
Group Search Bases (groupSearchBases)
Description
Specifies the LDAP tree node(s) for groups/roles. If multiple nodes are defined, all are considered in the defined order when finding groups.

Groups/roles are not searched if this property is not configured.

The separate property "Group Search Scope" controls whether groups are only searched in the nodes defined by this property or in its subtrees as well.

Attributes
String-List
Optional
Group Search Scope (groupSearchScope)
Description
Specifies whether the search should consider the complete subtree of the search base "User Search Bases" or only its direct child nodes.
  • ONE_LEVEL: Search groups only in the specified "Group Search Bases" - the subtree is ignored.
  • SUBTREE: Search groups recursively in the specified "Group Search Bases" - considers the complete subtree.
  • SUBORDINATE_SUBTREE: Search groups recursively in the specified "Group Search Bases" - considers the complete subtree from one level below the specified "Group Search Bases" and ignores groups directly in it.
  • BASE: Only the exact entries in the specified "Group Search Bases" are considered.
Attributes
Enum
Optional
Default value
SUBTREE
Group Search Filter (groupSearchFilter)
Description
LDAP search filter expression applied when searching for groups.

Note that this filter is automatically combined (logical AND) with a username filter based on the "Username Attribute".
The format and interpretation of filter follow RFC 2254.

Attributes
String
Optional
Multi-line-text
Default value
(objectClass=group)
Example
(objectClass=group)
Example
(objectCategory=group)
Example
(objectClass=*)
Resolve Nested Groups (resolveNestedGroups)
Description
If enabled, also nested groups are assigned to a user as roles. If disabled, only groups directly connected to the user (memberOf) are read from the Active Directory and are assigned to the user as roles.

Notice that in any case, only groups in the "Group Search Bases" will be found.

Attributes
Boolean
Optional
Default value
true
Static Roles (staticRoles)
Description
Static list of roles added to all users. Every user found in the AD gets these roles in addition to his roles/groups in the Active Directory (if configured).
Attributes
String-List
Optional
Role Filters (roleFilters)
Description
Allows filtering of retrieved user roles by regular expressions. If configured, only roles that match at least one of the filter patterns are assigned to the user. Static roles are not filtered.
Attributes
RegEx-List
Optional
Match Roles Case Sensitive (matchRolesCaseSensitive)
Description
If enabled, roles are matched against the role filters considering the case (the default).
Attributes
Boolean
Optional
Default value
true
Use Groups From memberOf Attribute (useGroupsFromMemberOfAttribute)
Description
If enabled, the group values from the memberOf attribute are imported as user roles. This is combinable with the groups search. The values from the memberOf attribute will also be filtered by the role filter.

Note that nested roles can NOT be resolved via the memberOf attribute. This can only be done using the groups search. The role lookup through the memberOf attribute is readonly, as is the lookup through the groups search.

Attributes
Boolean
Optional
Default value
false
Search Result Page Size (searchResultPageSize)
Description

If set to a value greater than zero and the Active Directory supports the SimplePaging control, "paging" is enabled for LDAP searches: This property defines the number of entries to fetch at once when searching in a directory.

This setting may be useful if the Active Directory limits the number of entries in a search result.
If the property is set to zero (the default) or if the server does not announce to support the SimplePaging control, paging is disabled

Attributes
Integer
Optional
Default value
1000
Suppress Substring Search (suppressSubstringSearch)
Description
If enabled, substring searches are suppressed, i.e. attributes do only match a filter if the whole filter string matches.
This may greatly improve search performance in large directories.
Attributes
Boolean
Optional
Default value
false
Soft Account Lock (softAccountLock)
Description

Lock users when they have more than the configured number of successive incorrect password checks on the AD. (E.g.: the value "2" means that 2 incorrect passwords are still OK).

If the number is smaller than the corresponding setting in AD, this allows "soft-locking" the account if accessed via Airlock IAM without actually locking the account on the AD. This feature may be used to prevent AD accounts from being locked by unsuccessful remote logins.

Note: if "Stealth Mode" is used (see "Main Authenticator" plugin), it is strongly recommended to enable this feature.

Attributes
Integer
Optional
Unlock User On Password Reset (unlockUserOnPasswordReset)
Description
If set to TRUE the user attribute "Lockout Time" is reset to 0 upon password reset.
Attributes
Boolean
Optional
Default value
true
Check Server-Side Password Policies On Change/Reset (checkServersidePasswordPoliciesOnChange)
Description

If enabled the server side password policy is checked when a user changes or resets the password (not when an administrator sets one). This is for example useful to enforce advanced server-side policies like password histories.

Note that the AD might impose further password constraints (e.g. minimal length), that cannot be weakened or disabled with these settings.

Attributes
Boolean
Optional
Default value
true
Context Data Attributes (contextDataAttributes)
Description
A list of attribute names that are loaded into the context data container of the user, e.g. address data.
Notice: Context data attributes are string based. Values will be read as strings and are converted to string when written.

To prevent attributes from being changed by Airlock IAM/Login, add them also to the list of "Read-only Attributes".

Notice: The attributes "objectGUID" and "ImmutableID" are always considered read-only.

Attributes
String-List
Optional
Binary Attributes (binaryAttributes)
Description
A list of attribute names that should be treated as binary data (instead of string data).

Those attributes are Base64 encoded for use in Airlock IAM/Login.

If the attribute name from "Credential Data Attribute" is also listed here, the credential data will be treated as binary.

Attributes
String-List
Optional
Read-only Attributes (readOnlyAttributes)
Description
A list of attribute names that are never written when updating a user. This must be a subset of the attributes listed in Context Data Attributes.
Attributes
String-List
Optional
Realm Attribute (realmAttribute)
Description
Name of the LDAP attribute holding the realm of the user.
Setting this attribute is mandatory when using the Multi-Realm feature. The column specificied here must not also be in the list of Context Data Attributes.
Attributes
String
Optional
Suggested values
realm
User DN Context Data Attribute (userDNContextDataAttribute)
Description
The name of the context data field to hold the user's distinguished name (DN).
This DN is in the format "uid=user,ou=People,dc=company,dc=ch"
Attributes
String
Optional
Example
dn
Domain DN (domainDN)
Description
The distinguished name (DN) of the root domain. If left unconfigured the default naming context of the Active Directory server is used.
Attributes
String
Optional
Example
DC=example, DC=org
Password Settings Container DN (passwordSettingsContainerDN)
Description
The distinguished name (DN) of the Password Settings Container (PSC). If left unconfigured the PSC "CN=Password Settings Container, CN=System" in the default naming context of the Active Directory server is used.
Attributes
String
Optional
Example
CN=Password Settings Container, CN=System, DC=example, DC=org
User Count Search Filter (userCountSearchFilter)
Description
The search filter expression applied (in addition to the "User Search Filter" expression if present) to count the users. If no filter expression is given, the "User Search Filter" expression is used to count users. If also no "User Search Filter" expression is given the default filter is used to count users. The format and interpretation of filter follow RFC 2254.

Note: The user count is relevant for the product license. This filter should therefore describe the set of users who are able to authenticate through Airlock IAM.

Attributes
String
Optional
Example
(objectCategory=user)
LDS Mode (adLdsMode)
Description
Activates the AD LDS mode of operation ("Lightweight Directory Services")
Attributes
Boolean
Optional
Default value
false
YAML Template (with default values)

type: ActiveDirectoryConnector
id: ActiveDirectoryConnector-xxxxxx
displayName: 
comment: 
properties:
  adLdsMode: false
  binaryAttributes:
  checkServersidePasswordPoliciesOnChange: true
  connectionPool:
  contextDataAttributes:
  credentialDataAttribute: mobile
  domainDN:
  groupSearchBases:
  groupSearchFilter: (objectClass=group)
  groupSearchScope: SUBTREE
  isReadOnly: false
  matchRolesCaseSensitive: true
  passwordSettingsContainerDN:
  readOnlyAttributes:
  realmAttribute:
  resolveNestedGroups: true
  roleFilters:
  searchResultPageSize: 1000
  softAccountLock:
  staticRoles:
  suppressSubstringSearch: false
  unlockUserOnPasswordReset: true
  useGroupsFromMemberOfAttribute: false
  userChangeEventListeners:
  userCountSearchFilter:
  userDNContextDataAttribute:
  userIdAttributeName: sAMAccountName
  userSearchBases:
  userSearchFilter: (objectCategory=user)
  userSearchScope: SUBTREE
  usernameConversionPattern:
  usernameConversionReplacement: