LDAP Authentication your Backstage deployment
This package is the Backend Provider to add LDAP authentication to your Backstage instance!
- Customizable: Authentication request format and marshaling of the response can be injected with custom ones;
- Works on simple stand-alone process or scaled infrastracture spanning multiple deployments using the shared PostgreSQL instance that Backstage already uses;
This plugin is not meant to be used alone but in pair with:
- The official @backstage/plugin-catalog-backend-module-ldap which keeps in sync your LDAP users with Backstage user catalogs!
- Its sibling frontend package @immobiliarelabs/backstage-plugin-ldap-auth
All the current LTS versions are supported.
These packages are available on npm.
You can install them in your backstage installation using yarn workspace
# install yarn if you don't have it
$ npm install -g yarn
# install backend plugin
$ yarn workspace backend add @immobiliarelabs/backstage-plugin-ldap-auth-backend
# install frontend plugin
$ yarn workspace app add @immobiliarelabs/backstage-plugin-ldap-authThis documentation assumes that you have already scaffolded your Backstage instance from the official
@backstage/create-app, all files that we're going to customize here are the one already created by the CLI!
If you are using new backend system, follow this Configurations guide.
If you didn't have already, you need to configure Backstage's official LDAP plugin, that is needed to import and keep in syncs users your LDAP users.
# in your backstage repo
yarn add @backstage/plugin-catalog-backend-module-ldap
packages/backend/src/plugins/catalog.ts
import type { Router } from 'express';
import type { PluginEnvironment } from '../types';
import { CatalogBuilder } from '@backstage/plugin-catalog-backend';
import { ScaffolderEntitiesProcessor } from '@backstage/plugin-scaffolder-backend';
import {
LdapOrgEntityProvider,
} from '@backstage/plugin-catalog-backend-module-ldap';
export default async function createPlugin(
env: PluginEnvironment,
): Promise<Router> {
const builder = await CatalogBuilder.create(env);
builder.addEntityProvider(
LdapOrgEntityProvider.fromConfig(env.config, {
id: '<YOUR-ID>',
target: 'ldaps://<YOUR-ADDRESS>',
logger: env.logger,
schedule: env.scheduler.createScheduledTaskRunner({
frequency: // whatever
timeout: // whatever
}),
}),
);
builder.addProcessor(new ScaffolderEntitiesProcessor());
const { processingEngine, router } = await builder.build();
await processingEngine.start();
return router;
}Adds connection configuration inside your backstage YAML config file, eg:
app-config.yaml
We use ldap-authentication for authentication, you can find all the configurations at this [link], ldapOpts fields are options provided to lower level ldap client read more at ldapjs
Add in you You backstage configuration file
auth:
environment: { ENV_NAME } # eg: production|staging|review|develop
providers:
ldap:
# eg: production|staging|review|develop
{ ENV_NAME }:
cookies:
secure: false # https cookies or not
field: 'backstage-token' # default
ldapAuthenticationOptions:
userSearchBase: 'ou=users,dc=ns,dc=farm' # REQUIRED
# what is the user unique key in your ldap instance
usernameAttribute: 'uid' # defaults to `uid`
# directory where to search user
# default search will be `[userSearchBase]=[username],[userSearchBase]`
# User able to list other users, this is used
# to check incoming JWT if user are already part of the LDAP
# NOTE: If no admin user/pass provided we'll attempt a credential-less search
adminDn: uid={ADMIN_USERNAME},ou=users,dc=ns,dc=farm
adminPassword: ''
ldapOpts:
url:
- 'ldaps://123.123.123.123'
tlsOptions:
rejectUnauthorized: falseThis is for a basic usage: - single process - No custom auth or user object marshaling - in-memory sessions
For more uses cases you can see the example folders
packages/backend/src/plugins/auth.ts
import { createRouter } from '@backstage/plugin-auth-backend';
import { Router } from 'express';
import { PluginEnvironment } from '../types';
import {
ldap,
JWTTokenValidator,
} from '@immobiliarelabs/backstage-plugin-ldap-auth-backend';
import Keyv from 'keyv';
export default async function createPlugin(
env: PluginEnvironment
): Promise<Router> {
return await createRouter({
logger: env.logger,
config: env.config,
database: env.database,
discovery: env.discovery,
tokenManager: env.tokenManager,
providerFactories: {
ldap: ldap.create({
tokenValidator: new JWTTokenValidator(new Keyv()),
/* Custom Configurations */
}),
},
});
}If your LDAP server connection options requires more fine tune than we handle here you can inject your custom auth function, take a look at ldap.create types at resolvers.ldapAuthentication, you can copy the default function and change what you need!
This can be also done for the resolvers.checkUserExists function, which runs when controlling a JWT token.
export default async function createPlugin(
env: PluginEnvironment,
): Promise<Router> {
return await createRouter({
logger: env.logger,
config: env.config,
database: env.database,
discovery: env.discovery,
tokenManager: env.tokenManager,
providerFactories: {
ldap: ldap.create({
tokenValidator: new JWTTokenValidator(new Keyv()),
resolvers: {
async ldapAuthentication(username, password, ldapOptions, authFunction): LDAPUser {
// modify your ldapOptions and do whatever you need to format it
// ...
const user = await authFunction(ldapOptions)
return { uid: user.uid };
}
}
},
});
}export default async function createPlugin(
env: PluginEnvironment,
): Promise<Router> {
return await createRouter({
logger: env.logger,
config: env.config,
database: env.database,
discovery: env.discovery,
tokenManager: env.tokenManager,
providerFactories: {
ldap: ldap.create({
tokenValidator: new JWTTokenValidator(new Keyv()),
resolvers: {
async checkUserExists(ldapAuthOptions, searchFunction): Promise<boolean> {
const { username } = ldapAuthOptions;
// Do you custom checks
// ....
return true;
}
}
},
});
}More on this in the frontend plugin documentation here
We need to replace the existing Backstage demo authentication page with our custom one!
In the App.tsx file, change the createApp function adding a components with our custom SignInPageIn the App.tsx file change the createApp function to provide use our custom SignInPage in the components key.
Note: This components isn't only UI, it also brings all the token state management and HTTP API calls to the backstage auth routes we already configured in the backend part.
packages/app/src/App.tsx
import { LdapAuthFrontendPage } from '@immobiliarelabs/backstage-plugin-ldap-auth';
const app = createApp({
// ...
components: {
SignInPage: (props) => (
<LdapAuthFrontendPage {...props} provider="ldap" />
),
},
// ...
});And you're ready to go! If you need more use cases, like having multiple processes and need a shared token store instead of in-memory look at the example folders
Backstage Plugin LDAP Auth was created by the amazing Node.js team at ImmobiliareLabs, the Tech dept of Immobiliare.it, the #1 real estate company in Italy.
We are currently using Backstage Plugin LDAP Auth in our products as well as our internal toolings.
If you are using Backstage Plugin LDAP Auth in production drop us a message.
Made with ❤️ by ImmobiliareLabs & Contributors
We'd love for you to contribute to Backstage Plugin LDAP Auth! If you have any questions on how to use Backstage Plugin LDAP Auth, bugs and enhancement please feel free to reach out by opening a GitHub Issue.
Backstage Plugin LDAP Auth is licensed under the MIT license.
See the LICENSE file for more information.