Default FTP Client Certificate Authentication Settings <clientCertAuthentication>

Overview

The <clientCertAuthentication> element specifies the settings for Client Certificate authentication. This form of Secure Sockets Layer (SSL) authentication was introduced in FTP 7 and uses client certificates to authenticate FTP clients by mapping to client certificates Windows user accounts.

Client Certificate authentication has the following dependencies:

  • For the <ssl> element:
    • The serverCertHash attribute must be set to a valid certificate hash.
    • The controlChannelPolicy and dataChannelPolicy attributes must be configured to allow SSL.
  • For the <sslClientCertificates> element:
    • The clientCertificatePolicy attribute must be configured to allow SSL certificates.
    • The useActiveDirectoryMapping attribute must be set to true.

Note: The FTP service requests Active Directory to validate client certificates, but the validation by Active Directory is performed independently of the FTP service.

Compatibility

Version Notes
IIS 7.5 The <clientCertAuthentication> element of the <authentication> element ships as a feature of IIS 7.5.
IIS 7.0 The <clientCertAuthentication> element of the <authentication> element was introduced in FTP 7.0, which was a separate download for IIS 7.0.
IIS 6.0 The <ftpServer> element and its child elements replace the IIS 6.0 FTP settings that were located in the LM/MSFTPSVC metabase path.

Note: The FTP 7.0 and FTP 7.5 services shipped out-of-band for IIS 7.0, which required downloading and installing the modules from the following URL:

http://www.iis.net/expand/FTP

With Windows 7 and Windows Server 2008 R2, the FTP 7.5 service ships as a feature for IIS 7.5, so downloading the FTP service is no longer necessary.

Setup

To support FTP publishing for your Web server, you must install the FTP service. To do so, use the following steps.

IIS 7.5 for 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, expand FTP Server.
  5. Select FTP Service.

    Note: To support ASP.Membership authentication or IIS Manager authentication for the FTP service, you will also need to select FTP Extensibility.
  6. Click Next.
  7. On the Confirm Installation Selections page, click Install.
  8. On the Results page, click Close.

IIS 7.5 for 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, and then FTP Server.
  4. Select FTP Service.

    Note: To support ASP.Membership authentication or IIS Manager authentication for the FTP service, you will also need to select FTP Extensibility.
  5. Click OK.

IIS 7.0 for Windows Server 2008 and Windows Vista

  1. Download the installation package from the following URL:
  2. Follow the instructions in the following walkthrough to install the FTP service:

How To

At this time there is no user interface that enables you to configure the Client Certificate authentication settings for an FTP site. See the Configuration and Sample Code sections of this document for additional information about how to configure the Client Certificate authentication settings for an FTP site.

Configuration

Attributes

Attribute Description
enabled Optional Boolean attribute.

true if Client Certificate authentication is enabled; otherwise, false.

The default value is false.

Child Elements

None.

Configuration Sample

The following configuration sample displays an example <siteDefaults> element for a server that has Client Certificate authentication enabled by default.

<siteDefaults>
   <ftpServer>
      <security>
         <ssl serverCertHash="57686f6120447564652c2049495320526f636b73" controlChannelPolicy="SslAllow" dataChannelPolicy="SslAllow" />
         <sslClientCertificates clientCertificatePolicy="CertAllow" useActiveDirectoryMapping="true" />
         <authentication>
            <clientCertAuthentication enabled="true" />
         </authentication>
      </security>
   </ftpServer>
</siteDefaults>

Sample Code

The following code samples illustrates how to enable Client Certificate authentication by default.

AppCmd.exe

appcmd.exe set config -section:system.applicationHost/sites /siteDefaults.ftpServer.security.ssl.controlChannelPolicy:"SslAllow" /commit:apphost
appcmd.exe set config -section:system.applicationHost/sites /siteDefaults.ftpServer.security.ssl.dataChannelPolicy:"SslAllow" /commit:apphost
appcmd.exe set config -section:system.applicationHost/sites /siteDefaults.ftpServer.security.ssl.serverCertHash:"57686f6120447564652c2049495320526f636b73" /commit:apphost
appcmd.exe set config -section:system.applicationHost/sites /siteDefaults.ftpServer.security.authentication.clientCertAuthentication.enabled:"True" /commit:apphost
appcmd.exe set config -section:system.applicationHost/sites /siteDefaults.ftpServer.security.sslClientCertificates.clientCertificatePolicy:"CertIgnore" /commit:apphost
appcmd.exe set config -section:system.applicationHost/sites /siteDefaults.ftpServer.security.sslClientCertificates.useActiveDirectoryMapping:"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 sitesSection = config.GetSection("system.applicationHost/sites");
         ConfigurationElement siteDefaultsElement = sitesSection.GetChildElement("siteDefaults");
         ConfigurationElement ftpServerElement = siteDefaultsElement.GetChildElement("ftpServer");

         ConfigurationElement securityElement = ftpServerElement.GetChildElement("security");
         ConfigurationElement sslElement = securityElement.GetChildElement("ssl");
            sslElement["controlChannelPolicy"] = @"SslAllow";
            sslElement["dataChannelPolicy"] = @"SslAllow";
            sslElement["serverCertHash"] = "57686f6120447564652c2049495320526f636b73";
			
         ConfigurationElement authenticationElement = securityElement.GetChildElement("authentication");
         ConfigurationElement clientCertAuthenticationElement = authenticationElement.GetChildElement("clientCertAuthentication");
            clientCertAuthenticationElement["enabled"] = true;
			
         ConfigurationElement sslClientCertificatesElement = securityElement.GetChildElement("sslClientCertificates");
            sslClientCertificatesElement["clientCertificatePolicy"] = @"CertRequire";
            sslClientCertificatesElement["useActiveDirectoryMapping"] = 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 sitesSection As ConfigurationSection = config.GetSection("system.applicationHost/sites")
        Dim siteDefaultsElement As ConfigurationElement = sitesSection.GetChildElement("siteDefaults")
        Dim ftpServerElement As ConfigurationElement = siteDefaultsElement.GetChildElement("ftpServer")

        Dim securityElement As ConfigurationElement = ftpServerElement.GetChildElement("security")
        Dim sslElement As ConfigurationElement = securityElement.GetChildElement("ssl")
        sslElement("controlChannelPolicy") = "SslAllow"
        sslElement("dataChannelPolicy") = "SslAllow"
        sslElement("serverCertHash") = "57686f6120447564652c2049495320526f636b73"

        Dim authenticationElement As ConfigurationElement = securityElement.GetChildElement("authentication")
        Dim clientCertAuthenticationElement As ConfigurationElement = authenticationElement.GetChildElement("clientCertAuthentication")
        clientCertAuthenticationElement("enabled") = True

        Dim sslClientCertificatesElement As ConfigurationElement = securityElement.GetChildElement("sslClientCertificates")
        sslClientCertificatesElement("clientCertificatePolicy") = "CertIgnore"
        sslClientCertificatesElement("useActiveDirectoryMapping") = True

        serverManager.CommitChanges()
    End Sub

End Module

JavaScript

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

var sitesSection = adminManager.GetAdminSection("system.applicationHost/sites", "MACHINE/WEBROOT/APPHOST");
var siteDefaultsElement = sitesSection.ChildElements.Item("siteDefaults");
var ftpServerElement = siteDefaultsElement.ChildElements.Item("ftpServer");

var securityElement = ftpServerElement.ChildElements.Item("security");
var sslElement = securityElement.ChildElements.Item("ssl");
   sslElement.Properties.Item("controlChannelPolicy").Value = "SslAllow";
   sslElement.Properties.Item("dataChannelPolicy").Value = "SslAllow";
   sslElement.Properties.Item("serverCertHash").Value = "57686f6120447564652c2049495320526f636b73";
   
var authenticationElement = securityElement.ChildElements.Item("authentication");
var clientCertAuthenticationElement = authenticationElement.ChildElements.Item("clientCertAuthentication");
   clientCertAuthenticationElement.Properties.Item("enabled").Value = true;
   
var sslClientCertificatesElement = securityElement.ChildElements.Item("sslClientCertificates");
   sslClientCertificatesElement.Properties.Item("clientCertificatePolicy").Value = "CertIgnore";
   sslClientCertificatesElement.Properties.Item("useActiveDirectoryMapping").Value = true;

adminManager.CommitChanges();

VBScript

Set adminManager = createObject("Microsoft.ApplicationHost.WritableAdminManager")
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST"
Set sitesSection = adminManager.GetAdminSection("system.applicationHost/sites", "MACHINE/WEBROOT/APPHOST")
Set siteDefaultsElement = sitesSection.ChildElements.Item("siteDefaults")
Set ftpServerElement = siteDefaultsElement.ChildElements.Item("ftpServer")

Set securityElement = ftpServerElement.ChildElements.Item("security")
Set sslElement = securityElement.ChildElements.Item("ssl")
   sslElement.Properties.Item("controlChannelPolicy").Value = "SslAllow"
   sslElement.Properties.Item("dataChannelPolicy").Value = "SslAllow"
   sslElement.Properties.Item("serverCertHash").Value = "57686f6120447564652c2049495320526f636b73"
   
Set authenticationElement = securityElement.ChildElements.Item("authentication")
Set clientCertAuthenticationElement = authenticationElement.ChildElements.Item("clientCertAuthentication")
   clientCertAuthenticationElement.Properties.Item("enabled").Value = True
   
Set sslClientCertificatesElement = securityElement.ChildElements.Item("sslClientCertificates")
   sslClientCertificatesElement.Properties.Item("clientCertificatePolicy").Value = "CertIgnore"
   sslClientCertificatesElement.Properties.Item("useActiveDirectoryMapping").Value = True

adminManager.CommitChanges()
Deprecated Elements