Identity Management

/**
 * Client for interacting with auth-backend and authenticating Backstage identity tokens
 */
class IdentityClient {
  /**
   * Creates a new IdentityClient instance
   * @param options - Configuration options
   */
  constructor(options: {
    /** Service discovery for locating auth-backend */
    discovery: PluginEndpointDiscovery;
    /** JWT issuer identifier */
    issuer: string;
  });

  /**
   * Authenticates a Backstage identity token
   * @param token - JWT token to authenticate
   * @returns Promise resolving to user identity or throws if invalid
   */
  authenticate(token: string | undefined): Promise<BackstageIdentity>;
}

import { IdentityClient } from "@backstage/plugin-auth-backend";

const identityClient = new IdentityClient({
  discovery: discoveryService,
  issuer: "https://backstage.example.com",
});

// Authenticate user token
try {
  const identity = await identityClient.authenticate(userToken);
  console.log(`Authenticated user: ${identity.id}`);
} catch (error) {
  console.error("Authentication failed:", error);
}

/**
 * Factory for issuing JWT identity tokens
 */
class TokenFactory implements TokenIssuer {
  /**
   * Creates a new TokenFactory instance
   * @param options - Token factory configuration
   */
  constructor(options: TokenFactoryOptions);

  /**
   * Issues a new JWT identity token
   * @param params - Token parameters
   * @returns Promise resolving to signed JWT token
   */
  issueToken(params: TokenParams): Promise<string>;

  /**
   * Lists public keys for token verification
   * @returns Promise resolving to JWK set
   */
  listPublicKeys(): Promise<{ keys: AnyJWK[] }>;
}

interface TokenFactoryOptions {
  /** Logger instance */
  logger: Logger;
  /** JWT issuer identifier */
  issuer: string;
  /** Key store for managing signing keys */
  keyStore: KeyStore;
  /** Key duration in seconds, defaults to 3600 */
  keyDurationSeconds?: number;
}

interface TokenParams {
  /** Claims to include in the token */
  claims: {
    /** Subject (user ID) */
    sub: string;
    /** Entity reference */
    ent?: string[];
    /** Additional custom claims */
    [key: string]: any;
  };
}

import { TokenFactory, DatabaseKeyStore } from "@backstage/plugin-auth-backend";

// Create key store
const keyStore = await DatabaseKeyStore.create({ database: knexInstance });

// Create token factory
const tokenFactory = new TokenFactory({
  logger: winston.createLogger(),
  issuer: "https://backstage.example.com",
  keyStore,
  keyDurationSeconds: 3600,
});

// Issue token for user
const token = await tokenFactory.issueToken({
  claims: {
    sub: "user:default/jane.doe",
    ent: ["user:default/jane.doe"],
  },
});

/**
 * Database-backed key store for JWT signing keys
 */
class DatabaseKeyStore implements KeyStore {
  /**
   * Creates a new DatabaseKeyStore instance
   * @param options - Database connection options
   * @returns Promise resolving to configured key store
   */
  static create(options: { database: Knex }): Promise<DatabaseKeyStore>;

  /**
   * Adds a new key to the store
   * @param key - JSON Web Key to store
   */
  addKey(key: AnyJWK): Promise<void>;

  /**
   * Removes keys by their key IDs
   * @param kids - Array of key IDs to remove
   */
  removeKeys(kids: string[]): Promise<void>;

  /**
   * Lists all stored keys
   * @returns Promise resolving to stored keys with metadata
   */
  listKeys(): Promise<{ items: StoredKey[] }>;
}

interface StoredKey {
  /** Key ID */
  kid: string;
  /** JSON Web Key */
  key: AnyJWK;
  /** Creation timestamp */
  createdAt: Date;
}

/**
 * Creates OIDC endpoints for identity verification
 * @param options - OIDC router configuration
 * @returns Express router with OIDC endpoints
 */
function createOidcRouter(options: {
  /** Base URL for OIDC endpoints */
  baseUrl: string;
  /** Token issuer for generating JWTs */
  tokenIssuer: TokenIssuer;
}): express.Router;

import { createOidcRouter, TokenFactory } from "@backstage/plugin-auth-backend";

// Create OIDC router for external verification
const oidcRouter = createOidcRouter({
  baseUrl: "https://backstage.example.com",
  tokenIssuer: tokenFactory,
});

// Mount OIDC endpoints
app.use("/.well-known", oidcRouter);

interface BackstageIdentity {
  /** Unique user identifier */
  id: string;
  /** Optional JWT identity token */
  idToken?: string;
  /** User profile information */
  profile?: ProfileInfo;
}

interface ProfileInfo {
  /** User email address */
  email?: string;
  /** User display name */
  displayName?: string;
  /** Profile picture URL */
  picture?: string;
}

interface KeyStore {
  /** Add a new key to the store */
  addKey(key: AnyJWK): Promise<void>;
  /** Remove keys by their IDs */
  removeKeys(kids: string[]): Promise<void>;
  /** List all stored keys */
  listKeys(): Promise<{ items: StoredKey[] }>;
}

interface TokenIssuer {
  /** Issue a new JWT token */
  issueToken(params: TokenParams): Promise<string>;
  /** List public keys for verification */
  listPublicKeys(): Promise<{ keys: AnyJWK[] }>;
}

interface AnyJWK {
  /** Key type */
  kty: string;
  /** Key ID */
  kid: string;
  /** Key use */
  use?: string;
  /** Algorithm */
  alg?: string;
  /** Additional key parameters */
  [key: string]: any;
}