U4-8734 - Custom two factor authentication built in for umbraco back office

Created by Shannon Deminick 18 Jul 2016, 09:15:57 Updated by Biagio Paruolo 19 Jun 2017, 08:27:04

Tags: PR Gold partner

Subtask of: UAASSCRUM-765

Currently we recommend using an OAuth provider if you require 2 factor authentication. Most OAuth providers will have 2 factor auth built in to them (i.e. Identity Server). However some developers wish to have 2 factor authentication built into Umbraco by way of extending the authentication mechanism so this is the tech write up of how we could make this possible.

We started implementing part of the solution a while back but it never got finished. This interface was already created IUmbracoBackOfficeTwoFactorOptions https://github.com/umbraco/Umbraco-CMS/blob/dev-v7/src/Umbraco.Web/Security/Identity/IUmbracoBackOfficeTwoFactorOptions.cs

And this has been coded already: https://github.com/umbraco/Umbraco-CMS/blob/dev-v7/src/Umbraco.Web/Editors/AuthenticationController.cs#L181

Therefore if the BackOfficeUserManager has been extended in Umbraco and replaced during OWIN startup with a custom UserManager that:

  • Implements IUserTwoFactorStore
  • Overrides SupportsUserTwoFactor to return true
  • Implements IUmbracoBackOfficeTwoFactorOptions to return the custom angular view used to display the 2 factor auth screen

Then the logic mentioned above will execute. This means the call to PostLogin would return something like:


Currently there is no code written on the angular side to handle this. The code in AuthenticationController should be changed to return a custom http code instead of 200/Ok, normally when working in a normal MVC app, this issues a response call to redirect to a different screen to display the 2 factor input. The status code should be: 407 - i think umbraco's angular implementation auto-checks for 403 behavior so a different code is required like 407.

Then the angular Umbraco.Dialogs.LoginController will need to handle an error response from it's call to userService.authenticate, so it can display the custom 2 factor auth form. The custom view will then need to implement the logic of calling the server with the correct code. This custom view should follow the principals used in the default ASP.Net MVC app template and display a drop down list of potential 2 factor auth providers that the user can select.

Upon submitting the form it will send a request to the server. The AuthenticationController will need to be updated to handle this logic - again should follow the same logic/principals found in the default ASP.Net MVC app template with a SendCode action.

Instead of relying on the developer to implement all of these things manually: IUserTwoFactorStore, SupportsUserTwoFactor, IUmbracoBackOfficeTwoFactorOptions, the Umbraco core should natively support all of this and have a default view to show the 2 factor options. Then a developer would just need to implement the 2 factor providers, Umbraco would then detect if these have been set and return true/false for SupportsUserTwoFactor accordingly. A developer would still be able to override all of this behavior by inheriting from BackOfficeUserManager and returning their own angular view which could have their own logic for handling 2 factor auth.


Stephen Roberts 13 Oct 2016, 14:02:04

@Shandem 407 isnt going to work due to https://bugs.chromium.org/p/chromium/issues/detail?id=372136 Basically Chrome sees a 407 in an XHR request and decides to treat it differently. you don't have access to the contents of the response. but the frontend changes are now support this functionality with my pull request https://github.com/umbraco/Umbraco-CMS/pull/1524

Shannon Deminick 02 Feb 2017, 23:24:24

I've merged this in and added additional methods to core to make the REST process available, you can see additional changes made in these revs: 5060e709d143f6b706bdfd7b553a9210d84f4723, 86021c50524c8456dde062dc32f7b03db57b75c3

Biagio Paruolo 16 Jun 2017, 05:35:52

@Shandem How to use or disable this function? I use an external OAuth server implementation ( this is one https://github.com/mattbrailsford/umbraco-authu ), but the postlogin form don't work anymore. See this issue: https://github.com/mattbrailsford/umbraco-authu/pull/7

Shannon Deminick 19 Jun 2017, 05:02:10

Here's a fully working example/demo which does not use a real 2FA provider and just allows any code to be used, but shows how to wire everything up: https://gist.github.com/Shazwazza/2fbbbe6567a2b0509f5215af8ba9ab37

We will be working towards making this easier in the future but for now you would need to provide your own db tables, etc... to get it all done.

Biagio Paruolo 19 Jun 2017, 08:27:04

@Shandem thank you. I read it. Not simple to integrate. I think that a base Umbraco native OAuth or 2FA is a must today. Also must be implemented a CORS setup.

Priority: Normal

Type: Exception

State: Fixed


Difficulty: Normal


Backwards Compatible: True

Fix Submitted:

Affected versions: 7.6.3

Due in version: 7.6.0

Sprint: Sprint 51

Story Points: 2