Basic Authentication <basicAuthentication>

Overview

The <basicAuthentication> element contains configuration settings for the Internet Information Services (IIS) 7 Basic authentication module. You configure this element to enable or disable Basic authentication, identify the realm and default logon domain, and determine the logon method the module uses.

The Basic authentication scheme is a widely used, industry-standard method for collecting user name and password information. Basic authentication transmits user names and passwords across the network in an unencrypted form. You can use SSL encryption in combination with Basic authentication to help secure user account information transmitted across the Internet or a corporate network.

Compatibility

Version Notes
IIS 7.5 The <basicAuthentication> element was not modified in IIS 7.5.
IIS 7.0 The <basicAuthentication> element was introduced in IIS 7.0.
IIS 6.0 The <basicAuthentication> element replaces portions of the IIS 6.0 AuthType and AuthFlags metabase properties.

Setup

The default installation of IIS 7 does not include the Basic authentication role service. To use Basic authentication on Internet Information Services (IIS), you must install the role service, disable Anonymous authentication for your Web site or application, and then enable Basic authentication for the site or application.

To install the Basic authentication role service, use the following steps.

Windows Server 2008 or Windows Server 2008 R2

  1. On the taskbar, click Start, point to Administrative Tools, and then click Server Manager.
  2. In the Server Manager hierarchy pane, expand Roles, and then click Web Server (IIS).
  3. In the Web Server (IIS) pane, scroll to the Role Services section, and then click Add Role Services.
  4. On the Select Role Services page of the Add Role Services Wizard, select Basic Authentication, and then click Next.
  5. On the Confirm Installation Selections page, click Install.
  6. On the Results page, click Close.

Windows Vista or Windows 7

  1. On the taskbar, click Start, and then click Control Panel.
  2. In Control Panel, click Programs and Features, and then click Turn Windows Features on or off.
  3. Expand Internet Information Services, expand World Wide Web Services, expand Security, select Basic Authentication, and then click OK.

How To

How to enable basic authentication and disable anonymous authentication

  1. Open Internet Information Services (IIS) Manager:
    • If you are using Windows Server 2008 or Windows Server 2008 R2:
      • On the taskbar, click Start, point to Administrative Tools, and then click Internet Information Services (IIS) Manager.
    • If you are using Windows Vista or Windows 7:
      • On the taskbar, click Start, and then click Control Panel.
      • Double-click Administrative Tools, and then double-click Internet Information Services (IIS) Manager.
  2. In the Connections pane, expand the server name, expand Sites, and then click the site, application or Web service for which you want to enable basic authentication.
  3. Scroll to the Security section in the Home pane, and then double-click Authentication.
  4. In the Authentication pane, select Basic Authentication, and then, in the Actions pane, click Enable.
  5. In the Authentication pane, select Anonymous Authentication, and then click Disable in the Actions pane.

Configuration

The <basicAuthentication> element is configurable at the site, application, virtual directory, and URL level. After you install the role service, IIS 7 commits the following configuration settings to the ApplicationHost.config file.

<basicAuthentication enabled='false' />

Attributes

Attribute Description
defaultLogonDomain Optional String attribute.

Specifies the default logon domain for Basic authentication.
enabled Optional Boolean attribute.

Specifies whether Basic authentication is enabled.

The default value is false.
logonMethod Optional enum attribute.

The logonMethod attribute can be one of the following possible values. The default is ClearText.
Value Description
Batch This logon type is intended for batch servers, where processes may be executing on behalf of a user without that user's direct intervention.

The numeric value is 1.
ClearText This logon type preserves the name and password in the authentication package, which allows the server to make connections to other network servers while impersonating the client.

The numeric value is 3.
Interactive This logon type is intended for users who will be using the computer interactively.

The numeric value is 0.
Network This logon type is intended for high performance servers to authenticate plaintext passwords. Credentials are not cached for this logon type.

The numeric value is 2.
realm Optional String attribute.

Specifies the realm for Basic authentication.

Child Elements

None.

Configuration Sample

The following configuration sample enables Basic authentication for a Web site, Web application, or Web service. By default these settings must be included in your ApplicationHost.config file, and you must include them in a <location> element and use the path attribute to define the Web site or application where you want to apply the authentication settings.

<security>
   <authentication>
      <anonymousAuthentication enabled="false" />
      <basicAuthentication enabled="true" />
   </authentication>
</security>

Sample Code

The following examples enable Basic authentication for a site.

AppCmd.exe

appcmd.exe set config "Contoso" -section:system.webServer/security/authentication/basicAuthentication /enabled:"True" /commit:apphost

Note: You must be sure to set the commit parameter to apphost when you use AppCmd.exe to configure these settings. This commits the configuration settings to the appropriate location section in the ApplicationHost.config file.

C#

using System;
using System.Text;
using Microsoft.Web.Administration;

internal static class Sample
{

    private static void Main()
    {

        using (ServerManager serverManager = new ServerManager())
        {
            Configuration config = serverManager.GetApplicationHostConfiguration();

            ConfigurationSection basicAuthenticationSection = config.GetSection("system.webServer/security/authentication/basicAuthentication", "Contoso");
            basicAuthenticationSection["enabled"] = true;

            serverManager.CommitChanges();
        }
    }
}

VB.NET

Imports System
Imports System.Text
Imports Microsoft.Web.Administration

Module Sample
    Sub Main()
        Dim serverManager As ServerManager = New ServerManager
        Dim config As Configuration = serverManager.GetApplicationHostConfiguration

        Dim basicAuthenticationSection As ConfigurationSection = config.GetSection("system.webServer/security/authentication/basicAuthentication", "Contoso")
        basicAuthenticationSection("enabled") = True

        serverManager.CommitChanges()
    End Sub
End Module

JavaScript

var adminManager = new ActiveXObject('Microsoft.ApplicationHost.WritableAdminManager');
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST";

var basicAuthenticationSection = adminManager.GetAdminSection("system.webServer/security/authentication/basicAuthentication", "MACHINE/WEBROOT/APPHOST/Contoso");
basicAuthenticationSection.Properties.Item("enabled").Value = true;

adminManager.CommitChanges();

VBScript

Set adminManager = CreateObject("Microsoft.ApplicationHost.WritableAdminManager")
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST"

Set basicAuthenticationSection = adminManager.GetAdminSection("system.webServer/security/authentication/basicAuthentication", "MACHINE/WEBROOT/APPHOST/Contoso")
basicAuthenticationSection.Properties.Item("enabled").Value = True

adminManager.CommitChanges()
Deprecated Elements