Controllers
An Umbraco API Controller is an ASP.NET WebApi controller that is used for creating REST services.
Umbraco contains different types of controllers to perform different tasks:
When you make a page request to the MVC application, a controller is responsible for returning the response to that request. The controller can perform one or more actions.
By default, all front-end requests to an Umbraco site are auto-routed via the Index action of a core Controller:
Umbraco.Cms.Web.Common.Controllers.RenderController.A SurfaceController is an MVC controller that interacts with the front-end rendering of an UmbracoPage. They can be used for rendering view components and for handling Form data submissions. SurfaceControllers are auto-routed which means you don't have to add/create your own routes for these controllers to work.
All implementations of Surface Controllers inherit from the base class:
Umbraco.Cms.Web.Website.Controllers.SurfaceController.An Umbraco API Controller is an ASP.NET WebAPI controller that is used for creating REST services. These controllers are auto-routed which means that you don't have to add/create your own routes for these controllers to work.
All implementations of Umbraco API Controllers inherit from the base class:
Umbraco.Cms.Web.Common.Controllers.UmbracoApiController.An Umbraco Authorized Controller is used when the controller requires member or user authentication (authN) and/or authorization (authZ). If either the
authN or authZ fail, the controller will return a 401 - unauthorized response.The Umbraco Authorized controllers and attributes for Backoffice Users are:
- MVCA base class implementation for backoffice authorized controllers is inherited from:
Umbraco.Cms.Web.Common.Controllers.UmbracoAuthorizedController. These MVC controllers are not auto-routed. - WebAPIA base class implementation for authorized auto-routed Umbraco API controllers is inherited from:
Umbraco.Cms.Web.BackOffice.Controllers.UmbracoAuthorizedApiController. This controller inherits fromUmbraco.Cms.Web.Common.Controllers.UmbracoApiControllerit is auto-routed. This controller is also attributed withUmbraco.Cms.Web.Common.Attributes.IsBackOfficeAttributeto ensure that it is routed correctly to be authenticated for the backoffice.Another base class implementation for the backoffice isUmbraco.Cms.Web.BackOffice.Controllers.UmbracoAuthorizedJsonController. It inherits fromUmbraco.Cms.Web.BackOffice.Controllers.UmbracoAuthorizedApiControllerbut has some special filters applied to it to automatically handle anti-forgery tokens for use with AngularJS in the backoffice.
For more details on Routing requirements, see the Routing requirements for backoffice authentication article.
Authorizing a controller for a front-end member is achieved with attributes:
Umbraco.Cms.Web.Common.Filters.UmbracoMemberAuthorizeAttribute- Ensures authorization is successful for a website user (member).Umbraco.Cms.Web.Common.Filters.UmbracoMemberAuthorizeFilter- Ensures authorization is successful for a front-end member
You can attribute your controller or action with this attribute which will ensure that a member must be logged in to access the resource. An example:
using Microsoft.AspNetCore.Mvc;
using Umbraco.Cms.Core.Cache;
using Umbraco.Cms.Core.Logging;
using Umbraco.Cms.Core.Routing;
using Umbraco.Cms.Core.Services;
using Umbraco.Cms.Core.Web;
using Umbraco.Cms.Infrastructure.Persistence;
using Umbraco.Cms.Web.Common.Filters;
using Umbraco.Cms.Web.Website.Controllers;
namespace UmbracoProject.Controller
{
[UmbracoMemberAuthorize]
public class AccountController : SurfaceController
{
public AccountController(
IUmbracoContextAccessor umbracoContextAccessor,
IUmbracoDatabaseFactory databaseFactory,
ServiceContext services,
AppCaches appCaches,
IProfilingLogger profilingLogger,
IPublishedUrlProvider publishedUrlProvider)
: base(umbracoContextAccessor, databaseFactory, services, appCaches, profilingLogger, publishedUrlProvider)
{
}
[HttpPost]
public IActionResult UpdateAccountInfo(AccountInfo accountInfo)
{
// TODO: Update the account info for the current member
}
}
}
The
UmbracoMemberAuthorizeAttribute() and UmbracoMemberAuthorizeFilter() contain the following properties to provide control over the authorization process for which members can access the resource:AllowType- Comma delimited list of allowed member types.AllowGroup- Comma delimited list of allowed member groups.AllowMembers- Comma delimited list of allowed members.
For more details, see the Using MemberAuthorizeAttribute section in the Umbraco API - Authorization article.
For Umbraco to authenticate a request for the backoffice, the routing needs to be specific. For details on the routes and route requirements, see the Routing requirements for backoffice authentication. To secure your Umbraco API controllers based on a users membership, see the Umbraco API - Authorization article.