How do I use my own database with SimpleMembership and WebSecurity? What is MVC4 security all about?

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.

Summaries

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

Detail

1.What is SimpleMembership/SimpleMembershipProvider

To understand how it all fits together it helps to understand the history.

• ASP.NET in 2005 introduced the ASP.NET Membership system
• This system used providers to abstract away implementation details from common interfaces used to manage accounts and roles etc.
• It also gave us a basic "user profile" capability (stored in a single column xml field which people therefore tended to avoid)
• SimpleMembership was released into the world in 2010 ish as a provider that plugs in to the ASP.NET membership system, but also allows for OAuth authentication, and property-per-column user profile storage (instead of the single column storage used in the original implementation).
• SimpleMembershipProvider implements ExtendedMembershipProvider to extend the original provider implementation

It 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.

2.What is WebSecurity (WebMatrix.WebData)?

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 user
• WebSecurity.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.

3.What is the Membership (System.Web.Security) class?

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.

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?

• 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.
• There is an extra table called 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.

5.What is the UsersContext class?

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.

• codeplex source (mirrored on github).
• WebSecurity
• OAuthWebSecurity
• SimpleMembershipProvider
• ExtendedMembershipProvider
• SimpleRoleProvider
• Membership
• Roles
• DbContext and the DbContext API

EDIT Footnote: the detail for doing a rolling password upgrade

• Add a property to UserProfile which stores what password version the account is on (e.g. 1 for legacy, 2 for SimpleMembership)
• In the "Login" Action, write code so that:
  • If they are on your SimpleMembership password version, you do a normal login
  • If they are on the legacy password version, you:
    • check it using your old method
    • if it is correct you reset it using ResetPassword then ChangePassword to use the SimpleMembership version, this will update the field to the new password version
    • and finally update the Password version on the UserProfile
• Update any other AccountsController methods that use password in a similar way.
• Live with the hacky workaround and coupling to the webpages_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.