JSON Web Token (JWT) support in ADFS

Hi, there! In the past few posts, I’ve covered some of the new features in Active Directory Federation Services (ADFS) on Windows Server 2012 R2. One of the new capabilities we’ve added is the ability for ADFS to issue JWTs (JSON Web Tokens) in response to authorization requests. JWT is a JSON-based open standard that enables authorization services like ADFS to issue tokens with claims represented in a compact manner. This compact representation makes JWTs ideal for consumption by web applications and makes them mobile device friendly (i.e. consume less bandwidth and fit in size constrained HTTP headers on mobile browsers etc.). Additionally, JWTs are primarily JSON objects which are very easy to work with in a wide variety of languages making app development significantly easier.

JWT support across federation protocols

The following table illustrates the support in ADFS for issuing JWTs for each of the authorization protocols supported by it.

In a nutshell, JWTs are the only supported token type for OAuth requests. We proceeded to extend support for JWTs to WS-Fed and WS-Trust as well. In both these protocols, there’s either configuration required on ADFS (for WS-Fed) or JWTs need to be requested explicitly (for WS-Trust). Subsequent sections describe this in further detail.

JWT support for OAuth requests

The OAuth server implementation in ADFS on Windows Server 2012 R2 will issue only JWTs in response to OAuth authorization requests. This applies to both access tokens as well as refresh tokens issued by ADFS in response to an OAuth authorization grant request. There is no way to turn off this behavior in ADFS.

JWT support for WS-Fed requests

By default, ADFS continues to issue SAML tokens in response to WS-Fed requests. However, you can configure ADFS to issue JWTs in response to WS-Fed requests. This configuration is done via PowerShell and is on a per-relying party basis. In other words, you can configure ADFS to issue JWT access tokens to specific applications/relying parties in ADFS.

This is done by using the following PowerShell command.

Once you set this, all access tokens issued by ADFS in response to WS-Fed requests for authorization to access this relying party/application will be JWTs.

JWT Support for WS-Trust requests

You can request JWTs from ADFS in response to WS-Trust requests. This is done by crafting an RST that explicitly demands JWTs from ADFS. This is done by setting the TokenType for the RST to the value “urn:ietf:params:auth:token-type:jwt”.

A code snippet that illustrates how to request JSON Web Tokens (JWTs) from ADFS is below:

Note that the token response in the RSTR returned by ADFS is the Base64 encoding of the JWT. The JWT itself consists of three parts – header, body and signature separated by a “.” (i.e. a period character). You can get hold of the JWT by base64 decoding the payload that is contained within the InnerXML of the security token response to the WS-Trust call.

What does a JWT issued by ADFS look like?

The following snippet illustrates a JSON Web Token issued by ADFS. This access token contains a bunch of claims that were asserted by ADFS after successfully authenticating and authorizing the user to access the relying party.

JWTs issued by ADFS on Windows Server 2012 R2 are signed using ADFS’ issuing certificate. ADFS does not support JWT encryption.

If you’ve seen SAML tokens issued by ADFS in the past, you’ll notice the shorter claim names that enable the token to be represented more compactly. These short claim names are registered with ADFS – to see the short name that corresponds to a claim, use the Get-ADFSClaimDescription PowerShell cmdlet. You can also register your custom claim descriptions and corresponding short names to be used with JWTs using the Add-AdfsClaimDescription PowerShell Cmdlet.

Working with JWTs - JSON Web Token Handler for .Net

You can use the JSON Web Token Handler for .Net to parse and validate JSON Web Tokens. The JSON Web Token Handler extension for Windows Identity Foundation enables you to create and validate JSON Web Tokens (JWT) in your applications. The JWT Token Handler can be configured to run in the WIF pipeline like other built-in security token handlers, but it can also be used independently to perform token validation in lightweight applications. 

The JWT Handler is available for download as a NUGET package at: https://www.nuget.org/packages/System.IdentityModel.Tokens.Jwt/ 

Documentation for the JWT handler is available on MSDN at https://msdn.microsoft.com/en-us/library/dn205065(v=vs.110).aspx 

That’s all for this post. Thanks for reading!

-----------------------

Mahesh Unnikrishnan