Home

Dks.SimpleToken

How to:

• Integrate with ASP.NET Core MVC 6
• Integrate with ASP.NET MVC 5
• Integrate with ASP.NET Web API 2
• Serialize tokens using Protobuf instead of Json
• [[Protect tokens using System.Web utilities like MachineKey and FormsAuthenticationTicket|Utilities: System.Web]]
• Generate a new random AES key

Quick Start

How to quickly use Dks.SimpleToken for token generation and validation

Installation

PM> Install-Package Dks.SimpleToken.Core

Authorization Server

var config = new AESEncryptionConfiguration("my-secret-key");
var provider = DefaultSecureTokenProvider.Create(config);

var token = provider.GenerateToken(new { UserId = 12 }, 120); // token will expire in 120 seconds
// return token to user

Resource server

var config = new AESEncryptionConfiguration("my-secret-key");
var provider = DefaultSecureTokenProvider.Create(config);

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

if(validated.Data["UserId"] != "12")
{
    // token data does not match! return error
    throw new SecurityException("Data does not match!");
}
// user is allowed to proceed, return resource.

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.

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"

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.