Configuring Windows AD authentication

Kentico supports Windows integrated authentication. This means that when a user signs in to a Windows domain, Kentico automatically recognizes their identity without requiring a user name and password.

Prerequisite

For Windows authentication to work, the application must be able to access the following attributes of user objects in Active Directory (i.e. the attributes cannot be protected or confidential):

  • memberof
  • userAccountControl

When an authenticated user comes to a site configured for Windows authentication, the system automatically creates a matching user account in the Kentico database and also imports the user’s domain groups as roles. The user’s assignment to Kentico roles is updated on each login based on the current state of the user’s groups in Active Directory.

The imported roles do not authorize the users to perform any actions in Kentico by default. You need to configure permissions and UI personalization settings for the imported roles manually if you wish to use them.

Disabling the automatic role import

If you wish to disable the automatic import of user domain groups as roles in Kentico, add the following key to the /configuration/appSettings section of your project’s web.config file:




<add key="CMSImportWindowsRoles" value="false" />


Configuring Windows authentication

Before you configure your project for Windows authentication, you need to create a user account for your current domain name and grant this user account administrator permissions. This will allow you to access all features as an administrator once you sign in using Windows authentication.

  1. Open the Users application.
  2. Create a new user with the following values:
    • User name: your domain user name in format domain-username, for example: office-johns
    • Full name: your full name
  3. Click Save.
  4. On the General tab, set the following values:
    • Privilege level: Global administrator
    • Is external user: yes
    • Is domain user: yes
  5. Click Save.

Now you can switch the application to Windows authentication mode.

  1. Edit the web.config file of the web project.

  2. Set the mode attribute of the <authentication> element in the <system.web> section to Windows:

    
    
    
     <authentication mode="Windows">
    
    
     
  3. (Optional) You can also make Windows authentication required for access to the live site. To achieve this result, uncomment the following <location> element in your web.config:

    
    
    
     <location path="">
       <system.web>
         <authorization>
           <deny users="?"/>
         </authorization>
       </system.web>
     </location>
    
    
     

    If you want to require Windows authentication for only part of the live website, see Securing a website section using Windows authentication.

  4. Save the modified web.config file.

  5. Close all browsers with Kentico and open the website in a new browser.

  6. Try to go to <site domain>/admin to make sure you are recognized as a global administrator.

    • If you encounter the 401 error, continue to the Enabling Windows authentication in IIS section below.

With this configuration, the system automatically authenticates users from Windows Active Directory and imports them to the Kentico database.

Sign out button missing with Windows authentication

When Windows authentication is enabled, the Sign out button in user menu in the top right corner of the administration interface is not displayed. The same applies to the live site, where the sign out link is not displayed in all web parts that can be used to sign out.

Enabling Windows authentication in IIS

If you are experiencing the 401 error with Windows authentication, you need to enable Windows authentication in your IIS:

  1. Start the Internet Information Services (IIS) Manager.

  2. Locate and select your site in the IIS tree.

  3. Double-click the Authentication icon.

    Open the Authentication feature in IIS

    Windows Authentication missing in the list

    If your IIS installation does not contain Windows Authentication by default, you need to install it:

    1. Go to Control Panel -> Programs and Features -> Turn windows features on or off.
    2. Expand Internet Information Services -> World Wide Web Services.
    3. Under Security, enable the Windows Authentication checkbox.
    4. Click OK to finish the configuration.Windows Authentication appears as an option in IIS website authentication settings.
  4. Select Windows Authentication.

  5. Click Enable in the Actions menu.

    Enable the Windows authentication

IIS now enables Windows authentication on your site.

Forbidden character replacement during Active Directory import

When importing users and roles, forbidden characters in the names are replaced by the character defined in Settings -> URLs and SEO -> Forbidden characters replacement.

The default value is a dash “-” (domain-username instead of domain\username). If you are using a different character, please change the entered user name accordingly.

You can override this setting by adding the following keys to the AppSettings section of your web.config file. In both cases, the value must be exactly one character:




<add key="CMSForbiddenUserNameCharactersReplacement" value="-" />





<add key="CMSForbiddenRoleNameCharactersReplacement" value="-" />


If you want to achieve the same functionality as in older versions of Kentico (office\username), forbidden characters replacement can be turned off completely using the following two keys. This may cause problems when using wildcard URLs with user names in the wildcard part and is therefore not recommended.




<add key="CMSEnsureSafeUserNames" value="false" />





<add key="CMSEnsureSafeRoleNames" value="false" />