Featured Articles

Featured Articles

Securing a Web API with ADFS 3.0 and JWT tokens


As APIs and web services become more and more prevalent, particularly in the Enterprise, there is an increasing need to look at ways to secure the more important interfaces, particularly if they enable access to sensitive data.

Recently, I’ve been investigating ways to secure ASP.NET Web APIs using Active Directory Federation Services (AD FS) version 3.0 (rather than Azure Active Directory) – which ships as a standard role in Windows Server 2012 R2.  Those who read this site regularly will not be surprised to find yet another ADFS article!

The Problem Defined

There are heaps of articles which explain how to secure a web application and a web API using Windows Identity Foundation (WIF), and with WS-Federation.  This suits scenarios where the user would authenticate in an interactive fashion with web applications and/or ADFS.

However, what if we want to cater for scenarios where interactive authentication (i.e. responding to a redirect to a Web Form or Windows Integrated Authentication) isn’t preferable – or possible.  I’m talking about software-to-server scenarios, or software to API where the software is manually (statically) configured, like setting a username and password a-la Basic Authentication.

What we want is for the API consumer to obtain a Json Web Token (JWT) using a SOAP request (over secure transport) and then pass that JWT in the header of subsequent REST calls to the target Web API. The Web API should validate the JWT and obtain the user’s credentials, and then complete the request as the authenticated user.

Although this would work over (unencrypted) HTTP, HTTPS is strongly recommended for all communications between a client and services you host.

Can we do it?  Yes we can. 

Here’s what the solution looks like in diagram form:


In order to properly understand how this all fits together, it would help immensely if you have some prior knowledge and experience in the following:

  • Configuring ADFS Relying Parties (and working with ADFS),
  • PowerShell, or equivalent,
  • SOAP and REST,
  • ASP.NET Web APIs/.NET Framework 4.6 (or later),
  • Visual Studio 2013 or 2015

For simplicity, we’ll authenticate identities in Active Directory (as illustrated above).

The Solution – Part 1: Obtain a JWT Token

So I’m  going to take serious liberties with an approach which is reasonably well documented in the following article: http://virtualstation.azurewebsites.net/?p=4331

The original article focuses on using a JWT with Azure AD, but the same approach works just fine as it turns out for on-premise ADFS Relying Parties (RPs).

You set up a relying party (RP) as per normal, although it doesn’t require WS-Fed or SAML configuration – because we’re not going to use either.  We’ll request a JWT token, C/- ADFS 3.0’s lightweight OAuth2 implementation.  The script accomplishes this by crafting a SOAP message and sends it to the appropriate ADFS endpoint specified to request a JWT token using the username and password specified.  Note that the endpoint specified in the $sendTo variable must be enabled.

# Originally found at http://virtualstation.azurewebsites.net/?p=4331
$ADFShost = "https://<your-adfs-server>"
$sendTo = "$ADFShost/adfs/services/trust/13/usernamemixed"
$username = "<domain>\<username>"
$password =  "<password>” 
$applyTo = "https://<rp-identifier>"
$tokenType = "urn:ietf:params:oauth:token-type:jwt"
$xml = @"
<s:envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
    <a:action s:mustunderstand="1">http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Issue</a:action>
    <a:to s:mustunderstand="1">$sendTo</a:to>
    <o:security s:mustunderstand="1" xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
      <o:usernametoken u:id=" uuid-00000000-0000-0000-0000-000000000000-0">
        <o:password type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">$password</o:password>
    <trust:requestsecuritytoken xmlns:trust="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
      <wsp:appliesto xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
$tokenresponse = [xml] ($xml | Invoke-WebRequest -uri $sendTo -Method Post -ContentType "application/soap+xml" -TimeoutSec 30 )
$tokenString = $tokenresponse.Envelope.Body.RequestSecurityTokenResponseCollection.RequestSecurityTokenResponse.RequestedSecurityToken.InnerText
$token = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($tokenString))
$resource = "https://<your-rp-identifier><controller api>/<value>"
Invoke-RestMethod -Method Get -Uri $resource -Header @{ "Authorization" = 'Bearer '+ $token }

Assuming you properly configure the variable assignments at the start of this script, have configured the target RP and provide valid user credentials you ought to be able to run this script and obtain a valid JWT.  You may need to enable the OAuth2 endpoint in ADFS if it is disabled (possibly), and the credentials endpoint:


You’ll need to configure the Web API at the end to handle the ADFS issued JWT, which we’ll look into shortly.

The Solution – Part 2: Accept and validate a JWT Token

The next part took me a while, and then I somehow stumbled upon a dated official Microsoft sample which demonstrates exactly how to validate an ADFS-issued JWT token!  Here’s the address: https://code.msdn.microsoft.com/AAL-Server-to-Server-9aafccc1

I strongly recommend you download and extract the sample linked above.  For one thing, it’ll save me from having to list the various NuGet packages you’ll need to get this solution working.

Note that although this sample related to Azure Active Directory, it works just fine with on-premise ADFS.  The key is in implementing functionality which strips the Authorization: Bearer <JWT> out of a request header.

If we look at the sample’s Web API implementation (TelemetryServiceWebAPI), all we really need to get working is the Global.asax.cs implementation of a global request handler.

Note that the samples are distributed under the following license:

Copyright 2013 Microsoft Corporation
//    Licensed under the Apache License, Version 2.0 (the "License");

The Application_Start configures a token handler:

GlobalConfiguration.Configuration.MessageHandlers.Add(new TokenValidationHandler());

Which invokes a token validation class as follows.  Note that I don’t believe you have to register the Relying Party with ADFS, i.e. you don’t require a client id or a client secret.  Now confirmed. 

internal class TokenValidationHandler : DelegatingHandler
        const string Audience = https://<rp-identifier>;
        // Domain name or Tenant name
        const string DomainName = https://<rp-identifier>;

        static string _issuer = string.Empty;
        static List<X509SecurityToken> _signingTokens = null;
        static DateTime _stsMetadataRetrievalTime = DateTime.MinValue;

        // SendAsync is used to validate incoming requests contain a valid access token, and sets the current user identity 
        protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
            string jwtToken;
            string issuer;
            string stsMetadataAddress = string.Format(CultureInfo.InvariantCulture, "https://<your-adfs-server>/federationmetadata/2007-06/federationmetadata.xml", DomainName);

            List<X509SecurityToken> signingTokens;
            using (HttpResponseMessage responseMessage = new HttpResponseMessage())

                if (!TryRetrieveToken(request, out jwtToken))
                    return Task.FromResult(new HttpResponseMessage(HttpStatusCode.Unauthorized));

                    // Get tenant information that's used to validate incoming jwt tokens
                    GetTenantInformation(stsMetadataAddress, out issuer, out signingTokens);
                catch (WebException)
                    return Task.FromResult(new HttpResponseMessage(HttpStatusCode.InternalServerError));
                catch (InvalidOperationException)
                    return Task.FromResult(new HttpResponseMessage(HttpStatusCode.InternalServerError));

                JwtSecurityTokenHandler tokenHandler = new JwtSecurityTokenHandler()
                    // for demo purposes certificate validation is turned off. Please note that this shouldn't be done in production code.
                    CertificateValidator = X509CertificateValidator.None

                TokenValidationParameters validationParameters = new TokenValidationParameters
                    AllowedAudience = Audience,
                    ValidIssuer = issuer,
                    SigningTokens = signingTokens

                    // Validate token
                    ClaimsPrincipal claimsPrincipal = tokenHandler.ValidateToken(jwtToken,

                    //set the ClaimsPrincipal on the current thread.
                    Thread.CurrentPrincipal = claimsPrincipal;

                    // set the ClaimsPrincipal on HttpContext.Current if the app is running in web hosted environment.
                    if (HttpContext.Current != null)
                        HttpContext.Current.User = claimsPrincipal;

                    return base.SendAsync(request, cancellationToken);
                catch (SecurityTokenValidationException)
                    responseMessage.StatusCode = HttpStatusCode.Unauthorized;
                    return Task.FromResult(responseMessage);
                catch (SecurityTokenException)
                    responseMessage.StatusCode = HttpStatusCode.Unauthorized;
                    return Task.FromResult(responseMessage);
                catch (ArgumentException)
                    responseMessage.StatusCode = HttpStatusCode.Unauthorized;
                    return Task.FromResult(responseMessage);
                catch (FormatException)
                    responseMessage.StatusCode = HttpStatusCode.Unauthorized;
                    return Task.FromResult(responseMessage);

        // Reads the token from the authorization header on the incoming request
        static bool TryRetrieveToken(HttpRequestMessage request, out string token)
            token = null;

            if (!request.Headers.Contains("Authorization"))
                return false;

            string authzHeader = request.Headers.GetValues("Authorization").First<string>();

            // Verify Authorization header contains 'Bearer' scheme
            token = authzHeader.StartsWith("Bearer ", StringComparison.Ordinal) ? authzHeader.Split(' ')[1] : null;

            if (null == token)
                return false;

            return true;

        /// <summary>
        /// Parses the federation metadata document and gets issuer Name and Signing Certificates
        /// </summary>
        /// <param name="metadataAddress">URL of the Federation Metadata document</param>
        /// <param name="issuer">Issuer Name</param>
        /// <param name="signingTokens">Signing Certificates in the form of X509SecurityToken</param>
        static void GetTenantInformation(string metadataAddress, out string issuer, out List<X509SecurityToken> signingTokens)
            signingTokens = new List<X509SecurityToken>();

            // The issuer and signingTokens are cached for 24 hours. They are updated if any of the conditions in the if condition is true.            
            if (DateTime.UtcNow.Subtract(_stsMetadataRetrievalTime).TotalHours > 24
                || string.IsNullOrEmpty(_issuer)
                || _signingTokens == null)
                MetadataSerializer serializer = new MetadataSerializer()
                    // turning off certificate validation for demo. Don't use this in production code.
                    CertificateValidationMode = X509CertificateValidationMode.None
                MetadataBase metadata = serializer.ReadMetadata(XmlReader.Create(metadataAddress));

                EntityDescriptor entityDescriptor = (EntityDescriptor)metadata;

                // get the issuer name
                if (!string.IsNullOrWhiteSpace(entityDescriptor.EntityId.Id))
                    _issuer = entityDescriptor.EntityId.Id;

                // get the signing certs
                _signingTokens = ReadSigningCertsFromMetadata(entityDescriptor);

                _stsMetadataRetrievalTime = DateTime.UtcNow;

            issuer = _issuer;
            signingTokens = _signingTokens;

        static List<X509SecurityToken> ReadSigningCertsFromMetadata(EntityDescriptor entityDescriptor)
            List<X509SecurityToken> stsSigningTokens = new List<X509SecurityToken>();

            SecurityTokenServiceDescriptor stsd = entityDescriptor.RoleDescriptors.OfType<SecurityTokenServiceDescriptor>().First();

            if (stsd != null && stsd.Keys != null)
                IEnumerable<X509RawDataKeyIdentifierClause> x509DataClauses = stsd.Keys.Where(key => key.KeyInfo != null && (key.Use == KeyType.Signing || key.Use == KeyType.Unspecified)).
                                                             Select(key => key.KeyInfo.OfType<X509RawDataKeyIdentifierClause>().First());

                stsSigningTokens.AddRange(x509DataClauses.Select(clause => new X509SecurityToken(new X509Certificate2(clause.GetX509RawData()))));
                throw new InvalidOperationException("There is no RoleDescriptor of type SecurityTokenServiceType in the metadata");

            return stsSigningTokens;

Once this code is in place, you can decorate ApiControllers and methods as per normal with the [Authorize] attribute to force the authentication requirement.

You can access the identity information from the User object at runtime, e.g. if you threw a standard out-of-the-box values controller into the sample: (I added this to a local copy, it is not part of the official sample)

namespace Microsoft.Samples.Adal.TelemetryServiceWebApi.Controllers
    public class ValuesController : ApiController
        // GET api/values
        public IEnumerable<string> Get()
            return new string[] { "value1", "value2" };

        // GET api/values/5
        public string Get(int id)
            return User.Identity.Name;

Assuming that you have mapped the user’s UPN (user principal name) to “name” in the Relying Party claim rules, you’d see the user’s FQDN in the response when invoking this GET request and passing a valid ADFS-issued JWT.


Here’s a PowerShell script successfully making a GET request with an ADFS issued JWT:


Note that in this particular case, I successfully tested the approach against ADFS vNext (4.0)!

The future approach may well lie in the following sample: https://github.com/Azure-Samples/active-directory-dotnet-daemon which is listed as the future direction.

Tips on Troubleshooting

Always check the ADFS configuration, and ensure that your endpoints are correct.  Keep an eye on the ADFS event logs, as RP misconfigurations usually end up as failed requests there.


Even something as simple as a trailing forward slash in the RP identifier can ruin the token validation (above).

Ensure appropriate ADFS endpoints are enabled, and if you can, try to secure your identifiers using HTTPS for best results.  In our test lab we use internal DNS and an Enterprise CA over self-signed certificates to handle site bindings.

Lastly, don’t be afraid to debug the Web API (locally or remotely), remembering that you can configure an RP in ADFS to be localhost Smile


Well, I hope this has been an informative article for you.  I’m aiming to reproduce this solution in its entirety later this week in a Greenfields environment, so this article may be subject to further edits.

I was quite happy to see a complete end-to-end scenario working perfectly in our Development environment.  In theory, this approach should work without too much configuration overhead, but the usual disclaimers apply: it works on my machine.

Feel free to post comments if you have questions or would like to know more.

Further Reading

It took a lot of reading to get this far.  Here are some very helpful articles/links which provided much needed hints and pointers.


JWT in ADFS overview: http://blogs.technet.com/b/maheshu/archive/2015/05/26/json-web-token-jwt-support-in-adfs.aspx

Helpful Links:

High Availability: MassTransit 2.x with Clustered MSMQ – Part 2   Recently updated !


In this post, we’ll look at configuring a Windows Failover Cluster and then install an MSMQ role onto the cluster.  If you’re looking for how to configure MassTransit 2.x against an existing clustered MSMQ role, you might want to skip ahead to Part 3 (coming soon).

Disclaimer: I’ve personally configured MSMQ in 4 separate Failover Clusters to date, and the experience was completely different each time.  I can’t really cover off all the potential problems you might encounter, but I present here the consolidated experience I have had to endure, in case it saves you time and headaches.

Prerequisites – Per-Machine Configuration

In order to be successful, machines participating in the cluster need to be configured identically before clustered roles are installed. I’ve found that it’s better to have the configuration set before even adding them to a failover cluster.

Windows Features

We need the following to be installed on all nodes in the cluster:

  • · Message Queuing
    • Message Queuing Services
    • Message Queuing Server
    • Directory Service Integration
    • Message Queuing Triggers


Important! Message Queuing must be running in Directory mode, not Workgroup mode. Once MSMQ is installed and running, check the value of the following Windows Registry key to ensure the mode is correct:

Workgroup = 0


Shared Disk

You’ll also need shared disk made available to all potential members of a Windows Failover cluster.  The clustered MSMQ role needs to be able to fail it’s shared disk over to an active node.

Installing the Failover Cluster

Install the Failover Clustering feature on each candidate node (each server which will participate in the cluster). 

Note the user performing the installation/configuration must be a member of the Enterprise Admins and Domain Admins security groups within the domain. Don’t forget to validate the cluster once configured. The setup should create a new cluster AD object in the same OU as the node member servers.


Each cluster member needs to be configured to access appropriate shared disk resources (e.g iSCSI, NFS mounts etc.). The MSMQ clustered role requires shared disk in order to function.

I’m not going to walk through the setup, it is pretty straightforward.

Once all the cluster members are installed and configured, run Failover Cluster Manager on one of the nodes and you can proceed to installing MSMQ.

Configuring the MSMQ Cluster Role


  • IP Address reserved within the cluster subnet (optionally, create a DNS A record to match the network name you wish to use)
  • Shared disk between cluster nodes

Once the failover cluster has been successfully created, there are a couple of permissions changes which need to be made before you can begin to install the MSMQ cluster role.

Permission Changes & Role Installation

In Active Directory, there should be a computer object which represents the cluster name, e.g. BUS10$

The cluster AD object needs to have “Create all child objects “ permissions on all member server objects in Active Directory, i.e. under the Servers OU (if that’s where they are located).

Using the Wizard, select MSMQ and follow the dialogs. You’ll need to provide the Client Access Point name (like a NETBIOS name), and an IP address.

The MSMQ role installation wizard tries to create a DNS A record for you (for the network name of the MSMQ queue), but requires permissions within DNS to do so. I find it’s cleaner to not have to set this permission, and just create the record manually (if the record exists, or the object doesn’t have permissions, it doesn’t break the role).


Next, select a shared disk for the resource and click through to finish. See the troubleshooting section for help if you encounter issues.

In one environment, once configured, after many, many attempts the MSMQ Cluster Service wouldn’t install on either of the cluster nodes. The only path forward was to add the Queue AD Computer object (BUSQ) to the Domain Admins group temporarily. Once the failover had occurred to all nodes (31 & 32), this membership could be safely revoked.


Generate Cluster Logs

Open an elevated PowerShell prompt on a cluster node and type : Get-ClusterLog –timespan X

This will generate a log to (System Drive) C:\Windows\Cluster\Reports\ Cluster.log with the last X minutes of log.  It sometimes provides more accurate information, but beware it can be incredibly verbose, so make sure you limit the span of the log with –timespan.  I’ve had this command (sans timespan) generate a half terabyte log file before!


This leads into the next post – how to install and run MassTransit against the clustered MSMQ queue.  Coming soon.