From ee28fa94daef3bf47ee89a63f9501b8a08c76c16 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Fri, 11 Aug 2023 16:54:37 +0200
Subject: [PATCH] auth-node: minor review fixes

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
---
 .../auth-backend-module-gcp-iap-provider/config.d.ts   | 10 ++++++++++
 .../src/sign-in/readDeclarativeSignInResolver.ts       |  6 ++++--
 plugins/auth-node/src/types.ts                         |  6 +++++-
 3 files changed, 19 insertions(+), 3 deletions(-)

diff --git a/plugins/auth-backend-module-gcp-iap-provider/config.d.ts b/plugins/auth-backend-module-gcp-iap-provider/config.d.ts
index c8460470af..945378ada6 100644
--- a/plugins/auth-backend-module-gcp-iap-provider/config.d.ts
+++ b/plugins/auth-backend-module-gcp-iap-provider/config.d.ts
@@ -17,10 +17,20 @@
 export interface Config {
   auth?: {
     providers?: {
+      /**
+       * Configuration for the Google Cloud Platform Identity-Aware Proxy (IAP) auth provider.
+       */
       gcpIap?: {
         [authEnv: string]: {
+          /**
+           * The audience to use when validating incoming JWT tokens.
+           * See https://backstage.io/docs/auth/google/gcp-iap-auth
+           */
           audience: string;
 
+          /**
+           * The name of the header to read the JWT token from, defaults to `'x-goog-iap-jwt-assertion'`.
+           */
           jwtHeader?: string;
         };
       };
diff --git a/plugins/auth-node/src/sign-in/readDeclarativeSignInResolver.ts b/plugins/auth-node/src/sign-in/readDeclarativeSignInResolver.ts
index 31c4dd92a9..82b4918326 100644
--- a/plugins/auth-node/src/sign-in/readDeclarativeSignInResolver.ts
+++ b/plugins/auth-node/src/sign-in/readDeclarativeSignInResolver.ts
@@ -45,7 +45,9 @@ export function readDeclarativeSignInResolver<TAuthResult>(
         const { resolver: _ignored, ...resolverOptions } =
           resolverConfig.get<JsonObject>();
 
-        return resolver(resolverOptions);
+        return resolver(
+          Object.keys(resolverOptions).length > 0 ? resolverOptions : undefined,
+        );
       }) ?? [];
 
   if (resolvers.length === 0) {
@@ -53,7 +55,7 @@ export function readDeclarativeSignInResolver<TAuthResult>(
   }
 
   return async (profile, context) => {
-    for (const resolver of resolvers ?? []) {
+    for (const resolver of resolvers) {
       try {
         return await resolver(profile, context);
       } catch (error) {
diff --git a/plugins/auth-node/src/types.ts b/plugins/auth-node/src/types.ts
index ccdfb0c39b..d52abf00fb 100644
--- a/plugins/auth-node/src/types.ts
+++ b/plugins/auth-node/src/types.ts
@@ -106,7 +106,7 @@ export type AuthResolverCatalogUserQuery =
     };
 
 /**
- * Parameters used to issue new ID Tokens
+ * Parameters used to issue new Backstage Tokens
  *
  * @public
  */
@@ -199,6 +199,10 @@ export interface AuthProviderRouteHandlers {
    * (Optional) If the auth provider supports refresh tokens then this method handles
    * requests to get a new access token.
    *
+   * Other types of providers may also use this method to implement its own logic to create new sessions
+   * upon request. For example, this can be used to create a new session for a provider that handles requests
+   * from an authenticating proxy.
+   *
    * Request
    * - to contain a refresh token cookie and scope (Optional) query parameter.
    * Response