or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

flow.md identity.md index.md oauth.md providers.md router.md

tile.json

Authentication Router

The authentication router provides the main HTTP endpoints for authentication flows, handling provider coordination, session management, and authentication state.

Capabilities

Create Router

Creates the main authentication router with configured providers and options.

/**
 * Creates the main authentication router for Backstage authentication
 * @param options - Router configuration options
 * @returns Promise resolving to Express router
 */
function createRouter(options: RouterOptions): Promise<express.Router>;

interface RouterOptions {
  /** Winston logger instance for authentication logs */
  logger: Logger;
  /** Plugin database manager for session and key storage */
  database: PluginDatabaseManager;
  /** Backstage configuration object */
  config: Config;
  /** Service discovery for inter-service communication */
  discovery: PluginEndpointDiscovery;
  /** Optional custom provider factories, defaults to defaultAuthProviderFactories */
  providerFactories?: { [providerId: string]: AuthProviderFactory };
}

Usage Example:

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

const app = express();

// Create router with default providers
const authRouter = await createRouter({
  logger: winston.createLogger(),
  database: databaseManager,
  config: configObject,
  discovery: discoveryService,
  providerFactories: defaultAuthProviderFactories, // Optional
});

// Mount the router
app.use("/auth", authRouter);

Router Endpoints

The created router provides several standard endpoints:

Provider Authentication Endpoints:

GET /auth/{providerId}/start - Initiates authentication flow
POST /auth/{providerId}/handler/frame - Handles OAuth callback
POST /auth/{providerId}/refresh - Refreshes authentication tokens (if supported)
POST /auth/{providerId}/logout - Logs out from provider (if supported)

Identity Endpoints:

GET /auth/.well-known/jwks.json - JSON Web Key Set for token verification
GET /auth/.well-known/openid_configuration - OpenID Connect configuration

Session Management:

Session cookies for maintaining authentication state
CORS headers for cross-origin authentication flows
Security headers including CSP and HSTS

Router Configuration

The router behavior is controlled through Backstage configuration:

auth:
  # Environment-specific settings
  environment: development # or production
  
  # Session configuration
  session:
    secret: your-session-secret
    
  # Provider-specific configuration
  providers:
    github:
      development:
        clientId: ${GITHUB_CLIENT_ID}
        clientSecret: ${GITHUB_CLIENT_SECRET}
    google:
      development:
        clientId: ${GOOGLE_CLIENT_ID}
        clientSecret: ${GOOGLE_CLIENT_SECRET}

Custom Provider Integration

import { createRouter, AuthProviderFactory } from "@backstage/plugin-auth-backend";

// Define custom provider factory
const customProviderFactory: AuthProviderFactory = ({
  providerId,
  globalConfig,
  config,
  logger,
}) => {
  return {
    async start(req, res) {
      // Handle authentication start
    },
    async frameHandler(req, res) {
      // Handle OAuth callback
    },
  };
};

// Create router with custom provider
const router = await createRouter({
  logger,
  database,
  config,
  discovery,
  providerFactories: {
    custom: customProviderFactory,
    ...defaultAuthProviderFactories,
  },
});

Types

Core Router Types

interface Logger {
  error(message: string, meta?: any): void;
  warn(message: string, meta?: any): void;
  info(message: string, meta?: any): void;
  debug(message: string, meta?: any): void;
}

interface PluginDatabaseManager {
  getClient(): Promise<Knex>;
}

interface PluginEndpointDiscovery {
  getBaseUrl(pluginId: string): Promise<string>;
  getExternalBaseUrl(pluginId: string): Promise<string>;
}