dexus-vault 0.3.1

Synchronizer of Dex clients with secrets in Vault

DEXUS VAULT

dexus-vault - synchronizer of Dex clients with secrets in Vault

🚩 Table of Contents

• 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

🚀 About the project

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.

How it works

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.

💾 Installation

The recommended installation method is using pip:

pip install dexus-vault

Using docker:

docker run ifurs/dexus-vault

you can find docker image here

📙 Usage

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.

🔧 Configuration

Currently dexus-vault support only Environment variables.

General

variable	required	default	description
SYNC_INTERVAL	-	60	Interval in seconds, dexus_vault will refresh in
LOG_LEVEL	-	INFO	Set log level(logging lib)
METRICS_ENABLE	-	True	Enable prometheus metrics publisher
METRICS_PORT	-	8000	Set Metrics port, require METRICS_ENABLE to be enabled
INTERNAL_METRICS	-	False	Enable the built-in metrics for Python (not application-specific)

Dex client configuration

variable	required	default	description
DEX_GRPC_URL	-	127.0.0.1:5557	url, with your dex grpc
CLIENT_CRT	-	-	path to Dex GRPC client certificate
CLIENT_KEY	-	-	path to Dex GRPC client certificate key
CA_CRT	-	-	path to Dex GRPC client certificate authority
DEX_MAX_RETRIES	-	20	How many retries need to wait for Dex to be reachable
DEX_RETRY_WAIT	-	3	How many seconds need to wait before next retry

Vault client configuration

variable	required	default	description
VAULT_CLIENTS_PATH	yes	-	path in vault where clients could be found
VAULT_MOUNT_POINT	yes	-	vault mount point
VAULT_ENGINE	-	v2	KV engine version, supported values v1 and v2
VAULT_ADDR	-	http://127.0.0.1:8200	vault address
VAULT_TOKEN	-	-	used to auth to Vault via token
VAULT_CERT	-	-	Vault client certificate path
VAULT_CERT_KEY	-	-	Vault client certificate key path
VAULT_CERT_CA	-	-	Vault certificate authority path or bool, false - do not validate, true - validate with internal truststore
VAULT_LDAP_USERNAME	-	-	LDAP username used to auth to Vault
VAULT_LDAP_PASSWORD	-	-	LDAP password used to auth to Vault
VAULT_APPROLE_ROLE_ID	-	-	Vault approle role id
VAULT_APPROLE_SECRET_ID	-	-	Vault approle secret id
VAULT_APPROLE_SECRET_PATH	-	-	Vault approle secret path used to gain secret created by agent
VAULT_KUBERNETES_ROLE	-	-	Vault role, used for kube app
VAULT_KUBERNETES_JWT_PATH	-	/var/run/secrets/kubernetes.io/serviceaccount/token	Path to jwt mounted by Vault agent
VAULT_KUBERNETES_MOUNT_POINT	-	kubernetes	Mount point for role "/auth/{mount_point}/role"
VAULT_MAX_RETRIES	-	20	How many retries need to mark Vault unreachable
VAULT_RETRY_WAIT	-	3	How many seconds need to wait before next retry

About Dex auth

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.

About Vault auth

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

Metrics

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.

🔒 Vault secret structure

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.

💻 Local Testing

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.

📓 Other notes

• 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

Roadmap

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

🔥 Thanks

• Hurlenko for references copied from your repos