In ASP.NET,  authentication cookies are encrypted using the machine key. Also, if you use encrypted passwords, then the password encryption also uses the machine key as a factor in encrypting passwords. By default, the machine key is auto generated unless you specify it directly in Web.config. However, if you just let the machine key be auto generated, what happens is, if you move your site to a different server, the machine key is different and therefore it cannot decrypt the passwords and all your accounts would be locked out. Also, in a Web farm or cluster the machine key needs to be the same on each server in order to work correctly so that all servers encrypt cookies and passwords the same.

In mojoPortal content management system, we include a machine key specified in Web.config so that you won't get locked out if you move a site to a different server. But mojoPortal is an open-source project so anyone can see the machine key we include in Web.config and therefore could potentially be able to forge a cookie with the same encryption and try to authenticate or elevate their roles such that they could have administrative access to your site.

To avoid this, it is very important that you generate your own machine key and replace the one in your Web.config with one you generated yourself. Make sure you do this before changing the password format to encrypted, otherwise changing the machine key will prevent you from logging in since it can no longer decrypt the password.

If you have already set your site to use encrypted passwords, you should backup your site and database and then change to clear text passwords and then change your machine key and then change it back to encrypted.

If your passwords are set to clear text or hashed, no workarounds are needed when changing the machine key.

There are several methods you can use to generate a new machine key:

  1. If you are using mojoPortal or later, there is a built-in machine key generator in the Security Advisor section of your site's Administration page. During initial setup for new installations if the web.config file is writable then the setup page will automatically generate a custom machinekey and update web.config.
  2. You can generate a machine key in IIS 7.x if you have administrative access to the server, see:
  3. This article on MSDN also has sample code for a console application that can generate a machine key.
  4. There are also several online tools that can generate a machine key for you, I recommend this one:

Once you have changed to a custom machine key, that means you must maintain that customization whenever you upgrade to new versions of mojoPortal, so you need to backup Web.config file so you can copy your machine key into the new Web.config file after upgrading.

When you do change the machine key, everyone using the site will be logged out because their authentication cookie will no longer be valid, so they will have to login again.

Make Upgrades Easier

You can make upgrades easier by creating a special file with your MachineKey in it and then referencing that file using the configSource attributes. Read more about how to do that in our "Using Separate Files for Config Sections" document.

Additional Considerations When Changing the MachineKey

If you have enabled SMTP configuration from Site Settings by adding this in your user.config:

<add key="EnableSiteSettingsSmtpSettings" value="true" />

then the SMTP settings are stored in the database and the user and password are encrypted. So changing the machine key may cause an error in the Site Settings page because it will not be able to decrypt the values that were encrypted with the previous machine key. So ideally you should clear out the SMTP user and password from Site Settings before changing the machine key and then put those settings back after you change the machine key. Otherwise you may need to fix it as follows from the database:

  1. UPDATE mp_SiteSettingsEx SET KeyValue = '' WHERE KeyName = 'SMTPUser'
  2. UPDATE mp_SiteSettingsEx SET KeyValue = '' WHERE KeyName = 'SMTPPassword'
  3. The above will clear those values from the database but Site Settings are cached so you will need to clear the cache by recycling the application pool to touching the Web.config file.
  4. Go back into Site Settings and reset the SMTP settings so they get encrypted with the new machine key.
Created by Joe Audette on Sep 17, 2010
Last Modified by Joe Davis on Mar 16, 2023