Working With IAuthenticationFilter in the MVC 5 Framework

When implementing a custom authentication filter it’s important to know where in the pipeline your filter is invoked; if your purpose is to prevent unauthorized access to a controller action, be sure to implement your credentials verification early enough in the process. This post walks you through the creation of a basic authentication filter and shows the correct method in which to do the check. Good news: it’s easy!

We can learn a lot about the new IAuthenticationFilter interface by implementing one and seeing where it fits in the MVC pipeline.  Before we get started, let’s first remember that authentication and authorization are separate concerns in your application, so this filter is a welcome little addition.

Authentication is where a user provides credentials to access a resource, whereas authorization allows access to particular resources based on properties of the user’s identity. In previous versions of the MVC Framework we had the AuthorizeAttribute, which could be used to cause a redirect if you were unauthenticated, but it’s also true that it blurred the lines a little around auth & auth. 

Creating a Basic Do-Nothing Filter

Now that Authentication can more easily stand alone, the process to implement it is pretty simple:

  • Add a class to your project called NewAuthenticationFilter
  • Inherit from ActionFilterAttribute and IAuthenticationFilter
  • Implement the interface (click on the interface name and press Ctrl+. and hit enter)
  • Throw a couple of debug statements in so that we can set breakpoints, remembering to add the diagnostics namespace to your using statements

Just a few quick side notes on the above code.

  • I usually stick my filters into a Filters folder in my project (or into a separate DLL project to keep them reusable) to try to keep things clean
  • We inherit from ActionFilterAttribute so that we can use it as an attribute on our actions; just using IAuthenticationFilter isn’t enough
  • You can implement interface members by clicking on the interface name and pressing Ctrl+. and then tapping Enter

Your final class should look like the following:

public class NewAuthenticationFilter: ActionFilterAttribute, IAuthenticationFilter
    public void OnAuthentication(AuthenticationContext filterContext)

    public void OnAuthenticationChallenge(AuthenticationChallengeContext filterContext)

With that in place, go the the Index action on the HomeController and add the attribute to the method. This will let the events fire as the request is processed. Also, set a breakpoint on the return statement. Your action should look like this:

public ActionResult Index()
    return View();

Great! Let’s hit F5 and see what happens:

  • The OnAuthentication method is invoked, press F5 to continue
  • The action is executed, press F5 to continue
  • The OnAuthenticationChallenge is called last

Perfect, some of how we can use this is now becoming apparent. First of all, it’s important to note that the action can be fully executed before the OnAuthenticationChallenge is executed. This means that if you’re intending on preventing any DB writes or calls to something mutable or executable during the action, you’ll need to implement logic in OnAuthentication method to prevent this (we’ll get to that in a minute).

Second, both methods allow you to evaluate request information and set properties of the response, such as the Result (an ActionResult), but remember that the Action itself has the ability to set some of these properties and might overwrite what you set up in OnAuthentication (which, again, is called before the index action method in our example).

Finally, remember that this is just one part of the pipeline. The Result of the action hasn’t yet been executed when OnAuthenticationChallenge is complete, so something like a View hasn’t been rendered, or a FileResult that would load data from disk hasn’t yet been called.

But Wait! What is This All For?

I’m so glad you asked. Here’s the thing…Debug statements aren’t that interesting and don’t really show you how this can come into context. The user passes through the above code and our action is executed, as is our result, so the user gets to see whatever they requested come back in their browser. Let’s update our code and take another look at how our application might use this.

An authentication filter doesn’t really do much for us if it’s not, oh, say, filtering for authentication, so let’s start by checking to see if our user is actually presenting some kind of credentials.

public void OnAuthentication(AuthenticationContext filterContext)
    if (!filterContext.Principal.Identity.IsAuthenticated)
        filterContext.Result = new HttpUnauthorizedResult();

This is the most basic form of a check. “The identity of the principal is not authenticated, so set the result to unauthorized, an HTTP 401 status code.” Now we’re cooking with peanut oil and our 401 will not let the user access the action until they satisfy whatever arguments you’d like them to fulfill.  To that end, you don’t only need to use the principal identity, you can use whatever you like, such as a tie-in to a third-party SSO provider in a mixed identity environment.

Next, we have to deal with the fact that someone who is unauthenticated tried to access a resource we were protecting. The way the Authorize attribute worked was just by letting that 401 we set above flow through the framework. In an MVC application the default mechanism for authentication is Forms, for which there is a default account controller and corresponding views added to our project. Thus, by simply letting the user “fall through” here, they will end up at the login page.  For the following code in your challenge method:

public void OnAuthenticationChallenge(AuthenticationChallengeContext filterContext)
    // redirect the user to some form of log in

…the user will keep that 401 state through, and will ultimately be bounced back to the site’s login page.


So, in it’s simplest form as we’ve done above, authentication filters give us a way to remove Authorize attributes (separation of concerns) and mimic the behavior we were previously leveraging to force users to log in. But there’s more, right?

Practical Uses of Our New Custom Authentication Bestie

We get pretty good support with the Authorize attribute and our ability to create custom filters already, but if we agree that separation of concerns is important, we get a few benefits with the new Authentication filters and the timing with which their methods are fired.

Isolated Custom Authentication

One of the first possibilities is that you can now setup an action or controller to have a custom authentication mechanism, rather than using whatever the default is for the site. If you have an external provider (perhaps something legacy) that you can proxy credentials to, this might be one way you could approach this.

Customizing UI For Login

There may be some cases where you want to do something like augment credentials, or perhaps configure part of the application, or even let users log in with a single-use code. OnAuthenticationChallenge lets you configure the result, so you can route the user to whatever view you like in your application.

Things to Remember

I actually don’t have a lot of caveats to suggest here, but perhaps the most important bit to remember is that if you IAuthenticationFilter.OnAuthenticate fall through without a 401, you’re letting the user into the action. Your OnAuthenticateChallenge will still fire, but remember from the breakpoints set above (when we were just spitting out debug lines) that the action will fire and your code will be executed. Logging the user in at this point happens after the invocation…a worst case scenario would be on a POST where an update is happening.

Finally, remember that Authentication wraps Authorization and action execution, and the Authenticate method precedes your first opportunity to interact with the request pipeline when you use ActionFilterAttribute inheritance on its own.

Next Steps

It’s pretty easy to try this out! Why not give the following a try?

  • File –> New –> Project and give the exercise above a try
  • Think of other uses or scenarios where one could leverage this
  • Break out your custom authentication filters built on the old objects in older versions of the MVC Framework

Happy coding!

Thanks to good friend David Paquette who reviewed and suggested updates on this post.

  • Pingback: Friday Five - December 13, 2013 - The Microsoft MVP Award Program Blog - Site Home - MSDN Blogs()

  • Pingback: Az IAuthenticationFilter használata | MolePlex()

  • Mike Diehl

    public class CustomAuthenticationFilter :
    ActionFilterAttribute, IAuthenticationFilter

    public void OnAuthentication(AuthenticationContext
    if (!filterContext.Principal.Identity.IsAuthenticated)
    filterContext.Result = new HttpUnauthorizedResult();
    Hi James,

    Saleng pointed me to your blog post about this.

    We are using Windows authentication, and I want to add a couple of Claims to the Identity of the user when they are authenticated. Basically, we look up a couple of keys in a database based on their SID (AddPersonClaim) and what groups they belong to (AddTeamClaim).

    Is this the right place to do this? When a user first hits our website, I definitely want to add these claims. What about subsequent HttpRequests? Do the claims that I add here get included in some sort of state
    so I don’t need to add the claims each time? Should I check to see if the claim exists before I add it? Maybe there’s a better place to add the claims earlier in the pipeline?
    Mike Diehl

    • James Chambers

      Hi Mike! You’re correct in thinking that they are durable for the session. Once the claim is added to the identity it will remain there until they log out or the session times out. In your filter, just do a check to see if the claim exists and short circuit out if it does. Cheers!