ASP.NET Web API Security: The Thinktecture.IdentityModel AuthenticationHandler

AuthenticationHandler is an ASP.NET Web API message handler that can map incoming credentials to a token handler. The token handler in turn can parse credentials and create a principal.

In addition AuthenticationHandler provides some common services like claims transformation, session tokens and handling of response headers.


Your job is to do provide the mapping between credential and token handler, e.g.

  • Basic Authentication credentials on the Authorization header
  • JWT or SAML token on the Authorization header
  • Client certificate
  • Access key on the query string
  • Signature over incoming HTTP request

…and which authentication hint gets sent back (along the 401 status code).

For this definition you use the AuthenticationOptionMapping class:

var mapping = new AuthenticationOptionMapping


    // where to look for credentials

    Options = options,


    // how to validate them

    TokenHandler = handler,


    // which hint to give back if not successful

    Scheme = scheme


Options could be e.g.:

  • the Authorization header (with some scheme)
  • some other HTTP header
  • a query string parameter
  • a client certificate
  • a cookie

Thinktecture IdentityModel comes with several pre-defined token handlers, e.g.

  • JWT, SWT and SAML tokens
  • Basic Authentication
  • client certificates
  • access keys

…and last but not least, you have control over the Www-Authenticate header that get’s sent back if authorization was not successful, e.g.

  • some scheme and some realm
  • scheme only
  • scheme and some challenge

You can add all required associations to the authentication configuration:

var config = new AuthenticationConfiguration
    RequireSsl = true


…and finally add the handler to the Web API runtime:

    name: "DefaultApi",
    routeTemplate: "api/{controller}/{id}",
    defaults: new { id = RouteParameter.Optional }
var authConfig = ConfigureAuthentication();
config.MessageHandlers.Add(new AuthenticationHandler(authConfig));


After that, authentication handler will inspect every request, look for credentials, and if successful create and populate the principal.


This entry was posted in IdentityModel, OAuth, WebAPI. Bookmark the permalink.

12 Responses to ASP.NET Web API Security: The Thinktecture.IdentityModel AuthenticationHandler

  1. Pingback: Web API Security: Basic Authentication with Thinktecture.IdentityModel AuthenticationHandler |

  2. Jan Corluy says:

    Can i also use ws federation with web-api? And wath do i need to do then?

  3. Pingback: Web API Security: JSON Web Token/OAuth2 with Thinktecture.IdentityModel AuthenticationHandler |

  4. justneedanid says:

    I was wondering if anyone had examples of using IoC to provide services like the ‘tokenHandler’ above or the ‘ClaimsAuthenticationTransformer’. I imagine a common scenario would use some repository to convert tokens to users/claims but how I wire that in is a bit of a stumper.

  5. Pingback: ASP.NET Web API Authentication: Using multiple (simultaneous) Authentication Methods with Thinktecture AuthenticationHandler |

  6. I’m using the above approach with a MessageHandler to process JWT tokens, but when I turn on Federated Security, it always redirects to my Home Realm Discovery page, instead of accepting the JWT token. Incidentally, I only want to use direct login (HRD) for a couple of Administration pages (MVC Controllers), but all other ASP.NET Web API calls will use the self-signed JWT tokens via a proxy. How can I separate the authentication methods for different parts of the MVC/Web API Application. Thanks :)

  7. I guess there is a conflict between the Web API and the FAM. Do you have a global authZ element in config? The FAM also has a RedirectingToIdentityProvider event where you can fine tune when a redirect happens or not.

    The best approach is to separate UI and services into different IIS applications.

    • Bhasker Kottapally says:

      Just as you mentioned above.
      Our system is architected into two applications:
      The business layer – published as REST API – ASP.NET MVC Web API (Resource Server?)
      The UI Layer – ASP.NET MVC 4 web application consuming the API (Relying Party?)
      This is just one application and there are more. While some follow a similar architecture as above, others are just ASP.NET MVC application (without REST API)

      Our requirement now is to implement SSO for all the above explained application stack.
      After a wide range of discussions, we decided to go with an OpenSource solution and finally picked IdentityServer.

      What have we done so far:
      Was able to deploy Identity Server – from the download build and from code
      Was able to get Membership reboot integrated with IdentityServer, as we needed most of the features, like – Two Factor, Secret Questions etc. Thanks for Membership reboot.

      I am a little confused between WS-Federation, SAML and JWT to understand what fits our scenario and what kind of configuration does it need on the ID server setup.
      Any guidance or help in this regard is greatly appreciated.

  8. Naeem Arshad says:

    What is the diffrence between IdentityModel and IdentityServer ?

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s