CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-backstage--plugin-auth-backend

Authentication backend plugin for Backstage - handles OAuth flows and authentication with various providers including Google, GitHub, GitLab, Microsoft, Okta, Auth0, SAML and more

—

Pending
Overview
Eval results
Files

Backstage Auth Backend Plugin

The Backstage Auth Backend Plugin is a comprehensive authentication system for Backstage applications, providing OAuth-based authentication with support for 11+ identity providers including Google, GitHub, GitLab, Microsoft, Okta, Auth0, SAML, and more. It handles secure session management, JWT token issuance, and provides a pluggable architecture for custom authentication strategies.

Package Information

  • Package Name: @backstage/plugin-auth-backend
  • Package Type: npm
  • Language: TypeScript
  • Installation: yarn add @backstage/plugin-auth-backend

Core Imports

import { 
  createRouter, 
  IdentityClient,
  defaultAuthProviderFactories,
  OAuthAdapter
} from "@backstage/plugin-auth-backend";

Basic Usage

import { createRouter, defaultAuthProviderFactories } from "@backstage/plugin-auth-backend";
import { Router } from "express";
import { Logger } from "winston";
import { Config } from "@backstage/config";

// Create authentication router with built-in providers
const authRouter: Router = await createRouter({
  logger,
  config,
  database,
  discovery,
  providerFactories: defaultAuthProviderFactories,
});

// Mount in your backend
app.use("/auth", authRouter);

Architecture

The Backstage Auth Backend Plugin is built around several key components:

  • Router System: Main authentication router handling HTTP endpoints and provider orchestration
  • Provider Factory System: Pluggable architecture for authentication providers with built-in support for 11+ identity providers
  • Identity Management: JWT token issuance, verification, and user identity resolution with database-backed key storage
  • OAuth Library: Comprehensive OAuth 2.0/OIDC support with security helpers and adapters
  • Flow Handlers: CORS-safe authentication flows using postMessage communication for popup-based login

Capabilities

Authentication Router

Core router functionality for handling authentication HTTP endpoints and coordinating with identity providers.

function createRouter(options: RouterOptions): Promise<express.Router>;

interface RouterOptions {
  logger: Logger;
  database: Knex;
  config: Config;
  discovery: PluginEndpointDiscovery;
  providerFactories?: { [providerId: string]: AuthProviderFactory };
}

Authentication Router

Identity Management

Identity client for token authentication and JWT token issuance with database-backed key storage.

class IdentityClient {
  constructor(options: { discovery: PluginEndpointDiscovery; issuer: string });
  authenticate(token: string | undefined): Promise<BackstageIdentity>;
}

class TokenFactory implements TokenIssuer {
  constructor(options: TokenFactoryOptions);
  issueToken(params: TokenParams): Promise<string>;
  listPublicKeys(): Promise<{ keys: AnyJWK[] }>;
}

Identity Management

Authentication Providers

Built-in authentication providers supporting major identity systems with a pluggable factory architecture.

const defaultAuthProviderFactories: {
  [providerId: string]: AuthProviderFactory;
};

interface AuthProviderRouteHandlers {
  start(req: express.Request, res: express.Response): Promise<void>;
  frameHandler(req: express.Request, res: express.Response): Promise<void>;
  refresh?(req: express.Request, res: express.Response): Promise<void>;
  logout?(req: express.Request, res: express.Response): Promise<void>;
}

type AuthProviderFactory = (options: AuthProviderFactoryOptions) => AuthProviderRouteHandlers;

Authentication Providers

OAuth Library

OAuth 2.0/OIDC support with adapters, environment handlers, and security utilities.

class OAuthAdapter implements AuthProviderRouteHandlers {
  static fromConfig(
    config: Config,
    providerId: string,
    options: OAuthAdapterOptions
  ): OAuthAdapter;
  start(req: express.Request, res: express.Response): Promise<void>;
  frameHandler(req: express.Request, res: express.Response): Promise<void>;
}

function encodeState(state: OAuthState): string;
function verifyNonce(req: express.Request, providerId: string): void;
function readState(stateString: string): OAuthState;

OAuth Library

Flow Helpers

CORS-safe authentication flow utilities for popup-based login with postMessage communication.

function ensuresXRequestedWith(req: express.Request, res: express.Response, next: express.NextFunction): void;
function postMessageResponse(res: express.Response, appOrigin: string, response: WebMessageResponse): void;

interface WebMessageResponse {
  type: string;
  message?: string;
  error?: Error;
}

Flow Helpers

Types

Core Authentication Types

interface BackstageIdentity {
  id: string;
  idToken?: string;
  profile?: ProfileInfo;
}

interface ProfileInfo {
  email?: string;
  displayName?: string;
  picture?: string;
}

interface AuthResponse<ProviderInfo> {
  providerInfo: ProviderInfo;
  profile: ProfileInfo;
  backstageId?: string;
}

interface RedirectInfo {
  url: string;
  status?: number;
}

OAuth Types

interface OAuthProviderInfo {
  accessToken: string;
  refreshToken?: string;
  scope: string;
  expiresInSeconds?: number;
}

interface OAuthState {
  nonce: string;
  env: string;
  origin?: string;
  scope?: string;
  redirectUrl?: string;
}

interface OAuthResult {
  fullProfile: any;
  accessToken: string;
  refreshToken?: string;
  params: any;
}

Provider Configuration Types

interface AuthProviderConfig {
  [key: string]: any;
}

interface AuthProviderFactoryOptions {
  providerId: string;
  globalConfig: Config;
  config: Config;
  logger: Logger;
  catalogApi?: CatalogApi;
  tokenIssuer?: TokenIssuer;
}

Install with Tessl CLI

npx tessl i tessl/npm-backstage--plugin-auth-backend
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@backstage/plugin-auth-backend@0.3.x
Publish Source
CLI
Badge
tessl/npm-backstage--plugin-auth-backend badge