NancyFX: Stateless Auth Example

An Update...

Some time ago, I did an example of using JWTs with Nancy. This post is an update to that. It shows a lighter way of consuming JWTs with a Nancy service. The example solution is hosted on Github.

This example uses the following libraries:

• Nancy
• Nancy.Hosting.Aspnet
• Nancy.Authentication.Stateless
• JWT.

The test project adds the following libraries:

• FakeItEasy
• NBuilder
• FluentAssertions
• Nancy.Testing

A Word on JWTs

JWTs are one of the token formats that are quite common today. The jwt.io site has a pretty good introductory page on them. The short story is they are a compact way to securely move information between parties (to paraphrase the jwt.io site).

The Bootstrap Class

I'll start with the Nancy Bootstrap class. This class initializes the stateless authentication when the application is started. It gets an instance of the stateless authentication configuration, and enables it with a call to StatelessAuthentication.Enable(pipelines, configuration);.

Verifying The Token

The StatelessAuthConfigurationFactory returns a configuration used in the previous step. It contains the steps used to verify the JWT is valid. This is done by ensuring the issuer and audience are correct, checking if the token has expired, and if the user is valid.

Securing the Endpoint

The last bit part of the process is securing the endpoint(s). Nancy has a number of extension methods to help with this. The Health module will respond to any call with an OK status. It's not a great way to report the health of a service, but it demonstrates the idea.

The Secure module demonstrates a few ways to use the extension methods. What's really cool is the requirements can be placed at the module level as well as the endpoint level. There are two endpoints in the example: /secure and /needsclaim. Both endpoints require the call use SSL and be made with a valid JWT. The /needsclaim endpoint further requires the authenticated user be an administrator.

The End

That's the basics for getting started with stateless authentication and Nancy.

Nancy Authentication with Owin and JWT

A huge part of this stuff is based upon blog posts by Jonathan Channon and Mike Hadlow.

It took me a bit of time to figure out all the working bits to building something atop Nancy using JWT for authentication. I decided to create an example app that could be used as a reference when I need to do this again. This isn't a tutorial. It's the descriptions of all the different moving parts.

The app has a very basic SPA, some RESTful endpoints, and basic unit tests. This particular app is setup for ASP.NET hosting (handy for hosting it in Azure).

The example app is on GitHub.

Solution Layout

The solution consists of two projects: NancyAspNetOwin.WebApp and NancyAspNetOwin.WebApp.UnitTests. The App directory contains all the files which comprise the SPA front-end. The Authentication directory houses the C# classes which support the token authentication. It also includes the Nancy Module which provides the endpoints that support authentication. Content, fonts, and Scripts all hold the plumbing bits such as Bootstrapper, KnockoutJS, etc. MyBootstrapper.cs and Startup.cs wire up the Nancy and Owin bits. index.html and IndexModule.cs are the kick off point.

Setting Things Up

There are a boat load of NuGet packages which need to be added when starting from an empty web application project. Some are the Nancy/Owin related stuff for the back-end. Others support the front-end SPA stuff. For this app, there were a few other things I dropped.

Nancy/Owin NuGet Packages:

• JWT
• Microsoft.Owin
• Microsoft.Owin.Host.SystemWeb
• Nancy
• Nancy.Hosting.Aspnet
• Nancy.Owin
• OWIN
• Owin.StatelessAuth

SPA NuGet Packages:

• Bootstrap CSS
• KnockoutJS
• RequireJS
• Require.JS.Text

Other Bits:

• login.css - Pulled from bootsnip.com.
• form.css

The web.config file needs to be updated. The system.web and system.webServer sections need things for Nancy. An appSettings entry is created for the OWIN middleware.

You'll also want to set the project to use HTTPS.

The Workflow

The flow for this app is pretty simple. A login form is displayed when first landing on the home page. When the credentials are entered, a token is retrieved from the login endpoint. This token is then used to pull the greeting from the secure endpoint.

Startup Code

There are two files running the show here: Startup.cs and MyBootstrapper.cs. Startup.cs has the Owin stuff. The pathsToIgnore variable contains all the routes we want exempted from the token-based security. These paths, along with an instance of the SecureTokenValidator class are passed into the RequiresStatelessAuth() method.



MyBootstrapper has two overrides. The RequestStartup() override contains the glue for the Owin stuff. The ConfigureConventions() override tells Nancy about the other directories that hold static content (JavaScript files, CSS files, etc.).


The Client UI

The UI implementation starts with the index.html file. Its layout was pulled from a template site. The rest of the client app is housed within the App folder. It contains the two knockout components, the config for RequireJS (config.js), and the basic application view model (myapp.js).

The index.html and myapp.js files act as the main view/view model for the app. index.html contains the markup, CSS file references, and script file references. myapp.js has the data bindings used by the app.

Each component is split into three files. These three files contain the HTML which serves as the view, the JavaScript view model, and code to register the component in Knockout.

The login component view (login-control.html) is a basic html file.


The login component view model (login-control.js) is a little more interesting. The params are come from a data binding on the index.html page. If a token is returned the page adds the token to future headers, raises an event, and hides the form. This is the spot you could store the token in a cookie or something.


The login component registration (login-control-register.js) tells Knockout what files to use to display the component. Pay attention to the template property. The use of "text!" lets RequireJS know that the file isn't a code file.


The Service Stuff

Nancy supports a number of view engines, routing definitions, etc. The NancyModule is quite capable of returning views, exposing RESTful endpoints, etc. Each module can support different authentication requirements.

IndexModule.cs is a NancyModule with two endpoints: /, and ./health. Both require an https call. /health requires that the caller supply a valid token in the request header. The RequiresAuthentication() method uses the ClaimsPrincipal data created by the SecureTokenValidator class.


The SecureTokenValidator class (lifted from here) verifies that the token provided in a request is valid. It also converts the token into the ClaimsPrincipal object used by Nancy. It's interesting to note that I've seen two variations on this class. Both have noted that the token does not directly decode to a set of claims.



Testing Notes

Nancy was designed to be very testable. There's the Nancy.Testing package goes a long way to helping with that. The Nancy documentation does a good job of explaining how to test your Nancy app. Testing Nancy with OWIN is a little more involved. You'll need the Microsoft.Owin.Testing package. OwinTests.cs in the test project gives an example of how those tests are done.

In Closing

That's all I have so far. Hopefully, this will help some other people who are trying to work through these issues.

NancyFX Notes: Static Content

NancyFX Notes

This is part of a set of articles that are my developer notes for working with Nancy. Taken from the Nancy introduction, "Nancy is a lightweight, low-ceremony, framework for building HTTP based services on .Net and Mono." It's (she's?) great for building microservices and other things.

Static Content

Static content are files like images, JavaScript files, css files, etc. Nancy automatically supports static files which are placed in the Content directory. The example on GitHub has custom directories for the 3rd-party scripts and the application-specific scripts. These are Scripts and App directories.

Other directories can be included by adding to NancyConventions.StaticContentConventions property. Do this by overriding the ConfigureConventions method in your bootstrapper.



The shot from Fiddler below shows a before and after. The calls from 5-8 were made before the additions to the bootstrapper. The later calls show that the changes enabled Nancy hosting the files in those directories.