LDAP

LDAP service extensions let you customize how the Orchestrator handles directory operations when running as an LDAP provider. Use these hooks to implement custom search logic, authenticate users against external systems, or support Windows integrated authentication (NTLM via GSSAPI/SPNEGO).

Request Lifecycle

The LDAP provider operates over TCP using the LDAP protocol (not HTTP). Each operation type has its own processing flow and hook point.

Search

Simple Bind Authentication

NTLM Authentication (GSSAPI/SPNEGO)

NTLM authentication is a multi-message handshake within a SASL bind. The getHashedCredentialsSE hook is called during the final Authenticate phase to retrieve the password hashes needed for verification.

Hooks

`searchSE`

Handle LDAP search requests by returning directory entries that match the query. Each entry maps a distinguished name (DN) to its attributes. Use this to implement custom search logic, query external directories, filter results, or build virtual directory entries from non-LDAP sources like databases or REST APIs. Signature:

func Search(api orchestrator.Orchestrator, baseDN string, filter string, attrs []string) (map[string]map[string]interface{}, error)

App types: LDAP Provider Config location: ldapProvider.search.searchSE Parameters:

Parameter	Type	Description
`api`	`orchestrator.Orchestrator`	Access to sessions, caches, secrets, logging, and other Orchestrator services
`baseDN`	`string`	The base distinguished name for the search
`filter`	`string`	The LDAP search filter expression
`attrs`	`[]string`	The list of attribute names to return

Returns:

map[string]map[string]interface{} — a map of DNs to attribute maps, where each attribute map contains the requested attribute name-value pairs
error — return nil on success, or an error if the search fails

`authenticateSE`

Authenticate a user via LDAP simple bind. Return true if the credentials are valid, or false to deny authentication. Use this to validate credentials against an external system, implement custom password policies, or bridge LDAP authentication to a non-LDAP identity store. Signature:

func Authenticate(api orchestrator.Orchestrator, dn string, password string) (bool, error)

App types: LDAP Provider Config location: ldapProvider.authentication.methods.simple.authenticateSE Parameters:

Parameter	Type	Description
`api`	`orchestrator.Orchestrator`	Access to sessions, caches, secrets, logging, and other Orchestrator services
`dn`	`string`	The distinguished name of the user attempting to bind
`password`	`string`	The password provided by the user

Returns:

bool — true if the credentials are valid, false otherwise
error — return nil on success, or an error if the authentication process fails

Examples:

Delegate simple bind to an IdP via ROPC

When an LDAP client performs a simple bind, this extension extracts the username from the bind DN and authenticates the user against an OIDC identity provider using the Resource Owner Password Credentials (ROPC) grant. This bridges LDAP authentication with a modern IdP without changes to the client application.

Extension
Configuration

ldap-authenticate.go

package main

import (
    "errors"
    "fmt"
    "strings"

    "github.com/strata-io/service-extension/idfabric"
    "github.com/strata-io/service-extension/orchestrator"
)

func Authenticate(
    api orchestrator.Orchestrator,
    dn string,
    password string,
) (bool, error) {
    logger := api.Logger()
    logger.Debug("se", "ldap-auth", "msg", "authenticating user", "dn", dn)

    // Extract the username from the bind DN.
    username, err := parseUsername(dn)
    if err != nil {
        logger.Error("se", "ldap-auth", "msg", "failed to parse DN", "error", err.Error())
        return false, err
    }

    // Delegate authentication to the OIDC provider via ROPC.
    idp, err := api.IdentityProvider("oidc")
    if err != nil {
        logger.Error("se", "ldap-auth", "msg", "failed to get IdP", "error", err)
        return false, err
    }

    var result idfabric.LoginResult
    idp.Login(
        nil,
        nil,
        idfabric.WithGrantTypeROPC(
            idfabric.ROPCRequest{Username: username, Password: password},
            &result,
        ),
    )

    if result.Error != nil {
        logger.Error("se", "ldap-auth", "msg", "authentication failed", "error", result.Error)
        return false, result.Error
    }

    return true, nil
}

// parseUsername extracts the value of the first RDN from a DN.
// e.g., "cn=jdoe,ou=users,dc=example,dc=com" -> "jdoe"
func parseUsername(dn string) (string, error) {
    parts := strings.Split(dn, ",")
    if len(parts) == 0 {
        return "", errors.New("invalid DN format")
    }

    rdn := parts[0]
    eqIdx := strings.Index(rdn, "=")
    if eqIdx < 0 || eqIdx == len(rdn)-1 {
        return "", fmt.Errorf("malformed RDN: %s", rdn)
    }

    return rdn[eqIdx+1:], nil
}

maverics.yaml

connectors:
  - name: oidc
    type: oidc
    oidcWellKnownURL: https://idp.example.com/.well-known/openid-configuration
    oauthClientID: my-client
    oauthClientSecret: <client_secret>
    scopes: openid profile email

ldapProvider:
  enabled: true
  uri: ldaps://0.0.0.0:636
  authentication:
    allowAnonymous: false
    methods:
      simple:
        enabled: true
        authenticateSE:
          file: /etc/maverics/service-extensions/ldap-authenticate.go
          funcName: Authenticate

Add TOTP multi-factor authentication to simple bind

Applications that authenticate via LDAP simple bind have no built-in way to support multi-factor authentication. This extension works around that limitation by treating the password field as a concatenation of the real password and a TOTP code (e.g., myP@ssword12345678). The password portion is verified against an IdP via ROPC, and the TOTP code is verified against an external MFA API.

Extension
Configuration

ldap-authenticate-totp.go

package main

import (
    "encoding/base64"
    "fmt"
    "io"
    "net/http"
    "net/url"
    "strings"

    "github.com/strata-io/service-extension/idfabric"
    "github.com/strata-io/service-extension/orchestrator"
)

const (
    // Number of characters at the end of the password that
    // contain the TOTP code.
    totpCodeLength = 8
)

func Authenticate(
    api orchestrator.Orchestrator,
    dn string,
    password string,
) (bool, error) {
    logger := api.Logger()
    logger.Debug("se", "ldap-auth", "msg", "authenticating user", "dn", dn)

    // Split the password into the real password and appended TOTP code.
    if len(password) < totpCodeLength {
        logger.Debug("se", "ldap-auth", "msg", "password too short to contain TOTP code")
        return false, nil
    }
    actualPassword := password[:len(password)-totpCodeLength]
    totpCode := password[len(password)-totpCodeLength:]

    // Step 1: Verify the password via ROPC against the IdP.
    idp, err := api.IdentityProvider("oidc")
    if err != nil {
        logger.Error("se", "ldap-auth", "msg", "failed to get IdP", "error", err)
        return false, err
    }

    username, err := parseUsername(dn)
    if err != nil {
        return false, err
    }

    var loginResult idfabric.LoginResult
    idp.Login(
        nil,
        nil,
        idfabric.WithGrantTypeROPC(
            idfabric.ROPCRequest{Username: username, Password: actualPassword},
            &loginResult,
        ),
    )

    if loginResult.Error != nil {
        logger.Error("se", "ldap-auth", "msg", "password verification failed", "error", loginResult.Error)
        return false, loginResult.Error
    }

    // Step 2: Verify the TOTP code against the MFA provider.
    verified, err := verifyTOTP(api, totpCode)
    if err != nil {
        logger.Error("se", "ldap-auth", "msg", "TOTP verification error", "error", err)
        return false, err
    }

    if !verified {
        logger.Debug("se", "ldap-auth", "msg", "TOTP verification failed")
        return false, nil
    }

    return true, nil
}

// verifyTOTP calls an external MFA provider API to verify the TOTP code.
func verifyTOTP(api orchestrator.Orchestrator, totpCode string) (bool, error) {
    sp := api.SecretProvider()
    accountSID, err := sp.GetString("mfa-account-sid")
    if err != nil {
        return false, fmt.Errorf("failed to get MFA account SID: %w", err)
    }
    authToken, err := sp.GetString("mfa-auth-token")
    if err != nil {
        return false, fmt.Errorf("failed to get MFA auth token: %w", err)
    }
    serviceID, err := sp.GetString("mfa-service-id")
    if err != nil {
        return false, fmt.Errorf("failed to get MFA service ID: %w", err)
    }
    entityID, err := sp.GetString("mfa-entity-id")
    if err != nil {
        return false, fmt.Errorf("failed to get MFA entity ID: %w", err)
    }

    apiURL := fmt.Sprintf(
        "https://verify.example.com/v2/Services/%s/Entities/%s/Challenges",
        serviceID, entityID,
    )

    formData := url.Values{}
    formData.Set("AuthPayload", totpCode)

    req, err := http.NewRequest(http.MethodPost, apiURL, strings.NewReader(formData.Encode()))
    if err != nil {
        return false, fmt.Errorf("failed to create request: %w", err)
    }

    req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
    auth := base64.StdEncoding.EncodeToString([]byte(accountSID + ":" + authToken))
    req.Header.Set("Authorization", "Basic "+auth)

    resp, err := api.HTTP().DefaultClient().Do(req)
    if err != nil {
        return false, fmt.Errorf("failed to call MFA API: %w", err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    api.Logger().Debug("se", "ldap-auth", "msg", "MFA API response", "status", resp.StatusCode, "body", string(body))

    return resp.StatusCode == http.StatusCreated, nil
}

// parseUsername extracts the value of the first RDN from a DN.
func parseUsername(dn string) (string, error) {
    parts := strings.Split(dn, ",")
    if len(parts) == 0 {
        return "", fmt.Errorf("invalid DN format")
    }

    rdn := parts[0]
    eqIdx := strings.Index(rdn, "=")
    if eqIdx < 0 || eqIdx == len(rdn)-1 {
        return "", fmt.Errorf("malformed RDN: %s", rdn)
    }

    return rdn[eqIdx+1:], nil
}

maverics.yaml

connectors:
  - name: oidc
    type: oidc
    oidcWellKnownURL: https://idp.example.com/.well-known/openid-configuration
    oauthClientID: my-client
    oauthClientSecret: <client_secret>
    scopes: openid profile email

ldapProvider:
  enabled: true
  uri: ldaps://0.0.0.0:636
  authentication:
    allowAnonymous: false
    methods:
      simple:
        enabled: true
        authenticateSE:
          file: /etc/maverics/service-extensions/ldap-authenticate-totp.go
          funcName: Authenticate

`getHashedCredentialsSE`

Provide the password hashes needed for Windows integrated authentication (NTLM). The Orchestrator calls this during the GSSAPI/SPNEGO handshake with the user and domain identifiers, and expects back the pre-computed NT and LM password hashes. Use this to look up hashes from a credential store or compute them from a source system. Signature:

func GetHashedCredentials(api orchestrator.Orchestrator, user []byte, domain []byte) ([]byte, []byte, error)

App types: LDAP Provider Config location: ldapProvider.authentication.methods.sasl.mechanisms.gssspnego.ntlm.getHashedCredentialsSE Parameters:

Parameter	Type	Description
`api`	`orchestrator.Orchestrator`	Access to sessions, caches, secrets, logging, and other Orchestrator services
`user`	`[]byte`	The user identifier for the NTLM authentication
`domain`	`[]byte`	The domain identifier for the NTLM authentication

Returns:

[]byte — the NT password hash for the user
[]byte — the LM password hash for the user
error — return nil on success, or an error if the credential lookup fails

Service Extensions Overview

Configuration, SDK reference, and best practices

LDAP Provider Mode

LDAP provider mode configuration and setup

Console Administration

Orchestration

Request Lifecycle

Search

Simple Bind Authentication

NTLM Authentication (GSSAPI/SPNEGO)

Hooks

`searchSE`

`authenticateSE`

`getHashedCredentialsSE`

Service Extensions Overview

LDAP Provider Mode

​Request Lifecycle

​Search

​Simple Bind Authentication

​NTLM Authentication (GSSAPI/SPNEGO)

​Hooks

​searchSE

​authenticateSE

​getHashedCredentialsSE

​Related Pages

Service Extensions Overview

LDAP Provider Mode

Request Lifecycle

Search

Simple Bind Authentication

NTLM Authentication (GSSAPI/SPNEGO)

Hooks

`searchSE`

`authenticateSE`

`getHashedCredentialsSE`

Related Pages