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

> Secure your INFINI Console by configuring LDAP authentication. Learn how to set up security realms with connection details, credentials, and role mappings for seamless integration.

- Repository: [INFINI Labs/console](https://github.com/infinilabs/console)
- Tags: how-to-guide
- Published: 2026-03-04

---

**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`](https://github.com/infinilabs/console/blob/main/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`](https://github.com/infinilabs/console/blob/main/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`](https://github.com/infinilabs/console/blob/main/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).

```yaml
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`](https://github.com/infinilabs/console/blob/main/modules/security/realm/authc/ldap/ldap.go).

```yaml
          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.

```yaml
          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`](https://github.com/infinilabs/console/blob/main/modules/security/realm/authc/ldap/ldap.go) and processed by the initialization logic in [`modules/security/realm/realm.go`](https://github.com/infinilabs/console/blob/main/modules/security/realm/realm.go).

```yaml

# 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`](https://github.com/infinilabs/console/blob/main/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`](https://github.com/infinilabs/console/blob/main/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`](https://github.com/infinilabs/console/blob/main/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`](https://github.com/infinilabs/console/blob/main/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`](https://github.com/infinilabs/console/blob/main/modules/security/realm/realm.go) registers enabled LDAP providers, while [`modules/security/realm/authc/ldap/ldap.go`](https://github.com/infinilabs/console/blob/main/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`](https://github.com/infinilabs/console/blob/main/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.