The ASP.NET Identity System is a new collection of software components for supporting authourization and authentication within ASP.NET applications. It provides significant improvements over the previous ASP.NET Membership and Simple Membership and aims to make it easier support non-relational backing stores, such as Couchbase Server. In addition to authentication and authorization it provides profile store, role and claims-based authorization, support for social logins such as Facebook and Twitter and OWIN support…it no longer depends upon the System.Web namespace.
The Couchbase ASP.NET Identity Provider aims to be a “full-fledged” provider supporting nearly all if not all of the features of the ASP.NET Identity API. In this Developer Preview (DP) only the authentication portion has been tested; in subsequent releases role and claims-based authorization will be added as well integration with 3rd party social media providers via Single Sign-On (SSO), in addition to features such as SMS and Email Two-Factor Authentication. In this post
we will show you how to integrate the Couchbase ASP.NET Identity Provider DP with an ASP.NET MVC Web Application.
Getting Started
The package is available on NuGet or you can build it yourself from the repository on Github which is found here. For this blog we will use the packages published through NuGet.
Using Visual Studio 2013 (or perhaps 2015), create a new MVC Web Application as follows:
You can name it whatever you like; I called it CouchbaseIdentity. Click “OK” and then select MVC in the next dialog.
Click “OK” again and Visual Studio will create the MVC project for you. By default, Visual Studio will use the Entity Framework Identity Provider. Since we want to use the Couchbase Identity Provider, we need to remove the package dependency on the Entity Framework provider, add reference to Couchbase Identity package and then replace all references to using Microsoft.AspNet.Identity.EntityFramework; with Couchbase.AspNet.Identity.
To change the package dependency, open the NuGet Package Manager and locate the Microsoft ASP.NET Identity EntityFramework package and uninstall it:
You will have to restart Visual Studio at this point. Then switch to the “Online” tab and change the dropdown to “Include Prerelease” and type “couchbase” into the search text box:
Select the Couchbase ASP.NET Identity and click “Install” and “Close” to close the dialog.
Updating the Package Dependencies
Now that you have swapped the default Entity Framework Identity Provider packages and replaced it with the Couchbase ASP.NET Identity dependencies and package, you need to update the project to use the new provider.
First, go through and replace every reference to using Microsoft.AspNet.Identity.EntityFramework; with using Couchbase.AspNet.Identity;. The easiest way to do this is a simple search and replace (Ctrl F).
Then in IdentityModels.cs, change the ApplicationDbContext class to derive from ThrowableBucket instead of IdentityDbContext and then override the base constructor so that the Bucket that you chose to store your Identity information is passed in. I chose to store my Identity information in the “default” bucket; you could create a separate bucket if you chose to:
Note the “ThrowableBucket” is a wrapper around some the CouchbaseBucket CRUD methods that changes the behavior of the SDK slightly; operation failures are thrown. In future versions, this may change!
Finally, open the Global.asax file and add the code to initialize the Couchbase SDK, which the Couchbase ASP.NET Identity Provider uses:
The ClusterHelper is a helper class for the Couchbase .NET SDK which makes it easy to manage buckets and references. It’s recommended that you initialize the ClusterHelper in Application_Start and close it in Application_End. Once you have completed this step, the web application is ready to use Couchbase as a backing store for identity and profiles!
Testing it out!
Once you have completed the steps above, you can test the integration by running the application (right click>debug=>Start new instance) and navigating to the register page:
Fill in your email, password and confirm you password, then click “Register”.
Assuming all went well you should be redirected back to the home page and you should see a “Hello ….” message. You are now authenticated!
How the Profile is Modeled in Couchbase
The default identity provider is based upon a series of relational tables with foreign keys linking the data together. The Couchbase ASP.NET Provider takes the NoSQL approach and stores the data as JSON documents and uses “manual indexes” for secondary indexes in cases where the key to fetch the data is not a primary index.
The primary document has the following structure:
It’s a fairly simple document; in nearly all cases we use “embedding” to store relationships such as Roles and Claims (we will go over these in a later blog post!). To perform a lookup against a field within this document, we create a second, binary document which associates the email address of the profile with the primary key (914dc..); this is similar to a modeling concept called “referring”.
We could have used N1QL queries which would make the “manual” secondary indexes obsolete, but the intention is to support Couchbase Server 3.0 and greater; N1QL will be a feature of Couchbase Server 4.0 which will be released later this year.
How to get it:
The Couchbase ASP.NET Identity Provider is available as a package on NuGet or can be built directly from source using the Github reposotory. If you wish to contribute, pull requests are always welcome. If you find a bug, you can create a Jira ticket and you will be notifed about its current status.
- Github: https://github.com/couchbaselabs/couchbase-aspnet-identity
- NuGet: https://www.nuget.org/packages/CouchbaseIdentity/1.0.0-dp
- Jira: https://issues.couchbase.com/browse/CBASP
