LDAP Auth lets Backstage use your existing directory for sign in. LDAP stands for Lightweight Directory Access Protocol. Many teams use it through Active Directory or OpenLDAP. If your users already have LDAP accounts, this plugin helps you reuse those identities inside Backstage.
The plugin provides a simple login page in the frontend. It also handles token creation and validation on the backend. It works alongside the official catalog LDAP module, which syncs users and groups into the catalog but does not handle authentication. Together they cover sync and sign in without adding another identity provider.
Common use cases include internal portals that must sit behind corporate credentials. Self hosted environments where cloud SSO is not an option. Networks with strict access rules. Teams that want to customize the login view while keeping server side control of sessions and checks.
The project comes from ImmobiliareLabs, the engineering team at Immobiliare.it. They report real world use in their products and internal tools. As they put it, “We are currently using Backstage Plugin LDAP Auth in our products as well as our internal toolings.”
If you already run Backstage and maintain LDAP, this plugin keeps things simple. Your users sign in with the same username and password they use everywhere else.
Installation Instructions
These instructions apply to self-hosted Backstage only.
Install the packages
Use yarn workspaces from the root of your Backstage repo.
# frontend
yarn workspace app add @immobiliarelabs/backstage-plugin-ldap-auth
# backend
yarn workspace backend add @immobiliarelabs/backstage-plugin-ldap-auth-backend
# optional user sync for your catalog
yarn workspace backend add @backstage/plugin-catalog-backend-module-ldap
Add LDAP settings to your app config
Add a provider entry under auth in your Backstage config. Use your own values.
Example in app-config.yaml.
auth:
environment: production
providers:
ldap:
production:
cookies:
secure: false
field: 'backstage-token'
ldapAuthenticationOptions:
userSearchBase: 'ou=users,dc=ns,dc=farm'
usernameAttribute: 'uid'
adminDn: uid=${ADMIN_USERNAME},ou=users,dc=ns,dc=farm
adminPassword: ''
ldapOpts:
url:
- 'ldaps://123.123.123.123'
tlsOptions:
rejectUnauthorized: false
You can keep multiple environments if you need. Match the environment value under auth with the one you pass to providers.
Set the custom sign in page in the frontend
Wire the login page so users can log in with LDAP.
Edit packages/app/src/App.tsx.
import React from 'react';
import { createApp } from '@backstage/app-defaults';
import { LdapAuthFrontendPage } from '@immobiliarelabs/backstage-plugin-ldap-auth';
const app = createApp({
components: {
SignInPage: props => <LdapAuthFrontendPage {...props} provider="ldap" />,
},
});
export default app.render();
This page also handles token state and calls the backend auth routes.
Backend setup with the new backend system
Add the auth backend and the LDAP auth backend module. This gives you working LDAP routes and token handling.
Edit packages/backend/src/index.ts.
import { createBackend } from '@backstage/backend-defaults';
const backend = createBackend();
// core auth backend
backend.add(import('@backstage/plugin-auth-backend'));
// ldap auth backend module
backend.add(import('@immobiliarelabs/backstage-plugin-ldap-auth-backend'));
backend.start();
Optional token store with Postgres
By default tokens live in memory. To share tokens across backend instances, plug in a validator that uses your database.
Edit packages/backend/src/index.ts.
import { createBackend } from '@backstage/backend-defaults';
import { tokenValidatorFactory } from '@immobiliarelabs/backstage-plugin-ldap-auth-backend';
import { createTokenValidator } from './plugins/auth'; // you will create this
const backend = createBackend();
backend.add(import('@backstage/plugin-auth-backend'));
backend.add(import('@immobiliarelabs/backstage-plugin-ldap-auth-backend'));
// provide your token validator
backend.add(tokenValidatorFactory({ createTokenValidator }));
backend.start();
Create packages/backend/src/plugins/auth.ts.
import { Config } from '@backstage/config';
import Keyv from 'keyv';
import { JWTTokenValidator } from '@immobiliarelabs/backstage-plugin-ldap-auth-backend';
export function createTokenValidator(config: Config) {
const host = config.getString('backend.database.host');
const port = config.getNumber('backend.database.port');
const user = config.getString('backend.database.user');
const password = config.getString('backend.database.password');
const url = `postgresql://${user}:${password}@${host}:${port}/mydb`;
return new JWTTokenValidator(new Keyv(url, { table: 'token' }));
}
Note. Use your own database settings. The code above is only a sample.
Optional custom LDAP resolvers
You can inject custom logic for authentication or for checking if a user exists.
Create a backend module file. For example packages/backend/src/plugins/auth-ldap-ext.ts.
import { coreServices, createBackendModule } from '@backstage/backend-plugin-api';
import { ldapAuthExtensionPoint } from '@immobiliarelabs/backstage-plugin-ldap-auth-backend';
export default createBackendModule({
pluginId: 'auth',
moduleId: 'ldap-ext',
register(reg) {
reg.registerInit({
deps: {
config: coreServices.rootConfig,
ldapAuth: ldapAuthExtensionPoint,
},
async init({ config, ldapAuth }) {
ldapAuth.set({
resolvers: {
async ldapAuthentication(username, password, ldapOptions, authFunction) {
const user = await authFunction(ldapOptions);
return { uid: user.uid };
},
async checkUserExists(ldapAuthOptions, searchFunction) {
return true;
},
},
});
},
});
},
});
Wire the module in packages/backend/src/index.ts.
backend.add(import('./plugins/auth-ldap-ext'));
Backend setup with the old backend system
This package documents the new backend system. The legacy backend setup is not provided here. If your backend still uses the legacy service builder, keep the frontend and config steps above. Then plan a move to the new backend system to use this plugin as shown.
Keep users in sync with the catalog
Add the official catalog module so your Backstage catalog has your LDAP users.
yarn workspace backend add @backstage/plugin-catalog-backend-module-ldap
Follow the Backstage LDAP catalog guide to configure ingestion.
Changelog
This changelog is produced from commits made to the LDAP Auth plugin since about 1 year ago. It may not contain information about all commits. Releases and version bumps are intentionally omitted. This changelog is generated by AI.
Set up Backstage in minutes with Roadie
Focus on using Backstage, rather than building and maintaining it.
