@backstage/backend-app-api 0.7.6-next.0 → 0.7.6-next.1

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @backstage/backend-app-api
 
+## 0.7.6-next.1
+
+### Patch Changes
+
+- 398b82a: Add support for JWKS tokens in ExternalTokenHandler.
+- 9e63318: Added an optional `accessRestrictions` to external access service tokens and service principals in general, such that you can limit their access to certain plugins or permissions.
+- Updated dependencies
+  - @backstage/backend-tasks@0.5.24-next.1
+  - @backstage/backend-plugin-api@0.6.19-next.1
+  - @backstage/plugin-permission-node@0.7.30-next.1
+  - @backstage/backend-common@0.23.0-next.1
+  - @backstage/cli-node@0.2.6-next.0
+  - @backstage/config-loader@1.8.0
+  - @backstage/plugin-auth-node@0.4.14-next.1
+
 ## 0.7.6-next.0
 
 ### Patch Changes

package/alpha/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/backend-app-api",
-  "version": "0.7.6-next.0",
+  "version": "0.7.6-next.1",
   "main": "../dist/alpha.cjs.js",
   "types": "../dist/alpha.d.ts"
 }

package/config.d.ts

@@ -88,6 +88,46 @@ export interface Config {
                */
               subject: string;
             };
+            /**
+             * Restricts what types of access that are permitted for this access
+             * method. If no access restrictions are given, it'll have unlimited
+             * access. This access restriction applies for the framework level;
+             * individual plugins may have their own access control mechanisms
+             * on top of this.
+             */
+            accessRestrictions?: Array<{
+              /**
+               * Permit access to make requests to this plugin.
+               *
+               * Can be further refined by setting additional fields below.
+               */
+              plugin: string;
+              /**
+               * If given, this method is limited to only performing actions
+               * with these named permissions in this plugin.
+               *
+               * Note that this only applies where permissions checks are
+               * enabled in the first place. Endpoints that are not protected by
+               * the permissions system at all, are not affected by this
+               * setting.
+               */
+              permission?: string | Array<string>;
+              /**
+               * If given, this method is limited to only performing actions
+               * whose permissions have these attributes.
+               *
+               * Note that this only applies where permissions checks are
+               * enabled in the first place. Endpoints that are not protected by
+               * the permissions system at all, are not affected by this
+               * setting.
+               */
+              permissionAttribute?: {
+                /**
+                 * One of more of 'create', 'read', 'update', or 'delete'.
+                 */
+                action?: string | Array<string>;
+              };
+            }>;
           }
         | {
             /**
@@ -130,6 +170,87 @@ export interface Config {
                */
               subject: string;
             };
+            /**
+             * Restricts what types of access that are permitted for this access
+             * method. If no access restrictions are given, it'll have unlimited
+             * access. This access restriction applies for the framework level;
+             * individual plugins may have their own access control mechanisms
+             * on top of this.
+             */
+            accessRestrictions?: Array<{
+              /**
+               * Permit access to make requests to this plugin.
+               *
+               * Can be further refined by setting additional fields below.
+               */
+              plugin: string;
+              /**
+               * If given, this method is limited to only performing actions
+               * with these named permissions in this plugin.
+               *
+               * Note that this only applies where permissions checks are
+               * enabled in the first place. Endpoints that are not protected by
+               * the permissions system at all, are not affected by this
+               * setting.
+               */
+              permission?: string | Array<string>;
+              /**
+               * If given, this method is limited to only performing actions
+               * whose permissions have these attributes.
+               *
+               * Note that this only applies where permissions checks are
+               * enabled in the first place. Endpoints that are not protected by
+               * the permissions system at all, are not affected by this
+               * setting.
+               */
+              permissionAttribute?: {
+                /**
+                 * One of more of 'create', 'read', 'update', or 'delete'.
+                 */
+                action?: string | Array<string>;
+              };
+            }>;
+          }
+        | {
+            /**
+             * This access method consists of a JWKS endpoint that can be used to
+             * verify JWT tokens.
+             *
+             * Callers generate JWT tokens via 3rd party tooling
+             * and pass them in the Authorization header:
+             *
+             * ```
+             * Authorization: Bearer eZv5o+fW3KnR3kVabMW4ZcDNLPl8nmMW
+             * ```
+             */
+            type: 'jwks';
+            options: {
+              /**
+               * The full URL of the JWKS endpoint.
+               */
+              url: string;
+              /**
+               * Sets the algorithm(s) that should be used to verify the JWT tokens.
+               * The passed JWTs must have been signed using one of the listed algorithms.
+               */
+              algorithm?: string | string[];
+              /**
+               * Sets the issuer(s) that should be used to verify the JWT tokens.
+               * Passed JWTs must have an `iss` claim which matches one of the specified issuers.
+               */
+              issuer?: string | string[];
+              /**
+               * Sets the audience(s) that should be used to verify the JWT tokens.
+               * The passed JWTs must have an "aud" claim that matches one of the audiences specified,
+               * or have no audience specified.
+               */
+              audience?: string | string[];
+              /**
+               * Sets an optional subject prefix. Passes the subject to called plugins.
+               * Useful for debugging and tracking purposes.
+               */
+              subjectPrefix?: string;
+            };
           }
       >;
     };

package/dist/index.cjs.js

@@ -1697,14 +1697,15 @@ class DatabaseKeyStore {
   }
 }
 
-function createCredentialsWithServicePrincipal(sub, token) {
+function createCredentialsWithServicePrincipal(sub, token, accessRestrictions) {
   return {
     $$type: "@backstage/BackstageCredentials",
     version: "v1",
     token,
     principal: {
       type: "service",
-      subject: sub
+      subject: sub,
+      accessRestrictions
     }
   };
 }
@@ -1783,7 +1784,11 @@ class DefaultAuthService {
     }
     const externalResult = await this.externalTokenHandler.verifyToken(token);
     if (externalResult) {
-      return createCredentialsWithServicePrincipal(externalResult.subject);
+      return createCredentialsWithServicePrincipal(
+        externalResult.subject,
+        void 0,
+        externalResult.accessRestrictions
+      );
     }
     throw new errors.AuthenticationError("Illegal token");
   }
@@ -2197,18 +2202,112 @@ class UserTokenHandler {
   }
 }
 
+function readAccessRestrictionsFromConfig(externalAccessEntryConfig) {
+  const configs = externalAccessEntryConfig.getOptionalConfigArray("accessRestrictions") ?? [];
+  const result = /* @__PURE__ */ new Map();
+  for (const config of configs) {
+    const validKeys = ["plugin", "permission", "permissionAttribute"];
+    for (const key of config.keys()) {
+      if (!validKeys.includes(key)) {
+        const valid = validKeys.map((k) => `'${k}'`).join(", ");
+        throw new Error(
+          `Invalid key '${key}' in 'accessRestrictions' config, expected one of ${valid}`
+        );
+      }
+    }
+    const pluginId = config.getString("plugin");
+    const permissionNames = readPermissionNames(config);
+    const permissionAttributes = readPermissionAttributes(config);
+    if (result.has(pluginId)) {
+      throw new Error(
+        `Attempted to declare 'accessRestrictions' twice for plugin '${pluginId}', which is not permitted`
+      );
+    }
+    result.set(pluginId, {
+      ...permissionNames ? { permissionNames } : {},
+      ...permissionAttributes ? { permissionAttributes } : {}
+    });
+  }
+  return result.size ? result : void 0;
+}
+function readStringOrStringArrayFromConfig(root, key, validValues) {
+  if (!root.has(key)) {
+    return void 0;
+  }
+  const rawValues = Array.isArray(root.get(key)) ? root.getStringArray(key) : [root.getString(key)];
+  const values = [
+    ...new Set(
+      rawValues.map((v) => v.split(/[ ,]/)).flat().filter(Boolean)
+    )
+  ];
+  if (!values.length) {
+    return void 0;
+  }
+  if (validValues?.length) {
+    for (const value of values) {
+      if (!validValues.includes(value)) {
+        const valid = validValues.map((k) => `'${k}'`).join(", ");
+        throw new Error(
+          `Invalid value '${value}' at '${key}' in 'permissionAttributes' config, valid values are ${valid}`
+        );
+      }
+    }
+  }
+  return values;
+}
+function readPermissionNames(externalAccessEntryConfig) {
+  return readStringOrStringArrayFromConfig(
+    externalAccessEntryConfig,
+    "permission"
+  );
+}
+function readPermissionAttributes(externalAccessEntryConfig) {
+  const config = externalAccessEntryConfig.getOptionalConfig(
+    "permissionAttribute"
+  );
+  if (!config) {
+    return void 0;
+  }
+  const validKeys = ["action"];
+  for (const key of config.keys()) {
+    if (!validKeys.includes(key)) {
+      const valid = validKeys.map((k) => `'${k}'`).join(", ");
+      throw new Error(
+        `Invalid key '${key}' in 'permissionAttribute' config, expected ${valid}`
+      );
+    }
+  }
+  const action = readStringOrStringArrayFromConfig(config, "action", [
+    "create",
+    "read",
+    "update",
+    "delete"
+  ]);
+  const result = {
+    ...action ? { action } : {}
+  };
+  return Object.keys(result).length ? result : void 0;
+}
+
 class LegacyTokenHandler {
-  #entries = [];
-  add(options) {
-    this.#doAdd(options.getString("secret"), options.getString("subject"));
+  #entries = new Array();
+  add(config) {
+    const allAccessRestrictions = readAccessRestrictionsFromConfig(config);
+    this.#doAdd(
+      config.getString("options.secret"),
+      config.getString("options.subject"),
+      allAccessRestrictions
+    );
   }
   // used only for the old backend.auth.keys array
-  addOld(options) {
-    this.#doAdd(options.getString("secret"), "external:backstage-plugin");
+  addOld(config) {
+    this.#doAdd(config.getString("secret"), "external:backstage-plugin");
   }
-  #doAdd(secret, subject) {
+  #doAdd(secret, subject, allAccessRestrictions) {
     if (!secret.match(/^\S+$/)) {
       throw new Error("Illegal secret, must be a valid base64 string");
+    } else if (!subject.match(/^\S+$/)) {
+      throw new Error("Illegal subject, must be a set of non-space characters");
     }
     let key;
     try {
@@ -2216,10 +2315,18 @@ class LegacyTokenHandler {
     } catch {
       throw new Error("Illegal secret, must be a valid base64 string");
     }
-    if (!subject.match(/^\S+$/)) {
-      throw new Error("Illegal subject, must be a set of non-space characters");
+    if (this.#entries.some((e) => e.key === key)) {
+      throw new Error(
+        "Legacy externalAccess token was declared more than once"
+      );
     }
-    this.#entries.push({ key, subject });
+    this.#entries.push({
+      key,
+      result: {
+        subject,
+        allAccessRestrictions
+      }
+    });
   }
   async verifyToken(token) {
     try {
@@ -2234,10 +2341,10 @@ class LegacyTokenHandler {
     } catch (e) {
       return void 0;
     }
-    for (const entry of this.#entries) {
+    for (const { key, result } of this.#entries) {
       try {
-        await jose.jwtVerify(token, entry.key);
-        return { subject: entry.subject };
+        await jose.jwtVerify(token, key);
+        return result;
       } catch (e) {
         if (e.code !== "ERR_JWS_SIGNATURE_VERIFICATION_FAILED") {
           throw e;
@@ -2250,45 +2357,104 @@ class LegacyTokenHandler {
 
 const MIN_TOKEN_LENGTH = 8;
 class StaticTokenHandler {
-  #entries = [];
-  add(options) {
-    const token = options.getString("token");
+  #entries = /* @__PURE__ */ new Map();
+  add(config) {
+    const token = config.getString("options.token");
+    const subject = config.getString("options.subject");
+    const allAccessRestrictions = readAccessRestrictionsFromConfig(config);
     if (!token.match(/^\S+$/)) {
       throw new Error("Illegal token, must be a set of non-space characters");
-    }
-    if (token.length < MIN_TOKEN_LENGTH) {
+    } else if (token.length < MIN_TOKEN_LENGTH) {
       throw new Error(
         `Illegal token, must be at least ${MIN_TOKEN_LENGTH} characters length`
       );
-    }
-    const subject = options.getString("subject");
-    if (!subject.match(/^\S+$/)) {
+    } else if (!subject.match(/^\S+$/)) {
       throw new Error("Illegal subject, must be a set of non-space characters");
+    } else if (this.#entries.has(token)) {
+      throw new Error(
+        "Static externalAccess token was declared more than once"
+      );
     }
-    this.#entries.push({ token, subject });
+    this.#entries.set(token, { subject, allAccessRestrictions });
   }
   async verifyToken(token) {
-    const entry = this.#entries.find((e) => e.token === token);
-    if (!entry) {
-      return void 0;
+    return this.#entries.get(token);
+  }
+}
+
+class JWKSHandler {
+  #entries = [];
+  add(config) {
+    if (!config.getString("options.url").match(/^\S+$/)) {
+      throw new Error(
+        "Illegal JWKS URL, must be a set of non-space characters"
+      );
     }
-    return { subject: entry.subject };
+    const algorithms = readStringOrStringArrayFromConfig(
+      config,
+      "options.algorithm"
+    );
+    const issuers = readStringOrStringArrayFromConfig(config, "options.issuer");
+    const audiences = readStringOrStringArrayFromConfig(
+      config,
+      "options.audience"
+    );
+    const subjectPrefix = config.getOptionalString("options.subjectPrefix");
+    const url = new URL(config.getString("options.url"));
+    const jwks = jose.createRemoteJWKSet(url);
+    const allAccessRestrictions = readAccessRestrictionsFromConfig(config);
+    this.#entries.push({
+      algorithms,
+      audiences,
+      issuers,
+      jwks,
+      subjectPrefix,
+      url,
+      allAccessRestrictions
+    });
+  }
+  async verifyToken(token) {
+    for (const entry of this.#entries) {
+      try {
+        const {
+          payload: { sub }
+        } = await jose.jwtVerify(token, entry.jwks, {
+          algorithms: entry.algorithms,
+          issuer: entry.issuers,
+          audience: entry.audiences
+        });
+        if (sub) {
+          const prefix = entry.subjectPrefix ? `external:${entry.subjectPrefix}:` : "external:";
+          return {
+            subject: `${prefix}${sub}`,
+            allAccessRestrictions: entry.allAccessRestrictions
+          };
+        }
+      } catch {
+        continue;
+      }
+    }
+    return void 0;
   }
 }
 
 const NEW_CONFIG_KEY = "backend.auth.externalAccess";
 const OLD_CONFIG_KEY = "backend.auth.keys";
+let loggedDeprecationWarning = false;
 class ExternalTokenHandler {
-  constructor(handlers) {
+  constructor(ownPluginId, handlers) {
+    this.ownPluginId = ownPluginId;
     this.handlers = handlers;
   }
   static create(options) {
-    const { config, logger } = options;
+    const { ownPluginId, config, logger } = options;
     const staticHandler = new StaticTokenHandler();
     const legacyHandler = new LegacyTokenHandler();
+    const jwksHandler = new JWKSHandler();
     const handlers = {
       static: staticHandler,
-      legacy: legacyHandler
+      legacy: legacyHandler,
+      jwks: jwksHandler
     };
     const handlerConfigs = config.getOptionalConfigArray(NEW_CONFIG_KEY) ?? [];
     for (const handlerConfig of handlerConfigs) {
@@ -2300,10 +2466,11 @@ class ExternalTokenHandler {
           `Unknown type '${type}' in ${NEW_CONFIG_KEY}, expected one of ${valid}`
         );
       }
-      handler.add(handlerConfig.getConfig("options"));
+      handler.add(handlerConfig);
     }
     const legacyConfigs = config.getOptionalConfigArray(OLD_CONFIG_KEY) ?? [];
-    if (legacyConfigs.length) {
+    if (legacyConfigs.length && !loggedDeprecationWarning) {
+      loggedDeprecationWarning = true;
       logger.warn(
         `DEPRECATION WARNING: The ${OLD_CONFIG_KEY} config has been replaced by ${NEW_CONFIG_KEY}, see https://backstage.io/docs/auth/service-to-service-auth`
       );
@@ -2311,13 +2478,29 @@ class ExternalTokenHandler {
     for (const handlerConfig of legacyConfigs) {
       legacyHandler.addOld(handlerConfig);
     }
-    return new ExternalTokenHandler(Object.values(handlers));
+    return new ExternalTokenHandler(ownPluginId, Object.values(handlers));
   }
   async verifyToken(token) {
     for (const handler of this.handlers) {
       const result = await handler.verifyToken(token);
       if (result) {
-        return result;
+        const { allAccessRestrictions, ...rest } = result;
+        if (allAccessRestrictions) {
+          const accessRestrictions = allAccessRestrictions.get(
+            this.ownPluginId
+          );
+          if (!accessRestrictions) {
+            const valid = [...allAccessRestrictions.keys()].map((k) => `'${k}'`).join(", ");
+            throw new errors.NotAllowedError(
+              `This token's access is restricted to plugin(s) ${valid}`
+            );
+          }
+          return {
+            ...rest,
+            accessRestrictions
+          };
+        }
+        return rest;
       }
     }
     return void 0;
@@ -2338,16 +2521,7 @@ const authServiceFactory = backendPluginApi.createServiceFactory({
     // new auth services in the new backend system.
     tokenManager: backendPluginApi.coreServices.tokenManager
   },
-  async createRootContext({ config, logger }) {
-    const externalTokens = ExternalTokenHandler.create({
-      config,
-      logger
-    });
-    return {
-      externalTokens
-    };
-  },
-  async factory({ config, discovery, plugin, tokenManager, logger, database }, { externalTokens }) {
+  async factory({ config, discovery, plugin, tokenManager, logger, database }) {
     const disableDefaultAuthPolicy = Boolean(
       config.getOptionalBoolean(
         "backend.auth.dangerouslyDisableDefaultAuthPolicy"
@@ -2367,6 +2541,11 @@ const authServiceFactory = backendPluginApi.createServiceFactory({
       publicKeyStore,
       discovery
     });
+    const externalTokens = ExternalTokenHandler.create({
+      ownPluginId: plugin.getId(),
+      config,
+      logger
+    });
     return new DefaultAuthService(
       userTokens,
       pluginTokens,