I've read everything on this topic I could find, including MSDN articles and SO posts, but I'm still very lost and confused.
Please answer the following (briefly, if possible):
What is SimpleMembership/SimpleMembershipProvider (WebMatrix.WebData) and what is it/are they responsible for?
What is WebSecurity (WebMatrix.WebData)?
What is the Membership (System.Web.Security) class?
Why does MVC4 create a UserProfile table and a webpages_Membership table? What are they for and what is the difference? What is the UserProfile class that MVC4 creates?
What is the UsersContext class?
How do all of these work together to make user authentication?
These questions then lead into the next problem:
Suppose I have an existing database with users (IDs, Usernames, passwords). I'm creating a new MVC4 application and using Forms Authentication. User passwords are stored in the database in an encrypted form (not bcrypt).
What do I have to do to make it work with MVC4?
Do I have to create a custom MembershipProvider?
As far as I can understand, WebSecurity is a static class (Module) that interacts with a MembershipProvider. A MembershipProvider is a class that explains how particular functions work, such as ValidateUser, CreateUser, ChangePassword.
To solve my problem I assume I need to create a custom MembershipProvider and tell WebSecurity to use my new MembershipProvider.
I have placed a bounty on this question and intend to award it to Andy Brown for an outstanding answer.
See the summaries below each quote for a quick answer, and the paragraphs for detail. Also see the References section at the end for the authoritative sources.
1.What is SimpleMembership/SimpleMembershipProvider (WebMatrix.WebData) and what is it/are they responsible for?
SimpleMembership (a term that covers both the SimpleMembershipProvider and SimpleRoleProvider) is responsible for providing a clean and quick way of implementing an 80 %-there plug and play authentication and authorisation framework with secure password storage, that anyone can use.
2.What is WebSecurity (WebMatrix.WebData)?
WebSecurity is a helper class for common membership tasks that works alongside Membership and OAuthWebSecurity. Roles are still accessed separately through Roles.
3.What is the Membership (System.Web.Security) class?
Membership is a static class from the original ASP.NET membership implementation that manages user settings and operations. Many user operations are still done here rather than repeating them in WebSecurity. They both use the same provider of your choice.
4.Why does MVC4 create a UserProfile table and a webpages_Membership table? What are they for and what is the difference? What is the UserProfile class that MVC4 creates?
The two tables perform different functions. The webpages_Membership schema is controlled by the framework and used for credentials, the UserProfile schema is controlled by us and used for any properties we want to store against a user.
5.What is the UsersContext class?
It is a DbContext (part of the DbContext API) provided as a starting by the MVC Internet Application template. Its only job is to contain the UserProfile class so we can work with it (e.g. through InitializeSimpleMembershipAttribute).
6.How do all of these work together to make user authentication?
This should now be evident from the summaries above and the detail below. Use: WebSecurity for common tasks; UserProfile for custom properties to store against a user, accessed through the UsersContext (in the Visual Studio "MVC Internet Application" template); Membership when WebSecurity or OAuthWebSecurity doesn't have the method; and Roles for roles. Use the VS template's controller to see examples of use.
Edit. In case anyone got this far
Suppose I have an existing database ...
If you have an existing database, and your only reason for writing a custom membership provider is to deal with your legacy password storage method, then you could use a workaround. This will only work if you can move away from your old password storage to the SimpleMembership algorithm (which uses the Rfc2898DeriveBytes class). See the footnote for details.
If you can't move away, then yes you are going to have to create your own provider to use your specific password algorithm, which you can do by deriving from SimpleMembershipProvider.
NOTE: SimpleMembershipProvider will HASH your passwords not ENCRYPT them. If you don't know the difference and why that is important then think twice before doing your own provider with custom security
To understand how it all fits together it helps to understand the history.
SimpleMembershipProvider implements ExtendedMembershipProvider to extend the original provider implementationIt is Open Source on codeplex (mirrored on github). As far as security goes you can therefore assess the code yourself, clone it, change it etc. You should take your own view on the benefits and drawbacks of open source security, and cook that up up with a pinch of NIH. (Personal view: I use it sometimes, I don't use it other times)
ExtendedMembershipProvider in itself adds commands like GeneratePasswordResetToken to the old membership provider apis.
WebSecurity is simply a facade, or helper class, to provide simple access to SimpleMembershipProvider and make common tasks easy and accessible in one place. It is there both to help and because the extension of the original framework through ExtendedMembershipProvider means some of the original classes like Membership aren't enough now. Examples:
WebSecurity.CurrentUserName - gets the name of the currently logged in userWebSecurity.CreateUserAndAccount. Simultaneously create a user and set user profile properties (e.g. WebSecurity.CreateUserAndAccount(userName, pw, new { Email = model.Email });WebSecurity.InitializeDatabaseConnection - Quickly setup a new/existing database for use with membership, choose your user id column and user natural key identifier etc.ResetPassword to reset a user password, GeneratePasswordResetToken and many more These methods generally defer to the provider you are using, they don't just depend on SimpleMembership, and they tie together objects like your provider and Membership to provide a common point to do membership functions.
Note there is also OAuthWebSecurity which is the equivalent of WebSecurity for OAuth authentication.
Membership is from the original implementation; it manages user settings and performs user-related operations using the basic MembershipProvider implementation which ExtendedMembershipProvider now extends. It is a static class, so is available anywhere you declare the namespace, and is therefore an easy way to, for example, retrieve the current user: Membership.GetUser
There is confusion caused by the fact that WebSecurity does some things and not others, and Membership does some things and not others. If you view WebSecurity as a toolkit for higher level operations, and Membership as a toolkit to do things to a user, you'll be ok; they work together on your provider.
webpages_Membership is a table with a fixed schema that we leave alone, and allows the provider to do the basic account operations, mainly storing credentials.UserProfile is a table that we customise to store information against a user account, and have that made available in a strongly typed format through the UserProfile class. webpages_OAuthMembership which does the same job as webpages_Membership, but for OAuth login providers that you want to integrate with.The magic of this setup is that a single user can have a membership login on your own site, and any number of OAuth logins with different providers like google, facebook, and they all share a common profile stored in UserProfile
Generally if a table starts with webpages_, it means there is an API to access it. The UserProfile table is represented by the UserProfile class in your UsersContext (if you use the default MVC Internet Application template). Therefore we access this through the usual methods we would use with any class contained in a DbContext.
UserProfile is very code-first friendly: you can add columns (like the user's Email address), and then set up a migration to include that column in your database on your next release (if you like using migrations). In fact, the UserProfile table does not have to be called that - you can change that using the WebSecurity.InitializeDatabaseConnection call, [Table("UserProfile")] public class UserProfile, and your own migrations.
This is from the MVC Internet Application template provided in Visual Studio New Project. The first thing I do is make sure that it shares a common connection string with my own database context (assuming the membership tables are in the same database). You can change this and decouple them later if you want.
You don't need to have it separate to your own context - that is only necessary if you want to store membership information in a different database now or in the future If you get rid of it you can just change references to UsersContext to your own context, adjusting Database.SetInitializer.
References:
Using SimpleMembership With ASP.NET WebPages - Matthew Osborn - This is the original reference about SimpleMembership and what it is, why it is, and what it does:
MSDN - Introduction to Membership - Membership is still at the core of SimpleMembership, so it helps to understand a bit about it.
WebSecurityOAuthWebSecuritySimpleMembershipProviderExtendedMembershipProviderSimpleRoleProviderMembershipRolesDbContext and the DbContext APIEDIT Footnote: the detail for doing a rolling password upgrade
UserProfile which stores what password version the account is on (e.g. 1 for legacy, 2 for SimpleMembership)ResetPassword then ChangePassword to use the SimpleMembership version, this will update the field to the new password versionUserProfilewebpages_Membership table we aren't meant to touch as you didnt have to write a new custom provider.It is possible to make all this transactional with TransactionScope. The only nasty thing going on is the extra code in the controller, and the coupling to webpages_Membership.