Security Provider - Active Directory¶

The Active Directory (AD) security provider is a forms-based authentication scheme. When using the AD security provider, users supply their AD user name and password to Vinyl. Vinyl uses LDAP to validate the user-supplied credentials against an AD store.

Modern deployments should favor SAML Single Sign-On (SSO) and WS-Federation over AD authentication. SAML SSO and WS-Federation offer greater security to the extent that users are not required to supply their credentials to a third-party application. Since AD does not honor an existing authentication context, AD authentication is not a proper SSO scheme. For this reason, SAML SSO and WS-Federation generally offer better usability because they do not require a user to re-enter their credentials. Finally, since SAML SSO and WS-Federation security tokens are brokered by the browser over HTTP, they do not require a third-party application to have direct access to AD domain controllers. This makes SAML SSO and WS-Federation more suitable for cloud deployments.

Configuration¶

The AD security provider supports both user and group provisioning. Users and groups are registered using their SAM account name.

Parameters¶

Parameter	Default Value	Example	Required	Description
Container		DC=example,DC=com	No	AD LDAP container specification.
Context	Domain			AD context type. Valid values include Domain, Machine and ApplicationDirectory.
Domain		example.com example.com:389	Yes	Active Directory (AD) domain name. May include an optional port number.
Password			No	AD account password. See below for more information.
UserName			No	AD account user name. See below for more information.

By default, Vinyl will connect to AD domain controllers as the IIS application pool user. This may not work in all situations, particularly if the web server is not hosted on the AD domain. In which case, you will need to provide the user name and password of an account on the domain. When creating account, consider the following:

The account needs to have read access to the AD tree: membership in the "Domain Users" security group is sufficient.
The account can belong to the Organizational Unit identified by the Container specification, but it does not have to be.

Claims¶

The Active Directory provider maps the following UserPrincipal properties to claim types:

SamAccountName
Name
DisplayName
EmailAddress
VoiceTelephoneNumber

Additional Information¶

In order to validate credentials against an Active Directory (AD) store, Vinyl will need to be able to connect to the AD domain controllers via LDAP. Traditionally, this takes place on port 389.

A delay of 20 seconds or more may occur when crossing domain boundaries. Appending the port number to the domain (e.g. example.com:389) may improve performance.

Troubleshooting¶

Error: "There is no such object on the server."

This error may signify that the Container specification is incorrect. It may refer to a non-existent Organizational Unit. If working with nested Organizational Units, it may signify that the order is incorrect. Organizational Units must be provided in reverse order. For instance, given the following path:

\Sales\North America

The correct Container specification would be:

OU=North America,OU=Sales,DC=example,DC=com

Note that Organizational Unit names are not case-sensitive.

Error: "The server could not be contacted." or "The LDAP server is unavailable."

This error indicates that Vinyl was unable to connect to the Active Directory domain controller. Check the Domain property.

Clients interface with Active Directory via LDAP. As noted in the following Microsoft Knowledgebase article, the LDAP Server communicates on port 389 using both the UDP and TCP protocols.

https://support.microsoft.com/en-us/help/832017/service-overview-and-network-port-requirements-for-windows

The Portqry tool can be used to test connectivity to Active Directory:

https://support.microsoft.com/en-us/help/816103/how-to-use-portqry-to-troubleshoot-active-directory-connectivity-issue

The tool can be downloaded from Microsoft's site:

https://www.microsoft.com/en-us/download/confirmation.aspx?id=17148

Note that the Portqry tool must be run from the Vinyl web server.

To test connectivity to port 389 using UDP, execute the following command:

> portqry -n ad.example.com -e 389 -p udp

Replace "ad.example.com" with the hot name or IP address of the Active Directory server.

To test connectivity to port 389 using TCP:

> portqry -n ad.example.com -e 389 -p tcp

If the tests are successful, you will see an LDAP query response including the current date and time, as well as various Active Directory properties. The following is an example of a sucessful LDAP query response:

currentdate: 10/20/2018 11:22:33 (unadjusted GMT)
subschemaSubentry: CN=Aggregate,CN=Schema,CN=Configuration,DC=example,DC=com
dsServiceName: CN=NTDS Settings,CN=SERVER,CN=Servers,CN=Default-First-Site-Name,CN=Sites,CN=Configuration,DC=example,DC=com
namingContexts: DC=example,DC=com
defaultNamingContext: DC=example,DC=com
schemaNamingContext: CN=Schema,CN=Configuration,DC=example,DC=com
configurationNamingContext: CN=Configuration,DC=example,DC=com
rootDomainNamingContext: DC=example,DC=com
supportedControl: 1.2.840.113556.1.4.319
supportedLDAPVersion: 3
supportedLDAPPolicies: MaxPoolThreads
highestCommittedUSN: 249947
supportedSASLMechanisms: GSSAPI
dnsHostName: SERVER.example.com
ldapServiceName: example.com:server$@EXAMPLE.COM
serverName: CN=SERVER,CN=Servers,CN=Default-First-Site-Name,CN=Sites,CN=Configuration,DC=example,DC=com
supportedCapabilities: 1.2.840.113556.1.4.800
isSynchronized: TRUE
isGlobalCatalogReady: TRUE
domainFunctionality: 6
forestFunctionality: 6
domainControllerFunctionality: 6

Error: "The user name or password is incorrect."

If the log file contains the error "The user name or password is incorrect," it may signify that the user name or password used by Vinyl to query the Active Directory domain controller is invalid. Check the UserName and Password properties.

Error: "Either the user name or password is incorrect."

A user may see the normal "Either the user name or password is incorrect" error when signing in, even if they've provided valid credentials. This may indicate that the user name has been provided in the wrong format.

When signing in, do not supply the user name in either the User Principal Name (user@example.com) or Down-Level Logon Name (EXAMPLE\user) formats. Instead, provide the unqualified user name.

Error: "The given user name did not match the SAM account name of a user principal."

This error indicates that the user is attempting to authenticate with an account that does not match the Container specification. For instance, the Container specification may restrict access to a given Organizational Unit. In which case, this error would indicate that the user account does not belong to the Organizational Unit.