Encryption key
Dataedo keeps certain secrets so it can function properly: passwords and tokens of your connections, the SMTP password, client secrets of your login methods, bot credentials and AI engine tokens. They are always stored encrypted. By default, Dataedo encrypts them with a key built into the application. You can, however, encrypt them with your own key instead.
The encryption key can be managed only by Admin users, and only in self-hosted installations (Windows and Docker). In Cloud, Dataedo manages the key for you.
Why use your own key
The built-in key is the same in every Dataedo installation and ships with the application. It keeps the secrets unreadable to someone browsing the tables, but it doesn't protect them from anyone who has a copy of the repository database, for example from a backup, a restored test environment or a database dump.
With your own key, the secrets are encrypted with AES-256-GCM using a key that never goes to the repository. This means:
- A copy of the repository can no longer be exploited to read your secrets.
- Access to the database and access to credentials are separated. People who administer the repository database, such as DBAs or a hosting provider don't automatically get access to the systems Dataedo connects to.
- You meet key ownership requirements. If your security policy says the organization must hold and control its encryption keys, a custom key covers that for Dataedo.
- You can rotate the key. Replace the key on a schedule, when an administrator who knew it leaves, or when you suspect it has leaked. Dataedo re-encrypts all secrets with the new key, so nobody has to enter any password again.
- You can see who uses the key. The Portal shows the fingerprint of the key in use and which Agents have it, so a misconfigured Agent is easy to spot.
Before you set your own key
Using a custom key has some consequences, read what happens before choosing to set your own key:
- Dataedo Desktop stops working with the repository. Desktop can't read secrets encrypted with your key, so it refuses to connect and asks users to use Dataedo Portal. If your team still documents with Desktop, keep the built-in key.
- Every Agent needs the same key. An Agent without the key, or with a different one, can't read the credentials it needs and stops running tasks.
- Keep the key safe. The key is shown only once. If you lose it, you'll have to reset the encryption and enter all the secrets again. Store it in a password manager or a secrets vault, not only on the Portal's server.
Secrets protected by the key
The key protects:
- passwords, keys and tokens of connections and credentials,
- SSH and SSL passwords and keys,
- the email (SMTP) password,
- Google, Microsoft Entra ID and OpenID Connect client secrets, and SAML signing certificates of your login methods,
- Microsoft Teams and Slack bot credentials,
- AI engine tokens.
Encryption settings
To manage the key, go to Settings > System Settings and open the Encryption tab.
The Current key field shows which key the Portal uses:
- Default key — the key built into Dataedo.
- Custom key — your own key. In this case the tab also shows:
- Key fingerprint — a short identifier of the key. It's not the key itself, so you can safely share it, for example to check which key an Agent uses.
- Key set in — where the Portal reads the key from: appsettings.json (Windows) or the Encryption__SecretKey environment variable (Docker).
- Online Agents — how many of the running Agents use the same key. Click View Agents to see them all.
Set your own key
Set the key on Windows
- In Settings > System Settings > Encryption, click Generate key.
- The Generate encryption key popup shows the new key and its fingerprint. Copy the key and store it somewhere safe. It won't be shown again.
- Set the key in every Agent and restart them. Do it now: once the Portal switches to the new key, Agents without it stop running tasks.
- Check I've saved the key and click Use key.
The Portal saves the key in its appsettings.json file, starts using it right away and re-encrypts all the existing secrets with it. You don't have to restart the Portal or enter any secret again.
Set the key in Docker
In Docker, the Portal can't save the key for you. You set it as the ENCRYPTION__SECRETKEY environment variable, so that both the Portal's API container and every Agent container get it.
-
In Settings > System Settings > Encryption, click Generate key.
-
The Generate encryption key popup shows the new key and its fingerprint. Copy the key and store it somewhere safe. It won't be shown again.
-
Check I've saved the key and click Done. The Encryption tab now shows that it's waiting for the key with the fingerprint you've just seen.
-
In the folder with your Dataedo Docker Compose files, open the
.envfile and add the key:.envENCRYPTION__SECRETKEY=<your key>The Dataedo Docker Compose files pass the
.envfile to both the Portal (backend) and the Agent (agent) containers. If you run Agents in a separate deployment, set the key there too. -
Recreate the containers, so they start with the new variable:
docker compose up -d --force-recreateinfodocker compose restartisn't enough. It restarts the containers with their old environment, so the key isn't picked up.
After the restart, the Encryption tab shows Custom key and the Portal re-encrypts the existing secrets with it.
Generate a key from the command line
You can also generate a key with the dataedo command-line tool. On Windows, it's located in the Portal's API folder (by default C:\Dataedo Web\Applications\API):
dataedo encryption generate-key
The command prints a new key and its fingerprint and changes nothing. Set the key in the Portal and in every Agent yourself, then restart them.
Set the key in Agents
Every Agent connected to the repository must use the same key as the Portal.
Agent on Windows:
- New Agent — when you install the Agent, paste the key into the Encryption key field next to the repository connection details. Leave it empty when the Portal uses the default key.
- Existing Agent — run the Agent Installer, choose Configure, select the Agent and click Change encryption key. Paste the key and finish the wizard. The Agent stays connected to the same repository and starts again with the new key.
When you upgrade an Agent, the installer keeps its current key.
Agent in Docker: set the ENCRYPTION__SECRETKEY variable for the Agent container and recreate it. If you use the Dataedo Docker Compose files, the Agent reads the same .env file as the Portal, so setting the key in Docker covers it.
Check which key the Agents use
Go to Settings > System Settings > Agent. Every Agent shows its Secret key status:
- OK — the Agent uses the same key as the Portal.
- Mismatch — the Agent has no key or a different one, so it can't read the secrets saved by the Portal. Hover over the status to compare the fingerprints, then set the right key in the Agent and restart it.
Rotate the key
Rotating replaces your key with a new one. Do it on a regular schedule, when someone who knew the key leaves the team, or as soon as you suspect the key has leaked. All secrets are re-encrypted with the new key, so nothing has to be entered again. After the rotation, the old key stops working, and every Agent needs the new one.
Rotate the key on Windows
- In Settings > System Settings > Encryption, click Rotate key.
- The Rotate encryption key popup shows the new key and the fingerprints of the new and the current key. Copy the new key and store it somewhere safe. It won't be shown again.
- Check I've saved the new key and click Rotate key.
The Portal re-encrypts all secrets with the new key and saves it in appsettings.json. Then set the new key in every Agent and restart them. Until you do, Agents with the old key don't run tasks.
Rotate the key in Docker
-
In Settings > System Settings > Encryption, click Rotate key.
-
The Rotate encryption key popup shows the new key and the fingerprints of the new and the current key. Copy the new key and store it somewhere safe. It won't be shown again.
-
Check I've saved the new key and click Rotate key. The Portal re-encrypts all secrets with the new key.
-
Finish the rotation in your containers right away. In the
.envfile, replace the value ofENCRYPTION__SECRETKEYwith the new key:.envENCRYPTION__SECRETKEY=<your new key> -
Recreate the Portal and Agent containers:
docker compose up -d --force-recreate
Don't leave the old key in the .env file. The running Portal already uses the new key, but containers started with the old one can't read the re-encrypted secrets.
Rotate the key from the command line
On Windows, you can also rotate the key with the dataedo tool from the Portal's API folder, for example as part of scheduled maintenance. Stop all Portals and Agents connected to the repository first, then run:
dataedo encryption rotate-key --confirm
The command prints the new key and its fingerprint before the rotation starts, re-encrypts every secret and saves the new key in the Portal's appsettings.json. To rotate to a key you've generated before, add --new-key <key>. Without --confirm, the command only explains what it would do.
Set the new key in every Agent, then start the Portals and the Agents.
Reset the encryption
Resetting the encryption makes the Portal go back to the default key. Use it when you no longer want a custom key, or when the key is lost.
A reset can't be undone. Secrets saved with the custom key aren't deleted, but they can't be read anymore.
- In Settings > System Settings > Encryption, click Reset encryption.
- Type Reset to confirm and click Reset encryption.
- Remove the key from the Portal's configuration:
- Windows — the Portal removes the key from appsettings.json for you.
- Docker — remove
ENCRYPTION__SECRETKEYfrom the.envfile and recreate the containers withdocker compose up -d --force-recreate. The Portal can't do it for you, and it uses the key again after a restart if the variable stays.
- Remove the key from every Agent and restart them.
- Enter the secrets listed in Secrets protected by the key again. Start with your login methods, so that users who sign in with SSO or email codes can get in.
Since resetting makes the stored secrets inaccessible, the following happens until you re-save them:
- imports, profiling and Data Quality checks fail for connections that use stored credentials,
- sign-in with Google, Microsoft Entra ID, OpenID Connect, SAML and email codes is blocked,
- email notifications aren't sent,
- Microsoft Teams and Slack bots and AI features stop working,
- Agents that still have the key stop running tasks until you remove it and restart them.
After the reset, Dataedo Desktop can connect to the repository again.
When the key doesn't match
If the Portal starts without the key the repository's secrets were encrypted with, or with a different one, it shows the Encryption key doesn't match banner. This happens, for example, when the Portal was reinstalled or moved to a new server and appsettings.json was replaced, or when the variable was left out of a new .env file.
The Portal keeps working, but nothing that needs the stored secrets does. Connections, credentials, login methods, integrations and AI engines whose secrets can't be read are marked with Enter secret again, and tasks that need them fail with a clear message instead of a connection error.
- If you have the key, set it in the Portal's configuration and restart the Portal:
-
Windows — in appsettings.json in the Portal's API folder, set the key in the
Encryptionsection, then restart the Portal's site in IIS:appsettings.json"Encryption": {
"SecretKey": "<your key>"
} -
Docker — set
ENCRYPTION__SECRETKEYin the.envfile and recreate the containers.
-
- If the key is lost, go to Settings > System Settings > Encryption and click Reset encryption. The popup lists the secrets you'll have to enter again. Type Reset to confirm and click Reset encryption.
Recover access when the key is lost
Several login methods depend on secrets encrypted with the key. When the key is lost, sign-in with Google, Microsoft Entra ID, OpenID Connect and SAML stops working, and so does sign-in with an email code, because the Portal can't send emails. If one of these was the only way you signed in, or the Portal redirects everyone straight to SSO, you can't get into the Portal to reset the encryption.
In that case, sign in with a database login instead:
-
Stop all Portals connected to the repository: the Portal's site in IIS on Windows, or the containers with
docker compose stopin Docker. -
Reset the encryption from the command line (Windows). Open a command prompt in the Portal's API folder and run:
dataedo encryption reset --confirmThe command makes the repository forget the lost key and removes the key from the Portal's appsettings.json. Without
--confirm, it only lists the secrets you'll have to enter again.In Docker, skip the command. If the
.envfile still has anENCRYPTION__SECRETKEYthat doesn't match, remove it. You'll reset the encryption in the Portal in step 5. -
Run the Grant Admin role script on the repository database. Besides giving your account the Admin role, it turns on the database login method, turns off the automatic redirect to SSO and releases your account from the login method it was bound to.
-
Start the Portal and sign in with the database login. The login page now shows the database login form instead of redirecting you to your identity provider.
-
Docker only: go to Settings > System Settings > Encryption and click Reset encryption.
-
Enter the secrets again, starting with the client secrets or certificates of your login methods and the SMTP password, so other users can sign in. Then you can set a new key.
-
Restore your sign-in method. Signing in with the database login bound your account to it. Once your SSO works again, change your account's login method in your user profile, otherwise you won't be able to sign in with SSO. If you used the automatic redirect to SSO, turn it on again.
Need help?
If you run into any problems or have questions, reach out to Dataedo support.