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.
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
| Name | Description |
|---|---|
| Domain | The 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 Username | The login name for the Gateway to use when querying Active Directory. Used for retrieving the list of users and roles via LDAP. |
| Password | The password for the above username. |
| Password | Re-type password for verification. |
| Primary Domain Controller Host | The IP address or hostname of your primary domain controller. Example: "192.168.1.4" or "MainServer" |
| Primary Domain Controller Port | The port number for the primary domain controller's LDAP interface. |
| Secondary Domain Controller Host | The IP address or hostname of your secondary domain controller (optional). Example: "192.168.1.4" or "MainServer" |
| Secondary Domain Controller Port | The port number for the secondary domain controller's LDAP interface. |
| Use SSL | Disable to use "ldap://" protocol, enable to use "ldaps://" |
| SSO Domain | The domain that Windows users must match in order to use SSO. If blank, the main "Domain" property will be used. Not case-sensitive. |
The 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
The following table describes various configurable LDAP properties. See Microsoft's official documentation on LDAP Syntax Filters for more in-depth information about LDAP.
| Name | Description |
|---|---|
| Username Prefix | This prefix will be prepended to the username before an Active Directory bind is attempted for authentication. |
| Username Suffix | This suffix will be appended to the username before an Active Directory bind is attempted for authentication. |
| Automatic Suffix | If 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 Base | The 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 Filter | The 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 Filter | The LDAP search filter used when querying for the list of all users. Should restrict the type to user. |
| User Name Attribute | The attribute on the User object to define the username. |
| User Role Attribute | Attributes of this name on the User object will define the user's roles. |
| Role Name Attribute | The 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 Attribute | The attribute on the User object to define the full name of the user. |
| Phone Attribute | The attribute name on the user object that represents the user's phone number. |
| Email Attribute | The attribute name on the user object that represents the user's email address. |
| SMS Attribute | The 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 Timeout | The read timeout in milliseconds for LDAP operations. |
| Results Page Size | The number of entries returned per page of results in a query. |
| Role Search Base | The 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 Filter | The 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 Anonymous | If 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 Protocol | Specifies the security protocol between the Gateway and AD server. The following options are available:
|
| Security Authentication | This property specifies how usernames and passwords are used to bind to LDAP. The following options are available:
|
| Referral | New in 8.1.1 Specifies how referrals are to be processed. Possible options are:
|
SASL Properties
These settings are utilized when Security Authentication is set to SASL.
| Name | Description |
|---|---|
| Mechanism | An 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). |
| Realm | A 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 Protection | A 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 Strength | A 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 Authentication | Enable 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.
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.
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.
Choose the Active Directory authentication type, and click Next.
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.
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.
On the Gateway Webpage, under the Config tab, go to Security > Users, Roles.
Click the Create new User Source blue arrow on the User Sources page.
Choose the Active Directory authentication type, and click Next.
Change the Primary Domain Controller Port to 636.
Check Use SSL to enable “ldaps://”.
Check Show advanced properties to expand.
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.