backend-{app,plugin}-api: add initial AuthService interface + implementation

Co-authored-by: Fredrik Adelöw <freben@gmail.com>
Co-authored-by: Carl-Erik Bergström <cbergstrom@spotify.com>
Co-authored-by: blam <ben@blam.sh>
Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

packages/backend-app-api/api-report.md

@@ -6,6 +6,7 @@
 /// <reference types="node" />
 
 import type { AppConfig } from '@backstage/config';
+import { AuthService } from '@backstage/backend-plugin-api';
 import { BackendFeature } from '@backstage/backend-plugin-api';
 import { CacheClient } from '@backstage/backend-common';
 import { Config } from '@backstage/config';
@@ -41,6 +42,9 @@ import { TokenManagerService } from '@backstage/backend-plugin-api';
 import { transport } from 'winston';
 import { UrlReader } from '@backstage/backend-common';
 
+// @public (undocumented)
+export const authServiceFactory: () => ServiceFactory<AuthService, 'plugin'>;
+
 // @public (undocumented)
 export interface Backend {
   // (undocumented)

packages/backend-app-api/package.json

@@ -65,6 +65,7 @@
     "express-promise-router": "^4.1.0",
     "fs-extra": "^11.2.0",
     "helmet": "^6.0.0",
+    "jose": "^4.6.0",
     "lodash": "^4.17.21",
     "logform": "^2.3.2",
     "minimatch": "^5.0.0",

packages/backend-app-api/src/services/implementations/auth/authServiceFactory.test.ts

@@ -0,0 +1,110 @@
+/*
+ * Copyright 2024 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {
+  ServiceFactoryTester,
+  mockServices,
+} from '@backstage/backend-test-utils';
+import {
+  InternalBackstageServiceCredentials,
+  InternalBackstageUserCredentials,
+  authServiceFactory,
+} from './authServiceFactory';
+import { decodeJwt } from 'jose';
+import { discoveryServiceFactory } from '../discovery';
+
+// TODO: Ship discovery mock service in the service factory tester
+const mockDeps = [
+  discoveryServiceFactory(),
+  mockServices.rootConfig.factory({
+    data: {
+      backend: {
+        baseUrl: 'http://localhost',
+        auth: { keys: [{ secret: 'abc' }] },
+      },
+    },
+  }),
+];
+
+describe('authServiceFactory', () => {
+  it('should authenticate issued tokens', async () => {
+    const tester = ServiceFactoryTester.from(authServiceFactory, {
+      dependencies: mockDeps,
+    });
+
+    const searchAuth = await tester.get('search');
+    const catalogAuth = await tester.get('catalog');
+
+    const { token: searchToken } = await searchAuth.issueServiceToken();
+
+    await expect(searchAuth.authenticate(searchToken)).resolves.toEqual(
+      expect.objectContaining({
+        type: 'service',
+        subject: 'external:backstage-plugin',
+      }),
+    );
+    await expect(catalogAuth.authenticate(searchToken)).resolves.toEqual(
+      expect.objectContaining({
+        type: 'service',
+        subject: 'external:backstage-plugin',
+      }),
+    );
+  });
+
+  it('should forward user tokens', async () => {
+    const tester = ServiceFactoryTester.from(authServiceFactory, {
+      dependencies: mockDeps,
+    });
+
+    const catalogAuth = await tester.get('catalog');
+
+    await expect(
+      catalogAuth.issueServiceToken({
+        forward: {
+          $$type: '@backstage/BackstageCredentials',
+          version: 'v1',
+          type: 'user',
+          userEntityRef: 'user:default/alice',
+          token: 'alice-token',
+        } as InternalBackstageUserCredentials,
+      }),
+    ).resolves.toEqual({ token: 'alice-token' });
+  });
+
+  it('should not forward service tokens', async () => {
+    const tester = ServiceFactoryTester.from(authServiceFactory, {
+      dependencies: mockDeps,
+    });
+
+    const catalogAuth = await tester.get('catalog');
+
+    const { token } = await catalogAuth.issueServiceToken({
+      forward: {
+        $$type: '@backstage/BackstageCredentials',
+        version: 'v1',
+        type: 'service',
+        subject: 'external:backstage-plugin',
+        token: 'some-upstream-service-token',
+      } as InternalBackstageServiceCredentials,
+    });
+
+    expect(decodeJwt(token)).toEqual(
+      expect.objectContaining({
+        sub: 'backstage-server',
+      }),
+    );
+  });
+});

packages/backend-app-api/src/services/implementations/auth/authServiceFactory.ts

@@ -0,0 +1,157 @@
+/*
+ * Copyright 2024 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { ServerTokenManager, TokenManager } from '@backstage/backend-common';
+import {
+  AuthService,
+  BackstageCredentials,
+  BackstageServiceCredentials,
+  BackstageUserCredentials,
+  IdentityService,
+  coreServices,
+  createServiceFactory,
+} from '@backstage/backend-plugin-api';
+import { AuthenticationError } from '@backstage/errors';
+import {
+  DefaultIdentityClient,
+  IdentityApiGetIdentityRequest,
+} from '@backstage/plugin-auth-node';
+import { decodeJwt } from 'jose';
+
+/** @internal */
+export type InternalBackstageServiceCredentials =
+  BackstageServiceCredentials & {
+    version: string;
+    token: string;
+  };
+
+function createServiceCredentials(
+  sub: string,
+  token: string,
+): BackstageServiceCredentials {
+  return {
+    $$type: '@backstage/BackstageCredentials',
+    version: 'v1',
+    token,
+    type: 'service',
+    subject: sub,
+  } as InternalBackstageServiceCredentials;
+}
+
+/** @internal */
+export type InternalBackstageUserCredentials = BackstageUserCredentials & {
+  version: string;
+  token: string;
+};
+
+function createUserCredentials(
+  sub: string,
+  token: string,
+): BackstageUserCredentials {
+  return {
+    $$type: '@backstage/BackstageCredentials',
+    version: 'v1',
+    token,
+    type: 'user',
+    userEntityRef: sub,
+  } as InternalBackstageUserCredentials;
+}
+
+export function toInternalBackstageCredentials(
+  credentials: BackstageCredentials,
+): InternalBackstageServiceCredentials | InternalBackstageUserCredentials {
+  if (credentials.$$type !== '@backstage/BackstageCredentials') {
+    throw new Error('Invalid credential type');
+  }
+  const internalCredentials = credentials as
+    | InternalBackstageServiceCredentials
+    | InternalBackstageUserCredentials;
+  if (internalCredentials.version !== 'v1') {
+    throw new Error(
+      `Invalid credential version ${internalCredentials.version}`,
+    );
+  }
+  return internalCredentials;
+}
+
+/** @internal */
+class DefaultAuthService implements AuthService {
+  constructor(
+    private readonly tokenManager: TokenManager,
+    private readonly identity: IdentityService,
+  ) {}
+
+  async authenticate(token: string): Promise<BackstageCredentials> {
+    const { sub, aud } = decodeJwt(token);
+
+    // Legacy service-to-service token
+    if (sub === 'backstage-server' && !aud) {
+      await this.tokenManager.authenticate(token);
+      return createServiceCredentials('external:backstage-plugin', token);
+    }
+
+    // User Backstage token
+    const identity = await this.identity.getIdentity({
+      request: {
+        headers: { authorization: `Bearer ${token}` },
+      },
+    } as IdentityApiGetIdentityRequest);
+
+    if (!identity) {
+      throw new AuthenticationError('No identity found');
+    }
+
+    return createUserCredentials(identity.identity.userEntityRef, token);
+  }
+
+  async issueServiceToken(options?: {
+    forward?: BackstageCredentials;
+  }): Promise<{ token: string }> {
+    const internalForward =
+      options?.forward && toInternalBackstageCredentials(options.forward);
+
+    if (internalForward) {
+      const { type } = internalForward;
+      if (type === 'user') {
+        return { token: internalForward.token };
+      } else if (type !== 'service') {
+        throw new AuthenticationError(
+          `Refused to issue service token for credential type '${type}'`,
+        );
+      }
+    }
+
+    const { token } = await this.tokenManager.getToken();
+    return { token };
+  }
+}
+
+/** @public */
+export const authServiceFactory = createServiceFactory({
+  service: coreServices.auth,
+  deps: {
+    config: coreServices.rootConfig,
+    logger: coreServices.rootLogger,
+    discovery: coreServices.discovery,
+  },
+  createRootContext({ config, logger }) {
+    return ServerTokenManager.fromConfig(config, { logger });
+  },
+  async factory({ discovery }, tokenManager) {
+    const identity = DefaultIdentityClient.create({ discovery });
+    return new DefaultAuthService(tokenManager, identity);
+  },
+});

packages/backend-app-api/src/services/implementations/auth/index.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2024 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export { authServiceFactory } from './authServiceFactory';

packages/backend-app-api/src/services/implementations/index.ts

@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
+export * from './auth';
 export * from './cache';
 export * from './config';
 export * from './database';

packages/backend-plugin-api/api-report.md

@@ -15,6 +15,16 @@ import { PermissionEvaluator } from '@backstage/plugin-permission-common';
 import { PluginTaskScheduler } from '@backstage/backend-tasks';
 import { Readable } from 'stream';
 
+// @public (undocumented)
+export interface AuthService {
+  // (undocumented)
+  authenticate(token: string): Promise<BackstageCredentials>;
+  // (undocumented)
+  issueServiceToken(options?: { forward?: BackstageCredentials }): Promise<{
+    token: string;
+  }>;
+}
+
 // @public (undocumented)
 export interface BackendFeature {
   // (undocumented)
@@ -76,6 +86,25 @@ export interface BackendPluginRegistrationPoints {
   }): void;
 }
 
+// @public (undocumented)
+export type BackstageCredentials =
+  | BackstageUserCredentials
+  | BackstageServiceCredentials;
+
+// @public (undocumented)
+export type BackstageServiceCredentials = {
+  $$type: '@backstage/BackstageCredentials';
+  type: 'service';
+  subject: string;
+};
+
+// @public (undocumented)
+export type BackstageUserCredentials = {
+  $$type: '@backstage/BackstageCredentials';
+  type: 'user';
+  userEntityRef: string;
+};
+
 // @public
 export interface CacheService {
   delete(key: string): Promise<void>;
@@ -100,6 +129,7 @@ export type CacheServiceSetOptions = {
 
 // @public
 export namespace coreServices {
+  const auth: ServiceRef<AuthService, 'plugin'>;
   const cache: ServiceRef<CacheService, 'plugin'>;
   const rootConfig: ServiceRef<RootConfigService, 'root'>;
   const database: ServiceRef<DatabaseService, 'plugin'>;

packages/backend-plugin-api/src/services/definitions/AuthService.ts

@@ -0,0 +1,54 @@
+/*
+ * Copyright 2022 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @public
+ */
+export type BackstageUserCredentials = {
+  $$type: '@backstage/BackstageCredentials';
+
+  type: 'user';
+
+  userEntityRef: string;
+};
+
+/**
+ * @public
+ */
+export type BackstageServiceCredentials = {
+  $$type: '@backstage/BackstageCredentials';
+
+  type: 'service';
+
+  subject: string;
+};
+
+/**
+ * @public
+ */
+export type BackstageCredentials =
+  | BackstageUserCredentials
+  | BackstageServiceCredentials;
+
+/**
+ * @public
+ */
+export interface AuthService {
+  authenticate(token: string): Promise<BackstageCredentials>;
+  issueServiceToken(options?: {
+    forward?: BackstageCredentials;
+  }): Promise<{ token: string }>;
+}

packages/backend-plugin-api/src/services/definitions/coreServices.ts

@@ -22,6 +22,15 @@ import { createServiceRef } from '../system';
  * @public
  */
 export namespace coreServices {
+  /**
+   * The service reference for the plugin scoped {@link IdentityService}.
+   *
+   * @public
+   */
+  export const auth = createServiceRef<import('./AuthService').AuthService>({
+    id: 'core.auth',
+  });
+
   /**
    * The service reference for the plugin scoped {@link CacheService}.
    *

packages/backend-plugin-api/src/services/definitions/index.ts

@@ -15,6 +15,12 @@
  */
 
 export { coreServices } from './coreServices';
+export type {
+  AuthService,
+  BackstageCredentials,
+  BackstageServiceCredentials,
+  BackstageUserCredentials,
+} from './AuthService';
 export type {
   CacheService,
   CacheServiceOptions,

yarn.lock

@@ -3250,6 +3250,7 @@ __metadata:
     fs-extra: ^11.2.0
     helmet: ^6.0.0
     http-errors: ^2.0.0
+    jose: ^4.6.0
     lodash: ^4.17.21
     logform: ^2.3.2
     minimatch: ^5.0.0