INTRODUCTION

By default, the Cyara Platform is not configured for Windows Active Directory (AD), but uses the Identity username and password. In some Cyara customer premises installations, there may be a requirement for AD to be used as a way to authenticate the user. Cyara portal is able to authenticate a user in AD via Lightweight Directory Application Protocol (LDAP) or Secure LDAP (LDAPS). This article demonstrates how to configure Cyara customer premises installation for AD authentication using LDAP and Secure LDAPS. A basic understanding of AD, LDAP or LDAPS makes the configuration much easier. Detailed understanding of AD, LDAP or LDAPS is beyond the scope of this article.

AD, LDAP and LDAPS

AD and LDAP are both software implementations of directory services. AD mostly authenticates leveraging Kerberos. However, AD does have the capability to authenticate via LDAP and LDAPS as well. LDAPS is a directory protocol similar to LDAP, but it incorporates SSL for greater security. Microsoft’s AD is largely a directory for Windows users, devices, and applications. AD requires a Microsoft Domain Controller to be present and when it is, users are able to use a single sign-on to Windows resources that live within the domain structure. LDAP, on the other hand, has largely worked outside of the Windows structure focusing on the Linux/Unix environment and with more technical applications. LDAP doesn’t have the same concepts of domains or single sign-on. LDAP is largely implemented with open source solutions and as a result has more flexibility than AD.

LDAP BASICS

LDAP is a software protocol for enabling anyone to locate organizations, individuals, and other resources such as files and devices in a network, whether on the public Internet or on a corporate intranet. With AD, LDAP allows you to search for an individual without knowing where they're located although additional information will help with the search.

An LDAP directory is organized in a simple "tree" hierarchy consisting for example the following levels:

• The root directory (the starting place or the source of the tree), which branches out to
• Countries, each of which branches out to
• Organizations, which branch out to
• Organizational units (divisions, departments, and so forth), which branches out to (includes an entry for)
• Individuals (which includes people, files, and shared resources such as printers)

Data stored in LDAP is stored in objects. These objects contain a number of attributes, which are basically a set of key/value pairs. Because data in LDAP is structured, objects can only contain valid keys.

A distinguished name (DN), is a LDAP attribute that uniquely defines an object.  Each DN must have a different name and location from all other objects in AD.  The DN provides a way of selecting any object in AD via LDAP.

Some examples of attributes are:

DC = Domain Component

SN = Surname or Last Name

CN = Common Name

OU = Organizational Unit

For example if a user, John Smith is stored in AD under CN=users, DC= corp, DC=example, DC=com, the details would have a DN of CN=John Smith,CN=users,DC=example,DC=com. Each level in the hierarchy is separated by commas.

Verifying that AD is configured for LDAP or LDAPS

Cyara portal uses underlying Windows LDAP or LDAPS services to access AD. Use ldp.exe from the Cyara web portal Windows server to test if AD is configured for LDAP or LDAPS. To run ldp.exe, open a command prompt on the Cyara web portal server and type ldp.exe and press enter. If ldp.exe is not installed on the server, then install “AD DS and AD LDS Tools” from Windows Server Manager Features.

Form the ldp.exe window select “connect” from the “Connection” drop-down” menu.

Enter the IP address of the AD server and LDAP port used and click on OK. The default LDAP port is 389 but it may be set to a different port by the customer.

If LDAP connection is established with the AD server, it will be displayed on the right pane of the ldp.exe window. If the connection fails, check to see is LDAP has been configured for AD, LDAP port used are correct or for any firewall issues.

Once ldp.exe successfully connects, select “Bind” from the “Connection” drop-down” menu.

In the Bind window, enter an AD user ID, password, AD IP address, select “Bind with credentials” radio button and press OK. Any AD user ID and password should work, but it recommended that a unique user created with read only AD access should be used. This user will be used in the Cyara web portal web.config LDAP configuration.

If Bind was successful, “Authenticated as…” message will be see on the ldp.exe right pane.

Select “Tree” from the “View” drop-down” menu.

From the Tree View window, select the BaseDN. In this example, the BaseDN is DC=corp,DC=example,DC=com.

Click on OK.

Expand the tree view on ldp.exe left pane. Note the DNs in the example below. LDAP uses the DN to located for users on AD. If the LDAP search path of all the user are required, in this example, the DN used can be CN=users,DC=corp,DC=example,DC=com. If the LDAP search is only for users in Dev, the DN is CN=dev,CN=users,DC=corp,DC=example,DC=com. Note the DN required as it will be used in the Cyara portal LDAP configuration. The DN is not case case sensitive and can be written all in lowercase.

To check if LDAPS is working, the steps are similar to the LDAP steps described above except for Connect. Form the ldp.exe window select “connect” from the “Connection” drop-down” menu.

 

For LDAPS, the FQDN of the AD must be used. Enter the FQDN of the AD server, LDAP port used, select SSL checkbox and click on OK. The default LDAPS port is 636 but it may be set to a different port by the customer.

If a connection is established with the AD server, it will be displayed on the right pane of the ldp.exe window. If the connection fails, check to see if AD has been configured for LDAPS, LDAPS port used are correct, correct certificates are installed or for any firewall issues.

The rest of the steps are similar to that described for connecting with LDAP. Also, make sure that FQDN is used instead of IP address of the AD server when using LDAPS.

Once it confirmed that LDAP and/or LDAPS is working from the Cyara web portal server and the DN to be used is noted, the Cyara web portal can be configured for LDAP or LDAPS.

Configuring Web Portal for Active Directory

By default, the Cyara Platform is not configured for Active Directory, but uses the Identity username and passwords. The default admin user is a Platform Administrator user and can be used to create and configure Active Directory users.

To set up for Active Directory, perform the following:

• Set the Active Directory configuration options in the web portal web.config file
• Create the Active Directory users as required
• Optionally disable the default Platform Administrator login

Active Directory Configuration is placed within two different sections in the web.config file.

• appSettings: clear text non encrypted configuration
• secureAppSettings: a special section that could be encrypted if required

Set the following values in the web.config appSettings section:

IdentitySettings.LoginProviders

This is a list of the enabled login providers. Before setting up your first Active Directory Platform Administrator user, this must be set to both Active Directory and Identity as shown:

<add key="IdentitySettings.LoginProviders" value="ActiveDirectory,Identity"/>

 

Once you are able to log in with Active Directory credentials, you may modify this to be only Active Directory, which will effectively disable the default admin user (and any other Identity user). If Active Directory is enabled, only Active Directory users will be able to be created through the Portal.

MembershipProviderSettings.ADDomain[index]

This is a container setting where index (starting with zero) represents grouping, meaning multiple AD domains can be configured.

The following settings apply:

• Name: fully qualified domain name that will be sent to the AD (for example, dc01.corp.example.com)
• LdapPath: LDAP connection string for user look ups (for example, LDAP://192.168.91.96/CN=Users,DC=corp,DC=example,DC=com)
• Alias: (optional) this is an alias that is used with usernames (for example, corp). For this example, it makes it possible for users to log in using just corp\username instead of dc01.corp.example.com\username. The alias is not case sensitive.

If multiple authentication domains are to be supported, the ADDomain group is simply repeated with the next index [1], [2], and so on.

In the secureAppSettings section, set up a user with access to Active Directory:

MembershipProviderSettings.ADCredential[index]

This is a container setting where index (starting with zero) represents grouping, meaning multiple AD credentials can be configured.

The credentials configured here are matched to the AD domains configured in the appSettings section through the [index]. They are used for AD user look-ups that are required when a new user is being registered. To check if the typed username is an actual existing AD user, perform an AD lookup using these credentials.

There could be a special AD user account configured for these look-ups, which needs to have read-only access to the LDAP path used for queries (see the LdapPath setting under ADDomain).

The following settings apply:

• Username: username to send with LDAP request
• Password: password to send with LDAP request

Example for this configuration in <appSettings> section of Web Portal web.config:

<add key="IdentitySettings.LoginProviders" value="ActiveDirectory, Identity"/>

<!-- ADDomain.Name is fully qualified domain name. -->

<add key="MembershipProviderSettings.ADDomain[0].Name" value="corp.example.com" />

<!-- ADDomain.LdapPath is the LDAP connection string used to look-up and authenticate users. -->

<add key="MembershipProviderSettings.ADDomain[0].LdapPath" value="LDAP://192.168.91.96/CN=Users,DC=corp,example,DC=com" />

<!-- For LDAPS use FQDN instead of IP address -->

<!-- add key="MembershipProviderSettings.ADDomain[0].LdapPath" value="LDAP://dc01.corp.example.com/CN=Users,DC=corp,example,DC=com" /-->

<!-- ADDomain.Alias is a short alias that users use to login to this domain (optional, if not provided, Name is used). -->

<add key="MembershipProviderSettings.ADDomain[0].Alias" value="corp" />

<!-- ADDomain.LockoutDurationLdapPath is used to specify LDAP path to the domain container where 'lockoutDuration' attribute is found. -->

<add key="MembershipProviderSettings.ADDomain[0].LockoutDurationLdapPath" value="LDAP://192.168.91.96/CN=Users,DC=devtest,DC=cyarasolutions,DC=com" />

<!-- ADDomain.AuthenticationTypes is used to specify the authentication method, can be one of the following or multiples separated by commas:

(Anonymous, Delegation, FastBind, None, ReadonlyServer, Sealing, Secure, SecureSocketsLayer, ServerBind, Signing). -->

<!-- See link for more details on available options. https://msdn.microsoft.com/en-us/library/system.directoryservices.authenticationtypes%28v=vs.110%29.aspx -->

<!-- Example: Use SSL = value="SecureSocketsLayer, Secure" -->

<add key="MembershipProviderSettings.ADDomain[0].AuthenticationTypes" value="Secure" />

 

And in <secureAppSettings> section:

<!-- ADCredential.Username - Username that will be used to perform Active Directory queries. -->

<add key="MembershipProviderSettings.ADCredential[0].Username" value="CORP\CyaraRO" />

<!-- ADCredential.Password - Password that will be used to perform Active Directory queries. -->

<add key="MembershipProviderSettings.ADCredential[0].Password" value="password" />

 

For LDAPS, all the setting used is the same as LDAP but add SecureSocketsLayer to MembershipProviderSettings. For example:

<add key="MembershipProviderSettings.ADDomain[0].AuthenticationTypes" value=" SecureSocketsLayer, Secure " />

Also use the FQDN of the AD server instead of the IP address.

For more details on configuring Cyara web portal web.config for AD, please refer to the Cyara Deployment Guide.

After configuring for LDAP or LDAPS, restart the IIS server using Internet Information Server (IIS) Manager.

Users that need to be authenticated using AD via LDAP need to be added to Cyara web portal. Users added will now have the domain included in the user name. Please see example below.

There should be no errors when saving user entry if the user exist in the AD server. If the user does not exist, an error will be reported. Please see example of an non-existent user entry below.

Once the an AD user has been added successfully to Cyara web portal and given the appropriate privileges, the user can then logon using the user’s AD password. The domain or the domain alias must be used with the user name for logging on. Please see example below.