implement external token access

Co-authored-by: Vincenzo Scamporlino <vincenzos@spotify.com> Signed-off-by: Fredrik Adelöw <freben@gmail.com>
2024-04-12 16:59:26 +02:00
parent 99305a09da
commit 00fca28b41
21 changed files with 1080 additions and 184 deletions
@@ -32,6 +32,104 @@ export interface Config {
       * unless you configure credentials for service calls.
       */
      dangerouslyDisableDefaultAuthPolicy?: boolean;
+
+      /**
+       * Configures methods of external access, ie ways for callers outside of
+       * the Backstage ecosystem to get authorized for access to APIs that do
+       * not permit unauthorized access.
+       *
+       * @deepVisibility secret
+       */
+      externalAccess: Array<
+        | {
+            /**
+             * This is the legacy service-to-service access method, where a set
+             * of static keys were shared among plugins and used for symmetric
+             * signing and verification. These correspond to the old
+             * `backend.auth.keys` set and retain their behavior for backwards
+             * compatibility. Please migrate to other access methods when
+             * possible.
+             *
+             * Callers generate JWT tokens with the following payload:
+             *
+             * ```json
+             * {
+             *   "sub": "backstage-plugin",
+             *   "exp": <epoch seconds one hour in the future>
+             * }
+             * ```
+             *
+             * And sign them with HS256, using the base64 decoded secret. The
+             * tokens are then passed along with requests in the Authorization
+             * header:
+             *
+             * ```
+             * Authorization: Bearer eyJhbGciOiJIUzI...
+             * ```
+             */
+            type: 'legacy';
+            options: {
+              /**
+               * Any set of base64 encoded random bytes to be used as both the
+               * signing and verification key. Should be sufficiently long so as
+               * not to be easy to guess by brute force.
+               *
+               * Can be generated eg using
+               *
+               * ```sh
+               * node -p 'require("crypto").randomBytes(24).toString("base64")'
+               * ```
+               */
+              secret: string;
+
+              /**
+               * Sets the subject of the principal, when matching this token.
+               * Useful for debugging and tracking purposes.
+               */
+              subject: string;
+            };
+          }
+        | {
+            /**
+             * This access method consists of random static tokens that can be
+             * handed out to callers.
+             *
+             * The tokens are then passed along verbatim with requests in the
+             * Authorization header:
+             *
+             * ```
+             * Authorization: Bearer eZv5o+fW3KnR3kVabMW4ZcDNLPl8nmMW
+             * ```
+             */
+            type: 'static';
+            options: {
+              /**
+               * A raw token that can be any string, but for security reasons
+               * should be sufficiently long so as not to be easy to guess by
+               * brute force.
+               *
+               * Can be generated eg using
+               *
+               * ```sh
+               * node -p 'require("crypto").randomBytes(24).toString("base64")'
+               * ```
+               *
+               * Since the tokens can be any string, you are free to add
+               * additional identifying data to them if you like. For example,
+               * adding a `freben-local-dev-` prefix for debugging purposes to a
+               * token that you know will be handed out for use as a personal
+               * access token during development.
+               */
+              token: string;
+
+              /**
+               * Sets the subject of the principal, when matching this token.
+               * Useful for debugging and tracking purposes.
+               */
+              subject: string;
+            };
+          }
+      >;
    };
  };