title: When does WebApi2 use OnAuthorizationAsync vs OnAuthorization
body: <p>We've recently implemented API authentication by implementing a custom AuthorizationFilterAttribute, using credentials stored in Azure Document DB.  DocDB mandates everything use Async.  </p>
  
  <p>Through experimenting we found that WebApi2 synchronous controllers will use the OnAuthorizationAsync if present, and OnAuthorization if no async method.  We also found that asyc controller methods can use either auth method.  But I'm not 100% sure it is working correctly. We only saw that code did hit breakpoints.</p>
  
  <p>Oddly, you can also override OnAuthorization mark it as async </p>
  
  <blockquote>
    <p>public async override Task OnAuthorization(....)</p>
  </blockquote>
  
  <p>This last method compiles and executes fine, but the controller will not wait for the auth filter to finish executing before the action method begins.  Usually the result is an ASP error:</p>
  
  <blockquote>
    <p>An asynchronous module or handler completed while an asynchronous operation was still pending</p>
  </blockquote>
  
  <p>Seems like this manipulation of the override should have been a compile error and not allowed.</p>
  
  <p>Regardless.... There are many mysteries about AuthorizationFilterAttribute and a few other posts exist about the confusion.  <a href="https://stackoverflow.com/questions/26464848/custom-authorization-in-asp-net-webapi-what-a-mess/26466849#26466849">Custom Authorization in Asp.net WebApi - what a mess?</a></p>
  
  <p>My question is how do you know which will execute and in which order of precedence?  It does appear if both exist in the filter, only one method is executed.  </p>
  
  <ol>
  <li><p>If your controller action is async, must you override the OnAuthorizationAsync method? </p></li>
  <li><p>If you have async await in your auth logic, and are forced to use OnAuthorizationAsync (like I am), does this then mean I have to change all my controller actions to now all be async controller actions?  </p></li>
  </ol>
  
  <p>I can't find any documentation that lays out scenarios for async action filters.</p>