LDAP / Active Directory

When to use: The common on-prem case: developers authenticate against Active Directory over LDAPS, and AD group membership (via memberOf) decides which busbar team (and budget) they land on.

public_url: "https://busbar.example.com"
plugins:
  enabled: true
  fetch:
    - github: GetBusbar/[email protected]
identity-providers:
  ldap:
    module: ldap
    settings:
      url: "ldaps://dc.corp.example:636"       # LDAPS, implicit TLS on 636
      bind_dn_template: "{username}@corp.example"   # AD UPN bind
      base_dn: "dc=corp,dc=example"
      group_attr: "memberOf"                   # default; each value is a group DN
      role_from: dn                            # key role_bindings on full group DNs
    browser_login: {}                          # show the login form; no client_secret
auth:
  signing_key: { file: /run/secrets/busbar-signing.key }
  chain: [keys]
  key_ttl: 90d
  role_bindings:
    ldap:
      "CN=engineers,OU=Groups,DC=corp,DC=example": { group: engineering }
      "CN=platform,OU=Groups,DC=corp,DC=example":  { group: platform }

A dev opens GET /auth/token, enters their AD username + password, and the plugin binds to the domain controller as <username>@corp.example. On success it reads memberOf and, with role_from: dn, uses the full lowercased group DN as the role, so the role_bindings.ldap keys are the group DNs shown. Identity is ldap:<username>; the dev gets their own budgeted key, re-shown on every later sign-in with a Refresh button.

When to use: A non-AD directory (OpenLDAP, 389 Directory Server, …) where the login name maps straight to a DN. Use a bind-DN template and the default CN-based role mapping; no service account needed.

public_url: "https://busbar.example.com"
plugins:
  enabled: true
  fetch:
    - github: GetBusbar/[email protected]
identity-providers:
  ldap:
    module: ldap
    settings:
      url: "ldap://ldap.corp.example:389"
      start_tls: true                          # upgrade the plaintext connection to TLS
      bind_dn_template: "uid={username},ou=people,dc=corp,dc=example"
      base_dn: "dc=corp,dc=example"
      group_attr: "memberOf"
      # role_from defaults to "cn" → CN=engineers,ou=… becomes the role "engineers"
    browser_login: {}
auth:
  signing_key: { file: /run/secrets/busbar-signing.key }
  chain: [keys]
  key_ttl: 90d
  role_bindings:
    ldap:
      "engineers": { group: engineering }      # default role_from: cn → short CN keys

The dev’s username is substituted into bind_dn_template ({username} is required and validated at boot) and the plugin binds directly as that DN, with no service account. With the default role_from: cn, each group DN collapses to its first CN value, so role_bindings.ldap keys are short names like engineers. When the login name isn’t the DN, set user_search_filter (e.g. (uid={username})) plus bind_service_dn for search-then-bind instead.

When to use: Your directory’s LDAPS certificate chains to a private/internal CA that isn’t in the public trust store. Trust that CA explicitly so the TLS bind succeeds.

public_url: "https://busbar.example.com"
plugins:
  enabled: true
  fetch:
    - github: GetBusbar/[email protected]
identity-providers:
  ldap:
    module: ldap
    settings:
      url: "ldaps://dc.corp.example:636"        # implicit LDAPS on 636
      bind_dn_template: "{username}@corp.example"
      base_dn: "dc=corp,dc=example"
      group_attr: "memberOf"
      role_from: dn
      ca_cert_pem: { file: /etc/busbar/corp-root-ca.pem }   # private AD/LDAPS CA, PEM
    browser_login: {}
auth:
  signing_key: { file: /run/secrets/busbar-signing.key }
  chain: [keys]
  key_ttl: 90d
  role_bindings:
    ldap:
      "CN=engineers,OU=Groups,DC=corp,DC=example": { group: engineering }

ca_cert_pem layers your private CA onto the trust store so the LDAPS bind validates against a certificate the public roots don’t chain to. For a directory that speaks STARTTLS on the plaintext port instead of implicit LDAPS, use url: ldap://…:389 with start_tls: true and the same ca_cert_pem. This is the direct-bind shape (login name maps to a DN); combine it with search-then-bind (next tab) if your login name isn’t the DN.

When to use: The login name (e.g. sAMAccountName) isn’t the DN, so you can’t template a bind DN directly. A service account locates the user’s entry first, then the plugin binds as the DN it found: the common AD pattern.

public_url: "https://busbar.example.com"
plugins:
  enabled: true
  fetch:
    - github: GetBusbar/[email protected]
identity-providers:
  ldap:
    module: ldap
    settings:
      url: "ldaps://dc.corp.example:636"
      bind_dn_template: "{username}@corp.example"          # still required (must contain {username})
      base_dn: "dc=corp,dc=example"                        # search base for the user lookup
      user_search_filter: "(sAMAccountName={username})"    # set → search-then-bind
      bind_service_dn: "CN=busbar-svc,OU=Service,DC=corp,DC=example"
      bind_service_password: { env: LDAP_SVC_PASSWORD }
      role_from: dn
    browser_login: {}
auth:
  signing_key: { file: /run/secrets/busbar-signing.key }
  chain: [keys]
  key_ttl: 90d
  role_bindings:
    ldap:
      "CN=engineers,OU=Groups,DC=corp,DC=example": { group: engineering }

Setting user_search_filter switches on search-then-bind: busbar binds as bind_service_dn, searches base_dn for the user entry, then binds as the DN it found with the dev’s password (that bind is still the credential check). Both user_search_filter and bind_dn_template must contain {username}, and bind_service_dn is required when the filter is set; all validated at boot. Note: bind_service_password is a raw module setting: there’s no core secret-resolution seam for a plugin-opened socket, so a { env: } reference here resolves at the busbar-config layer, not inside the plugin (documented ABI gap).