Intro

JWT (JSON Web Token) becomes more and more popular as a standard for securing web sites, and REST services. I discuss how you can implement JWT security for both a REST service and a MVC web application all build with .Net Core. I divided the JWT security in 3 blogs

1. Create JWT
2. Secure REST service with JWT
3. Secure web application with JWT

This is the first of the three blogs and I start with a small JWT explanation.

JWT Primer

JWT (JSON Web Tokens) is open, security protocol for securely exchanging claims between 2 parties. A server generates or issues a token and is signed by a secret key. The client also knows the secret key and the key and can verify if the token is genuine. The token contains claims for authentication and authorization. Authentication is simply the verification if someone is really who he claims to be be. Authorization is when an user is granted to access a resource or execute a certain task. For example user A can view payments and user B can execute payments. JWT are self contained. Because JWT is a protocol and not a framework it works across different languages like .net , Java Python and many more. The JWT is usually transmitted by adding the JWT to the header of the request but can also be used as a parameter in an URL. This transmission makes the JWT stateless.

JWT Structure

JWT has three parts:

1. Header
2. Payload
3. Signature

The parts are separated with a dot.

aaaa.bbbb.cccc

Header

The header and the payload has one or more key value pairs. The header contains the token type ('typ') and the hashing algorithm ('alg') SHA256.

The Header and the Payload parts are base64 encoded, this makes the Header part:

Payload

The payload part is the most interesting section because it contains all the claims. There are three claims types Registered, Public and Private claims.

Registered Claims

The registered claims are part of the JWT standard and have the same purpose on all implementations. In order to keep the JWT size small the key is always 3 characters long. Here's the short list:

• iss Issuer Identifies who issued the JWT.
• sub Subject Identifies the principal (read user) of the JWT.
• aud Audience Identifies recipients the JWT is intended for.
• exp Expiration Sets the expiration date and when expired the JWT must be refused.
• nbf Not before. Sets the date before the JWT may not be used.
• iat Issued at. Sets the date when the JWT was created.
• jti Unique identifier for the JWT. Use for a one time token and prevent token replay.

All registered claims dates are in the Unix Epoch date format and describe the seconds after UTC time 1 January 1970.

Public Claims

Public claims contain more general information for example 'name'. Public names are also registered to prevent collision with other claims.

Private Claims

A private claim is agreed between issuer and audience. Always check if a private claim does not collide with existing claims. The claim 'role' is private claim example we will use later on.

Payload Example

will result in

Signature

So far there was nothing secure about a JWT. All data is base64 encoded and although not human readable it's easy to decode it into a readable text. This where the signature comes in. With the signature we can verify if the JWT is genuine and has not been tampered. The signature is calculated from the Header, the Payload and a secret key.

The secret key is symmetric and is known to issuer and client. Needless to say, be care full where you store the secret key!

Put it all together

The screen dump below is constructed with help from https://jwt.io/ where you can test and debug JWT claims. The left pane holds the JWT and the other pane shows the extracted Header and Payload. If you add the secret key the page also verifies the signature.

General JWT Security Overview

The solution overview shows three separate servers, the Web application, the RESTful service and the JWT issuer server. They could be hosted in one server and in one project but I made three items for it. In this way it's much more clear how each server is configured. Because JWT is self contained there no need for some kind of connection between the JWT issuer and the REST service to validate the JWT claim.

General JWT Flow

The basic JWT flow is quite simple:

• The user enters the login credentials on the web application.
• The web application send the login credentials to JWT issuer and ask for a JWT claim.
• JWT issuer validates login credentials with user database.
• JWT issuers creates JWT based on claims and roles from user database and add the 'exp' (Expires) claim for limited lifetime (30 minutes).
• JWT issuer sends the JWT to web application.
• Web application receives JWT and stores it in an authentication cookie.
• Web application verifies JWT and parses payload for authentication and authorization.
• Web application adds JWT to REST service calls.

Pros and cons

Pros:

• Comparatively simple. Security is never easy, what ever you choose. JWT is a smart design and combined with the .net libraries who do the 'hard' work makes JWT relative easy to implement.
• REST service is truly stateless as it supposed to be. In most cases security adds some kind of session management for authentication.
• Stateless makes scalable. If you need more servers to handle the workload there is no need to shares sessions among all the servers. This makes scaling easier and less error prone.
• Useable across different services. JWT are self contained and the service can authorize without having access to the user database.
• JWT provides neat options for temporary authorization elevation. Claims can be added or removed during an user session. For example you can add a claim to a user that he successfully passed a two way authentication for executing a payment. The claim can be removed when the payment is successfully executed. In this manner there's no need to create special way for tracking the user status.

Cons:

• JWT has no build in features for sliding expirations, although you can build it your self.
• The Secret key is very important. If the secret key is somehow stolen or leaked the security is heavily compromised.

Create JWT Issuer project

The main task is to deliver JWT claims based on user credentials. The project is a standard MVC application with Individual User Accounts as Authentication.

The Individual User Accounts Authentication is used to secure the website and having easy access to users and their roles and claims. I added the package Microsoft.AspNetCore.Authentication.JwtBearer for the actual JWT creation. Because JWT is not used to secure this web site caller there is no need to register JwtBearer services during start up. Only the JWT parameters are configured during start up.

The DI (Dependency Injection) pattern is applied for the configuration. The class JwtIssuerSettings maps to the config section JwtIssuerSettings in appsettings.json and the class JwtIssuerFactory creates and instance of IJwtIssuerOptions interface.

They are added to the service collection and are now available as parameters in controller constructor.

Create JWT Claim

The function Login on controller JwtIssuerController creates the JWT claim. The process is pretty straight forward:

• Find the user.
• Check password.
• Create Issuer, Subject, Email, Unique Id and IssuedAt claims.
• Collect user roles (claims) from storage
• Create JWT based on configuration parameters and secret key.
• Send token to caller

Test Data

During startup an in-memory database is created. It contains three users and three roles and mimics an Human Resource department.

Roles:

• Employee this can be any company member.
• HR-Worker, every HR department member.
• HR-Manager, sure it's the HR-boss.

Users:

• employee@xyz.com
• hrworker@xyz.com
• hrmanager@xyz.com

Namespace Microsoft.AspNetCore.Identity contains RoleManager<IdentityRole> and is ready to use without explicit configuration. You don't read much about it in examples or documentation. It's a bit of a missed chance because the class is really useful for managing the roles in the system.

Testing JWT claim

I added Swagger by adding package Swashbuckle.AspNetCore for testing. You can read here more how to configure swagger. In short it comes to this

Swagger can now be tested at http://localhost:49842/swagger/

We can test the response at https://jwt.io/

and all looks fine and we can start securing the REST service.

Visual Studio Startup Projects

Sometimes the Visual Studio startup Project is lost and prevent running the application. Right click on the solution and choose 'Set Startup Projects..'

And repair the startup setting:

Conclusion

This blog demonstrates how you can setup a JWT (JSON Web Token) issuer. Stateless, self contained, scalable and other features makes JWT a smart design. With help from packages integrates JWT well with .Net Core and takes little effort to setup.

Next post : JWT Security Part 2, Secure REST service

Further reading

Versions

1.0 2017-08-31 Initial release

1.1 2017-09-05 Source Code upgraded for Dot Net Core 2.0