Synchronizing Trustelem Groups with the Enterprise Vault CLI (BETA)

🎯 Goal

Automatically define access rights to shared vaults and collections in Enterprise Vault based on membership in Trustelem groups, using a custom JSON attribute called vaultSync.

---

🧩 Overall Workflow

The script reads all Trustelem groups that include the vaultSync attribute.

1. For each group:

   • A shared vault is created or updated.

   • Collections are created or removed according to the configuration.

   • User permissions are applied.

2. If a user also has a vaultSync attribute, it overrides the group configuration.

---

🧷 Trustelem Configuration

Step 1 – Add custom attributes

🔹 vaultSync JSON attribute on a Trustelem Group (mandatory)

Example to adapt:

{ 
  "sharedVault": "SharedVault1",
  "collections": ["Collec1", "Collec2"],
  "createCollections": true,
  "deleteCollections": false,
  "role": "User",
  "permission": "view" 
}

🔹 vaultSync JSON attribute on a Trustelem User (optional)

Overrides group settings when applied.
Example to adapt:

[ 
  { 
    "sharedVault": "SharedVault1",
    "collections": ["Collec1"],
    "role": "Admin",
    "permission": "edit" 
  }
]

Step 2 – Generate a Trustelem API Key

1. In the Trustelem admin console, go to Rest API > New API key
   ⚠️if you can't see the Rest API tab, you have to create a ticket to require the feature.

2. Click the edit (pencil) icon

3. Check:

   • users_read

   • groups_read

4. Save.

5. Note the following values:

   • KEY ID

   • Bearer Token

---

🛠 CLI Script Configuration

1/ Download Enterprise Vault CLI.

2/ Create the synchro script

Example with the Linux CLI:

#!/bin/bash
# --- Configuration ---
vault_id="to_replace"
vault_secret="to_replace"
vault_password="to_replace"
vault_url="to_replace"
trustelem_key_id="to_replace"
trustelem_bearer="to_replace"
trustelem_url="to_replace"

# --- Function: Connect and unlock the Vault CLI ---
connect_to_vault() {
    ./wv logout > /dev/null 2>&1
    ./wv config server "$vault_url" > /dev/null 2>&1
    export WV_CLIENTID=$vault_id
    export WV_CLIENTSECRET=$vault_secret
    export WV_TRUSTELEMKEYID=$trustelem_key_id
    export WV_TRUSTELEMBEARER=$trustelem_bearer
    export WV_TRUSTELEMURL=$trustelem_url
    ./wv login --apikey > /dev/null 2>&1
    export WV_SESSION=$(./wv unlock "$vault_password" --raw)
}

# --- Main Execution ---
connect_to_vault
./wv syncgroups

PowerShell example with the Windows CLI:

# --- Configuration ---
$vault_id = "to_replace"
$vault_secret = "to_replace"
$vault_password = "to_replace"
$vault_url = "to_replace"
$trustelem_key_id = "to_replace"
$trustelem_bearer = "to_replace"
$trustelem_url = "to_replace"

# --- Function: Connect and unlock the Vault CLI ---
function Connect-ToVault {
    ./wv.exe logout | Out-Null
    ./wv.exe config server $vault_url | Out-Null
    $env:WV_CLIENTID = $vault_id
    $env:WV_CLIENTSECRET = $vault_secret
    $env:WV_TRUSTELEMKEYID = $trustelem_key_id
    $env:WV_TRUSTELEMBEARER = $trustelem_bearer
    $env:WV_TRUSTELEMURL = $trustelem_url
    ./wv.exe login --apikey | Out-Null
    $session = ./wv.exe unlock $vault_password --raw
    $env:WV_SESSION = $session.Trim()
}

# --- Main Execution ---
Connect-ToVault
./wv.exe syncgroups

Values to replace:

3/ Start the script.

---

⚙️ Detailed Synchronization Behavior

1. Shared Vault Management

• If the shared vault doesn't exist:

  • It is automatically created and the service account becomes the Owner.

• If it already exists:

  • The script checks if the service account is the Owner.

  • If not, an error is returned.

⚠️ Important: if the service account is not a shared vault member, it has no way to know if the shared vault already exists or not. In this case, the script will assume the shared vault doesn't exist and a new shared vault with the same name will be created.

2. Collection Management

• With createCollections=true:

  • Collections missing in the vault but listed in the JSON will be created.

  • The service account is given manage rights on these.

• With deleteCollections=true:

  • Collections present in the vault but not in the list will be deleted.

  • The service account must have manage rights to delete them.

• If collections = ["*"]:

  • No automatic create or delete, regardless of createCollections or deleteCollections.

⚠️ Important: do not set both createCollections=true and deleteCollections=true at the same time.

🔸 Note on User Attributes: User-level vaultSync attributes cannot create or delete collections—only assign permissions.

3. User Membership & Permissions

• If a user is not in Vault:

  • An error is returned.

• Adding users to collections:

  • If the user is not already in a listed collection (or "*"), they are added with the role and permission defined.

  • If the user has their own vaultSync config, it overrides the group config.

  • The service account must have "manage" rights.

• Updating permissions:

  • If the user has different permissions in a collection, they are updated accordingly.

  • Requires "manage" permission.

• Removing from collections:

  • If a user is in a collection not listed, they are removed.

  • Requires "manage" permission.

---

🧾 Special Cases

---

✅ Permissions Summary