> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strata.io/llms.txt
> Use this file to discover all available pages before exploring further.

# LDAP Authentication

The LDAP Authentication connector integrates the Maverics Orchestrator with LDAP-based directory services -- enabling user authentication via LDAP bind operations. For attribute-only lookups without authentication, see [LDAP Attribute Provider](/reference/orchestrator/identity-fabric/ldap-attr). For Microsoft Active Directory environments, see the dedicated [Active Directory connector](/reference/orchestrator/identity-fabric/activedirectory).

<Note>
  **Console terminology:** In the Maverics Console, this section is called
  **Identity Fabric**. The YAML configuration uses the `connectors` key to define
  identity provider integrations.
</Note>

## Overview

The LDAP Authentication connector supports both LDAP and LDAPS (LDAP over TLS) protocols for secure directory integration. It authenticates end users via LDAP bind operations against the directory. For attribute-only lookups without authentication, see the [LDAP Attribute Provider](/reference/orchestrator/identity-fabric/ldap-attr).

## Use Cases

* **Legacy app SSO with on-premises directories** -- Extend single sign-on to applications that authenticate against LDAP directories, without rewriting the application or migrating users out of the directory
* **IdP consolidation for LDAP-dependent apps** -- Route authentication through the Orchestrator so LDAP-bound applications can participate in a unified authentication layer, reducing the need for standalone LDAP integrations per app
* **Hybrid identity bridge** -- Combine LDAP bind authentication with cloud IdP sessions so users in on-premises directories can access both legacy and modern applications through a single login experience
* **Combined authentication and attribute retrieval** -- Authenticate users and retrieve directory attributes (group memberships, email, department) in a single connector for header injection or policy evaluation

## Setup

<Tabs>
  <Tab title="Console UI">
    To create an LDAP Authentication connector in the Maverics Console:

    **Settings**

    1. Navigate to **Identity Fabric** in the Console sidebar.
    2. Click **Create** and select **LDAP Authentication**.
    3. Enter a **Name** for the connector.
    4. Enter the **URL** of the LDAP server (e.g., `ldaps://ldap.example.com:636`).
    5. Enter the **Service Account Username** (bind DN used to connect to the server).
    6. Enter the **Service Account Password**.
    7. Enter the **Base DN** for LDAP searches (e.g., `dc=example,dc=com`).
    8. Enter the **Username Search Key** -- the attribute used to filter on during query and bind operations (e.g., `uid` for OpenLDAP, `sAMAccountName` for AD).
    9. Optionally select an **Authentication Search Scope** from the dropdown to control the search depth (e.g., `wholeSubtree`).
    10. Click **Save**.

    **Template and Assets**

    To configure a custom login page with localization:

    1. In the connector settings, scroll to the **Template and Assets** section.
    2. Upload a **Template File** -- an HTML file using Go Template syntax that renders the login form (e.g., `ldap-login.html`).
    3. Under **Methods**, configure the language parsing method:
       * **Parsing Method Type** -- How the Orchestrator determines the user's language. Options include `http.request.header` (from the `Accept-Language` header) or `http.request.query` (from a URL query parameter).
       * **Parsing Method Name** -- The specific header or query parameter name to read the language from (e.g., `Accept-Language` for headers, or `ui_local` for a query parameter).
    4. Under **Localization**, add one or more language entries:
       * **Language** -- A BCP 47 language tag (e.g., `en`, `fr`, `es`).
       * Upload the corresponding JSON localization file for each language.
    5. Click **Save**.
  </Tab>

  <Tab title="Configuration">
    ```yaml maverics.yaml theme={null}
    connectors:
      - name: ldap
        type: ldap
        url:
          - "ldaps://ldap.example.com:636"
        serviceAccountUsername: "cn=admin,dc=example,dc=com"
        serviceAccountPassword: <vault.ldap_password>
        baseDN: "dc=example,dc=com"
        usernameSearchKey: uid
        enableAuthentication: true
        authenticationSearchScope: wholeSubtree
        loginURL: /.ldap-login
        customLogin:
          templateFile: /etc/maverics/ldap-login.html
          parseLanguageFrom:
            type: http.request.header
            name: Accept-Language
          localization:
            en: /etc/maverics/en.json
            fr: /etc/maverics/fr.json
        userAttributes:
          - cn
          - email
          - memberOf
        attributeMapping:
          email: mail
          name: cn
        tls: ldap-tls
    ```

    ## Configuration Reference

    | Key                                  | Type      | Required | Description                                                                                                                                            |
    | ------------------------------------ | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | `name`                               | string    | Yes      | Unique connector identifier referenced by app policies and attribute providers                                                                         |
    | `type`                               | string    | Yes      | Must be `ldap`                                                                                                                                         |
    | `url`                                | string\[] | Yes      | LDAP server URLs -- supports `ldap://` (port 389) and `ldaps://` (port 636); multiple URLs enable failover                                             |
    | `serviceAccountUsername`             | string    | Yes      | Bind DN for the service account (e.g., `cn=admin,dc=example,dc=com`)                                                                                   |
    | `serviceAccountPassword`             | string    | Yes      | Service account password -- use secret reference syntax `<namespace.key>`                                                                              |
    | `baseDN`                             | string    | Yes      | Base DN for LDAP searches (e.g., `dc=example,dc=com`)                                                                                                  |
    | `usernameSearchKey`                  | string    | No       | LDAP attribute used for username lookup (e.g., `uid` for OpenLDAP, `sAMAccountName` for AD)                                                            |
    | `userRDNKey`                         | string    | No       | Relative Distinguished Name key for user entries                                                                                                       |
    | `enableAuthentication`               | boolean   | No       | Enable LDAP bind authentication for end users                                                                                                          |
    | `loginURL`                           | string    | No       | Custom endpoint for posting user credentials (default: `/.ldap-login`)                                                                                 |
    | `authenticationSearchScope`          | string    | No       | LDAP search scope for authentication queries (e.g., `wholeSubtree`, `singleLevel`, `baseObject`)                                                       |
    | `customLogin.templateFile`           | string    | No       | Path to a custom HTML login form template using Go Template syntax                                                                                     |
    | `customLogin.parseLanguageFrom.type` | string    | No       | How to determine the user's language -- `http.request.header` (from a request header) or `http.request.query` (from a URL query parameter)             |
    | `customLogin.parseLanguageFrom.name` | string    | No       | The header or query parameter name to read the language from (e.g., `Accept-Language` or `ui_local`)                                                   |
    | `customLogin.localization`           | map       | No       | Map of BCP 47 language tags to localization file paths (e.g., `en: /etc/maverics/en.json`)                                                             |
    | `userAttributes`                     | string\[] | No       | LDAP attributes to retrieve during searches (e.g., `["cn", "mail", "memberOf"]`)                                                                       |
    | `objectClasses`                      | string\[] | No       | Object classes for the LDAP search filter (e.g., `["inetOrgPerson"]`)                                                                                  |
    | `attributeMapping`                   | map       | No       | Map Orchestrator attribute names to LDAP attribute names (e.g., `email: "mail"`)                                                                       |
    | `attributeDelimiter`                 | string    | No       | Delimiter for multi-valued LDAP attributes (default: `","`)                                                                                            |
    | `tls`                                | string    | No       | Named TLS profile for LDAP connection                                                                                                                  |
    | `healthCheck`                        | object    | No       | Health check monitoring configuration (see [Identity Fabric Configuration Reference](/reference/orchestrator/identity-fabric#configuration-reference)) |

    For the complete connector field reference including health check details, see [Identity Fabric Configuration Reference](/reference/orchestrator/identity-fabric#configuration-reference).

    <Note>
      The LDAP connector supports `attributeMapping` to translate between LDAP attribute names and Orchestrator attribute names. For example, mapping `email: "mail"` allows you to reference the attribute as `ldap.email` in header templates and policy rules, even though the LDAP directory stores it as `mail`. OIDC-based connectors do not have this field -- they use claims directly from the OIDC token.
    </Note>
  </Tab>
</Tabs>

## Custom Login Page

When `customLogin.templateFile` is configured, the Orchestrator serves a custom HTML page for LDAP authentication instead of the default login form. The template file uses [Go Template](https://pkg.go.dev/html/template) syntax with the following variables:

| Variable        | Type   | Description                                                                                          |
| --------------- | ------ | ---------------------------------------------------------------------------------------------------- |
| `.LoginURL`     | string | The URL the form must POST credentials to                                                            |
| `.RedirectURL`  | string | The originally requested URL -- include as a hidden form field so the user is redirected after login |
| `.Error`        | string | An error message if the previous login attempt failed (empty on first load)                          |
| `.Language`     | string | The resolved BCP 47 language tag for the current request                                             |
| `.Localization` | object | The parsed localization data from the JSON file matching the current language                        |

The login form must submit a `POST` request to `{{ .LoginURL }}` with the following form fields:

* `username` -- the user's login name
* `password` -- the user's password
* `redirectURL` -- the value of `{{ .RedirectURL }}`

**Example template:**

```html ldap-login.html theme={null}
<!DOCTYPE html>
<html lang="{{ .Language }}">
<head>
    <meta charset="UTF-8">
    <title>{{ .Localization.title }}</title>
</head>
<body>
    <h1>{{ .Localization.title }}</h1>

    {{ if .Error }}
    <div class="error">{{ .Localization.error }}</div>
    {{ end }}

    <form method="POST" action="{{ .LoginURL }}">
        <input type="hidden" name="redirectURL" value="{{ .RedirectURL }}">
        <label>{{ .Localization.username }}</label>
        <input type="text" name="username" required>
        <label>{{ .Localization.password }}</label>
        <input type="password" name="password" required>
        <button type="submit">{{ .Localization.submit }}</button>
    </form>
</body>
</html>
```

## Localization

The custom login page supports standards-based language localization using [BCP 47](https://www.rfc-editor.org/info/bcp47) language tags. The Orchestrator determines the user's preferred language and loads the corresponding localization file, making its contents available as `.Localization` in the Go Template.

### Language Detection

The `customLogin.parseLanguageFrom` block controls how the Orchestrator determines the user's preferred language:

* **`http.request.header`** -- Parses the language from an HTTP request header. Set `name` to `Accept-Language` to use the browser's default language preference.
* **`http.request.query`** -- Parses the language from a URL query parameter. Set `name` to the query parameter name (e.g., `ui_local` for URLs like `?ui_local=fr`).

If the detected language does not match any configured localization, the Orchestrator falls back to the first localization entry.

### Localization File Format

Each localization file is a JSON object with key-value pairs. The keys are referenced in the Go Template as fields on `.Localization`:

```json en.json theme={null}
{
  "title": "Login",
  "username": "Username",
  "password": "Password",
  "submit": "Sign In",
  "error": "Invalid username or password. Please try again."
}
```

```json fr.json theme={null}
{
  "title": "Connexion",
  "username": "Nom d'utilisateur",
  "password": "Mot de passe",
  "submit": "Se connecter",
  "error": "Nom d'utilisateur ou mot de passe invalide. Veuillez réessayer."
}
```

Reference localization values in the template using `{{ .Localization.<key> }}` (e.g., `{{ .Localization.title }}`).

## Troubleshooting

* **Test LDAP connectivity from the Orchestrator host** -- Use `ldapsearch` or a similar tool to verify the Orchestrator can reach the LDAP server on the configured port. Network firewalls or DNS issues are common causes of connection failures.
* **Verify the service account has read permissions on the baseDN** -- The bind DN specified in `serviceAccountUsername` must have sufficient permissions to search the `baseDN` subtree and read the attributes listed in `userAttributes`.
* **For LDAPS, ensure the TLS profile includes the correct CA certificate** -- If the LDAP server uses a private CA, the TLS profile referenced by the `tls` field must include the CA certificate via `caFile`. Self-signed certificates require `insecureSkipVerify: true` (not recommended for production).
* **Check attribute names in mapping** -- LDAP attribute names are case-insensitive in the protocol but must match the directory schema. Common sources of confusion: `mail` vs `email`, `cn` vs `commonName`, `sAMAccountName` vs `uid`.
* **Custom login page not rendering** -- Verify that the `customLogin.templateFile` path is correct and the file is readable by the Orchestrator process. Check Orchestrator logs for template parsing errors.
* **Localization not switching languages** -- Confirm that the `parseLanguageFrom.type` and `parseLanguageFrom.name` values match how your application sends language preferences. Verify the BCP 47 tags in the `localization` map match the tags sent by the client.

## Related Pages

<CardGroup cols={2}>
  <Card title="LDAP Attribute Provider" icon="folder-tree" href="/reference/orchestrator/identity-fabric/ldap-attr">
    LDAP attribute lookups without authentication
  </Card>

  <Card title="Active Directory" icon="microsoft" href="/reference/orchestrator/identity-fabric/activedirectory">
    LDAP-based connector optimized for Active Directory environments
  </Card>

  <Card title="Identity Fabric" icon="id-badge" href="/reference/orchestrator/identity-fabric">
    Overview of all identity providers
  </Card>

  <Card title="Continuity" icon="arrows-rotate" href="/reference/orchestrator/identity-fabric/continuity">
    IdP failover connector
  </Card>
</CardGroup>