From a566662958b54dfad91dd2ccc1fde8807c97d4b5 Mon Sep 17 00:00:00 2001 From: BiyonFernando Date: Wed, 2 Oct 2024 10:35:20 +0530 Subject: [PATCH 1/2] Add Harshicrop Vault integration to docs --- .../harshicrop-vault-extension.md | 293 ++++++++++++++++++ en/mkdocs.yml | 1 + 2 files changed, 294 insertions(+) create mode 100644 en/docs/install-and-setup/setup/security/logins-and-passwords/harshicrop-vault-extension.md diff --git a/en/docs/install-and-setup/setup/security/logins-and-passwords/harshicrop-vault-extension.md b/en/docs/install-and-setup/setup/security/logins-and-passwords/harshicrop-vault-extension.md new file mode 100644 index 0000000000..09e841b13f --- /dev/null +++ b/en/docs/install-and-setup/setup/security/logins-and-passwords/harshicrop-vault-extension.md @@ -0,0 +1,293 @@ + +# Integrate with HashiCorp Vault + +Using [HashiCorp Vault extension](https://github.com/wso2-extensions/carbon-securevault-hashicorp/tree/master), you can set up HashiCorp Vault to store passwords that are mapped to aliases instead of the actual passwords. When setting up Harshicrop Vault with APIM you can use either of the following authentication methords, based on your requirment. + +1. Using Root Token authentication +2. Using App-Role authentication + +## Setting up using Root Token authentication + +### Step 1 - Setup HashiCorp Vault + +1. Start the HashiCorp Vault server and create a new **KV engine**. Enter a path name when creating the kv engine (e.g., `wso2apim`). The following commands can be used to add secrets with the HashiCorp Vault. + + ```shell + # Create a new kv engine + vault secrets enable -path=wso2apim -version=2 kv + + # Add new secret + vault kv put wso2apim/admin_password value=admin + + # Get a secret (To check) + vault kv get -field=value wso2apim/admin_password + ``` + +### Step 2 - Configure HashiCorp Vault extension + +1. Clone [HashiCorp Vault extension](https://github.com/wso2-extensions/carbon-securevault-hashicorp/tree/master) repo. + +2. Build the HashiCorp Vault Integration OSGI bundle using `mvn clean install` command and copy + the `target/org.wso2.carbon.securevault.hashicorp-1.0.jar` file to the `/repository/components/dropin/` + directory. + +3. Add **HashiCorp Vault Java Driver** (e.g., `vault-java-driver-5.1.0.jar`) to the + `/repository/components/lib/` directory. + +4. Create the `/repository/conf/security/secret-conf.properties` file and set the following configurations. + + ```properties + keystore.identity.location=repository/resources/security/wso2carbon.jks + keystore.identity.type=JKS + keystore.identity.store.password=identity.store.password + keystore.identity.store.secretProvider=org.wso2.carbon.securevault.DefaultSecretCallbackHandler + keystore.identity.key.password=identity.key.password + keystore.identity.key.secretProvider=org.wso2.carbon.securevault.DefaultSecretCallbackHandler + carbon.secretProvider=org.wso2.securevault.secret.handler.SecretManagerSecretCallbackHandler + + secVault.enabled=true + secretRepositories=vault + secretRepositories.vault.provider=org.wso2.carbon.securevault.hashicorp.repository.HashiCorpSecretRepositoryProvider + secretRepositories.vault.properties.address=https://127.0.0.1:8200 + secretRepositories.vault.properties.namespace=ns1 + secretRepositories.vault.properties.enginePath=wso2apim + secretRepositories.vault.properties.engineVersion=2 + secretRepositories.vault.properties.authType=ROOT_TOKEN + ``` + + !!! note + In production, you should always use the vault address with TLS enabled. + +5. Add the following lines to the `/repository/conf/log4j2.properties` file. + + ```properties + logger.org-wso2-carbon-securevault-hashicorp.name=org.wso2.carbon.securevault.hashicorp + logger.org-wso2-carbon-securevault-hashicorp.level=INFO + logger.org-wso2-carbon-securevault-hashicorp.additivity=false + logger.org-wso2-carbon-securevault-hashicorp.appenderRefCARBON_CONSOLE. ref = CARBON_CONSOLE + ``` + +6. Then append `org-wso2-carbon-securevault-hashicorp` to the `loggers` list in the same file as follows. + + ```properties + loggers = AUDIT_LOG, trace-messages, ..., org-wso2-carbon-securevault-hashicorp + ``` + +### Step 3 - Update passwords with their aliases + +1. Open the `deployment.toml` file in the `/repository/conf/` directory and add + the `[secrets]` configuration section **at the bottom of the file** as shown below. + Give an alias for the passwords and put the value as blank (`""`). + + ```toml + [secrets] + admin_password = "" + ``` + +2. Add the encrypted password alias to the relevant sections in the `deployment.toml` + file by using a placeholder: `$secret{alias}`. For example: + + ```toml + [super_admin] + username="admin" + password="$secret{admin_password}" + ``` + +### Step 4 - Start the server + +1. Provide the `VAULT_TOKEN` to the prompted message in the console or by creating a new file in the `` + directory. The file should be named according to your Operating System. + + === "Linux" + The file name should be `hashicorpRootToken-tmp`. + + + === "Windows" + ``` + The file name should be `hashicorpRootToken-tmp.txt`. + ``` + + !!! note + When you add `tmp` to the file name, note that this will automatically get deleted from the file system after the server starts. Alternatively, if you want to retain the password file after the server starts, the file should be named as follows: + + === "Linux" + The file name should be `hashicorpRootToken-persist`. + + === "Windows" + The file name should be `hashicorpRootToken-persist.txt`. + + + +2. Start the WSO2 API Manager Server and enter the keystore password at startup when prompted: + + ```shell + [Enter KeyStore and Private Key Password :] wso2carbon + ``` + + +## Setting up using App-Role authentication + +### Step 1 - Setup HashiCorp Vault + +1. Start the HashiCorp Vault server and set the environment variables. + + ```shell + export VAULT_ADDR='http://127.0.0.1:8200' + export VAULT_TOKEN='' + ``` + +2. Include the policy in the `kv-read-write.hcl` file as below. + + ```hcl + path "wso2apim/data/*" { + capabilities = ["create", "read", "update", "delete", "list"] + } + ``` + +3. Upload the kv policy using the command below. + + ```shell + vault policy write kv-read-write kv-read-write.hcl + ``` + +4. The following commands can be used to create the AppRole using the created policy. + + ```shell + vault auth enable approle + ``` + ```shell + vault write auth/approle/role/my-role \ + token_policies="kv-read-write" \ + token_type="service" \ + token_ttl="24h" \ + token_max_ttl="72h" + ``` + +5. Get the role-id as below. + + ```shell + vault read auth/approle/role/my-role/role-id + ``` + +6. Get the secret-id as below. + + ```shell + vault write -f auth/approle/role/my-role/secret-id + ``` + +7. Create the kv engine with a path name (e.g., `wso2apim`). + + The following commands can be used to add secrets with the HashiCorp Vault. + + ```shell + # Create a new kv engine + vault secrets enable -path=wso2apim -version=2 kv + + # Add new secret + vault kv put wso2apim/admin_password value=admin + + # Get a secret (To check) + vault kv get -field=value wso2apim/admin_password + ``` + +### Step 2 - Configure HashiCorp Vault extension + +1. Clone [HashiCorp Vault extension](https://github.com/wso2-extensions/carbon-securevault-hashicorp/tree/master) repo. + +2. Build the HashiCorp Vault Integration OSGI bundle using `mvn clean install` command and copy the `target/org.wso2.carbon.securevault.hashicorp-1.0.jar` file to the `/repository/components/dropin/` + directory. + +3. Add **HashiCorp Vault Java Driver** (e.g., `vault-java-driver-5.1.0.jar`) to the + `/repository/components/lib/` directory. + +4. Create the `/repository/conf/security/secret-conf.properties` file and set the following configurations. + + ```properties + keystore.identity.location=repository/resources/security/wso2carbon.jks + keystore.identity.type=JKS + keystore.identity.store.password=identity.store.password + keystore.identity.store.secretProvider=org.wso2.carbon.securevault.DefaultSecretCallbackHandler + keystore.identity.key.password=identity.key.password + keystore.identity.key.secretProvider=org.wso2.carbon.securevault.DefaultSecretCallbackHandler + carbon.secretProvider=org.wso2.securevault.secret.handler.SecretManagerSecretCallbackHandler + + secVault.enabled=true + secretRepositories=vault + secretRepositories.vault.provider=org.wso2.carbon.securevault.hashicorp.repository.HashiCorpSecretRepositoryProvider + secretRepositories.vault.properties.address=http://127.0.0.1:8200 + secretRepositories.vault.properties.namespace=ns1 + secretRepositories.vault.properties.enginePath=wso2apim + secretRepositories.vault.properties.engineVersion=2 + secretRepositories.vault.properties.authType=APP_ROLE + secretRepositories.vault.properties.roleId= + ``` + !!! note + In production, you should always use the vault address with TLS enabled. + +5. Add the following lines to the `/repository/conf/log4j2.properties` file. + + ```properties + logger.org-wso2-carbon-securevault-hashicorp.name=org.wso2.carbon.securevault.hashicorp + logger.org-wso2-carbon-securevault-hashicorp.level=INFO + logger.org-wso2-carbon-securevault-hashicorp.additivity=false + logger.org-wso2-carbon-securevault-hashicorp.appenderRef.CARBON_CONSOLE.ref = CARBON_CONSOLE + ``` + + Then append `org-wso2-carbon-securevault-hashicorp` to the `loggers` list in the same file as follows. + + ```properties + loggers = AUDIT_LOG, trace-messages, ..., org-wso2-carbon-securevault-hashicorp + ``` + +### Step 3 - Update passwords with their aliases + +1. Open the `deployment.toml` file in the `/repository/conf/` directory and add + the `[secrets]` configuration section **at the bottom of the file** as shown below. + Give an alias for the passwords and put the value as blank (`""`). + + ```toml + [secrets] + admin_password = "" + ``` + +2. Add the encrypted password alias to the relevant sections in the `deployment.toml` + file by using a placeholder: `$secret{alias}`. For example: + + ```toml + [super_admin] + username="admin" + password="$secret{admin_password}" + ``` + +### Step 4 - Start the server + + +1. Provide the `Secret ID` to the prompted message in the console or by creating a new file in the `` + directory. The file should be named according to your Operating System. + + === "Linux" + The file name should be `hashicorpSecretId-tmp`. + + + === "Windows" + The file name should be `hashicorpSecretId-tmp.txt`. + + +!!! note + When you add `tmp` to the file name, note that this will automatically get deleted from the file system after the server starts. Alternatively, if you want to retain the password file after the server starts, the file should be named as follows. + + + === "Linux" + The file name should be `hashicorpSecretId-persist`. + + + === "Windows" + The file name should be `hashicorpSecretId-persist.txt`. + + + +2. Start the WSO2 API Manager Server and enter the keystore password at startup when prompted. + ```shell + [Enter KeyStore and Private Key Password :] wso2carbon + ``` + diff --git a/en/mkdocs.yml b/en/mkdocs.yml index 0bd47c07cb..2f6a7d4d10 100644 --- a/en/mkdocs.yml +++ b/en/mkdocs.yml @@ -1422,6 +1422,7 @@ nav: - Work with Encrypted Passwords: install-and-setup/setup/security/logins-and-passwords/working-with-encrypted-passwords.md - Set Up ReCaptcha: install-and-setup/setup/security/logins-and-passwords/setting-up-recaptcha.md - Configure reCaptcha for Single Sign On : install-and-setup/setup/security/logins-and-passwords/configuring-recaptcha-for-single-sign-on.md + - Intergrate with HashiCorp Vault : install-and-setup/setup/security/logins-and-passwords/harshicrop-vault-extension.md - Configure Keystores: - Configure Keystores in API Manager: install-and-setup/setup/security/configuring-keystores/configuring-keystores-in-wso2-api-manager.md - Keystore Basics: From f13af2e1e8944917c82c5285e6bb0c79cad4ba01 Mon Sep 17 00:00:00 2001 From: BiyonFernando Date: Thu, 3 Oct 2024 11:31:29 +0530 Subject: [PATCH 2/2] improve formatting --- .../harshicrop-vault-extension.md | 112 +++++++++--------- 1 file changed, 55 insertions(+), 57 deletions(-) diff --git a/en/docs/install-and-setup/setup/security/logins-and-passwords/harshicrop-vault-extension.md b/en/docs/install-and-setup/setup/security/logins-and-passwords/harshicrop-vault-extension.md index 09e841b13f..0b8a8afaf4 100644 --- a/en/docs/install-and-setup/setup/security/logins-and-passwords/harshicrop-vault-extension.md +++ b/en/docs/install-and-setup/setup/security/logins-and-passwords/harshicrop-vault-extension.md @@ -1,13 +1,15 @@ # Integrate with HashiCorp Vault -Using [HashiCorp Vault extension](https://github.com/wso2-extensions/carbon-securevault-hashicorp/tree/master), you can set up HashiCorp Vault to store passwords that are mapped to aliases instead of the actual passwords. When setting up Harshicrop Vault with APIM you can use either of the following authentication methords, based on your requirment. +Using [HashiCorp Vault extension](https://github.com/wso2-extensions/carbon-securevault-hashicorp/tree/master), you can set up HashiCorp Vault to store passwords that are mapped to aliases instead of the actual passwords. When setting up Hashicrop Vault with APIM you can use either of the following authentication methords, based on your requirment. 1. Using Root Token authentication 2. Using App-Role authentication ## Setting up using Root Token authentication +This method uses a static root token to authenticate with HashiCorp Vault, providing direct and full access to Vault's secrets. + ### Step 1 - Setup HashiCorp Vault 1. Start the HashiCorp Vault server and create a new **KV engine**. Enter a path name when creating the kv engine (e.g., `wso2apim`). The following commands can be used to add secrets with the HashiCorp Vault. @@ -64,7 +66,7 @@ Using [HashiCorp Vault extension](https://github.com/wso2-extensions/carbon-secu logger.org-wso2-carbon-securevault-hashicorp.name=org.wso2.carbon.securevault.hashicorp logger.org-wso2-carbon-securevault-hashicorp.level=INFO logger.org-wso2-carbon-securevault-hashicorp.additivity=false - logger.org-wso2-carbon-securevault-hashicorp.appenderRefCARBON_CONSOLE. ref = CARBON_CONSOLE + logger.org-wso2-carbon-securevault-hashicorp.appenderRefCARBON_CONSOLE.ref = CARBON_CONSOLE ``` 6. Then append `org-wso2-carbon-securevault-hashicorp` to the `loggers` list in the same file as follows. @@ -98,43 +100,46 @@ Using [HashiCorp Vault extension](https://github.com/wso2-extensions/carbon-secu 1. Provide the `VAULT_TOKEN` to the prompted message in the console or by creating a new file in the `` directory. The file should be named according to your Operating System. - === "Linux" - The file name should be `hashicorpRootToken-tmp`. - - - === "Windows" - ``` - The file name should be `hashicorpRootToken-tmp.txt`. - ``` + ```lang-none tab="Linux" + + The file name should be "hashicorpRootToken-tmp". + ``` + + ```lang-none tab="Windows" + + The file name should be "hashicorpRootToken-tmp.txt". + ``` !!! note When you add `tmp` to the file name, note that this will automatically get deleted from the file system after the server starts. Alternatively, if you want to retain the password file after the server starts, the file should be named as follows: - === "Linux" - The file name should be `hashicorpRootToken-persist`. + ```lang-none tab="Linux" - === "Windows" - The file name should be `hashicorpRootToken-persist.txt`. + The file name should be "hashicorpRootToken-persist". + ``` + + ```lang-none tab="Windows" + + The file name should be "hashicorpRootToken-persist.txt". + ``` 2. Start the WSO2 API Manager Server and enter the keystore password at startup when prompted: - ```shell - [Enter KeyStore and Private Key Password :] wso2carbon - ``` + >
[Enter KeyStore and Private Key Password :] wso2carbon
## Setting up using App-Role authentication +This method uses dynamic authentication based on role IDs and secret IDs, allowing for secure, scoped access to Vault without the need for storing static tokens. + ### Step 1 - Setup HashiCorp Vault 1. Start the HashiCorp Vault server and set the environment variables. - ```shell - export VAULT_ADDR='http://127.0.0.1:8200' - export VAULT_TOKEN='' - ``` + >
export VAULT_ADDR='https://127.0.0.1:8200'
+    export VAULT_TOKEN='xxxxxxxxxxxxxx'
2. Include the policy in the `kv-read-write.hcl` file as below. @@ -146,34 +151,24 @@ Using [HashiCorp Vault extension](https://github.com/wso2-extensions/carbon-secu 3. Upload the kv policy using the command below. - ```shell - vault policy write kv-read-write kv-read-write.hcl - ``` + >
vault policy write kv-read-write kv-read-write.hcl
4. The following commands can be used to create the AppRole using the created policy. - ```shell - vault auth enable approle - ``` - ```shell - vault write auth/approle/role/my-role \ + >
vault auth enable approle
+ >
vault write auth/approle/role/my-role \
         token_policies="kv-read-write" \
         token_type="service" \
         token_ttl="24h" \
-        token_max_ttl="72h"
-    ```
+        token_max_ttl="72h"
5. Get the role-id as below. - ```shell - vault read auth/approle/role/my-role/role-id - ``` + >
vault read auth/approle/role/my-role/role-id
6. Get the secret-id as below. - ```shell - vault write -f auth/approle/role/my-role/secret-id - ``` + >
vault write -f auth/approle/role/my-role/secret-id
7. Create the kv engine with a path name (e.g., `wso2apim`). @@ -214,13 +209,14 @@ Using [HashiCorp Vault extension](https://github.com/wso2-extensions/carbon-secu secVault.enabled=true secretRepositories=vault secretRepositories.vault.provider=org.wso2.carbon.securevault.hashicorp.repository.HashiCorpSecretRepositoryProvider - secretRepositories.vault.properties.address=http://127.0.0.1:8200 + secretRepositories.vault.properties.address=https://127.0.0.1:8200 secretRepositories.vault.properties.namespace=ns1 secretRepositories.vault.properties.enginePath=wso2apim secretRepositories.vault.properties.engineVersion=2 secretRepositories.vault.properties.authType=APP_ROLE secretRepositories.vault.properties.roleId= ``` + !!! note In production, you should always use the vault address with TLS enabled. @@ -265,29 +261,31 @@ Using [HashiCorp Vault extension](https://github.com/wso2-extensions/carbon-secu 1. Provide the `Secret ID` to the prompted message in the console or by creating a new file in the `` directory. The file should be named according to your Operating System. - === "Linux" - The file name should be `hashicorpSecretId-tmp`. - - - === "Windows" - The file name should be `hashicorpSecretId-tmp.txt`. - + ```lang-none tab="Linux" + + The file name should be "hashicorpSecretId-tmp". + ``` + + ```lang-none tab="Windows" + + The file name should be "hashicorpSecretId-tmp.txt". + ``` !!! note When you add `tmp` to the file name, note that this will automatically get deleted from the file system after the server starts. Alternatively, if you want to retain the password file after the server starts, the file should be named as follows. - - === "Linux" - The file name should be `hashicorpSecretId-persist`. - - - === "Windows" - The file name should be `hashicorpSecretId-persist.txt`. - - + ```lang-none tab="Linux" + + The file name should be "hashicorpSecretId-persist". + ``` + + ```lang-none tab="Windows" + + The file name should be "hashicorpSecretId-persist.txt". + ``` 2. Start the WSO2 API Manager Server and enter the keystore password at startup when prompted. - ```shell - [Enter KeyStore and Private Key Password :] wso2carbon - ``` + >
[Enter KeyStore and Private Key Password :] wso2carbon
+ +