How to Configure LDAP Authentication with INFINI Console: Security Realm Setup Guide

To configure LDAP authentication with INFINI Console, declare an LDAP realm in your security configuration with connection details, service account credentials, and role mappings, then set enabled: true to activate the provider.

The INFINI Console security module provides a pluggable realm-based architecture for authentication and authorization, allowing integration with corporate directory services like Active Directory or OpenLDAP. This guide explains how to configure LDAP authentication with INFINI Console based on the actual implementation in the infinilabs/console repository, covering the supported realm settings and the underlying code flow in modules/security/realm/authc/ldap/ldap.go.

Understanding INFINI Console's Security Realm Architecture

INFINI Console’s security subsystem is built around realms—pluggable authentication and authorization providers that handle identity verification. The framework ships with a native username/password realm and a fully implemented LDAP realm. While OAuth providers exist in the codebase, they are currently disabled placeholders.

When the Console initializes, the realm.Init routine in modules/security/realm/realm.go walks through the configured realms, instantiates enabled providers, and registers them in a global slice used for all Authenticate and Authorize calls.

Prerequisites for LDAP Integration

Before you configure LDAP authentication with INFINI Console, ensure you have:

• Service Account Credentials: A bind DN and password with read access to user entries and group attributes.
• Directory Schema Knowledge: The attribute names for user IDs (uid, sAMAccountName) and group memberships (memberOf, group).
• Network Connectivity: TCP access to your LDAP server on ports 389 (LDAP) or 636 (LDAPS).

Step-by-Step: Configure LDAP Authentication with INFINI Console

Step 1: Declare the LDAP Realm in Security Configuration

Define your LDAP realm in the Console configuration structure. In modules/security/config/config.go, the RealmsConfig struct contains a map of LDAP configurations, allowing you to define multiple named LDAP providers (for example, one for Active Directory and one for OpenLDAP).

security:
  enabled: true
  authentication:
    realms:
      ldap:
        corporate_ad:
          enabled: true

Step 2: Configure Connection Parameters

Provide the network and binding credentials that allow the Console to connect to your directory service. These fields map directly to the LDAPConfig struct in modules/security/realm/authc/ldap/ldap.go.

          tls: true
          host: ldap.corporate.com
          port: 636
          bind_dn: "cn=console-service,ou=service-accounts,dc=corporate,dc=com"
          bind_password: "${LDAP_BIND_PASSWORD}"

Setting tls: true enables LDAPS encryption, which is strongly recommended for production environments to protect credentials in transit.

Step 3: Map Users and Groups to INFINI Roles

Define how directory entries translate into Console permissions using search filters and role mappings. The user_filter uses standard LDAP filter syntax with {0} as a placeholder for the login username.

          base_dn: "ou=employees,dc=corporate,dc=com"
          user_filter: "(&(objectClass=user)(sAMAccountName={0}))"
          uid_attribute: "sAMAccountName"
          group_attribute: "memberOf"
          default_roles:
            - "viewer"
          role_mapping:
            group:
              "cn=platform-admins,ou=groups,dc=corporate,dc=com":
                - "admin"
                - "editor"
            uid:
              "service-account-01":
                - "system"

The role_mapping.group block translates LDAP group DNs into INFINI Console role names, while role_mapping.uid allows per-user overrides. The default_roles are granted to every successfully authenticated user regardless of directory group membership.

Complete LDAP Realm Configuration Example

Here is a production-ready configuration that combines all settings. This YAML block corresponds directly to the LDAPConfig struct defined in modules/security/realm/authc/ldap/ldap.go and processed by the initialization logic in modules/security/realm/realm.go.

# config/security.yaml

security:
  enabled: true
  authentication:
    realms:
      native:
        enabled: false          # Disable native auth when using LDAP exclusively

      ldap:
        primary_directory:
          enabled: true
          tls: true
          host: ldap.mycorp.com
          port: 636
          bind_dn: "cn=console,ou=service,dc=mycorp,dc=com"
          bind_password: "REPLACE_WITH_SECRET"
          base_dn: "ou=people,dc=mycorp,dc=com"
          user_filter: "(&(objectClass=person)(uid={0}))"
          uid_attribute: "uid"
          group_attribute: "memberOf"
          default_roles:
            - "viewer"
          role_mapping:
            group:
              "cn=admins,ou=groups,dc=mycorp,dc=com":
                - "admin"
                - "editor"
            uid:
              "jdoe":
                - "special-report"

After saving this configuration and restarting the Console, the security module initializes the LDAP provider during the realm.Init call and routes all authentication requests through the configured directory service.

How LDAP Authentication Works Under the Hood

When you configure LDAP authentication with INFINI Console, the following code path executes during startup and login operations.

Realm Registration

In modules/security/realm/realm.go, the Init function iterates over config.Authentication.Realms.LDAP. For each entry with enabled: true, it instantiates a new LDAPRealm by calling ldap2.New(v) and appends it to the global realms slice (lines 68-74). This makes the LDAP provider available for subsequent Authenticate and Authorize calls.

Authentication Flow

The LDAPRealm struct defined in modules/security/realm/authc/ldap/ldap.go implements the Authenticate method. When a user submits credentials:

1. The realm constructs an ldap.Config (lines 110-123 of ldap.go) using your LDAPConfig values.
2. It obtains an AuthenticateFunc via ldap.GetAuthenticateFunc.
3. The function attempts to bind to the LDAP server using the user-provided credentials.
4. Upon successful bind, it retrieves the user's LDAP entry and extracts attributes defined by uid_attribute and group_attribute.

Authorization Flow

After successful authentication, the Authorize method extracts group memberships from the LDAP entry using authInfo.GetGroups(). It then processes these through the mapLDAPRoles function, which compares the LDAP groups against the role_mapping.group configuration. Any matching entries grant the corresponding INFINI roles. Finally, the default_roles are appended to the permission set regardless of group membership.

Supported Realm Settings Reference

The following settings are defined in the LDAPConfig struct within modules/security/realm/authc/ldap/ldap.go and supported in your YAML configuration:

• enabled (Enabled): Boolean flag to activate (true) or deactivate (false) this LDAP realm.
• tls (Tls): Enable TLS encryption for the connection (true for LDAPS on port 636, false for plain LDAP on port 389).
• host (Host): Hostname or IP address of the LDAP server.
• port (Port): TCP port number (typically 389 for LDAP or 636 for LDAPS).
• bind_dn (BindDn): Distinguished Name of the service account used for initial directory searches.
• bind_password (BindPassword): Password for the bind DN service account.
• base_dn (BaseDn): Base Distinguished Name where user searches begin.
• user_filter (UserFilter): LDAP search filter to locate user entries, using {0} as the username placeholder (e.g., (&(objectClass=person)(uid={0}))).
• uid_attribute (UidAttribute): LDAP attribute containing the unique user identifier (commonly uid for OpenLDAP or sAMAccountName for Active Directory).
• group_attribute (GroupAttribute): LDAP attribute containing group memberships (typically memberOf in Active Directory).
• default_roles (DefaultRoles): List of INFINI Console roles automatically granted to all authenticated LDAP users.
• role_mapping.group (RoleMapping.Group): Map of LDAP group names to lists of INFINI Console role names.
• role_mapping.uid (RoleMapping.Uid): Map of specific LDAP UIDs to lists of INFINI Console role names for per-user overrides.

Summary

• INFINI Console uses a realm-based security architecture where LDAP is implemented as a pluggable provider alongside the native authentication realm.
• To configure LDAP authentication with INFINI Console, you must define an LDAPConfig block in your security YAML with connection details, bind credentials, and role mappings.
• The system supports TLS encryption, Active Directory (via sAMAccountName and memberOf attributes), and flexible role mapping through both group-based and UID-based assignments.
• Under the hood, the realm.Init function in modules/security/realm/realm.go registers enabled LDAP providers, while modules/security/realm/authc/ldap/ldap.go handles the bind operations and permission resolution.

Frequently Asked Questions

Does INFINI Console support Active Directory integration?

Yes, INFINI Console's LDAP realm is fully compatible with Active Directory. Configure uid_attribute as sAMAccountName and group_attribute as memberOf to match AD schema conventions. The user_filter should use (&(objectClass=user)(sAMAccountName={0})) to locate accounts correctly.

Can I use multiple LDAP realms simultaneously?

Yes, the configuration structure in modules/security/config/config.go defines LDAP as a map, allowing you to define multiple named realms (e.g., corporate_ad and legacy_openldap). Each realm operates independently, and you can enable or disable them individually while keeping the native realm as a fallback.

What happens if the LDAP server is unavailable?

If the LDAP server is unreachable during an authentication attempt, the LDAP realm returns an authentication error. If you have retained the native realm with enabled: true, the system can fall back to native authentication. Otherwise, users cannot log in until LDAP connectivity is restored.

How do I map LDAP groups to specific INFINI Console permissions?

Use the role_mapping.group configuration block to translate LDAP group names (e.g., cn=admins,ou=groups,dc=example,dc=com) into INFINI Console role names (e.g., admin, editor). You can also use role_mapping.uid for per-user overrides and default_roles to assign baseline permissions to all LDAP-authenticated users.

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