How to Create an Authentication Provider for FTP 7.5 using BlogEngine.NET's XML Membership Files
I ran into an interesting situation recently with BlogEngine.NET that I thought would make a good blog post.
Here's the background for the environment: I host several blog sites for friends of mine, and they BlogEngine.NET for their blogging engine. From a security perspective this works great for me, because I can give them accounts for blogging that are kept in the XML files for each of their respective blogs that aren't real user accounts on my Windows servers.
The problem that I ran into: BlogEngine.NET has great support for uploading files to your blog, but it doesn't provide a real way to manage the files that have been uploaded. So when one of my friends mentioned that they wanted to update one of their files, I was left in a momentary quandary.
My solution: I realized that I could write a custom FTP provider that would solve all of my needs. For my situation the provider needed to do three things:
- The provider needed to perform username/password validation.
- The provider needed to perform role lookups.
- The provider needed to return a custom home directory.
Here's why item #3 was so important - my users have no idea about the underlying functionality for their blog, so I didn't want to simply enable FTP publishing for their website and give them access to their ASP.NET files - there's no telling what might happen. Since all of their files are kept in the path ~/App_Data/files, it made sense to have the custom FTP provider return home directories for each of their websites that point to their files instead of the root folders of their websites.
Prerequisites
The following items are required to complete the steps in this blog:
- The following version of IIS must be installed on your Windows server, and the Internet Information Services (IIS) Manager must also be installed:
- IIS 7.0 must be installed on Windows Server 2008
- IIS 7.5 must be installed on Windows Server 2008 R2
- The FTP 7.5 service must be installed. To install FTP 7.5, follow the instructions in the following topic:
- You must have FTP publishing enabled for a site. To create a new FTP site, follow the instructions in the following topic:
Step 1: Set up the Project Environment
Note: I used Visual Studio 2008 when I created my custom provider and wrote the steps that appear in this blog, although since then I have upgraded to Visual Studio 2010, and I have successfully recompiled my provider using that version. In any event, the steps should be similar whether you are using Visual Studio 2008 or Visual Studio 2010.;-]
In this step, you will create a project inVisual Studio 2008for the demo provider.
- Open MicrosoftVisual Studio 2008.
- Click the File menu, then New, then Project.
- In the New Projectdialog box:
- Choose Visual C# as the project type.
- Choose Class Library as the template.
- Type FtpBlogEngineNetAuthentication as the name of the project.
- Click OK.
- When the project opens, add a reference path to the FTP extensibility library:
- Click Project, and then click FtpBlogEngineNetAuthentication Properties.
- Click the Reference Paths tab.
- Enter the path to the FTP extensibility assembly for your version of Windows, where C: is your operating system drive.
- For Windows Server 2008 and Windows Vista:
- C:\Windows\assembly\GAC_MSIL\Microsoft.Web.FtpServer\7.5.0.0__31bf3856ad364e35
- For Windows Server 2008 R2 and Windows 7:
- C:\Program Files\Reference Assemblies\Microsoft\IIS
- For Windows Server 2008 and Windows Vista:
- Click Add Folder.
- Add a strong name key to the project:
- Click Project, and then click FtpBlogEngineNetAuthentication Properties.
- Click the Signing tab.
- Check the Sign the assembly check box.
- Choose <New...> from the strong key name drop-down box.
- Enter FtpBlogEngineNetAuthenticationKey for the key file name.
- If desired, enter a password for the key file; otherwise, clear the Protect my key file with a password check box.
- Click OK.
- Optional: You can add a custom build event to add the DLL automatically to the Global Assembly Cache (GAC) on your development computer:
- Click Project, and then click FtpBlogEngineNetAuthentication Properties.
- Click the Build Events tab.
- Enter the following in the Post-build event command linedialog box for your version of Visual Studio:
If you have Visual Studio 2008:
net stop ftpsvc call "%VS90COMNTOOLS%\vsvars32.bat">nul gacutil.exe /if "$(TargetPath)" net start ftpsvc
If you have Visual Studio 2010:
net stop ftpsvc call "%VS100COMNTOOLS%\vsvars32.bat">nul gacutil.exe /if "$(TargetPath)" net start ftpsvc
- Save the project.
Step 2: Create the Extensibility Class
In this step, you will implement the logging extensibility interface for the demo provider.
- Add the necessary references to the project:
- Click Project, and then click Add Reference...
- On the .NET tab, click Microsoft.Web.FtpServer.
Note: If Microsoft.Web.FtpServer does not show up on the .NETtab, then use the following steps:- Click the Browse tab.
- Navigate to the reference path where Microsoft.Web.FtpServer.dll is located. (See the paths that were listed earlier in Step #1 for the location.)
- Highlight Microsoft.Web.FtpServer.dll.
- Click OK.
- Repeat the above steps to add the following reference to the project:
- System.Configuration
- Add the code for the authentication class:
In Solution Explorer, double-click the Class1.cs file.
Remove the existing code.
Paste the following code into the editor:
using System; using System.Collections.Specialized; using System.Collections.Generic; using System.Configuration.Provider; using System.IO; using System.Security.Cryptography; using System.Text; using System.Xml; using System.Xml.XPath; using Microsoft.Web.FtpServer; public class FtpBlogEngineNetAuthentication : BaseProvider, IFtpAuthenticationProvider, IFtpRoleProvider, IFtpHomeDirectoryProvider { // Create strings to store the paths to the XML files that store the user and role data. private string _xmlUsersFileName; private string _xmlRolesFileName; // Create a string to store the FTP home directory path. private string _ftpHomeDirectory; // Create a file system watcher object for change notifications. private FileSystemWatcher _xmlFileWatch; // Create a dictionary to hold user data. private Dictionary<string, XmlUserData> _XmlUserData = new Dictionary<string, XmlUserData>( StringComparer.InvariantCultureIgnoreCase); // Override the Initialize method to retrieve the configuration settings. protected override void Initialize(StringDictionary config) { // Retrieve the paths from the configuration dictionary. _xmlUsersFileName = config[@"xmlUsersFileName"]; _xmlRolesFileName = config[@"xmlRolesFileName"]; _ftpHomeDirectory = config[@"ftpHomeDirectory"]; // Test if the path to the users or roles XML file is empty. if ((string.IsNullOrEmpty(_xmlUsersFileName)) || (string.IsNullOrEmpty(_xmlRolesFileName))) { // Throw an exception if the path is missing or empty. throw new ArgumentException(@"Missing xmlUsersFileName or xmlRolesFileName value in configuration."); } else { // Test if the XML files exist. if ((File.Exists(_xmlUsersFileName) == false) || (File.Exists(_xmlRolesFileName) == false)) { // Throw an exception if the file does not exist. throw new ArgumentException(@"The specified XML file does not exist."); } } try { // Create a file system watcher object for the XML file. _xmlFileWatch = new FileSystemWatcher(); // Specify the folder that contains the XML file to watch. _xmlFileWatch.Path = _xmlUsersFileName.Substring(0, _xmlUsersFileName.LastIndexOf(@"\")); // Filter events based on the XML file name. _xmlFileWatch.Filter = @"*.xml"; // Filter change notifications based on last write time and file size. _xmlFileWatch.NotifyFilter = NotifyFilters.LastWrite | NotifyFilters.Size; // Add the event handler. _xmlFileWatch.Changed += new FileSystemEventHandler(this.XmlFileChanged); // Enable change notification events. _xmlFileWatch.EnableRaisingEvents = true; } catch (Exception ex) { // Raise an exception if an error occurs. throw new ProviderException(ex.Message,ex.InnerException); } } // Define the event handler for changes to the XML files. public void XmlFileChanged(object sender, FileSystemEventArgs e) { // Verify that the changed file is one of the XML data files. if ((e.FullPath.Equals(_xmlUsersFileName, StringComparison.OrdinalIgnoreCase)) || (e.FullPath.Equals(_xmlRolesFileName, StringComparison.OrdinalIgnoreCase))) { // Clear the contents of the existing user dictionary. _XmlUserData.Clear(); // Repopulate the user dictionary. ReadXmlDataStore(); } } // Override the Dispose method to dispose of objects. protected override void Dispose(bool IsDisposing) { if (IsDisposing) { _xmlFileWatch.Dispose(); _XmlUserData.Clear(); } } // Define the AuthenticateUser method. bool IFtpAuthenticationProvider.AuthenticateUser( string sessionId, string siteName, string userName, string userPassword, out string canonicalUserName) { // Define the canonical user name. canonicalUserName = userName; // Validate that the user name and password are not empty. if (String.IsNullOrEmpty(userName) || String.IsNullOrEmpty(userPassword)) { // Return false (authentication failed) if either are empty. return false; } else { try { // Retrieve the user/role data from the XML file. ReadXmlDataStore(); // Create a user object. XmlUserData user = null; // Test if the user name is in the dictionary of users. if (_XmlUserData.TryGetValue(userName, out user)) { // Retrieve a sequence of bytes for the password. var passwordBytes = Encoding.UTF8.GetBytes(userPassword); // Retrieve a SHA256 object. using (HashAlgorithm sha256 = new SHA256Managed()) { // Hash the password. sha256.TransformFinalBlock(passwordBytes, 0, passwordBytes.Length); // Convert the hashed password to a Base64 string. string passwordHash = Convert.ToBase64String(sha256.Hash); // Perform a case-insensitive comparison on the password hashes. if (String.Compare(user.Password, passwordHash, true) == 0) { // Return true (authentication succeeded) if the hashed passwords match. return true; } } } } catch (Exception ex) { // Raise an exception if an error occurs. throw new ProviderException(ex.Message,ex.InnerException); } } // Return false (authentication failed) if authentication fails to this point. return false; } // Define the IsUserInRole method. bool IFtpRoleProvider.IsUserInRole( string sessionId, string siteName, string userName, string userRole) { // Validate that the user and role names are not empty. if (String.IsNullOrEmpty(userName) || String.IsNullOrEmpty(userRole)) { // Return false (role lookup failed) if either are empty. return false; } else { try { // Retrieve the user/role data from the XML file. ReadXmlDataStore(); // Create a user object. XmlUserData user = null; // Test if the user name is in the dictionary of users. if (_XmlUserData.TryGetValue(userName, out user)) { // Search for the role in the list. string roleFound = user.Roles.Find(item => item == userRole); // Return true (role lookup succeeded) if the role lookup was successful. if (!String.IsNullOrEmpty(roleFound)) return true; } } catch (Exception ex) { // Raise an exception if an error occurs. throw new ProviderException(ex.Message,ex.InnerException); } } // Return false (role lookup failed) if role lookup fails to this point. return false; } // Define the GetUserHomeDirectoryData method. public string GetUserHomeDirectoryData(string sessionId, string siteName, string userName) { // Test if the path to the home directory is empty. if (string.IsNullOrEmpty(_ftpHomeDirectory)) { // Throw an exception if the path is missing or empty. throw new ArgumentException(@"Missing ftpHomeDirectory value in configuration."); } // Return the path to the home directory. return _ftpHomeDirectory; } // Retrieve the user/role data from the XML files. private void ReadXmlDataStore() { // Lock the provider while the data is retrieved. lock (this) { try { // Test if the dictionary already has data. if (_XmlUserData.Count == 0) { // Create an XML document object and load the user data XML file XPathDocument xmlUsersDocument = GetXPathDocument(_xmlUsersFileName); // Create a navigator object to navigate through the XML file. XPathNavigator xmlNavigator = xmlUsersDocument.CreateNavigator(); // Loop through the users in the XML file. foreach (XPathNavigator userNode in xmlNavigator.Select("/Users/User")) { // Retrieve a user name. string userName = GetInnerText(userNode, @"UserName"); // Retrieve the user's password. string password = GetInnerText(userNode, @"Password"); // Test if the data is empty. if ((String.IsNullOrEmpty(userName) == false) && (String.IsNullOrEmpty(password) == false)) { // Create a user data class. XmlUserData userData = new XmlUserData(password); // Store the user data in the dictionary. _XmlUserData.Add(userName, userData); } } // Create an XML document object and load the role data XML file XPathDocument xmlRolesDocument = GetXPathDocument(_xmlRolesFileName); // Create a navigator object to navigate through the XML file. xmlNavigator = xmlRolesDocument.CreateNavigator(); // Loop through the roles in the XML file. foreach (XPathNavigator roleNode in xmlNavigator.Select(@"/roles/role")) { // Retrieve a role name. string roleName = GetInnerText(roleNode, @"name"); // Loop through the users for the role. foreach (XPathNavigator userNode in roleNode.Select(@"users/user")) { // Retrieve a user name. string userName = userNode.Value; // Create a user object. XmlUserData user = null; // Test if the user name is in the dictionary of users. if (_XmlUserData.TryGetValue(userName, out user)) { // Add the role name for the user. user.Roles.Add(roleName); } } } } } catch (Exception ex) { // Raise an exception if an error occurs. throw new ProviderException(ex.Message,ex.InnerException); } } } // Retrieve an XPathDocument object from a file path. private static XPathDocument GetXPathDocument(string path) { Exception _ex = null; // Specify number of attempts to create an XPathDocument. for (int i = 0; i < 8; ++i) { try { // Create an XPathDocument object and load the user data XML file XPathDocument xPathDocument = new XPathDocument(path); // Return the XPathDocument if successful. return xPathDocument; } catch (Exception ex) { // Save the exception for later. _ex = ex; // Pause for a brief interval. System.Threading.Thread.Sleep(250); } } // Throw the last exception if the function fails to this point. throw new ProviderException(_ex.Message,_ex.InnerException); } // Retrieve data from an XML element. private static string GetInnerText(XPathNavigator xmlNode, string xmlElement) { string xmlText = string.Empty; try { // Test if the XML element exists. if (xmlNode.SelectSingleNode(xmlElement) != null) { // Retrieve the text in the XML element. xmlText = xmlNode.SelectSingleNode(xmlElement).Value.ToString(); } } catch (Exception ex) { // Raise an exception if an error occurs. throw new ProviderException(ex.Message,ex.InnerException); } // Return the element text. return xmlText; } } // Define the user data class. internal class XmlUserData { // Create a private string to hold a user's password. private string _password = string.Empty; // Create a private string array to hold a user's roles. private List<String> _roles = null; // Define the class constructor requiring a user's password. public XmlUserData(string Password) { this.Password = Password; this.Roles = new List<String>(); } // Define the password property. public string Password { get { return _password; } set { try { _password = value; } catch (Exception ex) { throw new ProviderException(ex.Message,ex.InnerException); } } } // Define the roles property. public List<String> Roles { get { return _roles; } set { try { _roles = value; } catch (Exception ex) { throw new ProviderException(ex.Message,ex.InnerException); } } } }
- Save and compile the project.
Note: If you did not use the optional steps to register the assemblies in the GAC, you will need to manually copy the assemblies to your IIS 7 computer and add the assemblies to the GAC using the Gacutil.exe tool. For more information, see the following topic on the Microsoft MSDN Web site:
Step 3: Add the custom FTP provider to IIS
In this step, you will add the provider to your FTP service. These steps obviously assume that you are using BlogEngine.NET on your Default Web Site, but these steps can be easily amended for any other website where BlogEngine.NET is installed.
- Determine the assembly information for the extensibility provider:
- In Windows Explorer, open your "C:\Windows\assembly" path, where C: is your operating system drive.
- Locate the FtpBlogEngineNetAuthentication assembly.
- Right-click the assembly, and then click Properties.
- Copy the Culture value; for example: Neutral.
- Copy the Version number; for example: 1.0.0.0.
- Copy the Public Key Token value; for example: 426f62526f636b73.
- Click Cancel.
- Using the information from the previous steps, add the extensibility provider to the global list of FTP providers and configure the options for the provider:
At the moment there is no user interface that enables you to add properties for a custom authentication module, so you will have to use the following command line:
cd %SystemRoot%\System32\Inetsrv appcmd.exe set config -section:system.ftpServer/providerDefinitions /+"[name='FtpBlogEngineNetAuthentication',type='FtpBlogEngineNetAuthentication,FtpBlogEngineNetAuthentication,version=1.0.0.0,Culture=neutral,PublicKeyToken=426f62526f636b73']" /commit:apphost appcmd.exe set config -section:system.ftpServer/providerDefinitions /+"activation.[name='FtpBlogEngineNetAuthentication']" /commit:apphost appcmd.exe set config -section:system.ftpServer/providerDefinitions /+"activation.[name='FtpBlogEngineNetAuthentication'].[key='xmlUsersFileName',value='C:\inetpub\wwwroot\App_Data\Users.xml']" /commit:apphost appcmd.exe set config -section:system.ftpServer/providerDefinitions /+"activation.[name='FtpBlogEngineNetAuthentication'].[key='xmlRolesFileName',value='C:\inetpub\wwwroot\App_Data\Roles.xml']" /commit:apphost appcmd.exe set config -section:system.ftpServer/providerDefinitions /+"activation.[name='FtpBlogEngineNetAuthentication'].[key='ftpHomeDirectory',value='C:\inetpub\wwwroot\App_Data\files']" /commit:apphost
Note: You will need to update the values for the xmlUsersFileName, xmlRolesFileName, and ftpHomeDirectory settings for your environment.
Step 4: Use the Custom Authentication Provider with your BlogEngine.NET Website
Just like the steps that I listed earlier, these steps assume that you are using BlogEngine.NET on your Default Web Site, but these steps can be easily amended for any other website where BlogEngine.NET is installed.
Add FTP publishing to your BlogEngine.NET website
- In the IIS 7 Manager, in the Connections pane, expand the Sites node in the tree, then highlight the Default Web Site.
- Click Add FTP Publishing in the Actions pane.
- When the Add FTP Site Publishingwizard appears:
- Choose an IP address for your FTP site from the IP Address drop-down, or choose to accept the default selection of "All Unassigned."
- Accept the default port of 21 for the FTP site, or enter a custom TCP/IP port in the Port box.
- Click Next.
- Do no choose any authentication or authorization options for now; you will set those later.
- Click Finish.
- Hit F5 to refresh the view in IIS 7 Manager.
Specify the custom authentication provider for your BlogEngine.NET website
- Double-click FTP Authentication in the main window for your website.
- Click Custom Providers... in the Actions pane.
- Check FtpBlogEngineNetAuthentication in the providers list.
- Click OK.
Add authorization rules for the authentication provider
- Double-click FTP Authorization Rules in the main window for your website.
- Click Add Allow Rule... in the Actions pane.
- You can add either of the following authorization rules:
- For a specific user from your BlogEngine.NET website:
- Select Specified users for the access option.
- Enter a user name that you created in your BlogEngine.NET website.
- For a role or group from your BlogEngine.NET website:
- Select Specified roles or user groups for the access option.
- Enter the role or group name that you created in your BlogEngine.NET website.
- Select Read and/or Write for the Permissions option.
- For a specific user from your BlogEngine.NET website:
- Click OK.
Specify a custom home directory provider for your BlogEngine.NET website
At the moment there is no user interface that enables you to add custom home directory providers, so you will have to use the following command line:
cd %SystemRoot%\System32\Inetsrv appcmd.exe set config -section:system.applicationHost/sites /+"[name='Default Web Site'].ftpServer.customFeatures.providers.[name='FtpBlogEngineNetAuthentication']" /commit:apphost appcmd.exe set config -section:system.applicationHost/sites /"[name='Default Web Site'].ftpServer.userIsolation.mode:Custom" /commit:apphost
Additional Information
To help improve the performance for authentication requests, the FTP service caches the credentials for successful logins for 15 minutes by default. This means that if you change your passwords, this change may not be reflected for the cache duration. To alleviate this, you can disable credential caching for the FTP service. To do so, use the following steps:
Open a command prompt.
Type the following commands:
cd /d "%SystemRoot%\System32\Inetsrv" Appcmd.exe set config -section:system.ftpServer/caching /credentialsCache.enabled:"False" /commit:apphost Net stop FTPSVC Net start FTPSVC
Close the command prompt.
FtpBlogEngineNetAuthentication.zip
Comments
Anonymous
July 01, 2011
This is a great post! I would have never thought to do this, and if someone had asked me if it could easily be done my first reaction would have been probably not wout tons of work. You made it easy, and this is a great feature that would benefit many websites.Anonymous
January 09, 2012
i was able to run IFtpAuthenticationProvider, but IFtpRoleProvider and IFtpHomeDirectoryProvider was not called :(Anonymous
February 07, 2012
Hi Alex, that is usually caused when you are missing the correct configuration settings to enable a particular feature. The home directory provider uses different configuration than authentication, and the following walkthrough lists all of the steps that are required: How to Use Managed Code (C#) to Create a Simple FTP Home Directory Provider learn.iis.net/.../how-to-use-managed-code-c-to-create-a-simple-ftp-home-directory-provider In particular, you need to make sure that you use the steps in "3. Add the custom provider to a site" and "4. Configure user isolation to use a custom provider"Anonymous
December 05, 2013
Great article. Unfortunately, the code is cut off on the right when I view it in Firefox and IE. Is there a way you let us download it?Anonymous
December 05, 2013
Hi Michael Z, I added the C# file as a download - thanks!Anonymous
March 20, 2014
Hi Rob, I want to dynamically add users in IIS FTP Authorization through code, but its not working I tried below code thruough dll class library its not working , but same code is working in a simple console application. Could you please point me if i am doing anything wrong and guide the correct way public class FtpAuthDemo : BaseProvider, IFtpAuthenticationProvider, IFtpLogProvider { protected override void Initialize(StringDictionary config) { using (ServerManager serverManager = new ServerManager()) { Configuration configFile = serverManager.GetApplicationHostConfiguration(); ConfigurationSection authorizationSection = configFile.GetSection("system.ftpServer/security/authorization", "MyCustomFTPSite"); if (authorizationSection != null) { ConfigurationElementCollection authorizationCollection = authorizationSection.GetCollection(); ConfigurationElement addElement = authorizationCollection.CreateElement("add"); addElement["accessType"] = @"Deny"; addElement["users"] = @"*"; addElement["permissions"] = @"Read, Write"; authorizationCollection.Add(addElement); ConfigurationElement addElement1 = authorizationCollection.CreateElement("add"); addElement1["accessType"] = @"Allow"; addElement1["users"] = @"guest"; addElement1["permissions"] = @"Read, Write"; authorizationCollection.Add(addElement1); serverManager.CommitChanges(); } } } }Anonymous
March 20, 2014
Hi, I found the problem, just posting it so as it may help someone. We need to provide Admin rights "Network Services" for folder "C:WindowsSystem32inetsrv" and also set the DefaultApplicationPoolIdentity to NetworkServices. After making this changes i am able to add FTP Authorization users for FTP website in FTP BaseProvider Initialize function. Thanks & Regards AjayAnonymous
March 21, 2014
Thanks, Ajay. While your approach seemed to produce the desired results, that's really not the way that you should do things because you are unnecessarily opening up your security. I'll explain the security problems in a minute, but I need to point out that if you are using IIS 8 or later, you can use IFtpAuthorizationProvider to provide dynamic authorization instead of trying to dynamically create authorization settings in your IIS configuration. See the following article for an example: www.iis.net/.../how-to-use-managed-code-c-to-create-an-ftp-authentication-and-authorization-provider-using-an-xml-database Having said that, I will explain what was happening with the security problems that you were seeing and how best to resolve the situation. You were initially seeing errors with your custom provider because the FTP extensibility process did not have access rights to the ApplicationHost.config file, which is where the authorization settings are physically written. All FTP extensibility runs in a COM+ DLLHOST.EXE process that runs as Network Service by default, which is why granting Network Service access to your C:WindowsSystem32inetsrv folder seemed to resolve the issue. But that unnecessarily opens up your system security because now any processes which run as Network Service can read/write your IIS configuration settings. There are several processes which run as Network Service by default, so any secure information that you have in your IIS settings can be easily accessed by other executables on your system, and this is a bad configuration from a security perspective. I mentioned that all FTP extensibility runs in a COM+ DLLHOST.EXE process which runs as Network Service by default, but you can change that identity, which is what I recommend for your situation. If you take a look at the following blog post, I provided a detailed explanation of the FTP extensibility process and how to change its identity to use a guest account which you create just for FTP extensibility: blogs.msdn.com/.../changing-the-identity-of-the-ftp-extensibility-process.aspx Once you have changed the identity of the FTP extensibility process to your new guest account, you would grant that guest account the necessary permissions for your C:WindowsSystem32inetsrv folder. FWIW - setting the DefaultApplicationPoolIdentity to Network Service or some other account shouldn't be necessary because FTP extensibility and the FTP service are in separate physical processes from a Worker Process that serves an Application Pool. Thanks!