Skip to content

Secrets and Configuration Encryption

How MetaMiner protects the client secret and other passwords at rest, how to encrypt the whole server configuration, and how to rotate the client secret.

How it works

The MetaMiner Server (MMS) keeps its configuration in server\config\config.json. Every secret in that file is stored encrypted, always:

Secret Entered in
Client secret of each Power BI environment's app registration MetaMiner Administrator (MMA) environment dialog
MetaMiner Database account password Configure MMDB
LDAP bind account password Preferences > Settings... > System
SMTP account password Preferences > Settings... > Email
MetaMiner Server SSL key password Configure SSL

The MMS decrypts a secret only in memory, when it needs it. The client secret is used only to request tokens from Microsoft Entra ID. Microsoft access tokens are kept in memory and never written to disk on the server.

You can add a second layer: Encrypt Config encrypts the whole configuration file with a password you choose.

Encryption is one layer. Keep NTFS permissions on server\config limited to administrators and the MetaMiner service account.

Rotate the client secret

Create the new secret before the old one expires, so the pull does not stop.

  1. In the Microsoft Entra admin center, add a new client secret to the MetaMiner app registration. Copy its value. See Client Secret.
  2. In MMA, select the Power BI environment and click Edit.
  3. Replace Client Secret with the new value.
  4. Click Test Connection and wait for the validation to pass.
  5. Save the environment and restart the MetaMiner Server when MMA offers it.
  6. Check that the next pull completes. See Collection Status.
  7. Delete the old secret in the Microsoft Entra admin center.

Image of the Edit Power BI environment dialog with the Client Secret field masked and Test Connection showing success

../images/security/mma-edit-pbi-client-secret.png

Never share the secret by e-mail

Your own administrator can enter the secret in MMA directly. If someone else must enter it, use a one-time secret link or another channel your policy approves.

Encrypt the configuration file

Encrypt Config encrypts the whole configuration file:

File Purpose
config\config.ecf The encrypted configuration. MetaMiner reads it instead of config.json
config\config.ek Key file that lets the MetaMiner Server service start without anyone typing the password
MetaMinerServer.properties Gets the entry use.encrypted.config=true

From then on, MMA asks for the configuration password each time it starts. The MetaMiner Server service starts unattended as before.

Before you begin

  • Run MMA on the MetaMiner Server host as a Windows administrator.
  • Back up the server\config folder and MetaMinerServer.properties.
  • Choose a password and store it in your password vault. If the password is lost, the configuration cannot be opened in MMA and you must configure MetaMiner again.

Steps

  1. In MMA, open the Security menu and click Encrypt Config.... The item is shown only while the configuration is not encrypted.

  2. In Encrypt Config, enter the password and confirm it.

    Image of the Encrypt Config password dialog with the warning about losing the password

    ../images/security/mma-encrypt-config.png

  3. MMA shows Config was successfully encrypted!.

  4. Close MMA and restart the MetaMiner Server service.
  5. Move the earlier plain-text config\config.json and its backup copies (config.json.back_*) to protected storage, or delete them once you have confirmed step 6.
  6. Start MMA. It shows Config is Encrypted and asks for the password.

TODO: confirm step 5

Confirm that MetaMiner no longer reads config.json or writes plain-text backups once use.encrypted.config=true, so customers can safely remove them.

Start MMA with an encrypted configuration

  1. Start MMA. The password prompt appears.
  2. Enter the configuration password and click OK. Click Exit to close MMA without changes.

Do not click Cancel unless you want to start over

Cancel asks Are you sure to erase current config?. If you confirm, MMA erases the current configuration and encrypts a new, empty one with a new password. Click Cancel only to rebuild the configuration from scratch.

If you see Incorrect password or decryption failure, check the password and try again.

What changes with an encrypted configuration

  • MMA writes the configuration file directly instead of sending changes to the running MetaMiner Server. Restart the MetaMiner Server after you change settings.
  • Some environment settings cannot be edited while the MetaMiner Server is running. Stop the server, edit, then start it.

TODO: document how to turn encryption off

MMA has no menu item to decrypt the configuration in this release. Product team to confirm the supported procedure.

Secrets on workstations

Item Where Protection How to remove
Microsoft sign-in token cache %APPDATA%\MetaMiner\auth\pbi-token-cache.bin Windows DPAPI, readable only by that Windows user on that computer Sign out of Power BI in the MetaMiner Client
MetaMiner password with Remember password %APPDATA%\MetaMiner\config\ Encrypted File > Forget Credentials...

The Microsoft password itself is never stored; Microsoft handles it in its own sign-in page. If an administrator revokes the user's sessions or the app's consent, the cached token stops working and the user must sign in again.

Verify

  1. server\config\config.json shows no secret in plain text. Secret values are unreadable strings.
  2. With encryption on: config\config.ecf and config\config.ek exist, MetaMinerServer.properties contains use.encrypted.config=true, and MMA asks for the password at start.

Troubleshooting

MMA starts without asking for a password

MMA was not started from its shortcut, so it did not read MetaMinerServer.properties. Start MMA from the MetaMiner Administrator shortcut or MetaMinerAdmin.exe in the server folder.

Encrypt Config... is missing from the Security menu

The configuration is already encrypted.

The pull stops after the client secret expired

Rotate the secret as described above. Validation in MMA shows an authentication error until the new secret is saved.

Next steps