auth-backend: move a couple more types to auth-node

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

plugins/auth-node/package.json

@@ -29,6 +29,7 @@
   },
   "dependencies": {
     "@backstage/backend-common": "workspace:^",
+    "@backstage/backend-plugin-api": "workspace:^",
     "@backstage/catalog-client": "workspace:^",
     "@backstage/catalog-model": "workspace:^",
     "@backstage/config": "workspace:^",

plugins/auth-node/src/index.ts

@@ -26,13 +26,19 @@ export { IdentityClient } from './IdentityClient';
 export type { IdentityApi } from './IdentityApi';
 export type { IdentityClientOptions } from './DefaultIdentityClient';
 export type {
+  AuthProviderConfig,
+  AuthProviderRouteHandlers,
+  AuthProviderFactory,
   AuthResolverCatalogUserQuery,
   AuthResolverContext,
   BackstageIdentityResponse,
   BackstageSignInResult,
   BackstageUserIdentity,
+  ClientAuthResponse,
   CookieConfigurer,
   IdentityApiGetIdentityRequest,
   ProfileInfo,
+  SignInInfo,
+  SignInResolver,
   TokenParams,
 } from './types';

plugins/auth-node/src/types.ts

@@ -14,10 +14,12 @@
  * limitations under the License.
  */
 
+import { LoggerService } from '@backstage/backend-plugin-api';
 import { EntityFilterQuery } from '@backstage/catalog-client';
 import { Entity } from '@backstage/catalog-model';
+import { Config } from '@backstage/config';
 import { JsonValue } from '@backstage/types';
-import { Request } from 'express';
+import { Request, Response } from 'express';
 
 /**
  * A representation of a successful Backstage sign-in.
@@ -165,6 +167,133 @@ export type AuthResolverContext = {
   ): Promise<BackstageSignInResult>;
 };
 
+/**
+ * Any Auth provider needs to implement this interface which handles the routes in the
+ * auth backend. Any auth API requests from the frontend reaches these methods.
+ *
+ * The routes in the auth backend API are tied to these methods like below
+ *
+ * `/auth/[provider]/start -> start`
+ * `/auth/[provider]/handler/frame -> frameHandler`
+ * `/auth/[provider]/refresh -> refresh`
+ * `/auth/[provider]/logout -> logout`
+ *
+ * @public
+ */
+export interface AuthProviderRouteHandlers {
+  /**
+   * Handles the start route of the API. This initiates a sign in request with an auth provider.
+   *
+   * Request
+   * - scopes for the auth request (Optional)
+   * Response
+   * - redirect to the auth provider for the user to sign in or consent.
+   * - sets a nonce cookie and also pass the nonce as 'state' query parameter in the redirect request
+   */
+  start(req: Request, res: Response): Promise<void>;
+
+  /**
+   * Once the user signs in or consents in the OAuth screen, the auth provider redirects to the
+   * callbackURL which is handled by this method.
+   *
+   * Request
+   * - to contain a nonce cookie and a 'state' query parameter
+   * Response
+   * - postMessage to the window with a payload that contains accessToken, expiryInSeconds?, idToken? and scope.
+   * - sets a refresh token cookie if the auth provider supports refresh tokens
+   */
+  frameHandler(req: Request, res: Response): Promise<void>;
+
+  /**
+   * (Optional) If the auth provider supports refresh tokens then this method handles
+   * requests to get a new access token.
+   *
+   * Request
+   * - to contain a refresh token cookie and scope (Optional) query parameter.
+   * Response
+   * - payload with accessToken, expiryInSeconds?, idToken?, scope and user profile information.
+   */
+  refresh?(req: Request, res: Response): Promise<void>;
+
+  /**
+   * (Optional) Handles sign out requests
+   *
+   * Response
+   * - removes the refresh token cookie
+   */
+  logout?(req: Request, res: Response): Promise<void>;
+}
+
+/** @public */
+export type AuthProviderConfig = {
+  /**
+   * The protocol://domain[:port] where the app is hosted. This is used to construct the
+   * callbackURL to redirect to once the user signs in to the auth provider.
+   */
+  baseUrl: string;
+
+  /**
+   * The base URL of the app as provided by app.baseUrl
+   */
+  appUrl: string;
+
+  /**
+   * A function that is called to check whether an origin is allowed to receive the authentication result.
+   */
+  isOriginAllowed: (origin: string) => boolean;
+
+  /**
+   * The function used to resolve cookie configuration based on the auth provider options.
+   */
+  cookieConfigurer?: CookieConfigurer;
+};
+
+/** @public */
+export type AuthProviderFactory = (options: {
+  providerId: string;
+  globalConfig: AuthProviderConfig;
+  config: Config;
+  logger: LoggerService;
+  resolverContext: AuthResolverContext;
+}) => AuthProviderRouteHandlers;
+
+/** @public */
+export type ClientAuthResponse<ProviderInfo> = {
+  providerInfo: ProviderInfo;
+  profile: ProfileInfo;
+  backstageIdentity?: BackstageIdentityResponse;
+};
+
+/**
+ * Type of sign in information context. Includes the profile information and
+ * authentication result which contains auth related information.
+ *
+ * @public
+ */
+export type SignInInfo<TAuthResult> = {
+  /**
+   * The simple profile passed down for use in the frontend.
+   */
+  profile: ProfileInfo;
+
+  /**
+   * The authentication result that was received from the authentication
+   * provider.
+   */
+  result: TAuthResult;
+};
+
+/**
+ * Describes the function which handles the result of a successful
+ * authentication. Must return a valid {@link @backstage/plugin-auth-node#BackstageSignInResult}.
+ *
+ * @public
+ */
+export type SignInResolver<TAuthResult> = (
+  info: SignInInfo<TAuthResult>,
+  context: AuthResolverContext,
+) => Promise<BackstageSignInResult>;
+
 /**
  * Used to display login information to user, i.e. sidebar popup.
  *