JSON Web Tokens and the new JWTSecurityTokenHandler class

Last week, Vittorio Bertocci announced the developer preview of the new JWT Security Token Handler, which provides support for a important piece of the modern identity and access control management puzzle.

What are security tokens?

In the context of the claims model, a security token is an interoperable  container of security-related information, typically identity claims, securely packaged for communication between two or more parties. This packaging ensures properties such as:

• Confidentiality – only the authorized receiver should be able to access the contained information
• Integrity – the authorized receiver should be able to detect any modifications to token, while in transit between the two parties.

On Web Single-Sign On protocols, security tokens are used to securely transport the identity information from the identity provider to the identity consumer. On a delegated authorization protocol, such as OAuth 2.0, security tokens can be used to convey the authorization information from the client to the resource server.

For instance, the SAML (Security Assertion Markup Language) assertion is an example of a very popular token format, used by  Single-Sign On protocols such as: Shibboleth, the SAML protocols and WS-Federation. SAML assertions are XML-based and use the XML Digital Signature and XML Encryption standards for providing integrity and confidentiality.

What is JWT?

JWT stands for  JSON Web Token, and is a new format for packing and protecting security information. It is based on the JSON (JavaScript Object Notation) syntax and aims to be usable in “space constrained environments such as HTTP Authorization headers and URI query parameters”.

The following example (taken from the spec), represents a unprotected token (line breaks added for display purposes)

eyJhbGciOiJub25lIn0
.
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ

 

The encoded token is composed by a sequence of parts, separated by the ‘.’ character. Each part is the base64url encoding of an octet stream. In this example, both octet stream result from the UTF-8 encoding of JSON objects. The first object (encoded in the first part) is the JWT header

{“alg”:”none”}

The header defines the token cryptographic protection, which is ‘none’ in this case.

The second object (encoded in the second part) is the JWT Claims Set

{“iss”:”joe”,

“exp”:1300819380,

“http://example.com/is_root”:true}

The JWT Claims Set object is a container of claims, where the object’s property corresponds to the claim type and the property’s value contains the claims value. Some claims types are defined by the JWT spec (e.g. “iss” and “exp”), while others are context specific (e.g. “http://example.com/is_root”).

We will see more examples of JWT tokens after presenting the JWT Security Token Handler.

What are Security Token Handlers?

Security Token Handlers are a concept introduced by the  WIF (Windows Identity Foundation) framework, which is now an integral part of the .NET 4.5 framework. A token handler has multiple responsibilities, namely:

• Serialize and deserialize tokens between a XML or string format and a SecurityToken-derived instance;
• Validate security tokens and extract the contained claims into a claims identity or a claims principal;
• Create a token from a token description.

This behavior is defined by the abstract SecurityTokenHandler class, with multiple concrete derived classes for each token type (e.g. the Saml2SecurityTokenHandler class).

The JTWSecurityTokenHandler class

The recently announced Microsoft.IdentityModel.Tokens.JWT NuGet package contains a new token handler for the JWT token format – the JWTSecurityTokenHandler class – depicted in the next diagram.

As a token handler,  the JWTSecurityTokenHandler can be used to create and validate JWT tokens, as shown by the next example

 

 

• First, we create a token handler and a symmetric key, that will be used by both the sending and the receiving party to sign and validate the token, respectively.
• Then, we create a token descriptor, defining the token contents, namely:
  • The contained claims, i.e., the subject of the token,
  • The token issuer name,
  • The intended recipient of the token (AppliesToAddress),
  • The token lifetime, defined by a not before and an expires date-time,
• The token descriptor also contains the signing credentials, namely the symmetric key and the MAC (Message Authentication Code) algorithm identifier (“http://www.w3.org/2001/04/xmldsig-more#hmac-sha256”).
• Then, we use the token handler to create the token from the token descriptor. We also use the token handler to serialize the token into a string.
• On the receiving side, we begin by defining the validation parameters, namely:
  • The allowed audience, i.e., the value defined in the AppliestoAddress property of the token descriptor. This value should be an identifier of the receiving party.
  • The validation cryptographic, in the form of a BinarySecretSecurityToken containing the shared symmetric key.
  • The name of the accepted issuer.
• Finally, we use the token handler to simultaneously deserialize the token, validate its signature and extract the contained claims into a claims principal.
• We end the example by asserting that the claims principal does contains the Name and Role claims inserted in the token by the issuer.

 

The serialized token is just the concatenation of three base64url encoded parts (line breaks added for display purposes).

 

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9

.

eyJhdWQiOiJodHRwOi8vd3d3LmV4YW1wbGUuY29tIiwiaXNzIjoic2VsZiIsIm5iZiI6MTM1Mzk3NDczNiwi

ZXhwIjoxMzUzOTc0ODU2LCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5

L2NsYWltcy9uYW1lIjoiUGVkcm8iLCJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDYv

aWRlbnRpdHkvY2xhaW1zL3JvbGUiOiJBdXRob3IifQ

.

a-Tu5ojQSyiGSzTb9E5QbEYxyhomywzh2wqKs4El7lc

 

The first part contains the JWT Header

{“typ”:”JWT”,”alg”:”HS256″}

The second part contains the claims, including the audience, issuer and validity

{“aud”:”http://www.example.com”,

“iss”:”self”,”nbf”:1353973142,”exp”:1353973262,

“http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name“:”Pedro”,

“http://schemas.microsoft.com/ws/2008/06/identity/claims/role”:”Author”}

Finally, the third part is the signature value, computed by the MAC algorithm over the first two parts.

Alice in Claims: the WIF claims class model

Introduction

This is the seventh post in a series about claims based identity management and the Windows Identity Foundation (WIF).

The first six were:

• Alice in Claims: decentralized identity
• Alice in Claims: the claims model
• Alice in Claims: protocols
• Alice in Claims: the anatomy of a token
• Alice in Claims: not only for federation 
• Alice in Claims: Windows Identity Foundation

In this post, we describe WIF’s class model for claims based identities.

Claims Class Model

The old identity model

Since the beginning, the Microsoft .NET Base Class Library defined two interfaces for representing identities:

• The IIdentity interface, which aims tp represent an identity, is characterized by
  • the IsAuthenticated boolean property,
  • the Name string property, and
  • the AuthenticationType string property, with a description of the authentication method used to verity the name.
• The IPrincipal interface represents the subject of an action, and it is characterized by
  • The IsInRole(string) method that verifies if the subject possesses a given role.
  • The Identity property that references an IIdentity.

In this model a subject is solely characterized by a role membership function and a name based identity. We will see below that the new claims based model extends this information with claims collections.

The concrete implementations of the IIdentity include: the GenericIdentity class, the WindowsIdentity class and the FormsIdentity class.

The IPrincipal interface is implemented by classes such as: the GenericPrincipal class, the WindowsPrincipal class and the RolePrincipal class.

Instances implementing the IPrincipal interface are exposed by properties and methods such as:

• the System.Threading.Thread.CurrentPrincipal property, and
• the  System.Web.HttpContext.User property.

The new model

The WIF model builds upon the old model by defining two new interfaces, as shown in the following diagram:

• The IClaimsIdentity interface derives from IIdentity and adds several new properties. The most important is the Claims property that references a claim collection. In this way, a identity is now much more that a single string-based name.
• The Claim class represents individual claims, which are characterized by a value, an issuer name and a type (the ClaimTypes class defines a set of common claim types).
• Finally, the IClaimsPrincipal interface derives from IPrincipal and adds the new Identities property that references a collection of IClaimIdentity.

In its essence, the new model extends the old one by characterizing an identity not only by a name string but also by a claim collection, where a claim has a value, a type and an issuer.

When using WIF, instances of this new model are exposed in the same places as before, namely by property System.Web.HttpContext.User.

The new model also contains some methods and properties not address in this post, which are only relevant in delegation scenarios. This theme will be the subject of a future post.

Alice in Claims: Windows Identity Foundation

Introduction

This is the sixth post in a series about claims based identity management and the Windows Identity Foundation (WIF).

The first five were:

• Alice in Claims: decentralized identity
• Alice in Claims: the claims model
• Alice in Claims: protocols
• Alice in Claims: the anatomy of a token
• Alice in Claims: not only for federation 

In this post, we introduce the Windows Identity Foundation – WIF.

Windows Identity Foundation

Contents

The Windows Identity Foundation SDK is composed by:

• The Microsoft.IdentityModel.dll .NET assembly
• The FedUtil command line tool.
• A Visual Studio add-in.

Purpose

The Microsoft.IdentityModel.dll assembly contains class models for:

• Claims-based identity representation.
• A claims and token issuance pipeline.
• A claims and token consumption pipeline.
• Host adaptation layer supporting the above generic pipelines over the ASP.NET and WCF “hosts”.

The FedUtil command line generates configuration files based on federation metadata.

Finally, the Visual Studio add-in contain templates for:

• Identity consumers – ASP.NET sites and WCF services.
• Identity producers – ASP.NET and WCF based security token services.

In the next post, we will begin our in-depth analysis of WIF by looking into the class model for claims based identity representation.