Authentication and Authorization in ASP.NET Web API
You've created a web API, but now you want to control access to it. In this series of articles, we'll look at some options for securing a web API from unauthorized users. This series will cover both authentication and authorization.
- Authentication is knowing the identity of the user. For example, Alice logs in with her username and password, and the server uses the password to authenticate Alice.
- Authorization is deciding whether a user is allowed to perform an action. For example, Alice has permission to get a resource but not create a resource.
The first article in the series gives a general overview of authentication and authorization in ASP.NET Web API. Other topics describe common authentication scenarios for Web API.
Authentication
Web API assumes that authentication happens in the host. For web-hosting, the host is IIS, which uses HTTP modules for authentication.
You can configure your project to use any of the authentication modules built in to IIS or ASP.NET, or write your own HTTP module to perform custom authentication.
When the host authenticates the user, it creates a principal, which is an IPrincipal object that represents the security context under which code is running.
The host attaches the principal to the current thread by setting Thread.CurrentPrincipal.
The principal contains an associated Identity object that contains information about the user.
If the user is authenticated, the Identity.IsAuthenticated property returns true.
For anonymous requests, IsAuthenticated returns false.
For more information about principals, see Role-Based Security.
public interface IPrincipal { // // Summary: // Gets the identity of the current principal. // // Returns: // The System.Security.Principal.IIdentity object associated with the current principal. IIdentity Identity { get; } // // Summary: // Determines whether the current principal belongs to the specified role. // // Parameters: // role: // The name of the role for which to check membership. // // Returns: // true if the current principal is a member of the specified role; otherwise, false. bool IsInRole(string role); }
HTTP Message Handlers for Authentication
Instead of using the host for authentication, you can put authentication logic into an HTTP message handler.
In that case, the message handler examines the HTTP request and sets the principal.
When should you use message handlers for authentication? Here are some tradeoffs:
- An HTTP module sees all requests that go through the ASP.NET pipeline. A message handler only sees requests that are routed to Web API.
- You can set per-route message handlers, which lets you apply an authentication scheme to a specific route.
- HTTP modules are specific to IIS. Message handlers are host-agnostic, so they can be used with both web-hosting and self-hosting.
- HTTP modules participate in IIS logging, auditing, and so on.
- HTTP modules run earlier in the pipeline. If you handle authentication in a message handler, the principal does not get set until the handler runs. Moreover, the principal reverts back to the previous principal when the response leaves the message handler.
Generally, if you don't need to support self-hosting, an HTTP module is a better option. If you need to support self-hosting, consider a message handler.
Setting the Principal
If your application performs any custom authentication logic, you must set the principal on two places:
- Thread.CurrentPrincipal. This property is the standard way to set the thread's principal in .NET.
- HttpContext.Current.User. This property is specific to ASP.NET.
The following code shows how to set the principal:
private void SetPrincipal(IPrincipal principal) { Thread.CurrentPrincipal = principal; if (HttpContext.Current != null) { HttpContext.Current.User = principal; } }
For web-hosting, you must set the principal in both places; otherwise the security context may become inconsistent.
For self-hosting, however, HttpContext.Current is null. To ensure your code is host-agnostic, therefore, check for null before assigning to HttpContext.Current, as shown.
Authorization
Authorization happens later in the pipeline, closer to the controller. That lets you make more granular颗粒状的 choices when you grant access to resources.
- Authorization filters run before the controller action. If the request is not authorized, the filter returns an error response, and the action is not invoked.
- Within a controller action, you can get the current principal from the ApiController.User property. For example, you might filter a list of resources based on the user name, returning only those resources that belong to that user.
Using the [Authorize] Attribute
Web API provides a built-in authorization filter, AuthorizeAttribute. This filter checks whether the user is authenticated. If not, it returns HTTP status code 401 (Unauthorized), without invoking the action.
You can apply the filter globally, at the controller level, or at the level of individual actions.
Globally: To restrict access for every Web API controller, add the AuthorizeAttribute filter to the global filter list:
public static void Register(HttpConfiguration config) { config.Filters.Add(new AuthorizeAttribute()); }
Controller: To restrict access for a specific controller, add the filter as an attribute to the controller:
// Require authorization for all actions on the controller. [Authorize] public class ValuesController : ApiController { public HttpResponseMessage Get(int id) { ... } public HttpResponseMessage Post() { ... } }
Action: To restrict access for specific actions, add the attribute to the action method:
public class ValuesController : ApiController { public HttpResponseMessage Get() { ... } // Require authorization for a specific action. [Authorize] public HttpResponseMessage Post() { ... } }
Alternatively, you can restrict the controller and then allow anonymous access to specific actions, by using the [AllowAnonymous]
attribute. In the following example, the Post
method is restricted, but the Get
method allows anonymous access.
[Authorize] public class ValuesController : ApiController { [AllowAnonymous] public HttpResponseMessage Get() { ... } public HttpResponseMessage Post() { ... } }
In the previous examples, the filter allows any authenticated user to access the restricted methods; only anonymous users are kept out. You can also limit access to specific users or to users in specific roles:
// Restrict by user: [Authorize(Users="Alice,Bob")] public class ValuesController : ApiController { } // Restrict by role: [Authorize(Roles="Administrators")] public class ValuesController : ApiController { }