Secure Credential Storage for Firewall for Artifactory

Starting with Firewall for Artifactory plugin version 2.7.5, you can encrypt IQ Server and proxy credentials stored in firewall.properties. Existing plaintext configurations remain supported after upgrade, and migration to encrypted credential storage is optional.

For information about other available plugin properties, see Firewall for Artifactory Configuration.

Keep Plaintext Credentials

For plaintext authentication, the plugin reads the configured values directly from firewall.properties and uses them to connect to IQ Server.

For example:

firewall.iq.url=<IQ_SERVER_URL>
firewall.iq.username=<IQ_SERVER_USERNAME>
firewall.iq.password=<IQ_SERVER_PASSWORD>

If you use an HTTP proxy, the following properties can also contain plaintext credentials:

firewall.iq.proxy.username=<PROXY_USERNAME>
firewall.iq.proxy.password=<PROXY_PASSWORD>

If you keep plaintext credentials, you do not need to change your configuration after upgrading. You do not need to add firewall.iq.encryptionFormat or firewall.iq.encryptedFields to firewall.properties. A key file and the credential tool are also not required.

Enable Encrypted Credentials

You can encrypt the following properties:

firewall.iq.username
firewall.iq.password
firewall.iq.proxy.username
firewall.iq.proxy.password

The plugin decrypts only the properties listed in firewall.iq.encryptedFields. All other properties are read as plaintext.

You can encrypt one or more supported properties while leaving the remaining properties as plaintext.

Important

For HA deployments, follow Recommended Deployment Order for HA Environments. Keep credentials in plaintext while you make the same encryption key available and load the JVM key-file argument on every node. Add encrypted values to firewall.properties only after every node is ready; configuration changes can synchronize to other nodes.

Before You Begin

Before enabling encrypted credential storage, ensure that you have:

JFrog Artifactory 7.125.18 or later.
Java 17 or later on the Artifactory host. The credential tool searches for Java in JAVA_HOME, under JFROG_HOME, and then on the system PATH.
The extracted plugin distribution. Keep firewall-credential-tool.sh and lib/nexus-iq-artifactory-plugin.jar in their original relative locations. The script does not run if the JAR file is missing.
A secure location for the key file outside any directory served or replicated by Artifactory.
A key file that the account running Artifactory can read.

The bundled credential tool uses Java and does not require additional external dependencies. OpenSSL is optional.

Note

On Windows, you can run firewall-credential-tool.sh in Git Bash if Git for Windows is installed. Git Bash is not included with Windows. The script requires Java, and lib/nexus-iq-artifactory-plugin.jar must remain in its original relative location within the same extracted plugin directory.

You can also run the bundled credential tool directly with Java from Command Prompt or PowerShell:

java -cp lib\nexus-iq-artifactory-plugin.jar com.sonatype.iq.artifactory.crypto.CredentialTool setup C:\secure\path\firewall-aes.key

Windows does not include OpenSSL or chmod by default. Use Windows file permissions to restrict access to the key file while ensuring that the Artifactory service account can read it.

Use the Credential Tool

The firewall-credential-tool.sh script launches the bundled credential tool, which performs the key-generation and encryption operations.

Command	Description
`setup <keyfile>`	Generates or reuses the key, prompts for a credential, encrypts it, and prints the required `firewall.properties` entries and JVM argument.
`genkey <keyfile>`	Generates a 32-byte AES-256 key file and refuses to overwrite an existing file. On Windows, set key-file permissions manually.
`encrypt <keyfile>`	Prompts for a credential and prints the encrypted value to add to `firewall.properties`.
`verify <keyfile> <value>`	Verifies that an encrypted value can be decrypted using the specified key.

Important

You can also use OpenSSL to create the encryption key. However, you must use the bundled credential tool to generate encrypted credential values because the plugin requires the format produced by that tool.

Quick Start

The setup command provides the quickest way to configure encrypted credential storage. It generates or reuses the encryption key, prompts for a credential, encrypts it, and prints the required firewall.properties entries and JVM argument.

On Linux or macOS, run the following command from the extracted plugin directory:

./firewall-credential-tool.sh setup /secure/path/firewall-aes.key

On Windows, run the following command from the extracted plugin directory in Command Prompt or PowerShell:

java -cp lib\nexus-iq-artifactory-plugin.jar com.sonatype.iq.artifactory.crypto.CredentialTool setup C:\secure\path\firewall-aes.key

Enter the credential at the prompt, apply the printed configuration, and then restart Artifactory.

To generate the key and encrypt credentials separately, follow the manual procedure.

Configure Encrypted Credentials Manually

Create the key file with OpenSSL or the bundled credential tool. OpenSSL can be used on Linux, macOS, or Windows when installed.
Linux or macOS — OpenSSL:
```
openssl rand -base64 32 > /secure/path/firewall-aes.key
```
Linux or macOS — bundled credential tool:
```
./firewall-credential-tool.sh genkey /secure/path/firewall-aes.key
```
Windows PowerShell — OpenSSL, if installed:
```
openssl rand -base64 -out C:\secure\path\firewall-aes.key 32
```
In Windows PowerShell 5.1, > writes UTF-16LE, which the plugin cannot read as a Base64 key file. The -out option lets OpenSSL write the file directly and works across PowerShell versions.
Windows PowerShell or Command Prompt — bundled credential tool:
```
java -cp lib\nexus-iq-artifactory-plugin.jar com.sonatype.iq.artifactory.crypto.CredentialTool genkey C:\secure\path\firewall-aes.key
```
The bundled credential tool refuses to overwrite an existing key file.
On systems with chmod, you can restrict access to the key file:
```
chmod 600 /secure/path/firewall-aes.key
```
Keep the key-file permissions restricted while ensuring that the Artifactory service account can read the key. On Windows, use Windows file permissions.
Encrypt the credential using the bundled credential tool so that the encrypted value uses the format expected by the plugin.
On Linux or macOS, run:
```
./firewall-credential-tool.sh encrypt /secure/path/firewall-aes.key
```
On Windows, run the following command from the extracted plugin directory:
```
java -cp lib\nexus-iq-artifactory-plugin.jar com.sonatype.iq.artifactory.crypto.CredentialTool encrypt C:\secure\path\firewall-aes.key
```
Enter the credential at the prompt. The command prints one encrypted value.
To verify an encrypted value on Linux or macOS, run:
```
./firewall-credential-tool.sh verify /secure/path/firewall-aes.key <ENCRYPTED_VALUE>
```
To verify an encrypted value on Windows, run:
```
java -cp lib\nexus-iq-artifactory-plugin.jar com.sonatype.iq.artifactory.crypto.CredentialTool verify C:\secure\path\firewall-aes.key <ENCRYPTED_VALUE>
```
Repeat the encryption command for each credential property you want to encrypt.

Add the encrypted value to firewall.properties.

The following example encrypts only the IQ Server password:

firewall.iq.username=<IQ_SERVER_USERNAME>
firewall.iq.password=<ENCRYPTED_VALUE>
firewall.iq.encryptionFormat=AES_GCM
firewall.iq.encryptedFields=firewall.iq.password

Replace <ENCRYPTED_VALUE> with the output from the credential tool.

If firewall.iq.encryptedFields already exists, append firewall.iq.password to its comma-separated list.

To encrypt another supported property, run the encryption command again, add the generated value as the property value, and add the property name to firewall.iq.encryptedFields.

For example, the following configuration encrypts all four supported credential properties:

firewall.iq.username=<ENCRYPTED_USERNAME_VALUE>
firewall.iq.password=<ENCRYPTED_PASSWORD_VALUE>
firewall.iq.proxy.username=<ENCRYPTED_PROXY_USERNAME_VALUE>
firewall.iq.proxy.password=<ENCRYPTED_PROXY_PASSWORD_VALUE>
firewall.iq.encryptionFormat=AES_GCM
firewall.iq.encryptedFields=firewall.iq.username,firewall.iq.password,firewall.iq.proxy.username,firewall.iq.proxy.password

Add the following argument to the Artifactory JVM launch options:
```
-Dfirewall.iq.encryptionKeyFile=/secure/path/firewall-aes.key
```
For example, you can add the argument to JF_SHARED_EXTRA_JAVA_OPTS.
Replace /secure/path/firewall-aes.key with the path to your encryption key file.
Restart JFrog Artifactory to load the JVM argument and updated configuration.
Note
In a high-availability deployment, the key file must be available on every Artifactory node at the path specified by the JVM argument.

Recommended Deployment Order for HA Environments

Each Artifactory node must be able to read the same encryption key at the path specified by -Dfirewall.iq.encryptionKeyFile.

To enable encrypted credentials in a high-availability deployment:

Back up the current firewall.properties file before changing it.
Generate the key once using the preceding instructions. Make the same key file available at the same path on every node, and keep a secure backup.
On Linux or macOS, you can restrict access to the key on each node:
```
chmod 600 /secure/path/firewall-aes.key
```
If you use this command, make the Artifactory service account the file owner. On Windows, grant the Artifactory service account read access to the key file.
Keep firewall.properties in plaintext while you set the JVM key-file argument and restart each node to load it.
Because configuration changes can be synchronized to other HA nodes, ensure that every node has restarted and can read the key file before adding encrypted values.
Configure encrypted credentials using the preceding instructions after every node has the key and JVM argument.
Ensure that the updated firewall.properties file is available on every node, and then reload the Firewall plugin on each node.
Check the IQ Server connection on every node. A successful connection on one node does not confirm that the other nodes have the correct key.
Important
Do not generate a separate encryption key for each node. A node with a missing or different key cannot decrypt the configured credentials.

What to Avoid When Upgrading to Encrypted Credentials

Enabling encryption before the key is available on every node: Distribute the same key and configure the JVM argument on each node first.
Pasting encrypted output into a REST API credential update: Use the bundled credential tool’s encrypted output only when editing firewall.properties directly. Submit the plaintext credential through the REST API; the plugin encrypts it before saving.
Losing the key: Keep a secure backup. Encrypted credential values cannot be recovered without the key.
Editing firewall.properties without reloading the plugin: Reload the Firewall plugin so that it uses the updated credentials. Adding or changing the key-file JVM argument requires an Artifactory restart.

Update Encrypted Credentials Through the REST API

When encrypted credential storage is enabled, you can submit new credential values through the following endpoints:

addOrUpdateFirewallProperties
setFirewallProperties

When you submit a new value for an encrypted property, the plugin encrypts the value before saving it. The encryption key must be available and readable.

If the plugin cannot load the key, it rejects the request with HTTP 409 Conflict, and no changes are saved. Restore the correct key file and resubmit the request.

Note

If the key file was missing or unreadable at startup, restore it, and then reload the plugin or update its configuration to reconnect to IQ Server. An Artifactory restart is not required.

Submitted Value	Result
A new value when the key is available	The value is encrypted and saved. HTTP `204`.
A new value when the key is missing or unreadable	The request is rejected. HTTP `409`; no changes are saved.

For information about the available endpoints, see JFrog Artifactory Plugin Configuration REST API.

Troubleshoot Encrypted Credential Storage

Switch Back to Plaintext Credentials

To stop using encrypted credential storage, replace the encrypted values with plaintext credentials. Removing the encryption settings alone does not decrypt the stored values.

Obtain the IQ Server username and password and any proxy credentials that you use.
If the key is lost, the encrypted values cannot be recovered from firewall.properties.
In firewall.properties, replace each encrypted credential value with its plaintext value.
Remove firewall.iq.encryptionFormat and firewall.iq.encryptedFields, or set both properties to empty values.
The following example shows the configuration after switching back to plaintext credentials. Other properties are omitted:
```
firewall.iq.url=<IQ_SERVER_URL>
firewall.iq.username=<IQ_SERVER_USERNAME>
firewall.iq.password=<IQ_SERVER_PASSWORD>
```
If you use an authenticated proxy, restore firewall.iq.proxy.username and firewall.iq.proxy.password to their plaintext values.
Reload the Firewall plugin after saving firewall.properties, and then check the IQ Server connection.
In an HA deployment, check the connection on every node. An Artifactory restart is not required to return to plaintext credentials.

The existing JVM key-file argument can remain in place because it does not affect plaintext authentication. You can remove the argument during a later planned restart.

Protect firewall.properties appropriately because it now contains plaintext credentials.

Recover from a Lost Encryption Key

If the key is lost and you want to continue using encrypted credential storage, retrieve or reset the IQ Server credentials and any proxy credentials.

Existing encrypted values cannot be recovered without the original key. Generate a new key and repeat the encryption procedure for every property listed in firewall.iq.encryptedFields.