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

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 (lines 70-95) and stored in the LdapConfig struct defined in 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 (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 (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:

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:

# 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:

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 (configuration parsing), src/ldap/model/mod.rs (data structures), and 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 (lines 70-95). These values are parsed into the LdapConfig struct defined in src/ldap/model/mod.rs and then passed to the LdapConnActor in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}