U4-10222 - Install a custom machine key during umbraco installation

Created by Shannon Deminick 02 Aug 2017, 06:20:31 Updated by Sebastiaan Janssen 02 Aug 2017, 10:32:22

Tags: Unscheduled

Subtask of: UAASSCRUM-964

For best practices and to ensure that every site has better security and is portable between any environment, a custom machine key should be installed during installation which would need to be done before the admin user is created too because the password is dependant on the machine key. A machine key is also always required for load balancing so this would save developers an extra step.

Perhaps in some cases a developer doesn't want a custom machine key - since maybe they have configured their own server's machine key settings at the machine.config level (server level) so this should be able to be bypassed in the advanced installer settings.

Some notes on the machine key and how it affects passwords:

  • When useLegacyEncoding = false (which is the default), the machine key will affect how a password is hashed, but the only part of the machine key that affects this is the 'validation' algorithm type. We will make this "HMACSHA256" which is the default in the latest .NET Framework versions too. This could also be overridden at the machine.config (server side level too)
  • When useLegacyEncoding = false, the machine key will not affect how the password is hashed if the membership provider has an explicit hashing algorithm set, for example: <membership defaultProvider="UmbracoMembershipProvider" userIsOnlineTimeWindow="15" hashAlgorithmType="HMACSHA256"> . This is not the default but if this was set before installation, then this algorithm will be used and the machinekey will play no part in the hashing of the password

In either case above you cannot just change the hashing algorithm type - either by changing the 'validation' attribute of the machine key or the hashAlgorithmType of the membership provider since your users will no longer be able to log in.

If you wanted to add a machine key to your Umbraco install after it's been installed and after users/members have been created, this may be possible but you would need to specify the correct algorithm type in the 'validation' attribute of the machine key to match what your users/members passwords have already been hashed with. This could vary based on how the server is configured (i.e. special machine.config settings or older versions of .NET Framework)

1 Attachments


Shannon Deminick 02 Aug 2017, 06:21:17

This is what the customized installer step looks like for explaining/prompting for a machine key (see screenshot)

Shannon Deminick 02 Aug 2017, 07:07:56

PR: https://github.com/umbraco/Umbraco-CMS/pull/2092

Priority: Normal

Type: Task

State: Fixed


Difficulty: Normal


Backwards Compatible: True

Fix Submitted:

Affected versions:

Due in version: 7.7.0

Sprint: Sprint 64

Story Points: