Dks.SimpleToken

Simple and lightweight library for stateless token authorization.

Installation

PM> Install-Package Dks.SimpleToken.Core

This library is targeting both .NET Standard 1.3 and .NET 4.5.
See the .NET Standard Platform Support Matrix for further details.

Documentation

For full documentation and integration possibilities please consult the project Wiki

Typical scenario:

This library was primarily born to handle authorization and access-control of uncoupled services that reside on different machines.

The typical scenario is the same of Amazon S3 or Azure Blob Storage, in which files and blobs are stored inside a completely different service and authorization must be handled using a secure token. This token is usually generated by the main web site or service, it has short lifetime and contains enough information for the resource server to fully authorize the request.

+----------+                                   +------------+
|   User   |    requests access to resource    | API Server |
|          |  +----------------------------->  |            |
|          |                                   |            |
|          |                                   | Generates  |
|          |        returns secure token       |   Token    |
|          |  <-----------------------------+  |            |
|          |                                   |            |
|          |                                   +------------+
| Requires |
|  access  |
|   to a   |                                 +-----------------+
| resource |       sends secure token        | Resource Server |
|          |  +--------------------------->  |                 |
|          |                                 |                 |
|          |                                 |    Validates    |
|          |                                 |      Token      |
|          |       returns the resource      |                 |
|          |  <---------------------------+  |                 |
+----------+                                 +-----------------+

With this library you may generate a secure encrypted token (by default protected using AES algorithm with a key shared between two services or machines) with custom data embedded inside it. This will ensure a stateless and freely scalable approach.

Notes

The core library contains abstractions and default implementations for generating and validating Secure Tokens protected with AES encryption and serialized as JSON.

Other packages extend the functionalities and integrate the library with other frameworks:

• Dks.SimpleToken.Serializers.Protobuf
  Google Protobuf token serialization (which greatly reduces token size).

• Dks.SimpleToken.SystemWeb
  Adds implementations for token encryption and serialization using native System.Web methods like MachineKey and FormsAuthenticationTicket.

• Dks.SimpleToken.Validation.MVC6
  Integrates Dks.SimpleToken with ASP .NET Core MVC 6 using ActionFilters. Retrives and validates tokens inside an HTTP header or in a query string parameter.

• Dks.SimpleToken.Validation.MVC5
  Integrates Dks.SimpleToken with ASP .NET MVC 5 using ActionFilters. Retrives and validates tokens inside an HTTP header or in a query string parameter.

• Dks.SimpleToken.Validation.WebAPI
  Integrates Dks.SimpleToken with ASP .NET Web API 2 using ActionFilters. Retrives and validates tokens inside an HTTP header or in a query string parameter.

Example Usage

Create a new ISecureTokenProvider instance with default settings (AES + Json):

// AES configuration using default values for key size and encryption modes
var config = new AESEncryptionConfiguration("3q2+796tvu/erb7v3q2+796tvu/erb7v3q2+796tvu8="); // example key DO NOT USE IN PRODUCTION

var provider = DefaultTokenProvider.Create(config);

Create a new DefaultTokenProvider using custom encryption and serialization:

// must provide to the constructor custom ISecureTokenSerializer and ISecureTokenProtector instances
var provider = new DefaultTokenProvider(serializer, protector);

Generate a Secure Token string with 5 minutes expiration and custom user data:

var userData =  new Dictionary<string, string> {
    { "Foo", "bar"}
};
var token = provider.GenerateToken(userData, 300);
// or using the extension method that accepts an object
var token = provider.GenerateToken(new { Foo = "bar" }, 300);

Validate a Secure Token string and extract custom user data:

var validated = provider.ValidateAndGetData(token);
// this will throw SecurityException if invalid or expired

var fooData = validated.Data["Foo"];
// fooData now contains "bar"

How to generate a new AES key:

The default ISecureTokenProtector will accept a standard AES key in Base64 format.

Please DO NOT USE THE KEY PROVIDED IN THE EXAMPLES as it is no secret at all.

You may generate a new key in C# using the following code:

string key;
using(var aes = System.Security.Cryptography.Aes.Create())
{
    // set the following parameters to what you will use inside
    // AESEncryptionConfiguration:
    aes.Mode = CipherMode.CBC; // this is the default mode
    aes.KeySize = 256; // this is the default size

    // generate the key
    aes.GenerateKey();

    // convert to Base 64
    key = Convert.ToBase64String(aes.Key);
}
// now key contains a base 64 encoded key ready for AESEncryptionConfiguration

Store this key in a secure place for both the token generating service and the token validation service. Typically you would store the key inside the Web.config file (better if in encrypted format), a json configuration file for ASP.NET Core or using Azure Key Vault and similar services.

License

This library is provided free of charge, under the terms of the MIT license.

Default AES encryption was inspired by Simple AES available under the MIT license.

Default JSON Serialization is provided by SimpleJson available under the MIT license.