# How to Configure LDAP Authentication in r-nacos Using Environment Variables

> Configure LDAP authentication in r-nacos using environment variables like RNACOS_LDAP_URL. Secure your r-nacos instance easily with step-by-step guidance.

- Repository: [Nacos Group/r-nacos](https://github.com/nacos-group/r-nacos)
- Tags: how-to-guide
- Published: 2026-03-07

---

**Enable LDAP authentication in r-nacos by setting `RNACOS_LDAP_ENABLE=true` and providing the server URL, base DN, and group-to-role mappings via environment variables.**

The r-nacos project (nacos-group/r-nacos) supports external LDAP authentication through a comprehensive set of environment variables. When configured, the application delegates user verification to your LDAP server and automatically assigns r-nacos roles based on group membership.

## Core Environment Variables for LDAP Configuration

The following variables control LDAP functionality. All values are read at startup from [`src/common/mod.rs`](https://github.com/nacos-group/r-nacos/blob/main/src/common/mod.rs) (lines 70-95) and stored in the `LdapConfig` struct defined in [`src/ldap/model/mod.rs`](https://github.com/nacos-group/r-nacos/blob/main/src/ldap/model/mod.rs) (lines 8-15).

| Variable | Purpose | Default |
|----------|---------|---------|
| `RNACOS_LDAP_ENABLE` | Master switch to activate LDAP authentication | `false` |
| `RNACOS_LDAP_URL` | LDAP server endpoint (e.g., `ldap://localhost:389`) | *empty* |
| `RNACOS_LDAP_USER_BASE_DN` | Base DN for user entry searches | *empty* |
| `RNACOS_LDAP_USER_FILTER` | Search filter template; `%s` expands to username | *empty* |
| `RNACOS_LDAP_USER_DEVELOPER_GROUP` | Comma-separated groups mapped to **DEVELOPER** role | *empty* |
| `RNACOS_LDAP_USER_ADMIN_GROUP` | Comma-separated groups mapped to **ADMIN** role | *empty* |
| `RNACOS_LDAP_USER_DEFAULT_ROLE` | Fallback role when no group matches (`VISITOR`, `DEVELOPER`, `ADMIN`) | `VISITOR` |

## How r-nacos Processes LDAP Configuration

### Configuration Loading

During startup, the function in [`src/common/mod.rs`](https://github.com/nacos-group/r-nacos/blob/main/src/common/mod.rs) (lines 70-95) reads the environment variables listed above. It constructs a `LdapConfig` instance that encapsulates the server URL, credentials, search parameters, and role mappings. If `RNACOS_LDAP_ENABLE` is not set to `true`, the LDAP actor is never instantiated and local authentication remains active.

### LDAP Connection Actor

The `LdapConnActor` defined in [`src/ldap/ldap_conn.rs`](https://github.com/nacos-group/r-nacos/blob/main/src/ldap/ldap_conn.rs) (lines 34-70) receives the `LdapConfig` and establishes the connection to the specified `ldap_url`. Upon successful connection, it spawns a `LdapMsgActor` that handles authentication requests. This actor uses the `user_base_dn` and `user_filter` (with `%s` substituted by the login username) to locate the user entry and verify credentials against the LDAP server.

### Group-to-Role Mapping

After successful authentication, r-nacos retrieves the user's group memberships from LDAP. It compares these groups against the comma-separated values in `RNACOS_LDAP_USER_DEVELOPER_GROUP` and `RNACOS_LDAP_USER_ADMIN_GROUP`. Matching groups assign the **DEVELOPER** or **ADMIN** role respectively. If no groups match, the user receives the role specified by `RNACOS_LDAP_USER_DEFAULT_ROLE`, which defaults to `VISITOR`.

## Practical Configuration Examples

### Docker Compose Configuration

Deploy r-nacos with LDAP enabled via Docker Compose by setting the environment variables under the `environment` key:

```yaml
services:
  r-nacos:
    image: nacos-group/r-nacos:latest
    environment:
      - RNACOS_LDAP_ENABLE=true
      - RNACOS_LDAP_URL=ldap://ldap.mycompany.com:389
      - RNACOS_LDAP_USER_BASE_DN=ou=employees,dc=mycompany,dc=com
      - RNACOS_LDAP_USER_FILTER=(&(objectClass=person)(uid=%s))
      - RNACOS_LDAP_USER_DEVELOPER_GROUP=developers,engineering
      - RNACOS_LDAP_USER_ADMIN_GROUP=admins,operations
      - RNACOS_LDAP_USER_DEFAULT_ROLE=VISITOR
    ports:
      - "8848:8848"
      - "9848:9848"

```

### Environment File Setup

For bare-metal or systemd deployments, create a `.env` file in the working directory. The example in `doc/conf/.env.example` (lines 81-94) demonstrates the required format:

```text

# Enable LDAP authentication

RNACOS_LDAP_ENABLE=true

# LDAP server connection

RNACOS_LDAP_URL=ldap://localhost:389
RNACOS_LDAP_USER_BASE_DN=ou=people,dc=example,dc=com
RNACOS_LDAP_USER_FILTER=(&(objectClass=inetOrgPerson)(uid=%s))

# Role mapping

RNACOS_LDAP_USER_DEVELOPER_GROUP=cn=developers,ou=groups,dc=example,dc=com
RNACOS_LDAP_USER_ADMIN_GROUP=cn=admins,ou=groups,dc=example,dc=com
RNACOS_LDAP_USER_DEFAULT_ROLE=DEVELOPER

```

### Shell Export Commands

Export variables directly in your shell before launching the r-nacos binary:

```bash
export RNACOS_LDAP_ENABLE=true
export RNACOS_LDAP_URL=ldap://ldap.local:389
export RNACOS_LDAP_USER_BASE_DN=ou=people,dc=example,dc=com
export RNACOS_LDAP_USER_FILTER='(&(objectClass=person)(uid=%s))'
export RNACOS_LDAP_USER_DEVELOPER_GROUP=dev_group1,dev_group2
export RNACOS_LDAP_USER_ADMIN_GROUP=admin_group1,admin_group2
export RNACOS_LDAP_USER_DEFAULT_ROLE=VISITOR

./r-nacos

```

## Summary

- **Enable LDAP** by setting `RNACOS_LDAP_ENABLE=true` before starting the server.
- **Configure connection** parameters (`RNACOS_LDAP_URL`, `RNACOS_LDAP_USER_BASE_DN`, `RNACOS_LDAP_USER_FILTER`) to point to your LDAP server and define the user search strategy.
- **Map groups to roles** using `RNACOS_LDAP_USER_DEVELOPER_GROUP` and `RNACOS_LDAP_USER_ADMIN_GROUP`; unmatched users receive the `RNACOS_LDAP_USER_DEFAULT_ROLE`.
- **Implementation details** are located in [`src/common/mod.rs`](https://github.com/nacos-group/r-nacos/blob/main/src/common/mod.rs) (configuration parsing), [`src/ldap/model/mod.rs`](https://github.com/nacos-group/r-nacos/blob/main/src/ldap/model/mod.rs) (data structures), and [`src/ldap/ldap_conn.rs`](https://github.com/nacos-group/r-nacos/blob/main/src/ldap/ldap_conn.rs) (connection handling).

## Frequently Asked Questions

### What is the minimum set of environment variables required to enable LDAP?

You must set `RNACOS_LDAP_ENABLE=true` and provide `RNACOS_LDAP_URL`, `RNACOS_LDAP_USER_BASE_DN`, and `RNACOS_LDAP_USER_FILTER`. Without these four variables, the `LdapConfig` struct cannot be properly initialized and the LDAP actor will fail to start.

### How does the group-to-role mapping work in r-nacos LDAP integration?

After successful authentication, r-nacos retrieves the user's LDAP groups and compares them against the comma-separated values in `RNACOS_LDAP_USER_DEVELOPER_GROUP` and `RNACOS_LDAP_USER_ADMIN_GROUP`. If the user belongs to any group listed in the admin variable, they receive the **ADMIN** role; otherwise, if they match a developer group, they receive the **DEVELOPER** role. If no groups match, the user receives the role specified by `RNACOS_LDAP_USER_DEFAULT_ROLE`.

### Where does r-nacos load the LDAP configuration from?

The configuration is loaded at startup from environment variables by the `init_ldap_config` function in [`src/common/mod.rs`](https://github.com/nacos-group/r-nacos/blob/main/src/common/mod.rs) (lines 70-95). These values are parsed into the `LdapConfig` struct defined in [`src/ldap/model/mod.rs`](https://github.com/nacos-group/r-nacos/blob/main/src/ldap/model/mod.rs) and then passed to the `LdapConnActor` in [`src/ldap/ldap_conn.rs`](https://github.com/nacos-group/r-nacos/blob/main/src/ldap/ldap_conn.rs) to establish the connection.

### Can I use LDAP with TLS/SSL in r-nacos?

The `RNACOS_LDAP_URL` variable accepts standard LDAP URLs, so you can specify `ldaps://ldap.mycompany.com:636` to enable TLS encryption. Ensure your r-nacos environment trusts the LDAP server's certificate; the underlying LDAP library used by the `LdapConnActor` handles the TLS handshake when the `ldaps` scheme is detected in the URL.