Importance of Keeping machineKey Confidential

In ASP.NET applications, the <machineKey> element is critical for securing various application-level features, such as ViewState validation, authentication, membership credentials, and anti-CSRF tokens. This key ensures that the data encrypted or hashed by the application remains tamper-proof and confidential. When stored in the web.config file, extra care must be taken to protect the <machineKey> and the web.config file.

Secure management of machineKey

To mitigate the risks associated with the exposed machine keys, the following security measures should be applied (see Finding your machineKey type below for details on identifying your machine key "type"):

1. Single Instance: use Azure Auto-Generated Machine Keys (preferred where possible): The preferred configuration relies on automatic machine key generation, following Microsoft’s guidance for the declaration of "AutoGenerate". This ensures that <machineKey>  is automatically generated using the auto-generate utility, only stored in the registry.
2. Scaled Instances: use Azure Platform-managed Keys (preferred where possible): The recent deployment of Sitecore products within an Azure-managed environment may be configured with the Azure management of machine keys. In this case, there will be no <machineKey> element within the web.config file as it is managed by Azure within the rootweb.config file.
3. Scaled Instances: Static Machine secured with Azure Best Practices (where required): If shared, static machine keys are used (a common scenario, required for non-Azure managed multi-instance deployments), the <machineKey>  must be explicitly declared in the web.config file and should be treated as a high-value secret, with practices including:
   • Encrypt <machineKey> within web.config files.
   • Rotate machine keys on a regular basis.
   • Never commit web.config files with machine keys to the source control (for example, GitHub).
   • Restrict web.config file access to application administrators only.

High Level Steps: static machineKey

High Level Steps for the management of shared (static) <machineKey> within the web.config file:

1. Create (new/updated) <machineKey>.
2. Encrypt <machineKey> with Microsoft’s RSA Key Container.
   1. Important: There is a known issue for SXP 9.3 and above which requires the application of a workaround documented as part of KB0253614
3. Export RSA Key Container to all instances.
4. Copy (encrypted) <machineKey> to all instances.
5. (If needed) restart instances, refresh sessions, regenerate content, including Active RSS signed with <machineKey>.

Detailed Steps: static machineKey

Detailed Steps for the management of shared (static) machineKey:

1. Create (new/updated) machine key:
   Securely create a new <machineKey>. For detailed instructions, refer to the official Microsoft documentation:  How to generate a <machineKey> element
   
   
2. Encrypt the Machine Key Section in web.config with RSA Key Container:
   Encrypting the <machineKey>  section of the web.config file adds an extra layer of protection by preventing plain-text exposure of sensitive keys in file systems. IIS supports encrypting configuration sections using the aspnet_regiis.exe tool.
   
   For detailed instructions, refer to the official Microsoft documentation:
   To encrypt the connectionStrings and machineKey sections of the Web.config file

   Important:

   • There is a known issue for SXP 9.3 and above which requires the application of a workaround documented as part of KB0253614
   • Important: Ensure you use the most recent version of the aspnet_regiis.exe tool, currently located in C:\Windows\Microsoft.NET\Framework64\v4.0.30319 folder.
     
     
3. Export RSA Key Container to all instances:
   This ensures that any items secured with the newly created and encrypted <machineKey> will be properly handled when load balanced across multiple instances.
   For detailed instructions, refer to the official Microsoft documentation: Walkthrough: Creating and Exporting an RSA Key Container
   
   
4. Copy (encrypted) <machineKey> to all instances:
   As the <machineKey> element is now encrypted, it can be copied to the web.config file of all relevant server instances.
   
   
5. (If needed) Restart instances, refresh sessions, regenerate content, including Active RSS, signed with <machineKey>.
   See below for the details of the impact of a new key to understand what and how to handle <machineKey> rotation in a Sitecore environment.
   
   
6. Best practice: Rotate the Machine Key Regularly.
   Key rotation ensures that even if a key is compromised, its window of exploitation is limited. Rotation practices are particularly important in environments exposed to the internet or with strict compliance requirements. Key rotation is simply the practice of creating and distributing a new machine key on a regular basis.

Considerations when creating and rotating the machineKey

To rotate a static <machineKey> within a Sitecore product environment, you can use the standard ASP.NET application instructions provided in the official Microsoft security blog: see Recommendations

To ensure a safe and smooth key rotation within your Sitecore product environments, follow the general recommendations below:

• Verify the rotation procedure in a pre-production environment.
  Simulate the exact rotation process in a staging or pre-production setup. This ensures your team is familiar with the steps, expected behavior, and potential pitfalls before applying changes in production.
• Schedule rotation during off-peak hours or maintenance windows.
  Perform the rotation at a time of minimal user activity to reduce the risk of session loss and disruption to business operations.
• Notify users about potential impact.
  Inform stakeholders and users in advance. This is especially important if the rotation may cause temporary logouts, invalidate active sessions or if there are known RSS feed users (as the Active RSS uses machine key protection and so links must be re-generated and distributed to these users).
• Simultaneously update all instances.
  It is recommended to rotate the key on all scaled instances simultaneously to avoid issues caused by inconsistencies between the old and new machine keys.

Additional Considerations

Note that after key rotation, old machine keys will no longer be valid. This means that any in-flight sessions involving ViewState (encrypted with an old machine key) will encounter an error and will be required to re-authenticate. For this reason, we recommend that all active sessions be terminated prior to key rotation and that key rotation be performed during off peak hours for the product.  

Examples of the types of errors and actions a user may experience include:

• Authentication Cookie Invalidation: All users will be logged out or encounter access denied errors and will need to re-log in.
• View State Invalidation: Errors occur during form submissions or page interactions may occur, and ViewStateException transient errors will be logged. Users will be required to refresh a (ViewState dependent) pages.
• Anti-Forgery Token Invalidation: Tokens generated before the rotation cannot be validated and HttpAntiForgeryException transient errors will be logged. Form submissions will fail until the user refreshes the page. Note that if restarting the instances as part of the key rotation, this scenario should not be experienced by the end user.

If instances are shut down/quiesced and sessions terminated prior to <machineKey> rotation, then the only impact should be:

• RSS feed links invalidation: The previously generated Active RSS feed links (signed with the old machine key) will no longer be valid; new links must be generated and communicated to users and RSS feed subscribers.

If the machineKey has been publicly disclosed

Note that while it is technically more difficult, AutoGenerate and Azure-managed machineKeys are also subject to exposure; for this reason, vigilance is required across your environment to monitor for suspicious or abnormal behaviour.

We recommend that you adopt Microsoft’s recommendations as appropriate for your environment if you suspect a compromise of your machineKeys.

From Microsoft: If a machine key has been publicly disclosed, the rotation of all machine keys should be initiated. If successful exploitation of publicly disclosed keys has occurred, rotating machine keys will not sufficiently address possible backdoors or persistence methods established by a threat actor or other post-exploitation activity, and additional investigation may be warranted.

Finding your machineKey "type"

To confirm the machineKey "type" used in your deployment, the <SITECORE_ROOT>\web.config file should be inspected.

AutoGenerate machineKey key

If auto-generated keys are used, the <machineKey> will appear with the values similar to the following:

  <machineKey
    decryptionKey="AutoGenerate"
    validationKey="AutoGenerate,IsolateApps" />

Azure managed

If Azure horizontal scaling is used, the <machineKey> is managed by Azure and the <machineKey> element will be "missing" from the web.config file. In this scenario, machine key management is handled by Azure as part of Platform management.

Static machineKey Keys

If you have static machine keys, the <machineKey> element will be present with exact key values, for example (note these are fabricated key examples):

     <machineKey decryptionKey="D94AB5..."
      validationKey="90F219..." ... />

In this scenario you or your operational partner (which may include the Sitecore MCP team depending on your deployment model) are responsible for machine key lifecycle management including secure creation, ongoing protection and rotation as needed.

machineKeys with Sitecore products

The following details are provided for customers who require additional information about various deployment, provisioning, and ongoing machineKey management scenarios.

Experience Platform

Sitecore’s deployment tooling for XM, XP or XC (more commonly known as the Sitecore Experience Platform):

• If deployed out-of-the-box in single instance mode, it will be deployed with an auto-generated machine key.
• If deployed in multi-instance mode, it will need to have customer-managed static machine keys configured.
• If a customer selects Azure App Services, then Azure will manage the machine key outside of <web.config>

Environments that require multiple instances and are configured with a shared, static machine key for all instances. More details can be found in Sitecore’s Configure multiple Content Delivery instances documentation (step 6).
Customers (or their operational partner) are responsible for the configuration and management of their environment including machine keys.

Managed Cloud Standard

With Managed Cloud Standard, Sitecore provisions the environment for the customer and hands over operational management to the customer or their operational partner.  

1. Single Instance mode (Containers or PaaS):
   1. Provisioned with an <AutoGenerate machineKey> (no machineKey stored in <web.config>)
2. Multi-instance mode:
   1. Containers will be provisioned with static machineKey in <web.config>)
      1. Alternatively, machineKey can be secured by storing in KeyVault and Inject via K8 Secrets; this will inject the KeyVault stored machineKey into <web.config> at runtime (no machineKey value will be stored or persisted in <web.config>).
   2. Azure App Services, also known as PaaS, will be provisioned with Azure-managed machine key (managed outside of <web.config>)
      1. Alternatively, the machineKey can be secured by storing in AppSettings as Environment variables; this will inject the machineKey into <web.config> at runtime (no machineKey value will be stored or persisted in <web.config>).

Managed Cloud Premium

With Managed Cloud Premium, Sitecore provisions the environment for the customer and the MCP Team is responsible for operational management of machine keys behalf of the customer. 

1. Single Instance mode (Containers or PaaS):
   1. Provisioned with an <AutoGenerate machineKey> (no machineKey stored in <web.config>)
2. Multi-instance mode:
   1. Containers will be provisioned with static machineKey in <web.config>)
      1. Alternatively, machineKey can be secured by storing in KeyVault and Inject via K8 Secrets; this will inject the KeyVault stored machineKey into <web.config> at runtime (no machineKey value will be stored or persisted in <web.config>).
   2. Azure App Services, also known as PaaS, customers can choose to provision with
      1. Multiple app services for CD role: Will be provisioned with static machineKey in <web.config>
      2. One app service, multiple instances for the CD role: When provisioned with Azure-managed machine key, no machineKey value will be stored or persisted in <web.config>
      3. Alternatively, the machineKey can be secured by storing in KeyVault and configured for Inject via AppSettings; this will inject the KeyVault stored machineKey into <web.config> at runtime (no machineKey value will be stored or persisted in <web.config>).

Sitecore MCP Team is responsible for rotation of static machineKey and will work with customers to accomplish rotation as requested or required.

XM Cloud (SaaS)

XM Cloud (SaaS) is managed by Sitecore. Sitecore is responsible for the management, including rotation, of machineKeys in the XM Cloud (SaaS) environment as needed.

Frequently Asked Questions

When will this Knowledge Base link be made public?
The Knowledge Base article will be published as part of a Security Bulletin on or around September 3, 2025.

Can I share the Knowledge Base link with others?
These instructions are currently confidential and restricted to recipients of the associated notification email.

Can I share this list with others?
This link should be kept private and confidential until publication of the Security Bulletin to give all customers time to respond. This is how we help ensure the protection of all Sitecore customers.

How do I know if I have been compromised?

How do I know if my machine keys have been made public?

Refer to Microsoft’s announcement and follow the provided guidance.  
Microsoft has provided a list of hash values for identified publicly disclosed machine keys in their Github repository and recommends checking machine keys in your environment using the provided script.
Microsoft’s lists should not be considered to be authoritative or exhaustive, in that the disclosed keys may not be included in their list. 
Sitecore recommends that you rotate your keys and institute a practice of regularly rotating them.

What do I do if I think that my keys have been disclosed?

I followed Sitecore’s instructions for deployment, am I vulnerable?  

How can I get Microsoft Defender added to my Managed Cloud account?

More here:
KB1003613
KB1003247