How to manage LDAP¶

LDAP (Lightweight Directory Access Protocol) enables centralized authentication for Valkey, reducing the overhead of managing local credentials. LDAP support in Charmed Valkey also enables role-based access control.

This guide goes over the steps to integrate LDAP as an authentication method with the Valkey charm within the Juju ecosystem.

Prerequisites¶

The following components are required before proceeding:

Charmed Valkey deployed on either a VM or Kubernetes.
A Kubernetes Juju controller to deploy the LDAP provider

Deploy LDAP server charm¶

The exact way we deploy the glauth-k8s charm depends on the substrate Charmed Valkey runs on:

Use a separate Juju controller with a Kubernetes model to deploy glauth-k8s (see the GLAuth tutorial for a walkthrough). You will create a cross-model relation to the Valkey VM model later in this guide.

K8s

No separate Juju model is required – run glauth-k8s alongside Charmed Valkey in the same model.

Now deploy glauth-k8s, self-signed-certificates, and postgresql-k8s:

juju deploy glauth-k8s --channel latest/edge --trust
juju deploy self-signed-certificates
juju deploy postgresql-k8s --channel 14/stable --trust

Caution

Self-signed certificates are not recommended for a production environment.

Check the Choosing a TLS provider page for an overview of all the TLS certificates charms available.

Integrate glauth-k8s with self-signed-certificates and postgresql-k8s:

juju integrate glauth-k8s self-signed-certificates
juju integrate glauth-k8s:pg-database postgresql-k8s:database

Deploy the glauth-utils charm to manage LDAP users, and integrate it with the GLAuth application:

juju deploy glauth-utils --channel latest/edge --trust
juju integrate glauth-k8s glauth-utils

Users and groups can now be created using glauth-utils.

Create a cross-model relation¶

Whether this step is needed depends on the substrate Charmed Valkey runs on:

GLAuth runs on a separate Kubernetes controller and model, so Valkey needs a cross-model relation to reach it.

Expose LDAP

Deploy the Traefik charm to expose LDAP endpoints from the Kubernetes cluster:

juju deploy traefik-k8s --trust

Integrate Traefik with the LDAP server:

juju integrate traefik-k8s:ingress glauth-k8s:ingress-per-unit

Expose cross-model relations

To offer the GLAuth interfaces, run:

juju offer glauth-k8s:ldap ldap
juju offer glauth-k8s:send-ca-cert send-ca-cert

Consume offers

Switch to the VM controller:

juju switch <vm_controller>:<model-name>

Consume the LDAP offers:

juju consume <k8s_controller>:admin/<k8s-model-name>.ldap
juju consume <k8s_controller>:admin/<k8s-model-name>.send-ca-cert

K8s

GLAuth already shares the same Juju model as Charmed Valkey, so no cross-model relation is required. Proceed to the next section: Define roles and permissions.

Define roles and permissions¶

Charmed Valkey supports a role-based access control model to allow permissions based on LDAP groups. To define the desired roles, configure entity-permissions through Data Integrator and configure the mapping of these roles to LDAP groups to Charmed Valkey.

Set up Data Integrator¶

Deploy the Data Integrator charm in the same model as Charmed Valkey:

juju deploy data-integrator --channel latest/edge

The configuration of entity-permissions expects a list of role definitions in JSON syntax. Let’s assume we want to configure two roles, one with read and write permissions and one with read-only permissions:

[
    {
        "resource_name": "ldap_users_write",
        "resource_type": "acl",
        "privileges": ["+@read", "+@write", "~*"]
    },
    {
        "resource_name": "ldap_users_read",
        "resource_type": "acl",
        "privileges": ["+@read", "~*"]    
    }
]

Configure permissions for Data Integrator:

juju config data-integrator prefix-name="*" entity-permissions='[{"resource_name": "ldap_users_write", "resource_type": "acl", "privileges": ["+@read", "+@write", "~*"]}, {"resource_name": "ldap_users_read", "resource_type": "acl", "privileges": ["+@read", "~*"]}]'

Now integrate with Valkey to provide the role definition:

juju integrate valkey:valkey-client data-integrator:valkey

Configure role mapping¶

After setting up a role-based access control model in Valkey, configure the mapping of LDAP groups to your defined roles in Valkey:

juju config valkey ldap-map="<ldap_group_name>:ldap_users_write,<another_ldap_group>:ldap_users_read"

Due to a limitation in GLAuth, it might also be required to configure the attribute that contains the username in the LDAP directory:

juju config valkey ldap-search-dn-attribute="mail"

Enable LDAP¶

After completing all required configuration, integrate Valkey with GLAuth to enable LDAP::

juju integrate valkey:ldap-ca-cert glauth-k8s:send-ca-cert
juju integrate valkey:ldap glauth-k8s:ldap

Wait for the deployment to settle and log in to Valkey with the username and password from LDAP. The permissions in Valkey are set up according to the defined roles and the configured role mapping.

If something goes wrong or a configuration is missing, Charmed Valkey will display a blocked status with more information, for example: LDAP: Missing config for 'ldap-map'.

Test LDAP authentication¶

Get the endpoint for login from juju status and log in using valkey-cli:

valkey-cli -h <your-ip-address> -p 6379

Authenticate with your username and password from LDAP:

AUTH <ldap username> <ldap password>

Now perform a basic health check:

ping

You should receive this response from the Valkey server:

PONG

Synchronize LDAP users¶

Charmed Valkey adds all users from the configured LDAP groups to its ACL files. Over time, the group assignments in LDAP might evolve: new users might be added to or existing users might be removed from LDAP groups.

Synchronize the LDAP users in Valkey by running the sync-ldap-users action on the leader unit:

juju run valkey/leader sync-ldap-users

This will update the ACL files on all units.

Disable LDAP¶

You can disable LDAP in Valkey by removing the relations with GLAuth:

juju remove-relation valkey:ldap-ca-cert glauth-k8s:send-ca-cert
juju remove-relation valkey:ldap glauth-k8s:ldap

This removes all LDAP users that were previously added to Valkey’s ACL files.