# 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: ```json { "sharedVault": "SharedVault1", "collections": ["Collec1", "Collec2"], "createCollections": true, "deleteCollections": false, "role": "User", "permission": "view" } ```

Field	Type	Description
`sharedVault`	`string`	Name of the shared vault to sync
`collections`	`string[]`	List of collections to manage
`createCollections`	`boolean`	Auto-create missing collections
`deleteCollections`	`boolean`	Auto-remove collections not listed
`role`	`string`	User role in the vault: `"Owner"`, `"Admin"`, or `"User"`
`permission`	`string`	Permission in the collection: `"view"`, `"viewExceptPass"`, `"edit"`, `"editExceptPass"`, `"manage"`

##### 🔹 `vaultSync` JSON attribute on a **Trustelem User** (optional) Overrides group settings when applied. Example to adapt: ```json [ { "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: ```shell #!/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: ```powershell # --- 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:

Variable	Description
`vault_id`	API service account ID (web client > Account parameters > Security > API Keys)
`vault_secret`	API service account secret (web client > Account parameters > Security > API Keys)
`vault_password`	Master password for the service account
`vault_url`	Vault instance URL (e.g., `https://vault-yourdomain.trustelem.com`)
`trustelem_key_id`	KEY ID from Step 2
`trustelem_bearer`	Bearer Token from Step 2
`trustelem_url`	Trustelem admin URL (e.g., `https://admin-yourdomain.trustelem.com`)

##### 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

Scenario	Behavior
🔁 Trustelem group renamed in AD	Synchronization continues (attribute remains present)
🗑 Trustelem group deleted	Synchronization stops, but the vault remains unchanged
♻️ Group deleted and recreated	Vault is no longer linked; re-adding the attribute resumes sync

--- ### ✅ Permissions Summary

Action	Required Right (Service Account)
Create shared vault	None (becomes `Owner`)
Modify existing vault	Must be `Owner`
Create/delete collection	`manage`
Add/remove users from collections	`manage`
Update user permissions	`manage`