Skip to main content
Version: v2 (current)

Integrate LDAP / Active Directory with PanDev Metrics on-prem

TL;DR. This guide connects PanDev Metrics on-prem to your LDAP or Active Directory server in about 20 minutes. By the end, employees sign in with their corporate credentials, new users are provisioned on first login, and IDE plugins reuse the same identity. Audience: admin.

Before you begin​

  • PanDev Metrics on-prem installed and reachable
  • A reachable LDAP or AD server with TLS on port 636 (LDAPS) — plain ldap:// on 389 also works but is not recommended
  • A service account in the directory with permission to read user entries — bind DN and password
  • The base DN where your users live (for example ou=Users,dc=example,dc=com)
  • The search attribute your users sign in with — usually sAMAccountName for Active Directory or mail / uid for OpenLDAP
warning

LDAP is the only SSO option supported in PanDev Metrics on-prem today. SAML, OIDC, and Google sign-in are not available on-prem. Plan around LDAP for any single sign-on requirement.

Step 1 — Decide where to configure LDAP​

You have two options: configure LDAP through the admin UI after first login, or set the environment variables in .env before the first start. Both end in the same place — env vars override UI values on backend restart.

The UI route is recommended for an existing install because it gives immediate feedback from the Test connection button. The env-var route is preferred when you bake the configuration into infrastructure-as-code.

Step 2 — Configure LDAP environment variables (env-var route)​

Add the following variables to .env on the application host. Substitute your directory's values:

.env
LDAP_INTEGRATION_ENABLED=true
LDAP_URL=ldaps://ldap.example.com:636
LDAP_USER_SEARCH_BASE=ou=Users,dc=example,dc=com
LDAP_USER_SEARCH_ATTRIBUTE=sAMAccountName
LDAP_ADMIN_USERNAME=cn=svc-pandev,ou=Service Accounts,dc=example,dc=com
LDAP_ADMIN_PASSWORD=<STRONG_SERVICE_PASSWORD>
VariablePurposeExample
LDAP_INTEGRATION_ENABLEDMaster switchtrue
LDAP_URLDirectory URL with scheme and portldaps://ldap.example.com:636
LDAP_USER_SEARCH_BASEBase DN to search for usersou=Users,dc=example,dc=com
LDAP_USER_SEARCH_ATTRIBUTEAttribute users enter to sign insAMAccountName, mail, uid
LDAP_ADMIN_USERNAMEBind DN of the read-only service accountcn=svc-pandev,ou=Service Accounts,dc=example,dc=com
LDAP_ADMIN_PASSWORDPassword for the bind DN<STRONG_SERVICE_PASSWORD>

Apply the changes:

terminal
docker compose up -d --force-recreate pandev-metrics

Step 3 — Configure LDAP through the UI​

Sign in as an administrator and open Settings → Basic settings → Ldap.

Fill in each field using the same values as the env vars in Step 2:

FieldWhat to enter
LDAP URLldaps://ldap.example.com:636 (or ldap:// for plain LDAP)
LDAP search baseBase DN for the user search
LDAP search attributeAttribute users sign in with (sAMAccountName, mail, uid)
LDAP admin usernameBind DN of the service account
PasswordService account password

Select Test connection and save. PanDev Metrics binds with the service account, runs a sample search, and confirms success before persisting the configuration.

Step 4 — Verify the integration​

Sign out of the administrator session and sign in with an LDAP account that exists in the configured search base. The first sign-in provisions a user record automatically — the new user appears in Settings → Users with no role assigned.

Verify the actuator health endpoint stays UP after the LDAP change:

terminal
curl -fsS http://localhost:9090/actuator/health | jq '.status'
# → "UP"

Roles are not assigned automatically. An administrator must assign a role (Owner, Maintainer, or Viewer) before the new user can use the product.

Troubleshooting​

Test connection fails with Cannot connect to LDAP server

The backend container cannot reach the directory. Check three things:

  1. The URL hostname resolves from the backend container: docker exec pandev-metrics-app getent hosts ldap.example.com.
  2. The port is open from the container: docker exec pandev-metrics-app nc -vz ldap.example.com 636.
  3. The certificate chain on the LDAP server is trusted, or you are using plain ldap:// for the test.
Test connection fails with Invalid credentials (LDAP result code 49)

The bind DN or password is wrong. Confirm the service account DN in your directory tool — the DN must be the full path, not just the username. Test the bind with ldapsearch from another machine to isolate whether the issue is in PanDev or in the directory.

User sign-in fails with user not found in LDAP

The user exists in the directory but is outside LDAP_USER_SEARCH_BASE, or LDAP_USER_SEARCH_ATTRIBUTE does not match what the user is entering. Confirm with a directory query: ldapsearch -b "ou=Users,dc=example,dc=com" "(sAMAccountName=<USER>)".

User can sign in but sees an "access denied" screen

The user is provisioned in PanDev Metrics but has no role. An administrator must open Settings → Users, locate the user, and assign a role (Owner, Maintainer, or Viewer) before access works.

LDAPS connection fails with a TLS certificate error

The directory's TLS certificate is not trusted by the backend's Java truststore. Either install your CA chain into the backend container, or terminate TLS at a reverse proxy in front of the LDAP server and connect with ldap:// over the internal network.

FAQ​

Does PanDev Metrics support SAML or OIDC on-prem?​

No. LDAP is the only SSO option in PanDev Metrics on-prem today. SAML and OIDC are not available. If your identity provider does not expose LDAP, you can usually front it with a directory proxy (FreeIPA, Authentik) that does — but that work happens on your side, not in PanDev Metrics.

What about Google sign-in?​

Google sign-in is Cloud-only. The on-prem distribution does not include it. Set GOOGLE_AUTH_ENABLE=false in .env — this is the on-prem default.

Does PanDev Metrics sync groups from LDAP?​

PanDev Metrics authenticates users against LDAP but does not synchronize group membership automatically today. Department and team assignment is done inside PanDev Metrics after the user is provisioned. Group-to-role mapping is on the roadmap.

What happens to a user who is disabled in the directory?​

The user can no longer sign in once their LDAP bind fails. Their PanDev Metrics record remains in Settings → Users until an administrator archives it. Archiving keeps the historical metrics attribution intact.

Can I use multiple LDAP servers?​

PanDev Metrics on-prem connects to one directory at a time. If you operate multiple forests, use a directory proxy or replicate users into a single search base.

Is the bind password stored encrypted?​

The bind password is stored in the backend's encrypted configuration table. Treat the .env file with the same care — keep it chmod 600 and out of source control.

Next steps​