ALE with customer-managed keys

This feature is available across all tiers of our Enterprise licensing plan, including the Standard tier.

Warning:

Enabling this feature has serious implications with regards to data access. Should key issues arise, you risk losing access to your data.

Check the table below for some common problematic scenarios and their solutions.

Scenario	Solution
Your credentials for accessing the Azure Key Vault (AKV) have expired or have been deleted.	If you can still log in using your email and password (non-SSO)... ... and if you are an organization administrator, you can update your credentials in the Encryption section of the organization Admin page. ... and if you are not an organization administrator, you can ask, via a support ticket, to be promoted to an administrator role; you can then update your credentials in the Encryption section of the organization Admin page. If you can no longer log in, provide your organization ID through a support ticket, and we can invite and promote you as an administrator. You can then update your credentials in the Encryption section of the organization Admin page. Once you regain login access, we recommend that you create a new AKV key and credentials set, then configure the customer-managed key using this new information, thus ensuring that nobody else has access to your credentials.
Your AKV key has expired.	Your customer-managed key still works, but we recommend that you switch to a new key.
Your AKV key was deleted.	You can restore your AKV key from the Azure portal during the retention period.
Your AKV key was purged, but it had a backup.	You can restore the key from the Azure portal backup. By default, the restored key has the same ID as the original one, which you should not change.
Your AKV key was purged and it did not have a backup.	Warning: There is no solution for this scenario. In this situation, your UiPath® customer data is lost.

Overview

In addition to the standard TDE at the storage level, certain services also employ Implicit Application-Level Encryption (ALE). This means that data is encrypted at the application layer before being stored, providing an added layer of security.

Furthermore, some services/resources offer an optional, user-driven encryption known as Optional (Opt in) ALE. This gives you the option to decide whether those services/resources should employ ALE or not. For the list of services or resources, and the types of encryption relevant to them, please refer to the encrypted data page in our documentation.

For services with ALE, either implicit or opted in for, you have the ability to choose who handles the encryption key. It could be managed by either UiPath or yourself. To assist in this, Azure Key Vault supports secret versioning, allowing you to generate a secret to use in configuring your key at the organization level.

After you enable the customer-managed key, previously backed up data is not re-encrypted, and any existing backups are removed once they expire. Only new data is encrypted using this option.

Customer-managed keys explained

In the customer-managed key architecture, UiPath products or platform services (such as UiPath Orchestrator or UiPath Identity Service) generally encrypt sensitive customer data before storing it. When data access is required, the product or service calls your key management infrastructure to get the decryption key. This gives you control over the encrypted data in UiPath because you have the ability to refuse to return the key.

This process involves the following components:

• The key management service (KMS) - this is UiPath's internal tool, developed for key encryption purposes.
• The data encryption key (DEK or KMS DEK) - used to encrypt plain text data. Generally, the DEK is generated by the KMS or by UiPath's internal key vault, and is never stored anywhere in clear text.
• The key encryption key (KEK) - used to encrypt the DEK. The process of encrypting a key is known as key wrapping. Generally, the KEK is generated by you, it is stored in your key vault, and it constitutes the actual customer-managed key which is controlled by your key management service.
• The encrypted data encryption key (EDEK) - this is the DEK that is wrapped by the KEK. Generally, this key is stored by the service provider (such as Orchestrator); consequently, whenever a service needs to access encrypted data, the service calls the customer’s key management service to obtain the KEK needed to decrypt the EDEK, and to produce the DEK which is then used to decrypt the data.
• The UiPath internal key - this is used to encrypt data columns, including the CMK and the KMS DEK.

This diagram illustrates how the various components involved in enabling customer-managed keys work together:

Enabling the customer-managed key

Warning:

Enabling this feature has serious implications with regards to data access. Should key issues arise, you risk losing access to your data.

To create the necessary credentials and enable this option:

1. Create the required credentials in Azure Key Vault.
   Note:

   • The key vault can be created in any region, but we recommend that it pertain to the same region as your organization.
   • UiPath is granted access to the key vault used for the customer-managed key, so we recommend creating a vault dedicated solely to this purpose.
   • This feature supports any key size that can be configured in a key vault.
   • We only support key vault access policies for controlling access to Azure resources. These policies must be configured with Wrap Key and Unwrap Key permissions for Cryptographic Operations, and Get and Set secret permissions for Secret Management operations.

   
2. Log in to Automation Cloud as an organization administrator.
3. Go to Admin, select the organization name in the left panel, then click Security.
   The Security Settings page is displayed.

   
   

   

   
   
4. In the Encryption section, under Encryption type, select Customer managed key.
   The Customer managed key configuration window is displayed.

   
5. Fill in the required details, as defined in the Azure portal:
   1. Azure directory (tenant) ID (created as part of the app registration in Azure):
      
      
      
      
   2. Azure application (client) ID (created as part of the app registration in Azure):
      
      
      
      
   3. Client secret (created as part of the app registration in Azure) or Certificate (created in the Azure Key Vault and uploaded during the app registration in Azure):
      
      
      
      If you opt for Certificate, ensure that it's set up correctly as described on Setting up an Azure Key Vault certificate.
   4. Key identifier of the secret or certificate (created in Azure Key Vault):
      
      
      
      
      Important: Mandatory: Make sure you select the Wrap key and Unwrap key options to allow using this item as a customer-managed key.
6. Click Test and save.
   A confirmation message is displayed, informing you that you have configured your own encryption key.

   
   

   

   
   
   If you get an error message instead, check your credentials, then try again.

Note:

It can take 15 minutes to propagate the new customer-managed key after it is created. This is due to our internal cache preventing the same key from being propagated repeatedly, for performance reasons.

With Orchestrator, the caching cycle for external key retrieval is one hour long; on top of that, the caching cycle for internal usage is another 15 minutes.

Setting up an Azure Key Vault certificate for UiPath

Encryption with a customer-managed key can be done with a secret or a certificate. For details about setting up certificates, check setting and retrieving a certificate from Azure Key Vault in the Microsoft documentation. Follow these high-level steps to set up an Azure Key Vault certificate for encryption:

1. Log in to Azure Key Vault and navigate to the Certificates section.

2. Create a certificate with the Subject as CN=uipath.com and Content Type as PEM.

   
3. After creation, download the certificate in PFX/PEM format. Also save the Key Identifier for later use.

   
4. Open the .pem file with a text editor. It should consist of two sections: BEGIN PRIVATE KEY/END PRIVATE KEY and BEGIN CERTIFICATE/END CERTIFICATE.

   
5. Create a new .pem file containing only the lines between BEGIN CERTIFICATE and END CERTIFICATE.
6. In the Azure portal, locate the Certificates & secrets tab in your App Registration and upload the new .pem file.

   
7. In Automation Cloud, as part of customer-managed key configuration, you need to add the entire content of the downloaded .pem certificate from Azure Key Vault in the Client secret or certificate field, and add the Key Identifier as found in Azure Key Vault.

Editing the customer-managed key

Once you enable this option, you can also edit any details related to the connection. To that end, click Edit connection under the Customer managed key option, and change any information as needed.

Key rotation

It is good practice to routinely rotate your keys, so as to ensure the continuous protection of your encrypted data against any potential breaches.

Auto-rotation can be configured in the Azure Key Vault, but you must still manually update the customer-managed key information for your Automation Cloud^TM organization:

1. Create a new key in your current Azure Key Vault or in a new vault.
2. Return to the Security Settings page for your Automation Cloud^TM organization.
3. Click Edit connection under Customer managed key, then add the details for the new key you created.

Key rotation only works if both the old key and the new key are still valid.

Key rotation audit: You can see any changes to customer managed keys in the Audit page in Orchestrator, at the tenant level.

Licensing downgrade

If your Enterprise plan expires, you are automatically downgraded to the Free plan. This is what you can expect in terms of data encryption:

• The Customer managed key option is still enabled for you, but it is greyed out in the interface. As such, you can no longer edit its values, such as changing key vault details.
• You can switch to UiPath managed key (Default), but you will not be able to revert to Customer managed key until your plan is upgraded to Enterprise.

Best practices for using customer-managed keys

There are some important details to keep in mind before you start using customer-managed keys:

• Once you start using a new key as part of the key rotation process, the old one can no longer be used to access and encrypt data. It is therefore important to keep any old keys in the key vault, namely to disable them instead of deleting them. This is especially important in disaster recovery scenarios, where UiPath might need to revert to a backup of an older version of the database. If that backup uses one of your old keys, you can rotate to it to regain data access.

  If you choose to remove a key, it is important that you use the soft-delete feature.

• If you lose your key, you can no longer connect to the vault. You should therefore always create a backup of the key on the Azure portal or in a secure key vault separate from Azure, in accordance with your organization's security policies.
• If you are leveraging Single Sign On to access UiPath services, you may consider creating a local account to function as a break glass account. Because the external identity provider information is included in the data encrypted by the customer managed key, SSO accounts will be inaccessible should your key vault become unreachable.
• For security purposes, users that do not have top-level administrator privileges should not have purge rights over the customer-managed key.

• If you no longer want UiPath to have access to your data, you can disable the key from the Azure Key Vault, as shown in the image below:

  
  

  

  
  

  Find out more about Azure Key Vault recovery actions.