Team vault

Introduction

By default, XPipe starts out with an empty vault that does not have any passphrase lock, meaning that you can start XPipe without having to unlock it. This default vault does its best at encrypting the contained data, however, this is not as secure as giving it a custom encryption passphrase that only you know. You can do this in the vault settings menu:

Once this is set, XPipe can encrypt all data with your personal key. A team vault is the continuation of this idea where multiple vault users are added to a vault, each with their own individual passphrase. With this setup, multiple users can work on the same vault data while having the option to use their own passphrase for encryption to not give other users access to their connections. To have multiple users sync the vault data, the git synchronization has to be configured.

A team vault enables fine-grained access control via those personal encryption keys. However, a team vault is optional, meaning that if you are using XPipe with multiple users, it is not required to be configured. For example, if all team members should have access to all connections and identities, then vault users or a team vault aren't needed. The same applies for when you are just using individual local identities, as those are not synced and do not require any fine-grained access control.

Identity scope

Having a vault user configured enabled you to modify the scope of identities and associated connections. Without vault users, those are available to everyone with access to the vault. With a vault user, you have the option to mark any identity as personal

You can control whether any identity should be available only for your user or all users in a team vault. If you don't use a team vault, this option is greyed out.

This setting is visible in the connection hub where personal (= only available to your user) and global identities (= available to all users) have different descriptions:

An identity that is not available to a user, e.g. if it belongs to another user and the identity is marked as personal, then the identity will not show up for any other user. Any connections using this identity will also not show up for any other user. This allows you to keep connections and identities for yourself, even in a shared team vault.

Then, configuring a connection to use this personal identity will automatically make XPipe also encrypt the connection itself and all subconnections with your personal key as well. This will result in only your user having access to the identity and all associated connections. Any kind of key files associated with personal identities are also added to the repository using your personal key for encryption when needed.

For more information, see the identities docs.

Setup

To start off, each team member first has to sync to the same git repository. With no team vault settings configured yet, all members who sync with that repository will have full access to the same connections with this configuration.

You can then configure the vault authentication in the Vault settings menu. First, you can choose between user-based and group-based authentication.

User-based authentication

Each member has their own passphrase to either remember or stored in a password manager. With this passphrase, each team member can choose to encrypt certain connections and identities to only be available for themselves. This is suitable for smaller teams and requires minimal setup.

Group-based authentication

Each member can be assigned a group, which requires a group secret to unlock. With vault groups, this secret can be queried automatically, e.g. via commands, HTTP requests, password manager, and more. It is essentially the right type of authentication for larger teams where an organization administrator can configure the group assignments from a central location.

It is essentially what many people refer to as role-based access control (RBAC), however, that name was not chosen, to distinguish it from that as each member can only be a member of one group. There is not a flexible system of multiple roles that can be assigned to each user.

That administrator can, for example, hook up the vault authentication to an Azure Key Vault and manage access via Azure Active Directory permissions and the Azure CLI.

Changing authentication secrets

If, at a later date, you want to change the passphrase / group secrets of a vault user / group, you can do so at the edit button for the user / group entry. This action will re-encrypt the entire vault data and restart. This operation will take a while as this is a compute-intensive operation.

You can also delete a user / group. This will perform the same operation with the main difference that all personal / group-only connections will be encrypted with the generic vault key again, meaning that they will be accessible to everyone.

Merge conflicts

When working in a team, an occasional merge conflict might occur when another user pushes changes while your local XPipe instance is running. XPipe will automatically check in the background if someone else pushed something to the remote and will attempt to perform a fast-forward merge automatically. You will see this notification when this happens:

In most cases, you won't have to do anything as it can be handled automatically. However, if you and another team member modify the same connection configuration at the same time, you might receive a merge conflict error that can't be solved automatically. In this case, you can choose between either overriding your changes or the external changes.

Central API server

By default, the nature of XPipe and the git vault is decentralized, meaning that there isn't a central backend server to manage your vault. This makes it a bit complicated in enterprise environments where server changes should be propagated to a synced vault automatically via the HTTP API, as there is no central server to send those vault update requests to.

You can deploy the XPipe Webtop container as an API server to have a central server that is linked to your vault and can handle connection updates via the API without any user involvement.

Additional considerations

A team vault is essentially just a git repository consisting out of files that are encrypted with various keys. There is no database or other service involved. This introduces a few limitations that it is good to be aware of.

Trust

This authentication system for encryption and decryption is not the most complex system you will find when compared to other solutions. It is designed to be relatively simple and robust. Each team member has full control over all connection entries they have been granted access for, meaning that they can modify them, delete them, and inspect the used passwords and keys for them. There is no fine-grained permission system akin to an administrator only granting something like read-only permissions to certain connections. Each team member has to be trusted with the connection access that they are given. If you are looking to minimize possible leaks of secrets in this scenario, using security keys like Yubikeys for server authentication is the best option. This will prevent the possibility of any used private keys being leaked when an individual user's system is compromised.

Scaling limits

Furthermore, this vault sync system is not designed for an arbitrary number of users. The maximum amount of users who can share a vault is often limited by git itself. If you have something like 50 users working on one shared vault with the same connections, there will probably be a lot of continuous pushing and pulling going on, including a lot of merge conflicts at some point. The git workflow does not scale well when working on the same data, this is also true for other normal repositories.

Multiple vaults

A workspace is a completely separate data storage location, independent of others. It lives in its own directory on your local machine and has its own connections, settings, and vault. They can be created in the settings menu:

For fine-grained access control, like a few team members having access to a few specific connections outside of the normal group borders, you can try using multiple workspaces. In many cases, a separate workspace with a separate sync repository configured is the best option to solve these cases. Separate workspaces also work well when reducing the aforementioned increasing load on git repositories when more and more users start syncing to it.

For more info, see the workspaces page.

Example setups

This is how each variant of the team vault authentication could look like for group-based authentication.

Password manager

Each group member must have access to a supported password manager. Assuming that the secrets in that password manager are managed by an organization administrator, they can make the group secret available to group members in the password manager. If a password manager is configured in the XPipe settings, you can then retrieve that group secret to unlock the vault with the necessary name or key of the secret in the password manager.

For details on how to use password managers in XPipe, see the password manager page.

Command

If your secret is not stored in a password manager, and instead at the central location with built-in access control like an Azure Key Vault, the command option is probably the right one for you. It will simply execute a command and read the secret from stdout. Assuming that the necessary CLI tools are available on your system, this gives you a lot of flexibility on how and where to retrieve the secret from.

For example, you could follow this guide to create an Azure Key Vault and retrieve the command with the Azure CLI. Many CLI tools like the Azure CLI return json output. You can extract the raw values using a tool like jq. For example, if you create a new key vault called xpipe-auth-vault and the secret called my-group-secret, you can then pass the secret to XPipe by specifying the following command with the jq extraction for the raw value:

az keyvault secret show --name "my-group-secret" --vault-name "xpipe-auth-vault" | jq -r .value

The access control is built in as the Azure CLI requires you to authenticate to your Azure Active Directory setup, which automatically gives you the permissions you were assigned to. You just need to be assigned permissions to read the associated secret vault, and this command will work.

File-based secret

If your organization administrator can manage the file system of devices, creating a simple file containing the group secret is also an option. Although this is not as secure as the other ones. This file can then be used to obtain the groups secret. The file path in XPipe also supports ~ on all operating systems to allow you to refer to files in your home directory regardless of which operating system you're using.

HTTP request

You can also run a small HTTP server to handle the group secret authentication for you. Essentially, you can specify an HTTP URL in XPipe that will get called with a POST request. XPipe expects the group secret to be written in the body of the response. The access control can be implemented for example by matching the request IPs against a fixed table, for example, in an office set up with fixed device IPs. This approach requires a bit of manual scripting to create this HTTP server, but can be a good solution for certain setups.

Manual login

If the configured authentication method fails, or you don't have one configured yet, you can also just log in to the group manually in the login dialog.