• About the project
  • How it works
• Installation
• Usage
• Configuration
  • General
  • Dex client configuration
    • About Dex auth
  • Vault client configuration
    • About Vault auth
• Vault secret structure
• Local Testing
• Other notes
• Thanks

Dexus Vault is utility designed to synchronize Dex client configurations with secrets stored in Hashicorp Vault. This tool simplifies the management of Dex clients by automating the process of keeping them in sync with Vault secrets.

When you execute dexus-vault, it establishes a connection to the specified Vault using the hvac library and retrieves secrets from the provided path. Following this, dexus-vault connects to Dex IdP via gRPC and creates or updates clients.

Please note that Dex does not currently support a native "Update" method. As a workaround, dexus_vault will recreate the client. Be aware of this behavior when using the tool.

The recommended installation method is using pip:

pip install dexus-vault

Using docker:

docker run ifurs/dexus-vault

you can find docker image here

if you've installed dexus-vault using pip, you can execute it with the following command:

dexus-vault

or like a python module:

python3 -m dexus_vault

This will initiate a process that synchronizes Dex clients with the secrets stored in Vault.

Currently dexus-vault support only Environment variables.

If you don't specify certificates for Dex, the client will establish an insecure connection. Note that it's not necessary to use a certificate authority when you provide a client certificate and key.

There are several authentication methods available:

• Token-based authentication
• LDAP authentication
• Certificate-based authentication
• AppRole authentication: To use this method, set VAULT_APPROLE to true. The HVAC client will then log into Vault using the default file mounted by the Vault agent by default, also there is possible to specify approle id and secret via env vars too.
• Kubernetes authentication: To use this method, set variable VAULT_KUBERNETES_ROLE with role name

For now "dexus-vault" publish simplified metrics, like this:

client_create{status="ok"} 1.0
client_delete{status="failed"} 3.0
client_update{status="failed"} 0.0
client_skip 5.0
incorrect_secrets 2.0

• labeled metrics(status): client_create, client_delete, client_update
• non labeled: client_skip and incorrect_secrets for "status" label could be values "ok" and "failed"

NOTE: Metrics are still under discussion. Any contributions to this effort are greatly appreciated.

This example demonstrates all the parameters available for a client, which align with the Dex gRPC protocol message.

{
  "id": "my-first-client",
  "secret": "",
  "logo_url": "https://picsum.photos/200/300",
  "name": "My First Client",
  "public": false,
  "redirect_uris": ["http://127.0.0.1:5000/callback"],
  "trusted_peers": ["my-second-client"]
}

In the Vault configuration, secret are mandatory field same as id, but if you don't specify id, dexus-vault will use secret name for client id. The public field defaults to False at the dexus_vault level. If you wish to enable public, ensure that it is set as a boolean type in your Vault implementation, not as a string.

For defining lists in redirect_uris and trusted_peers, there are two methods:

1. Use a native JSON list, e.g., ["value1", "value2"]. Note that this will disable the non-JSON view for that secret in the Vault UI.
2. Use a string with commas as delimiters, e.g., "value1,value2". However, this method is not recommended and may be deprecated in future versions.

The docker/tests directory houses a docker-compose.yaml file, designed to facilitate local testing by running both Vault and Dex. However, this configuration is not suitable for production environments.

For more details, please see the README.

• This projects uses pre-commit: https://pre-commit.com/

• All gRPC API methods dexus_vault use, defined in api.proto and compiled with grpc_tools.protoc

Plans for future:

• Redesign metrics concept to make it more Prometheus friendly
• Switch to pydantic
• Implement functionality that tracks current clients state in Dex
• Make logs more Fluent
• Redesign dexus-vault to work like cli and accepts params
• Implement feature to use other storage options

• Hurlenko for references copied from your repos