This article is intended to assist with installation of our InstantKB Active Directory Module
Before attempting an installation of the InstantKB Active directory module, you should have installed and configured the latest version of InstantKB and fully tested to ensure proper functionality. It is vital that you ascertain that there are no installation/configuration issues before installing the Active Directory module, as this could exacerbate any existing issues. You should also have downloaded the most recent release version of the Active Directory Module, ready for installation.
We recommend that you fully back-up, your working InstantKB directory, and database, this is especially important if you are adding the module to a production installation which holds live or critical data. If you choose not to back-up your installation/data (not recommended), at the very least you should back up your Web.Config file, so that your configured settings are easily available during the rest of the installation process.
Adding the InstantKB Active Directory Module To An Existing Installation
1) Extract the contents of the Active Directory module ZIP file to a folder on your hard drive.
2) Copy all files, except for the provided Web.Config into your installation root, approving any overwrites that the system requests as existing files are replaced.
3) At this stage, you should test your KB, by visiting the home URL, if all has gone well you should still see a home page, and be able to log in as standard, if at this point you do not get a homepage, or cannot login, you may want to try the following quick troubleshooting steps:
- Re-Apply all permissions to the site-root, and all child files/directories.
- Check that the update to the database was successful, or re-execute the script.
- Re-Copy your backed up web.config to the site-root, in case you accidentally overwrote it.
5) Finally, before you can get to grips with the active directory module, you will need to configure your web.config file, there are two ways to do this.
a) Copy the provided active directory web.config file into your site root, overwriting your web.config file, then re-populate your database connection string and any other settings that you had customised previously within the new config file.
Configure the "WinLogin" Folder
After installing the InstantKB active directory module you will notice a new folder within the root of your InstantKB installation called "WinLogin". The WinLogin folder is important as it's used for automated windows authentication. The code within the WinLogin folder is used to automatically authenticate you against your domain controller using the service account configured below and will automatically create local InstantKB accounts & authenticate users upon successful active directory authentication.
To ensure the code within the WinLogin folder can execute correctly you need to ensure the WinLogin folder has both forms and windows authentication enabled within IIS however it must have anonymous authenticaiton disabled.
- 1. Ensure the WinLogin folder within your InstantKB folder within IIS is marked as a web application (use the same app pool as your parent InstantKB site / app).
- Within IIS click the WinLogin folder and then click "Authentication". Ensure Anonymous authentication is disabled and both forms & windows authentication are enabled.
- Open the WinLogin/web.config file within NotePad.
- Change InstantASP_InstallURL application setting to your absolute URL for your parent InstantKB installation.
Within the WinLogin/web.config file ensure the authentication element is set to "Windows". ie.<authentication mode="Windows" />.
IIS can change the authentication element within the web.config each time you visit the "Authentication" feature within IIS.If you make changes within IIS you should open the WinLogin/web.config after any changes within NotePad and ensure the authentication mode is still set to Windows.
Configure the InstantKB web.config settings
You will now need to configure the settings specific to your installation within the web.config file fount within the root of your InstantKB installation. The settings are detailed below...
- InstantASP_ConnectionString <-- the connection string to your InstantKB database
LDAP Connection String
- InstantASP_LDAPPath <-- the LDAP path to your domain controller
- InstantASP_LDAPDomain <-- Your AD Domain
InstantKB Service Account
- InstantASP_LDAPAdminUsername <-- the username of a AD account that has permission to query (cn, samaccountname, email)
- InstantASP_LDAPAdminPassword <-- the password of a AD account that has permission to query (cn, samaccountname, email)
The service account settings are used for automated windows authentication. This account queries the domain controller on your behalf if your not already authenticated to validate your windows username.For further information on configuring the service account please see Granting Read Access To Your Active Directory Domain.
Test Your Changes
These are the basic steps to configure the active directory module.
You will hopefully notice when you visit your new InstantKB installation with the AD module installed you are automatically logged in. With the active directory module installed all new visitors or sessions should be redirected through the "WinLogin/WinLogin.aspx" page. This page perform the authentication windows authentication & account creation / mapping. Please note you are only redirected through the WinLogin folder upon the very first request to InstantKB. We maintain a session cookie which is set on WinLogin/WinLogin.aspx and only expires only you close your browser. If this cookies exists you will not be automatically redirected through WinLogin/WinLogin.aspx. This means you may need to close your browser to tested the automated authentication each time.
If you are not automatically logged in via the WinLogin/WinLogin.aspx please try to visit the regular login page manually within the InstantKB UI and you should see a new LDAP Login check box below the regular login form. Enter your active directory information with this check box enabled and attempt to login manually. If logging in via active directory from the InstantKB login page works this would suggest your active directory is configured correctly.
If you are not automatically logged in via WinLogin upon your very first visit this is likely due to Kerberos authentication not working or the forms authentication cookie used by InstantKB to persist authentication between WinLogin & InstantKB is not being shared correctly between the InstantKB IIS application and the WinLogin IIS application.For further information on ensure the authentication cookie can be shared please see InstantKB single sign on considerations.
InstantKB depends upon Kerberos authentication to perform automated windows authentication. For security reasons we don't support the older NTLM provider. If you receive a NTLM login prompt when visiting WinLogin/WinLogin.aspx please ensure you've installed the Kerberos provider within IIS. For further information on trouble shooting Kerberos authenticaiton issues please see the TroubleshootingKerberosAuthenticationIssues.pdf attached to this article below.
Troubleshooting InstantKB Active Directory Issues
To help troubleshoot your installation please perform the following steps...
- Within the InstantKB web.config ensure the InstantASP_LDAPDebug application setting is set to "true".
- Open your browser and visit http://your-instantkb-url/WinLogin/WinLogin.aspx
You should see debug information that shows the process InstantKB is going through to perform the authentnciation. If your experiencing problems please contact firstname.lastname@example.org and enclose this debug information.
To test the active directory module is installed and configured correctly please navigate to your InstantKB installation within your web browser. If you are already logged in using forms authentication please log out. Once logged out please click the "Login" link in the top right of each InstantKB page. You will notice during login you can choose the LDAP Login check box and provide your active directory credentials to authenticate.
We hope you found this article helpful. If we can assist with any specific questions regarding active directory installation please don't hesitate to contact us.