Authentication Providers

/**
 * Object containing all built-in provider factory functions
 */
const defaultAuthProviderFactories: {
  github: AuthProviderFactory;
  google: AuthProviderFactory;
  gitlab: AuthProviderFactory;
  auth0: AuthProviderFactory;
  microsoft: AuthProviderFactory;
  oauth2: AuthProviderFactory;
  oidc: AuthProviderFactory;
  okta: AuthProviderFactory;
  onelogin: AuthProviderFactory;
  saml: AuthProviderFactory;
  awsalb: AuthProviderFactory;
};

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

// Use all default providers
const router = await createRouter({
  logger,
  database,
  config,
  discovery,
  providerFactories: defaultAuthProviderFactories,
});

// Use specific providers only
const customFactories = {
  github: defaultAuthProviderFactories.github,
  google: defaultAuthProviderFactories.google,
};

/**
 * Creates GitHub authentication provider
 * @param options - Provider factory options
 * @returns Provider route handlers
 */
function createGithubProvider(options: AuthProviderFactoryOptions): AuthProviderRouteHandlers;

interface GithubProviderOptions {
  /** GitHub OAuth client ID */
  clientId: string;
  /** GitHub OAuth client secret */
  clientSecret: string;
  /** GitHub Enterprise URL (optional) */
  enterpriseInstanceUrl?: string;
  /** Additional OAuth scopes */
  scope?: string;
}

/**
 * Creates Google authentication provider
 * @param options - Provider factory options
 * @returns Provider route handlers
 */
function createGoogleProvider(options: AuthProviderFactoryOptions): AuthProviderRouteHandlers;

interface GoogleProviderOptions {
  /** Google OAuth client ID */
  clientId: string;
  /** Google OAuth client secret */
  clientSecret: string;
  /** Hosted domain restriction (optional) */
  hostedDomain?: string;
  /** Additional OAuth scopes */
  scope?: string;
}

/**
 * Creates GitLab authentication provider
 * @param options - Provider factory options
 * @returns Provider route handlers
 */
function createGitlabProvider(options: AuthProviderFactoryOptions): AuthProviderRouteHandlers;

interface GitlabProviderOptions {
  /** GitLab OAuth client ID */
  clientId: string;
  /** GitLab OAuth client secret */
  clientSecret: string;
  /** GitLab instance URL (defaults to gitlab.com) */
  baseUrl?: string;
  /** Additional OAuth scopes */
  scope?: string;
}

/**
 * Creates Microsoft authentication provider
 * @param options - Provider factory options
 * @returns Provider route handlers
 */
function createMicrosoftProvider(options: AuthProviderFactoryOptions): AuthProviderRouteHandlers;

interface MicrosoftProviderOptions {
  /** Microsoft OAuth client ID */
  clientId: string;
  /** Microsoft OAuth client secret */
  clientSecret: string;
  /** Azure AD tenant ID */
  tenantId: string;
  /** Additional OAuth scopes */
  scope?: string;
}

/**
 * Creates Auth0 authentication provider
 * @param options - Provider factory options
 * @returns Provider route handlers
 */
function createAuth0Provider(options: AuthProviderFactoryOptions): AuthProviderRouteHandlers;

interface Auth0ProviderOptions {
  /** Auth0 client ID */
  clientId: string;
  /** Auth0 client secret */
  clientSecret: string;
  /** Auth0 domain */
  domain: string;
  /** Auth0 connection (optional) */
  connection?: string;
}

/**
 * Creates generic OAuth2 authentication provider
 * @param options - Provider factory options
 * @returns Provider route handlers
 */
function createOAuth2Provider(options: AuthProviderFactoryOptions): AuthProviderRouteHandlers;

interface OAuth2ProviderOptions {
  /** OAuth2 client ID */
  clientId: string;
  /** OAuth2 client secret */
  clientSecret: string;
  /** Authorization endpoint URL */
  authorizationUrl: string;
  /** Token endpoint URL */
  tokenUrl: string;
  /** User profile endpoint URL */
  profileUrl: string;
  /** Additional OAuth scopes */
  scope?: string;
}

/**
 * Creates OpenID Connect authentication provider
 * @param options - Provider factory options
 * @returns Provider route handlers
 */
function createOidcProvider(options: AuthProviderFactoryOptions): AuthProviderRouteHandlers;

interface OidcProviderOptions {
  /** OIDC client ID */
  clientId: string;
  /** OIDC client secret */
  clientSecret: string;
  /** OIDC issuer URL */
  issuer: string;
  /** Additional OAuth scopes */
  scope?: string;
}

/**
 * Creates Okta authentication provider
 * @param options - Provider factory options
 * @returns Provider route handlers
 */
function createOktaProvider(options: AuthProviderFactoryOptions): AuthProviderRouteHandlers;

interface OktaProviderOptions {
  /** Okta client ID */
  clientId: string;
  /** Okta client secret */
  clientSecret: string;
  /** Okta domain URL */
  audience: string;
  /** Additional OAuth scopes */
  scope?: string;
}

/**
 * Creates OneLogin authentication provider
 * @param options - Provider factory options
 * @returns Provider route handlers
 */
function createOneLoginProvider(options: AuthProviderFactoryOptions): AuthProviderRouteHandlers;

interface OneLoginProviderOptions {
  /** OneLogin client ID */
  clientId: string;
  /** OneLogin client secret */
  clientSecret: string;
  /** OneLogin issuer URL */
  issuer: string;
}

/**
 * Creates SAML authentication provider
 * @param options - Provider factory options
 * @returns Provider route handlers
 */
function createSamlProvider(options: AuthProviderFactoryOptions): AuthProviderRouteHandlers;

interface SamlProviderOptions {
  /** SAML entry point URL */
  entryPoint: string;
  /** SAML issuer identifier */
  issuer: string;
  /** Identity provider certificate */
  cert: string;
  /** Private key for signing (optional) */
  privateKey?: string;
}

/**
 * Creates AWS Application Load Balancer authentication provider
 * @param options - Provider factory options
 * @returns Provider route handlers
 */
function createAwsAlbProvider(options: AuthProviderFactoryOptions): AuthProviderRouteHandlers;

interface AwsAlbProviderOptions {
  /** AWS region */
  region: string;
  /** Optional issuer override */
  issuer?: string;
}

/**
 * Interface that all authentication providers must implement
 */
interface AuthProviderRouteHandlers {
  /** Initiates authentication flow */
  start(req: express.Request, res: express.Response): Promise<void>;
  /** Handles OAuth callback */
  frameHandler(req: express.Request, res: express.Response): Promise<void>;
  /** Refreshes authentication tokens (optional) */
  refresh?(req: express.Request, res: express.Response): Promise<void>;
  /** Logs out from provider (optional) */
  logout?(req: express.Request, res: express.Response): Promise<void>;
}

/**
 * Function type for creating provider handlers
 */
type AuthProviderFactory = (options: AuthProviderFactoryOptions) => AuthProviderRouteHandlers;

/**
 * Options passed to provider factories
 */
interface AuthProviderFactoryOptions {
  /** Provider identifier */
  providerId: string;
  /** Global Backstage configuration */
  globalConfig: Config;
  /** Provider-specific configuration */
  config: Config;
  /** Logger instance */
  logger: Logger;
  /** Optional catalog API client */
  catalogApi?: CatalogApi;
  /** Optional token issuer */
  tokenIssuer?: TokenIssuer;
}

/**
 * Configuration for authentication providers
 */
interface AuthProviderConfig {
  [key: string]: any;
}

/**
 * Generic authentication response type
 */
interface AuthResponse<ProviderInfo> {
  /** Provider-specific information */
  providerInfo: ProviderInfo;
  /** User profile information */
  profile: ProfileInfo;
  /** Optional Backstage identity ID */
  backstageId?: string;
}

/**
 * URL redirect information
 */
interface RedirectInfo {
  /** Redirect URL */
  url: string;
  /** HTTP status code (optional) */
  status?: number;
}

auth:
  environment: development
  providers:
    github:
      development:
        clientId: ${GITHUB_CLIENT_ID}
        clientSecret: ${GITHUB_CLIENT_SECRET}
        # Optional: restrict to organization
        # enterpriseInstanceUrl: https://github.company.com
    
    google:
      development:
        clientId: ${GOOGLE_CLIENT_ID}
        clientSecret: ${GOOGLE_CLIENT_SECRET}
        # Optional: restrict to domain
        # hostedDomain: company.com
    
    microsoft:
      development:
        clientId: ${MICROSOFT_CLIENT_ID}
        clientSecret: ${MICROSOFT_CLIENT_SECRET}
        tenantId: ${MICROSOFT_TENANT_ID}
    
    auth0:
      development:
        clientId: ${AUTH0_CLIENT_ID}
        clientSecret: ${AUTH0_CLIENT_SECRET}
        domain: ${AUTH0_DOMAIN}