auth-node: minor review fixes

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

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;
         };
       };

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) {

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