Tag Archives: claims

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)



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


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




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).











The first part contains the JWT Header


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





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


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

The first six were:

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 IPrincipal interface represents the subject of an action, and it is characterized by

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 new model

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


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


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

The first five were:

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

Windows Identity Foundation


The Windows Identity Foundation SDK is composed by:

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


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.

Alice in Claims: not only for federation


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

The first four were:

In this post, we show that the claims based model is useful in scenarios other than federation.

A scenario

Considerer the scenario presented in the following figure, where webapp1 and webapp2 are intranet web applications, deployed inside a windows domain and using windows based authentication.


In such a scenario, identity management is rather simple:

  • The user identity is managed by Active Directory (AD), namely domain group membership.
  • This user identity information is seamlessly made available to the web apps, using the integrated support for windows authentication available in ASP.NET.

However, consider the augmented scenario depicted in the next figure, where access must also be available from outside the windows domains, using password based or certificate based user authentication. Note that, for security reasons, the used passwords may be different from the ones used in the domain.

Since integrated windows authentication is not readily available in this scenario, each web app must deal with the identity management issues, namely authentication and group membership. This may imply the creation of credential and identity stores in each web app.NotOnlyForFederation2

In such a scenario, the usage of a claims based model, as showed next, solves this problems.NotOnlyForFederation3

  • Users are initially authenticated by the Identity Provider (IdP), releasing the web apps from this burden. This also simplifies the introduction of new authentication mechanisms, because the web apps are not impacted by these changes.
  • The web apps consume the claims (e.g. group membership, roles, authorizations) issued by the IdP. The claim issuance process can use other sources of information other than active directory, namely for storing user attributes that do not fit in AD’s schema.
  • Any change to the user’s identity (e.g. role change) is readily made available to all the internal web apps.

The advantages obtained from the use of a claims based model and an IdP are similar to the use of integrated windows authentication, but with the added benefits:

  • Authentication is not limited to windows mechanisms.
  • User identity attributes are not limited to the ones stored in the AD. Namely, the claims issuance process may also include the evaluation of authorization policies, releasing the web apps from this task.
  • By using commonly used specifications, it is easier to integrate application not based on Windows technologies.

Finally, the use of claims based model and an internal IdP paves the way to future federation scenarios where

  • Partners must access the web apps, or
  • Domain users must access external apps, namely cloud based apps.


Alice in Claims: the anatomy of a token


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

The first three were:

The previous post presented the protocols for requesting and exchanging security tokens between identity providers and identity consumers. In this post, we dissect the structure of a commonly used token type: SAML assertions.

A SAML assertion

The following excerpt shows the high-level structure of a SAML  2.0 assertion.

    IssueInstant="2010-07-04T22:57:50.284Z" Version="2.0"
          Method="urn:oasis:names:tc:SAML:2.0:cm:bearer" />

  • The top-level element is the Assertion element.
  • The Assertion/Issuer element defines the token issuer’s identity, in the form of an URL.
  • The Assertion/ds:Signature contains a signature computed over the assertion contents.
  • The Assertion/Subject contains information regarding the assertion’s subject, i. e., to whom or what do the contained claims apply. This information is carried in the SubjectConfirmation element, which in this case states that this token is a bearer token: the token subject is anyone in possession of the token.
  • The Assertion/Condition define the conditions for token acceptance by a consumer, which in this case are:
    • Time period (NotBefore and NotOnOrAfter attributes)
    • Consumer identity (AudienceRestriction element). Any consumer that does not match any of the audience restriction URLs should not accept the token.
  • Finally, the Assertion/AttributeStatement and Assertion/AuthnStatement contains the issued claims, which will be detailed next.

Attribute statement

The following XML excerpt shows the AttributeStatement contents, defining the issued claims:

  • One name claim (type = “http://…/name”) with value “Alice”
  • Two role claims (type = “http://…/role”) with values “Developer” and “LeadDeveloper”.

Authentication Statement

Finally, the next XML fragment shows the AuthnStatement element containing the authentication type claim, also called authentication context. In this example, Alice used a password based mechanism to authenticate herself when requesting the claims from the identity provider.

<AuthnStatement AuthnInstant="2010-07-04T22:57:49.396Z">


For completeness, the next XML fragment presents the signature contents.

<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        Algorithm="http://www.w3.org/…/xml-exc-c14n#" />
        Algorithm=http://www.w3.org/…#rsa-sha256 />
             Algorithm=http://...#enveloped-signature />
             Algorithm="http://…/xml-exc-c14n#" />
          Algorithm=http://www.w3.org/…#sha256 />
  <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
  • The Signature/Element defines the signed data, which is this case is the complete SAML Assertion. Note that the URI attribute matches the ID attribute in the Assertion element. Since the signature is inside the signed data, an “enveloped-signature” transform is used.
  • The Signature/KeyInfo/X509Data/X509Certificate contains the issuer’s certificate. There are several WIF configuration aspects that relate to this certificate, so its existence should be noted.

Alice in Claims: protocols


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

The first two were:

The previous post presented the claims model, namely concepts such as identity provider, identity consumer, claims and security tokens. In this one, we will describe some of the protocols available for the communication between providers and consumers, namely for requesting security tokens and exchanging them.

Passive protocols

The following figure shows a typical interaction between the Identity Provider (IdP) and the Identity Consumer (a web app), when the user agent is a browser without javascript code (passive client).


  1. The protocol begins by Alice’s browser making the initial HTTP request to the web app.
  2. Since this request does not contain any identity information, the response is a redirect to the IdP. Alice’s browser fulfills this redirect by sending a GET request to the IdP. The redirect target URL contains information contextualizing the request, namely the identity of the requesting web app.
  3. After this request, typically there is an interaction between the IdP and Alice’s browser with the purpose of authenticating the user. For example, the IdP may respond with an HTML form for username+password authentication, which is followed by a POST containing this information, sent by Alice’s browser. This interaction may also include a step where the IdP and Alice agree on the issued claims, which is useful when Alice wants some control over releasing parts of her identity.
  4. Finally, the IdP responds with a security token containing the issued claims. This response may be:
    1. A redirect to the web app, with the token encoded in the target URL, or
    2. An auto submitting HTML form, containing the token in an hidden field. The form’s target is the web app.

Both the WS-Federation and SAML protocols use the interactions described above. The SAML protocols have some variants not described above, namely the artifact binding.

These protocols are named passive, because the user agent (Alice’s browser) does not plays an active role in the protocols. It just has to play the HTTP protocol game. Namely, no browser javascript support is required.

Active protocols

In the active protocols, the user-agent plays an active role in the protocols.


  1. The protocol starts by the user agent directly requesting a token from the IdP. This request must contain all the information required for the IdP to authenticate the requesting user and determine the claims to issue.
  2. Next, the IdP responds with the issued token.
  3. Finally, the user agent sends the request to the Identity Consumer (typically a service), with the token attached.

The WS-Trust is an example of an active protocols based using the SOAP and WS-* specifications.

In the next post we will show some examples of security tokens, namely the SAML assertion format.

Alice in Claims: the claims model


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

The first one presented a scenario with decentralized identity authority. This posts uses this scenario to introduce the claims based model.

The following figure serves two goals:

· It presents the main claims model concepts, and

· Concretizes this concepts in the presented scenario


Claims model concepts

  • Identity is represented by a set of claims, where a claim is a declaration made by an entity. In this scenario, Alice, LeadDev, IssueMgr and IssueView are examples of claims that represent’s Alice’s identity.
  • An Identity Provider (or Issuer) is an entity that issues identity claims, typically containing information for which it is authoritative. In this scenario, WeDev is the identity provider, and it issues name and role claims (e.g Alice and IssueMgr).
  • An Identity Consumer (or Relying Party) is an entity that uses (consumes, relies on) identity claims. In the above example, the consumer is CloudTrack, which uses the consumed claims to make the authorization decisions..
  • A Security Token is a set of claims securely packaged for transportation between participants. This packaging ensures properties such as
    • Privacy: only the authorized receiver of the token is able to access the contained claims. This typically is obtained by encrypting the token to the authorized receiver.
    • Claim integrity and issuer authentication: the token receiver is able to determine the original claims producer. Usually, this property is achieved by the issuer digitally signing the token.
    • Subject authentication and proof of possession: the token receiver is able to determine who is the subject of the claims. The two more common proof of possession methods are
      • Bearer – any entity who has the token can allege that it is the claims subject. This is similar to bearer checks or bus tickets.
      • Holder of key – the claims subject is any entity who proves possession of a related key (e.g. by signing the message where the token is attached).


The “Proposal for a Common Identity Framework: A User-Centric Identity Metasystem” contains an interesting taxonomy of claims

  • Claims are divided between primordial and substantive
    • Primordial (or primitive) claims are proofs presentable by only one subject
    • Substantive claims are claims produced by claims providers, typically after the subject presenting a primordial or other substantive claim.
  • Substantive claims are further subdivided in
    • Static – properties of the subject (e.g. National Identifier Number; Date-of-Birth)
    • Derived – derived from other claims (e.g. Portuguese Citizen; Over-18)
    • Membership – role or group membership, relation with other subject (e.g. Administrator; Lead Developer; Purchase Officer)
    • Capability – authorization to something (e.g. Can-emit-purchase-order; Can-admin-CI-server)
    • Contextual – information about the context (e.g. Authentication method, location and time)

Claims transformers

A Claims Transformer is an entity or module that produces claims based on claims that it receives (consumes).

For instance, in above scenario, the WeDev identity provider can also be seen as a claims transformer since it produces the name and role claims (substantive claims) upon receiving and validating Alice’s credentials (primordial claims).

We also can see the CloudTrack’s web app as divided in to two modules:

  • The first module is a claims transformer, transforming the input role claims (LeadDev) into application specific roles (IssueMgr) and authorization roles (IssueView).
  • The second module is an identity consumer, using the input authorization claims (IssueView) to decide if the access is allowed or not.

Notice that the claims exchange between these two modules doesn’t have to use a token, since no unprotected communication channel is used.

In the next post, we will present some of the protocols that are used for requesting and communicating claims and tokens.