The Hybrid Provider Installer

It's finally up on CodePlex! Get it here.

The installer is pretty straight forward. I wanted to do an MSI, but there would be so much customization of the UI and so many custom actions that it would actually be easier to just write it from scratch. So I did. Also, it was an excuse to start coding some WPF.

The home page of this CodePlex project calls out everything you will need to know pre- and post-installation. I just wanted to formally write up a quick doc on the UI so you have some during-installation guidance.

I preset as many of the options as possible. Once you install the Hybrid Provider the first time, the settings are saved in isolated storage. So when you go to use this installer to remove the Hybrid Provider, (why ever you would do such a thing is baffling…except for an update of course) it’ll pick your settings back up.

Here’s what it looks like:

I’ll just go field by field, button by button, and explain each. If you see “[Configurable]” in an explanation, that means that this value is stored in the web.config, and you can change it post-installation. All textbox fields are required except for “SQL Account Password Strength Regular Expression.” “SQL Account Password Minimum Length” and “SQL Account Password Minimum Number Of Non-Alphanumeric Characters” must be non-negative integers.

• Site URL – This is the URL of the web app you want to install the Hybrid Provider on. The SharePoint Feature that does all of the work (the installer just copies files then uses stsadm to install and activate the Feature) is set to the “WebApplication” scope, so type in URL of that web app. All site collections under it will then use this authentication mechanism. Note that the Hybrid Provider is also installed (but not used; it’s still Windows Auth) on the Central Admin web app, so that you can choose site collection administrators.
• SharePoint Installation Path – You can probably leave this one alone. I didn’t have time to dig into the API and see if I could infer this. (And I mean it; it’s not a cop-out! The first working version on this installer used to have like ten more fields that I’ve since been able to infer!) I use this to know where to copy the Feature files. Future versions of the installer will use a Solution anyways, so this’ll probably go away.
• SQL Account Password Minimum Length – [Configurable] – Just like it sounds. The ASP.NET CreateUserWizard control will pick this setting up.
• SQL Account Password Minimum Number Of Non-Alphanumeric Characters – [Configurable] – Just like it sounds. The create user control will also pick this setting up.
• SQL Account Password Retrieval Enabled – [Configurable] – This was a pain in the ass to figure out. I hard-code in “Encrypted” for the password type for SQL accounts, since the other two options, “Clear Text” and “Hashed,” are not at all useful. Clear Text is a security nightmare, and Hashed passwords can never be retrieved since they are encrypted one-way. Read more about that here.  Basically, this allows you to turn this feature on and off. If it’s off, the ASP.NET PasswordRecovery control will throw an exception.
• SQL Account Password Reset Enabled – [Configurable] – Okay, so I leverage the ASP.NET login controls A LOT. (And so should you; they are very flexible and customizable and there’s no reason to need to rewrite them.) Similar to the above features: you can turn on and off the ability for an admin to send a new randomly-generated password to a user.
• SQL Account Requires Unique Email – [Configurable] – Just like it sounds. The CreateUserWizard control will pick this setting up, and throw an exception if you try to create a user with an Email that’s already in the database.
• SQL Account Requires Question And Answer - [Configurable] – If this is true, the CreateUserWizard control will show two additional textboxes for question and answer. Otherwise, nulls are allowed in the database for these two fields.
• SQL Account Password Strength Regular Expression – [Configurable] – A string of RegEx that the create user control will test the password against. I personally think it’s overkill, and it’s not required.
• AD Domain Name – [Configurable] – I pre-populate this field with System.Environment.UserDomainName to try and save you some typing.
• AD Administrative Account Name – [Configurable] – Also loaded from System.Environment, this is the UserName of the current user, and will be the account the Hybrid Provider will use to talk to AD. This works best when this account matches the account running the SharePoint IIS app pool of the site you’re installing on. However, it doesn’t have to. And by no means does this need to be something like the domain controller account! Technically any account with read only access to AD will work, since the Hybrid Provider (currently) isn’t designed to update AD.
• AD Administrative Account Password – [Configurable] – The last part of the AD credentials.
• SQL Connection String – [Configurable] – This is the connection string to the ASPNET database. Feel free to use Windows or SQL auth; Windows auth is more secure; SQL auth doesn’t require the account running the IIS app pool for this site to have permissions on the database.
• AD Connection String – [Configurable] – The LDAP (which is CaSe SeNsItIvE) path to your AD.
• Test SharePoint Settings – This button uses the “Server URL” field and passes it to the constructor of an SPSite object. I then open the RootWeb of the site, and get the name. Note that this SharePoint code runs under the context of the currently-logged in user, not the account you specify for the AD credential settings. Again, things work best when they are all the same.
• Test SQL Settings – All I do is pass this string to a SqlConnection object, and attempt to open the connection.
• Test AD Settings –You’ll get a decent error message from System.DirectoryServices if you botch the username, password, or LDAP connection string. However, I don’t trust it 100%. The one case I saw this fail is when I was working at home with my VPN disconnected. (And by “disconnected” I mean “MY ISP SUCKS!”) I work on a domain laptop, so my AD credentials were cached, and I think that was good enough for this AD connection test, which was successful. However, I couldn’t log in to a SharePoint site running locally on my box via the Hybrid Provider wired up to my company’s AD. But once I figured out my VPN, it started working. I’m sure there’s more to this… Regardless, as long as you run this from the SharePoint server, you should be fine.

That’s the UI! Once you enter everything in, click “Install.” This will copy files, GAC assemblies, and kick off stsadm commands. Below is an example of the output you’ll get (hopefully all successes like mine!) so you can debug if necessary.

One of these files is a generic login control that I’ve tweaked just a bit (and I leave up to you to customize), which needs some more discussion.

When you set up a forms-based authentication provider in SharePoint’s Central Admin, (which I do for you) you have the option to “Enable Client Integration.” This is OFF by default, and there’s even a little message dissuading you from turning it on. The message then goes on to say that users will then have to edit documents offline and then upload them.

Well that’s horse poop. I enable the hell out of client integration! All you have to do to get it to work is make sure users check the “Remember Me” box on the login control. This creates a cookie that not only lets SharePoint remember them, but also allows Office to communicate with SharePoint and work the same as though they were communicating through AD.

This is just fine from the SharePoint side, since there’s “Sign in as Different User” and “Sign Out” right there in the Welcome menu atop all SharePoint pages. In other words, this doesn’t affect SharePoint’s usability at all. So I configured the control to check this box by default, and added a bit of JavaScript to hide it so users don’t have to worry about it. I'll be writing more about using the ASP.NET login controls with the Hybrid Provider.

That’s all! Have fun, and please feel free to Email me with any questions!