@backstage/backend-defaults/dist/auth.d.ts

Backend defaults used by Backstage backend apps

import * as _backstage_backend_plugin_api from '@backstage/backend-plugin-api';
import { Config } from '@backstage/config';

/**
 * @public
 * Issues and verifies {@link https://backstage.io/docs/auth/service-to-service-auth | service-to-service tokens}.
 */
interface PluginTokenHandler {
    verifyToken(token: string): Promise<{
        subject: string;
        limitedUserToken?: string;
    } | undefined>;
    issueToken(options: {
        pluginId: string;
        targetPluginId: string;
        onBehalfOf?: {
            limitedUserToken: string;
            expiresAt: Date;
        };
    }): Promise<{
        token: string;
    }>;
}

/**
 * @public
 * This service is used to decorate the default plugin token handler with custom logic.
 */
declare const pluginTokenHandlerDecoratorServiceRef: _backstage_backend_plugin_api.ServiceRef<(defaultImplementation: PluginTokenHandler) => PluginTokenHandler, "plugin", "singleton">;
/**
 * Handles token authentication and credentials management.
 *
 * See {@link @backstage/code-plugin-api#AuthService}
 * and {@link https://backstage.io/docs/backend-system/core-services/auth | the service docs}
 * for more information.
 *
 * @public
 */
declare const authServiceFactory: _backstage_backend_plugin_api.ServiceFactory<_backstage_backend_plugin_api.AuthService, "plugin", "singleton">;

/**
 * @public
 * This interface is used to handle external tokens.
 * It is used by the auth service to verify tokens and extract the subject.
 */
interface ExternalTokenHandler<TContext> {
    type: string;
    initialize(ctx: {
        options: Config;
    }): TContext;
    verifyToken(token: string, ctx: TContext): Promise<{
        subject: string;
    } | undefined>;
}

/**
 * Creates an external token handler with the provided implementation.
 *
 * This helper function simplifies the creation of external token handlers by
 * providing type safety and a consistent API. External token handlers are used
 * to validate tokens from external systems that need to authenticate with Backstage.
 *
 * See {@link https://backstage.io/docs/auth/service-to-service-auth#adding-custom-externaltokenhandler | the service-to-service auth docs}
 * for more information about implementing custom external token handlers.
 *
 * @public
 * @param handler - The external token handler implementation with type, initialize, and verifyToken methods
 * @returns The same handler instance, typed as ExternalTokenHandler<TContext>
 *
 * @example
 * ```ts
 * const customHandler = createExternalTokenHandler({
 *   type: 'custom',
 *   initialize({ options }) {
 *     return { apiKey: options.getString('apiKey') };
 *   },
 *   async verifyToken(token, context) {
 *     // Custom validation logic here
 *     return { subject: 'custom:user' };
 *   },
 * });
 * ```
 */
declare function createExternalTokenHandler<TContext>(handler: ExternalTokenHandler<TContext>): ExternalTokenHandler<TContext>;

/**
 * @public
 * This service is used to add custom handlers for external token.
 */
declare const externalTokenHandlersServiceRef: _backstage_backend_plugin_api.ServiceRef<ExternalTokenHandler<unknown>, "plugin", "multiton">;

export { authServiceFactory, createExternalTokenHandler, externalTokenHandlersServiceRef, pluginTokenHandlerDecoratorServiceRef };
export type { ExternalTokenHandler, PluginTokenHandler };