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.

In the Microsoft Entra admin center, add a new client secret to the MetaMiner app registration. Copy its value. See Client Secret.
In MMA, select the Power BI environment and click Edit.
Replace Client Secret with the new value.
Click Test Connection and wait for the validation to pass.
Save the environment and restart the MetaMiner Server when MMA offers it.
Check that the next pull completes. See Collection Status.
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¶

In MMA, open the Security menu and click Encrypt Config.... The item is shown only while the configuration is not encrypted.
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
MMA shows Config was successfully encrypted!.
Close MMA and restart the MetaMiner Server service.
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.
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¶

Start MMA. The password prompt appears.
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¶

server\config\config.json shows no secret in plain text. Secret values are unreadable strings.
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.