diff --git a/modules/ROOT/assets/images/int-global-elements-panel-list.png b/modules/ROOT/assets/images/int-global-elements-panel-list.png new file mode 100644 index 000000000..21e65ee52 Binary files /dev/null and b/modules/ROOT/assets/images/int-global-elements-panel-list.png differ diff --git a/modules/ROOT/assets/images/int-secure-properties-form-editor.png b/modules/ROOT/assets/images/int-secure-properties-form-editor.png new file mode 100644 index 000000000..7c13ad47d Binary files /dev/null and b/modules/ROOT/assets/images/int-secure-properties-form-editor.png differ diff --git a/modules/ROOT/assets/images/int-secure-properties-overview-diagram.png b/modules/ROOT/assets/images/int-secure-properties-overview-diagram.png new file mode 100644 index 000000000..24958a77e Binary files /dev/null and b/modules/ROOT/assets/images/int-secure-properties-overview-diagram.png differ diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 83357c7bb..fe5935259 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -51,6 +51,7 @@ ** xref:vibes-skills.adoc[] ** xref:vibes-api-ai-create-spec.adoc[] ** xref:vibes-create-integrations.adoc[] +** xref:vibes-secure-properties.adoc[] ** xref:vibes-run-multiple-integration-projects-locally.adoc[] ** xref:vibes-prompt-examples.adoc[] ** xref:troubleshoot-generative-ai.adoc[] diff --git a/modules/ROOT/pages/int-create-secure-configs.adoc b/modules/ROOT/pages/int-create-secure-configs.adoc index dc83fdd91..a138a2902 100644 --- a/modules/ROOT/pages/int-create-secure-configs.adoc +++ b/modules/ROOT/pages/int-create-secure-configs.adoc @@ -13,6 +13,10 @@ Define configuration properties to secure and customize your Mule application co * Define and use variables instead of literal strings when setting values in the configuration XML. * Configure a variable for selecting different property files for a specific deployment environment, such as development, sandbox, or production. +.How secure properties work +image::int-secure-properties-overview-diagram.png[Diagram showing secure properties flow from runtime argument to global-configs.xml to encrypted properties file to flow references] + +For a guided, conversational approach to setting up secure properties, use MuleSoft Vibes. For additional information, see xref:vibes-secure-properties.adoc[]. == Before You Begin @@ -241,6 +245,19 @@ my-key-value \ ---- + IMPORTANT: Store your encryption key value (password) in a secure location. You'll need your key value later, when you deploy your application. ++ +TIP: To verify an encrypted value, decrypt it using the same tool with the `decrypt` command instead of `encrypt`: ++ +[source,terminal] +---- +$ java -cp secure-properties-tool.jar com.mulesoft.tools.SecurePropertiesTool \ +string \ +decrypt \ +Blowfish \ +CBC \ +my-key-value \ +"/MU0/xB/zoMPjxBA7/9X44Ad2H8O8AY5" +---- . In your properties file, add each encrypted property value within `![]` brackets. + .Example that replaces the unencrypted value `"mysensitivevalue"` with the encrypted value `"![/MU0/xB/zoMPjxBA7/9X44Ad2H8O8AY5]"`: @@ -442,6 +459,55 @@ This name serves as the key for the encryption value (password) used to encrypt + Notice the `secure::` prefix to the key. +[[edit-via-ui]] +== Edit Secure Properties Configuration via Global Elements + +Instead of manually editing your project's XML, you can configure secure properties through Global Elements. + +To edit the secure properties configuration: + +. Open *Project Properties* > *Global Elements*. ++ +image:int-global-elements-panel-list.png["Global Elements panel with list of configurations including Secure Properties Config."] ++ +. Select *global-configs.xml* from the *Selected File* dropdown. +. Find *Secure Properties Config* in the list. +. Click the *...* menu (three dots) next to the configuration name. +. Click *Edit*. + +The editor opens and you can modify these fields. + +image::int-secure-properties-form-editor.png["Form editor showing configurable fields for Secure Properties Config.", 75%, 75%] + +[%header,cols="20a,30a,50a"] +|=== +| Field | Example Value | What It Controls + +| *Name* +| Secure_Properties_Config +| Element name referenced internally + +| *File* +| ${env}.secure.properties +| Which encrypted file to load (resolves per environment) + +| *Key* +| ${encryption.key} +| The decryption key placeholder (resolved from system property) + +| *Algorithm* +| AES +| Encryption algorithm (AES, Blowfish, DES, DESede, RC2) + +| *Mode* +| CBC +| Cipher mode (CBC, CFB, ECB, OFB) +|=== + +Changes you make in the editor automatically update the XML in `global-configs.xml`. + +The editor manages the configuration element. To change the actual encrypted values in `.secure.properties` files, use the secure-properties-tool JAR, edit the file directly, or ask MuleSoft Vibes to re-encrypt values. See xref:vibes-secure-properties.adoc[]. + [[test-deploy]] == Test Encrypted Properties in Your IDE @@ -669,8 +735,46 @@ image::deploy-to-cloudhub-icon-with-deploy-json.png["Deploy to CloudHub rocket i + You can create properties or change the value of existing properties, for example, to fix some deployment errors. +[[quick-reference]] +== Quick Reference + +Use this table for quick access to common secure properties tasks and commands: + +[%header,cols="30a,70a"] +|=== +| Task | Command / Location + +| Encrypt a value +| `java -cp secure-properties-tool.jar com.mulesoft.tools.SecurePropertiesTool string encrypt AES CBC ` + +| Decrypt a value +| `java -cp secure-properties-tool.jar com.mulesoft.tools.SecurePropertiesTool string decrypt AES CBC ` + +| Reference encrypted property in XML +| `${secure::property.name}` + +| Reference non-encrypted property in XML +| `${property.name}` + +| Secure properties config element +| `` + +| Pass encryption key locally +| Add `-M-Dencryption.key=YourKey` to `mule.runtime.args` in `launch.json` + +| Pass encryption key in CloudHub +| Add to Properties tab in Runtime Manager: `encryption.key=YourKey` + +| Switch environment +| Pass `-M-Denv=qa` or `-M-Denv=prod` as runtime argument + +| Hide encryption key in CloudHub +| Add encryption key name to `secureProperties` array in `mule-artifact.json` +|=== + == See Also +* xref:vibes-secure-properties.adoc[] * xref:int-global-config-elements.adoc[] -* xref:mule-runtime::secure-configuration-properties.adoc[] * xref:int-run-mule-apps-with-properties.adoc[] +* xref:mule-runtime::secure-configuration-properties.adoc[] diff --git a/modules/ROOT/pages/int-run-mule-apps-with-properties.adoc b/modules/ROOT/pages/int-run-mule-apps-with-properties.adoc index 5eb4c9985..bd6a1d967 100644 --- a/modules/ROOT/pages/int-run-mule-apps-with-properties.adoc +++ b/modules/ROOT/pages/int-run-mule-apps-with-properties.adoc @@ -260,10 +260,164 @@ Reference these properties in your database configuration: ---- +[[shared-encryption-keys-workspace]] +== Configure Shared Encryption Keys Across a Workspace + +When you have multiple Mule projects in the same workspace that use the same encryption key, configure it once at the workspace level instead of duplicating it in each project's launch.json. + +Use the approach that better applies to your workflow and security requirements. + +* <>: Configure the encryption key in + your workspace settings.json. All projects inherit the setting + automatically. + +* <>: Store the key as an OS environment variable + in your shell profile. Use this method to keep + encryption keys completely out of version-controlled files or if you need + machine-specific configuration. + +* <>: Configure the encryption key directly in a + .code-workspace file. Use this approach when working with + multiple Mule projects open simultaneously in a multi-root + workspace. For information about multi-root workspaces, see + [link to VS Code docs or existing ACB topic]. + +[[workspace-settings-approach]] +=== Use Workspace Settings + +Add the encryption key to your workspace `settings.json` so all projects inherit it. + +. In your `.code-workspace` file or `.vscode/settings.json` at the workspace root, add the key. ++ +[source,json] +---- +{ + "settings": { + "mule.runtime.defaultArguments": "-M-Dencryption.key=MuleSecureKey024" + } +} +---- ++ +. Reference the shared setting in each project's `launch.json`. ++ +[source,json] +---- +{ + "mule.runtime.args": "${config:mule.runtime.defaultArguments}" +} +---- + +[[environment-variable-approach]] +=== Use an Environment Variable + +Set the key as an OS environment variable in your shell profile (`~/.zshrc` or `~/.bash_profile`) + +. Run this command. ++ +[source,bash] +---- +export MULE_ENCRYPTION_KEY="MuleSecureKey024" +---- ++ +. Reference the key in the workspace `launch.json`: ++ +[source,json] +---- +{ + "version": "0.2.0", + "configurations": [ + { + "type": "mule-xml-debugger", + "request": "launch", + "name": "Debug with Environment Variable", + "mule.project": "${workspaceFolder}", + "mule.home": "${config:mule.homeDirectory}", + "mule.runtime.args": "${config:mule.runtime.defaultArguments} -M-Dencryption.key=${env:MULE_ENCRYPTION_KEY}" + } + ] +} +---- + +[[multi-root-workspace-approach]] +=== Use a Shared Launch Configuration in Multi-Root Workspaces + +To configure a shared encryption key in a multi-root workspace: + +. Open or create your `.code-workspace` file. +. Add a `launch` section to the workspace configuration with the + encryption key: ++ +[source,json] +---- +{ + "folders": [ // <1> + { "path": "salesforce-sync" }, + { "path": "netsuite-integration" }, + { "path": "slack-notifications" } + ], + "launch": { // <2> + "configurations": [ + { + "type": "mule-xml-debugger", + "request": "launch", + "name": "Run Mule App (Shared Key)", // <3> + "noDebug": true, + "mule.projects": ["${workspaceFolder}"], + "mule.runtime.args": "${config:mule.runtime.defaultArguments} -M-Dencryption.key=MuleSecureKey024" // <4> + } + ] + } +} +---- +<1> List the relative paths to each Mule project in your workspace +<2> Add the launch configuration section with the shared encryption key +<3> Name that appears in the Run and Debug dropdown +<4> Replace `MuleSecureKey024` with your encryption key ++ +. Save the workspace file. + +When you select *Run Mule App (Shared Key)* from the Run and Debug +dropdown, Code Builder applies the shared encryption key to whichever +project is active. + +=== Protect Workspace Configuration in .gitignore + +If your workspace settings contain sensitive values, add them to `.gitignore`: + +[source,gitignore] +---- +# Workspace config (may contain encryption key) +*.code-workspace +.vscode/settings.json +---- + +[[key-rotation-workspace]] +=== Re-encrypt All Projects After Key Rotation + +When you rotate the shared key, re-encrypt every secure properties file across all projects: + +[source,bash] +---- +NEW_KEY="NewSharedKey2025!" + +# For each project in the workspace: +for project in salesforce-sync netsuite-integration slack-notifications; do + FILE="$project/src/main/resources/prod.secure.properties" + if [ -f "$FILE" ]; then + echo "Re-encrypting: $FILE" + # Decrypt each value with old key, re-encrypt with new key + # (or use a local backup file with plaintext to re-encrypt) + fi +done +---- + +Then update the single workspace-level key reference and all projects work immediately. + == See Also * xref:int-create-secure-configs.adoc[] * xref:int-run-multiple-mule-apps.adoc[] -* xref:ref-mule-settings.adoc#setting-mule-args[] +* xref:ref-mule-settings.adoc#setting-mule-args[Mule › Runtime: Default Arguments] * xref:int-global-config-elements.adoc[] +* xref:start-workspaces.adoc[] * xref:mule-runtime::configuring-properties.adoc[] diff --git a/modules/ROOT/pages/vibes-secure-properties.adoc b/modules/ROOT/pages/vibes-secure-properties.adoc new file mode 100644 index 000000000..6335e9725 --- /dev/null +++ b/modules/ROOT/pages/vibes-secure-properties.adoc @@ -0,0 +1,189 @@ += Working with Secure Properties Using MuleSoft Vibes +:page-deployment-options: cloud-ide, desktop-ide + +include::reuse::partial$beta-banner.adoc[tag="anypoint-code-builder"] + +Instead of manually creating files and editing XML, use MuleSoft Vibes to set up secure properties conversationally. MuleSoft Vibes can automatically encrypt values, create configuration files, update XML, and validate your setup. + +For information about secure properties concepts and manual configuration, see xref:int-create-secure-configs.adoc[]. + +.How secure properties work +image::int-secure-properties-overview-diagram.png[Diagram showing secure properties flow from runtime argument to global-configs.xml to encrypted properties file to flow references] + +[[setup-from-scratch]] +== Set Up Secure Properties from Scratch + +To set up secure properties, send a message to MuleSoft Vibes that asks to configure secure properties for your credentials and specifies the encryption algorithm to use. + +For example: + +---- +Set up secure properties for my Salesforce credentials using AES/CBC encryption +---- + +MuleSoft Vibes: + +* Adds the `mule-secure-configuration-property-module` dependency to `pom.xml` +* Adds the `` element to `global-configs.xml` +* Adds the required namespace and schema location +* Updates connector configurations to use `${secure::}` references +* Creates the `.secure.properties` file structure + +[[encrypt-value]] +== Encrypt a Value + +To encrypt a specific value, send a message to MuleSoft Vibes that includes the value to encrypt, your encryption key, and the algorithm to use. + +For example: + +---- +Encrypt the value 'MyPassword123' using my encryption key MuleSecureKey024 with AES CBC +---- + +MuleSoft Vibes runs the secure-properties-tool and returns the encrypted value ready to paste into your properties file. + +[[add-credential]] +== Add a New Credential to an Existing Setup + +To add a new encrypted property, send a message to MuleSoft Vibes that specifies the property name and value to encrypt. + +For example: + +---- +Add a new secure property called 'netsuite.password' with the value 'NS-Prod-Pass!' to my secure properties files +---- + +MuleSoft Vibes encrypts the value and adds it to the appropriate `.secure.properties` file. + +[[convert-plaintext]] +== Switch from Plaintext to Secure + +To convert existing plaintext credentials to secure properties, send this message to MuleSoft Vibes: + +---- +Convert all the plaintext Salesforce credentials in my project to use secure properties +---- + +MuleSoft Vibes: + +* Scans for hardcoded or plaintext credential values +* Encrypts each value +* Moves them to `.secure.properties` files +* Updates XML references from `${salesforce.password}` to `${secure::salesforce.password}` + +[[multi-environment-setup]] +== Set Up Multi-Environment Secure Properties + +To create environment-specific secure properties files, send a message to MuleSoft Vibes that specifies the environment name and requests the `${env}.secure.properties` pattern. + +For example: + +---- +Create a secure properties file for prod with the ${env}.secure.properties pattern +---- + +MuleSoft Vibes creates the environment-specific file and configures the dynamic file reference in `global-configs.xml`. + +For more information about multi-environment configuration, see xref:int-create-secure-configs.adoc#create-prop-file[]. + +[[validate-setup]] +== Validate Your Setup + +To check if your secure properties are configured correctly, send this message to MuleSoft Vibes: + +---- +Check if my secure properties are configured correctly +---- + +MuleSoft Vibes validates: + +* The dependency is in `pom.xml` +* The `` element exists with the correct namespace +* Referenced keys exist in the `.secure.properties` files +* The encryption key is configured in `launch.json` for local runs + +[[rotate-key]] +== Rotate the Encryption Key + +To change your encryption key and re-encrypt all values, send a message to MuleSoft Vibes that specifies the old key, the new key, and asks to re-encrypt all values. + +For example: + +---- +Rotate my encryption key from MuleSecureKey024 to NewSecureKey2025 and re-encrypt all values +---- + +MuleSoft Vibes: + +* Decrypts all values with the old key +* Re-encrypts with the new key +* Updates all `.secure.properties` files +* Updates `launch.json` with the new key + +[[vibes-skills]] +== Skills MuleSoft Vibes Uses + +When you ask MuleSoft Vibes to work with secure properties, it invokes specialized skills that handle the tasks: + +[%header,cols="30a,70a"] +|=== +| Skill | What It Does + +| *Secure Mule App* + +(`/secure-mule-app`) +| Scans for sensitive data, encrypts values using the secure-properties-tool JAR, creates `.secure.properties` files, updates XML with `${secure::}` references, adds the `pom.xml` dependency, and configures `launch.json`. + +| *Manage Global Configurations* + +(`/manage-global-configurations`) +| Creates the `` element in `global-configs.xml`, manages namespaces, handles the `${env}.secure.properties` multi-environment pattern, and validates the build. + +| *Build Mule Integration* + +(`/build-mule-integration`) +| When generating new flows that need credentials, automatically includes secure property placeholders and wires up the secure config element. +|=== + +These skills work together. For example, when you say "convert my plaintext credentials to secure properties," MuleSoft Vibes uses *Secure Mule App* to encrypt and create the files, then *Manage Global Configurations* to wire up the XML config element and validate everything builds. + +For more information about skills in MuleSoft Vibes, see xref:vibes-skills.adoc[]. + +[[common-prompts]] +== Common MuleSoft Vibes Prompts for Secure Properties + +Use these example prompts to work with secure properties: + +[%header,cols="30a,70a"] +|=== +| What You Want | What to Ask MuleSoft Vibes + +| Initial setup +| "Set up secure properties for this project" + +| Encrypt a single value +| "Encrypt 'my-secret' with key X using AES CBC" + +| Add credentials +| "Add encrypted DB credentials to my secure properties" + +| Convert plaintext +| "Move my hardcoded passwords to secure properties" + +| Production setup +| "Create a prod secure properties file" + +| Check configuration +| "Validate my secure properties setup" + +| Debug issues +| "Why is my secure property not resolving?" + +| Key rotation +| "Rotate my encryption key to a new value" +|=== + +== See Also + +* xref:int-create-secure-configs.adoc[] +* xref:int-global-config-elements.adoc[] +* xref:vibes-skills.adoc[] +* xref:mulesoft-vibes.adoc[] +* xref:vibes-get-started.adoc[]