@immobiliarelabs/backstage-plugin-ldap-auth-backend

@immobiliarelabs/backstage-plugin-ldap-auth-backend

Customizable Authentication backend provider for LDAP servers for your Backstage deployment

Works either 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.

Table of Content

• Installation
• Configurations
  • Connection Configuration
  • Setup Backstage official LDAP plugin
  • Add authentication backend
  • Add the login form
• Powered Apps
• Support & Contribute
• License

Installation

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-auth

Configurations

This 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!

Connection Configuration

Adds connection configuration inside your backstage YAML config file, eg: app-config.yaml

This fields are all required

key	description
url	Array of ldap connection strings
rejectUnauthorized	Reject non HTTPS traffic, this also set secure cookies when true
userDn	User distinguished name directory location
userSearchBase	Userbase search location

auth:
    environment: ENV_NAME
    providers:
        ldap:
            ENV_NAME:
                url:
                    - 'ldaps://123.123.123.123'
                rejectUnauthorized: true
                userDn: 'ou=usr,dc=ns,dc=frm'
                userSearchBase: 'dc=ns,dc=frm'

Setup Backstage official LDAP plugin

If you didn't have already, we need to configure the official LDAP plugin to imports and keep in syncs users

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;
}

Add authentication backend

This assumes a basic usage: single process without custom auth function or user object customization and in-memory token storage

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 } from '@immobiliarelabs/backstage-plugin-ldap-auth-backend';

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({}),
        },
    });
}

Add the login form

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

Powered Apps

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.

Support & Contribute

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.

License

Backstage Plugin LDAP Auth is licensed under the MIT license.
See the LICENSE file for more information.