FTP SSL Client Certificates <sslClientCertificates>


The <sslClientCertificates> element specifies the SSL client certificate options for FTP sites. More specifically, this element contains the following attributes, which are discussed in detail in the configuration section of this topic:

  • The clientCertificatePolicy attribute specifies whether client certificates will be allowed, required, or ignored.
  • The validationFlags attribute specifies an FTP site's behavior for checking for certificate revocation.
  • The revocationFreshnessTime attribute specifies the amount of time that the revocation list is valid.
  • The revocationUrlRetrievalTimeout attribute specifies the time-out for retrieving certificate revocation information
  • The useActiveDirectoryMapping attribute specifies whether Active Directory mapping should be allowed for client certificates. Note: This attribute is used in combination with the <clientCertAuthentication> element to configure certificate mapping by using Active Directory.


Version Notes
IIS 7.5 The <sslClientCertificates> element of the <security> element ships as a feature of IIS 7.5.
IIS 7.0 The <sslClientCertificates> element of the <security> 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:


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.


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 custom features to an FTP site.


The <sslClientCertificates> element is configured at the site level.


Attribute Description
clientCertificatePolicy Optional enum attribute.

Specifies the client certificate policy.
Value Description
CertIgnore Specifies that client certificates will not be negotiated for SSL session.

The numeric value is 0.
CertAllow Specifies that client certificates will be allowed. If the client chooses to send a certificate, then certificate must be valid and the server must be able to successfully validate it.

The numeric value is 1.
CertRequire Specifies that client certificates will be required. FTP clients will not be allowed to connect unless they send a valid client certificate to the server.

The numeric value is 2.
The default value is CertIgnore.
validationFlags Optional flags attribute.

Specifies the flags that affect client certificate validation.
Value Description

Specifies that certificate revocation checks will be skipped.

Warning: It is not recommended to skip revocation validation.

The numeric value is 1.

CertChainRevocationCheckCacheOnly Specifies that revocation checking only accesses cached URLs.

The numeric value is 2.
CertChainCacheOnlyUrlRetrieval Specifies only cached URLs in building a certificate chain. The Internet and intranet are not searched for URL-based objects.

The numeric value is 4.
CertNoUsageCheck Does not check client certificate for usage flags. Usage check is enabled by default and it is meant to assure that only client certificates that allow "Client authentication" are allowed.

The numeric value is 8.
There is no default value.
revocationFreshnessTime Optional timeSpan attribute.

Specifies the amount of time the revocation list is valid.

The default value is 00:00:00.
revocationUrlRetrievalTimeout Optional timeSpan attribute.

Specifies the timeout for retrieving certificate revocation information.

The default value is 00:01:00.
useActiveDirectoryMapping Optional Boolean attribute.

true if Active Directory mapping should be allowed for client certificates; otherwise, false. Active Directory mapping allows domain users to log on by using a client certificate that is configured in Active Directory.

Note: This feature only allows the SSL layer to attempt to map a client certificate to a user token; the token will not be used automatically. The <clientCertAuthentication> element is used to enable the mapped token for use by FTP instead of credentials specified through "USER" and "PASS" commands.

The default value is false.

Child Elements


Configuration Sample

The following sample displays an FTP site that requires SSL and client certificates for both the data channel and the control channel.

<site name="ftp.example.com" id="5">
   <application path="/">
      <virtualDirectory path="/" physicalPath="c:\inetpub\www.example.com" />
      <binding protocol="ftp" bindingInformation="*:21:" />
   <ftpServer serverAutoStart="true">
            <anonymousAuthentication enabled="false" />
            <basicAuthentication enabled="true" />
         <ssl serverCertHash="57686f6120447564652c2049495320526f636b73"
            dataChannelPolicy="SslRequire" />
         <sslClientCertificates clientCertificatePolicy="CertRequire"
            useActiveDirectoryMapping="false" />

Sample Code

The following examples configure an FTP site so that it requires client certificates and requires SSL for both the data channel and the control channel.


appcmd.exe set config -section:system.applicationHost/sites /[name='ftp.example.com'].ftpServer.security.ssl.serverCertHash:"57686f6120447564652c2049495320526f636b73" /commit:apphost
appcmd.exe set config -section:system.applicationHost/sites /[name='ftp.example.com'].ftpServer.security.ssl.controlChannelPolicy:"SslRequire" /commit:apphost
appcmd.exe set config -section:system.applicationHost/sites /[name='ftp.example.com'].ftpServer.security.ssl.dataChannelPolicy:"SslRequire" /commit:apphost

appcmd.exe set config -section:system.applicationHost/sites /[name='ftp.example.com'].ftpServer.security.sslClientCertificates.clientCertificatePolicy:"CertRequire" /commit:apphost
appcmd.exe set config -section:system.applicationHost/sites /[name='ftp.example.com'].ftpServer.security.sslClientCertificates.useActiveDirectoryMapping:"False" /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.


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");
         ConfigurationElementCollection sitesCollection = sitesSection.GetCollection();

         ConfigurationElement siteElement = FindElement(sitesCollection, "site", "name", @"ftp.example.com");
         if (siteElement == null) throw new InvalidOperationException("Element not found!");

         ConfigurationElement ftpServerElement = siteElement.GetChildElement("ftpServer");
         ConfigurationElement securityElement = ftpServerElement.GetChildElement("security");

         ConfigurationElement sslElement = securityElement.GetChildElement("ssl");
         sslElement["serverCertHash"] = @"57686f6120447564652c2049495320526f636b73";
         sslElement["controlChannelPolicy"] = @"SslRequire";
         sslElement["dataChannelPolicy"] = @"SslRequire";

         ConfigurationElement sslClientCertificatesElement = securityElement.GetChildElement("sslClientCertificates");
         sslClientCertificatesElement["clientCertificatePolicy"] = @"CertRequire";
         sslClientCertificatesElement["useActiveDirectoryMapping"] = false;

   private static ConfigurationElement FindElement(ConfigurationElementCollection collection, string elementTagName, params string[] keyValues)
      foreach (ConfigurationElement element in collection)
         if (String.Equals(element.ElementTagName, elementTagName, StringComparison.OrdinalIgnoreCase))
            bool matches = true;
            for (int i = 0; i < keyValues.Length; i += 2)
               object o = element.GetAttributeValue(keyValues[i]);
               string value = null;
               if (o != null)
                  value = o.ToString();
               if (!String.Equals(value, keyValues[i + 1], StringComparison.OrdinalIgnoreCase))
                  matches = false;
            if (matches)
               return element;
      return null;



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 sitesCollection As ConfigurationElementCollection = sitesSection.GetCollection

      Dim siteElement As ConfigurationElement = FindElement(sitesCollection, "site", "name", "ftp.example.com")
      If (siteElement Is Nothing) Then
         Throw New InvalidOperationException("Element not found!")
      End If

      Dim ftpServerElement As ConfigurationElement = siteElement.GetChildElement("ftpServer")
      Dim securityElement As ConfigurationElement = ftpServerElement.GetChildElement("security")

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

      Dim sslClientCertificatesElement As ConfigurationElement = securityElement.GetChildElement("sslClientCertificates")
      sslClientCertificatesElement("clientCertificatePolicy") = "CertRequire"
      sslClientCertificatesElement("useActiveDirectoryMapping") = False

   End Sub

   Private Function FindElement(ByVal collection As ConfigurationElementCollection, ByVal elementTagName As String, ByVal ParamArray keyValues() As String) As ConfigurationElement
      For Each element As ConfigurationElement In collection
         If String.Equals(element.ElementTagName, elementTagName, StringComparison.OrdinalIgnoreCase) Then
            Dim matches As Boolean = True
            Dim i As Integer
            For i = 0 To keyValues.Length - 1 Step 2
               Dim o As Object = element.GetAttributeValue(keyValues(i))
               Dim value As String = Nothing
               If (Not (o) Is Nothing) Then
                  value = o.ToString
               End If
               If Not String.Equals(value, keyValues((i + 1)), StringComparison.OrdinalIgnoreCase) Then
                  matches = False
                  Exit For
               End If
            If matches Then
               Return element
            End If
         End If
      Return Nothing
   End Function

End Module


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

var sitesSection = adminManager.GetAdminSection("system.applicationHost/sites", "MACHINE/WEBROOT/APPHOST");
var sitesCollection = sitesSection.Collection;
var siteElementPos = FindElement(sitesCollection, "site", ["name", "ftp.example.com"]);

if (siteElementPos == -1) throw "Element not found!";

var siteElement = sitesCollection.Item(siteElementPos);
var ftpServerElement = siteElement.ChildElements.Item("ftpServer");
var securityElement = ftpServerElement.ChildElements.Item("security");

var sslElement = securityElement.ChildElements.Item("ssl");
sslElement.Properties.Item("serverCertHash").Value = "57686f6120447564652c2049495320526f636b73";
sslElement.Properties.Item("controlChannelPolicy").Value = "SslRequire";
sslElement.Properties.Item("dataChannelPolicy").Value = "SslRequire";

var sslClientCertificatesElement = securityElement.ChildElements.Item("sslClientCertificates");
sslClientCertificatesElement.Properties.Item("clientCertificatePolicy").Value = "CertRequire";
sslClientCertificatesElement.Properties.Item("useActiveDirectoryMapping").Value = false;


function FindElement(collection, elementTagName, valuesToMatch) {
   for (var i = 0; i < collection.Count; i++) {
      var element = collection.Item(i);
      if (element.Name == elementTagName) {
         var matches = true;
         for (var iVal = 0; iVal < valuesToMatch.length; iVal += 2) {
            var property = element.GetPropertyByName(valuesToMatch[iVal]);
            var value = property.Value;
            if (value != null) {
               value = value.toString();
            if (value != valuesToMatch[iVal + 1]) {
               matches = false;
         if (matches) {
            return i;
   return -1;


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

Set sitesSection = adminManager.GetAdminSection("system.applicationHost/sites", "MACHINE/WEBROOT/APPHOST")
Set sitesCollection = sitesSection.Collection
siteElementPos = FindElement(sitesCollection, "site", Array("name", "ftp.example.com"))

If siteElementPos = -1 Then
Wscript.Echo "Element not found!"
End If

Set siteElement = sitesCollection.Item(siteElementPos)
Set ftpServerElement = siteElement.ChildElements.Item("ftpServer")
Set securityElement = ftpServerElement.ChildElements.Item("security")

Set sslElement = securityElement.ChildElements.Item("ssl")
sslElement.Properties.Item("serverCertHash").Value = "57686f6120447564652c2049495320526f636b73"
sslElement.Properties.Item("controlChannelPolicy").Value = "SslRequire"
sslElement.Properties.Item("dataChannelPolicy").Value = "SslRequire"

Set sslClientCertificatesElement = securityElement.ChildElements.Item("sslClientCertificates")
sslClientCertificatesElement.Properties.Item("clientCertificatePolicy").Value = "CertRequire"
sslClientCertificatesElement.Properties.Item("useActiveDirectoryMapping").Value = False


Function FindElement(collection, elementTagName, valuesToMatch)
   For i = 0 To CInt(collection.Count) - 1
      Set element = collection.Item(i)
      If element.Name = elementTagName Then
         matches = True
         For iVal = 0 To UBound(valuesToMatch) Step 2
            Set property = element.GetPropertyByName(valuesToMatch(iVal))
            value = property.Value
            If Not IsNull(value) Then
               value = CStr(value)
            End If
            If Not value = CStr(valuesToMatch(iVal + 1)) Then
               matches = False
               Exit For
            End If
         If matches Then
            Exit For
         End If
      End If
   If matches Then
      FindElement = i
      FindElement = -1
   End If
End Function
Deprecated Elements