Skip to main content
Version: 8.1

Active Directory Authentication

Active Directory User Source​

The Active Directory Authentication profile uses Microsoft's Active Directory over LDAP (Lightweight Directory Access Protocol) to store all the users, roles, and more that make up an Authentication profile. Active Directory Groups are used for Ignition's roles and user-role mappings.

While using an Active Directory User Source, administration of users and roles is through Active Directory itself, and not manageable within Ignition. Thus adding new users to an Active Directory User Source, or modifying pre existing users, requires the modifications be made from Active Directory, usually through an AD Administrator.

Active Directory User Sources supports SASL (Simple Authentication and Security Layer). SASL is a framework for authentication and data security in Internet protocols such as LDAP.

Property Reference​

Active Directory User Sources have the following properties shown in the table below, organized by category.

note

Certain properties in the Active Directory User Source allow you to filter users, such as the User List Filter. These filters only determine which users will be displayed on screen. They are not authentication filters, so even if a user does not show in the list they can still authenticate and may have access to unintended areas. Be sure to configure project security appropriately to prevent this from happening!

Main Properties​

Details on the Main Properties can be found on the Classic Authentication Strategy page.

Active Directory Properties​

NameDescription
DomainThe Windows Domain your active Active Directory server is running on. If you aren't sure of your domain, ask your network administrator.

Leave blank to set advanced properties manually.
Gateway UsernameThe login name for the Gateway to use when querying Active Directory. Used for retrieving the list of users and roles via LDAP.
PasswordThe password for the above username.
PasswordRe-type password for verification.
Primary Domain Controller HostThe IP address or hostname of your primary domain controller. Example: "192.168.1.4" or "MainServer"
Primary Domain Controller PortThe port number for the primary domain controller's LDAP interface.
Secondary Domain Controller HostThe IP address or hostname of your secondary domain controller (optional). Example: "192.168.1.4" or "MainServer"
Secondary Domain Controller PortThe port number for the secondary domain controller's LDAP interface.
Use SSLDisable to use "ldap://" protocol, enable to use "ldaps://"
SSO DomainThe domain that Windows users must match in order to use SSO. If blank, the main "Domain" property will be used. Not case-sensitive.

​

Changed in 8.1.17
This SSO Enabled setting was disabled and deprecated in 8.1.17 to protect against a potential security vulnerability. While the property is still visible, it cannot be enabled without setting a special system property. This is not recommended. See the Active Directory Deprecated Properties page for more information.

LDAP Search Properties​

NameDescription
Username PrefixThis prefix will be prepended to the username before an Active Directory bind is attempted for authentication.
Username SuffixThis suffix will be appended to the username before an Active Directory bind is attempted for authentication.
Automatic SuffixIf this option is checked, and the suffix is left blank, then the suffix will automatically be assigned a value of @<domain>.
Use prefix and suffix for Gateway username
New in 8.1.24
If this option is checked, the username prefix and suffix will be applied to the Gateway username before a bind is attempted. This option is checked by default.
User Search BaseThe base folder to search for users under, such as: DC=MyCompany,DC=com

The entire subtree under this folder will be searched using the User Search Filter. Multiple subtrees can be specified by putting them in parenthesis, like so:
(OU=Administrators,DC=MyCompany,DC=com)(OU=Operators,DC=MyCompany,DC=com)
User Search FilterThe LDAP search filter that will be used to find a specific user. Use the placeholder {0} as a standing for the login name.
User List FilterThe LDAP search filter used when querying for the list of all users. Should restrict the type to user.
User Name AttributeThe attribute on the User object to define the username.
User Role AttributeAttributes of this name on the User object will define the user's roles.
Role Name AttributeThe attribute of this name on the Role object will define the role's name. Leave blank to use the raw value of the attribute defined by the User Role Attribute property.
Full Name AttributeThe attribute on the User object to define the full name of the user.
Phone AttributeThe attribute name on the user object that represents the user's phone number.
Email AttributeThe attribute name on the user object that represents the user's email address.
SMS AttributeThe attribute name on the user object that represents the phone number that this user receives text messages on.
Badge Attribute
New in 8.1.25
The attribute on the User object to define the badge. This setting is required to enable badge-based authentication.
Read TimeoutThe read timeout in milliseconds for LDAP operations.
Results Page SizeThe number of entries returned per page of results in a query.
Role Search BaseThe base folder to search for roles under, such as: OU=Roles,DC=MyCompany,DC=com
The entire subtree under this folder will be searched using the Role Search Filter. If you specify the root of your tree structure, the search may take a very long time.
Multiple subtrees can be specified by putting them in parenthesis, like so: (OU=Builtin,DC=MyCompany,DC=com)(OU=Users,DC=MyCompany,DC=com)
If you leave this blank the whole subtree of the domain controller will be searched.
Role Search FilterThe LDAP search filter that will be used to locate roles.
Badge Search Filter
New in 8.1.25
The LDAP search filter to use to find a specific user given a badge. Use the placeholder {0} as a stand-in for the user's badge. Example: (&(objectClass=user)(badge={0}))
Allow AnonymousIf enabled, authentication attempts with blank passwords will be passed through to LDAP, which may choose to accept them.
Caution: It is highly recommended to disable this setting unless you know it is required. AD servers may allow logging in as any user with a blank password when Security Authentication is set to β€œNone” or β€œSimple” (even if a provided username does not exist in AD), which is a major security risk.
Security ProtocolSpecifies the security protocol between the Gateway and AD server. The following options are available:
  • AUTO: No security protocol is explicitly used or requested by the Gateway.
  • SSL: SSL should be used for the connection.
Security AuthenticationThis property specifies how usernames and passwords are used to bind to LDAP. The following options are available:
  • AUTO: Unspecified from the Gateway side, meaning the LDAP implementation will choose.
  • NONE: Anonymous access. (Not recommended due to security risks)
  • SIMPLE: Plaintext username and passwords will be used. (Not recommended due to security risks)
  • STRONG: Usernames and passwords will be encrypted.
  • SASL: Simple Authentication and Security Layer. See the SASL Properties table below for additional SASL authentication configuration settings.
Referral
New in 8.1.1
Specifies how referrals are to be processed. Possible options are:
  • Follow: Always automatically follow referrals. This is the default option.
  • Ignore: Ignores referrals.
  • Throw: Throws a ReferralException whenever a referral is encountered.

SASL Properties​

These settings are utilized when Security Authentication is set to SASL.

NameDescription
MechanismAn ordered list of space-separated mechanism names. The LDAP provider will use the first mechanism for which it finds an implementation. A blank value will leave this setting unspecified. (Default is DIGEST-MD5 CRAM-MD5).
RealmA realm defines the namespace from which the user is selected. A blank value will leave this setting unspecified. This setting will only be used by mechanisms which support it. Default is blank.
Quality of ProtectionA comma-separated list of Quality-of-Protection (QoP) values, the order of which specifies the preference order. There are three well-known values: "auth" (authentication only), "auth-int" (authentication with integrity protection), and "auth-conf" (authentication with integrity and privacy protection). A blank value will leave this setting unspecified. This setting will only be used by mechanisms which support it. (Default is auth-conf,auth-int,auth).
Protection StrengthA comma-separated list of privacy protection strength values, the order of which specifies the preference order. The three possible strength values are "low", "medium", and "high". A blank value will leave this setting unspecified. This setting will only be used by mechanisms which support it. Default is high,medium,low.
Mutual AuthenticationEnable or disable mutual authentication. This setting will only be used by mechanisms which support it. Default is disabled.

To Create an Active Directory User Source​

To configure an Active Directory User Source, you must specify the host that is acting as your primary domain controller. You can also use a secondary domain controller in case the primary is unavailable. You'll also need to specify the name of the domain and credentials for the Gateway itself to use: the Gateway needs a user account to interact with the AD server, even when it's simply querying for a list of roles.

note

When using Active Directory User Source, you may need to consult with your internal IT Department to get the required information to complete your user source setup. These settings are common to AD (not specific to Ignition), and your IT department will know what values to supply to each property.

  1. On the Gateway Webpage, under the Config tab, go to Security > Users, Roles. The User Sources page will be displayed. Click the blue arrow, Create new User Source.

  2. Choose the Active Directory authentication type, and click Next.

  3. The New User Source window will open. Some properties are optional. In the very least, you must specify the following: Domain, Gateway Username, Password, Primary Domain Controller Host.

  4. Cick the Create New User Source button to create the User Source.

Connect AD over SSL​

For additional security, you can adjust the Active Directory settings to enable SSL since LDAP is not encrypted by default. The default port for LDAP is port 389, but LDAPS uses port 636 and establishes SSL upon connecting.

  1. On the Gateway Webpage, under the Config tab, go to Security > Users, Roles.

  2. Click the Create new User Source blue arrow on the User Sources page.

  3. Choose the Active Directory authentication type, and click Next.

  4. Change the Primary Domain Controller Port to 636.

  5. Check Use SSL to enable β€œldaps://”.

  6. Check Show advanced properties to expand.

  7. Change the Security Protocol to SSL.

If you try to query or authenticate against the AD server at this point, you will receive the following error:

Caused by: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

This error indicates Ignition was unable find a valid certificate generated from the AD server, and therefore cannot validate the AD server's identity. Work with IT to obtain a certificate from the AD server. This certificate must be added to the data/certificates/supplemental directory and then imported into the Java cacerts keystore. Once the certificate is added, restart the Gateway.