mongodb 6.6.2 → 6.7.0-dev.20240607.sha.aa429f8c

package/src/cmap/auth/mongodb_oidc/human_callback_workflow.ts

@@ -0,0 +1,142 @@
+import { BSON } from 'bson';
+
+import { MONGODB_ERROR_CODES, MongoError, MongoOIDCError } from '../../../error';
+import { Timeout, TimeoutError } from '../../../timeout';
+import { type Connection } from '../../connection';
+import { type MongoCredentials } from '../mongo_credentials';
+import {
+  type IdPInfo,
+  OIDC_VERSION,
+  type OIDCCallbackFunction,
+  type OIDCCallbackParams,
+  type OIDCResponse
+} from '../mongodb_oidc';
+import { CallbackWorkflow, HUMAN_TIMEOUT_MS } from './callback_workflow';
+import { type TokenCache } from './token_cache';
+
+/**
+ * Class implementing behaviour for the non human callback workflow.
+ * @internal
+ */
+export class HumanCallbackWorkflow extends CallbackWorkflow {
+  /**
+   * Instantiate the human callback workflow.
+   */
+  constructor(cache: TokenCache, callback: OIDCCallbackFunction) {
+    super(cache, callback);
+  }
+
+  /**
+   * Execute the OIDC human callback workflow.
+   */
+  async execute(connection: Connection, credentials: MongoCredentials): Promise<void> {
+    // Check if the Client Cache has an access token.
+    // If it does, cache the access token in the Connection Cache and perform a One-Step SASL conversation
+    // using the access token. If the server returns an Authentication error (18),
+    // invalidate the access token token from the Client Cache, clear the Connection Cache,
+    // and restart the authentication flow. Raise any other errors to the user. On success, exit the algorithm.
+    if (this.cache.hasAccessToken) {
+      const token = this.cache.getAccessToken();
+      connection.accessToken = token;
+      try {
+        return await this.finishAuthentication(connection, credentials, token);
+      } catch (error) {
+        if (
+          error instanceof MongoError &&
+          error.code === MONGODB_ERROR_CODES.AuthenticationFailed
+        ) {
+          this.cache.removeAccessToken();
+          delete connection.accessToken;
+          return await this.execute(connection, credentials);
+        } else {
+          throw error;
+        }
+      }
+    }
+    // Check if the Client Cache has a refresh token.
+    // If it does, call the OIDC Human Callback with the cached refresh token and IdpInfo to get a
+    // new access token. Cache the new access token in the Client Cache and Connection Cache.
+    // Perform a One-Step SASL conversation using the new access token. If the the server returns
+    // an Authentication error (18), clear the refresh token, invalidate the access token from the
+    // Client Cache, clear the Connection Cache, and restart the authentication flow. Raise any other
+    // errors to the user. On success, exit the algorithm.
+    if (this.cache.hasRefreshToken) {
+      const refreshToken = this.cache.getRefreshToken();
+      const result = await this.fetchAccessToken(
+        this.cache.getIdpInfo(),
+        credentials,
+        refreshToken
+      );
+      this.cache.put(result);
+      connection.accessToken = result.accessToken;
+      try {
+        return await this.finishAuthentication(connection, credentials, result.accessToken);
+      } catch (error) {
+        if (
+          error instanceof MongoError &&
+          error.code === MONGODB_ERROR_CODES.AuthenticationFailed
+        ) {
+          this.cache.removeRefreshToken();
+          delete connection.accessToken;
+          return await this.execute(connection, credentials);
+        } else {
+          throw error;
+        }
+      }
+    }
+
+    // Start a new Two-Step SASL conversation.
+    // Run a PrincipalStepRequest to get the IdpInfo.
+    // Call the OIDC Human Callback with the new IdpInfo to get a new access token and optional refresh
+    // token. Drivers MUST NOT pass a cached refresh token to the callback when performing
+    // a new Two-Step conversation. Cache the new IdpInfo and refresh token in the Client Cache and the
+    // new access token in the Client Cache and Connection Cache.
+    // Attempt to authenticate using a JwtStepRequest with the new access token. Raise any errors to the user.
+    const startResponse = await this.startAuthentication(connection, credentials);
+    const conversationId = startResponse.conversationId;
+    const idpInfo = BSON.deserialize(startResponse.payload.buffer) as IdPInfo;
+    const callbackResponse = await this.fetchAccessToken(idpInfo, credentials);
+    this.cache.put(callbackResponse, idpInfo);
+    connection.accessToken = callbackResponse.accessToken;
+    return await this.finishAuthentication(
+      connection,
+      credentials,
+      callbackResponse.accessToken,
+      conversationId
+    );
+  }
+
+  /**
+   * Fetches an access token using the callback.
+   */
+  private async fetchAccessToken(
+    idpInfo: IdPInfo,
+    credentials: MongoCredentials,
+    refreshToken?: string
+  ): Promise<OIDCResponse> {
+    const controller = new AbortController();
+    const params: OIDCCallbackParams = {
+      timeoutContext: controller.signal,
+      version: OIDC_VERSION,
+      idpInfo: idpInfo
+    };
+    if (credentials.username) {
+      params.username = credentials.username;
+    }
+    if (refreshToken) {
+      params.refreshToken = refreshToken;
+    }
+    const timeout = Timeout.expires(HUMAN_TIMEOUT_MS);
+    try {
+      return await Promise.race([this.executeAndValidateCallback(params), timeout]);
+    } catch (error) {
+      if (TimeoutError.is(error)) {
+        controller.abort();
+        throw new MongoOIDCError(`OIDC callback timed out after ${HUMAN_TIMEOUT_MS}ms.`);
+      }
+      throw error;
+    } finally {
+      timeout.clear();
+    }
+  }
+}

package/src/cmap/auth/mongodb_oidc/machine_workflow.ts

@@ -0,0 +1,137 @@
+import { type Document } from 'bson';
+import { setTimeout } from 'timers/promises';
+
+import { ns } from '../../../utils';
+import type { Connection } from '../../connection';
+import type { MongoCredentials } from '../mongo_credentials';
+import type { Workflow } from '../mongodb_oidc';
+import { finishCommandDocument } from './command_builders';
+import { type TokenCache } from './token_cache';
+
+/** The time to throttle callback calls. */
+const THROTTLE_MS = 100;
+
+/**
+ * The access token format.
+ * @internal
+ */
+export interface AccessToken {
+  access_token: string;
+  expires_in?: number;
+}
+
+/** @internal */
+export type OIDCTokenFunction = (credentials: MongoCredentials) => Promise<AccessToken>;
+
+/**
+ * Common behaviour for OIDC machine workflows.
+ * @internal
+ */
+export abstract class MachineWorkflow implements Workflow {
+  cache: TokenCache;
+  callback: OIDCTokenFunction;
+  lastExecutionTime: number;
+
+  /**
+   * Instantiate the machine workflow.
+   */
+  constructor(cache: TokenCache) {
+    this.cache = cache;
+    this.callback = this.withLock(this.getToken.bind(this));
+    this.lastExecutionTime = Date.now() - THROTTLE_MS;
+  }
+
+  /**
+   * Execute the workflow. Gets the token from the subclass implementation.
+   */
+  async execute(connection: Connection, credentials: MongoCredentials): Promise<void> {
+    const token = await this.getTokenFromCacheOrEnv(connection, credentials);
+    const command = finishCommandDocument(token);
+    await connection.command(ns(credentials.source), command, undefined);
+  }
+
+  /**
+   * Reauthenticate on a machine workflow just grabs the token again since the server
+   * has said the current access token is invalid or expired.
+   */
+  async reauthenticate(connection: Connection, credentials: MongoCredentials): Promise<void> {
+    if (this.cache.hasAccessToken) {
+      // Reauthentication implies the token has expired.
+      if (connection.accessToken === this.cache.getAccessToken()) {
+        // If connection's access token is the same as the cache's, remove
+        // the token from the cache and connection.
+        this.cache.removeAccessToken();
+        delete connection.accessToken;
+      } else {
+        // If the connection's access token is different from the cache's, set
+        // the cache's token on the connection and do not remove from the
+        // cache.
+        connection.accessToken = this.cache.getAccessToken();
+      }
+    }
+    await this.execute(connection, credentials);
+  }
+
+  /**
+   * Get the document to add for speculative authentication.
+   */
+  async speculativeAuth(connection: Connection, credentials: MongoCredentials): Promise<Document> {
+    // The spec states only cached access tokens can use speculative auth.
+    if (!this.cache.hasAccessToken) {
+      return {};
+    }
+    const token = await this.getTokenFromCacheOrEnv(connection, credentials);
+    const document = finishCommandDocument(token);
+    document.db = credentials.source;
+    return { speculativeAuthenticate: document };
+  }
+
+  /**
+   * Get the token from the cache or environment.
+   */
+  private async getTokenFromCacheOrEnv(
+    connection: Connection,
+    credentials: MongoCredentials
+  ): Promise<string> {
+    if (this.cache.hasAccessToken) {
+      return this.cache.getAccessToken();
+    } else {
+      const token = await this.callback(credentials);
+      this.cache.put({ accessToken: token.access_token, expiresInSeconds: token.expires_in });
+      // Put the access token on the connection as well.
+      connection.accessToken = token.access_token;
+      return token.access_token;
+    }
+  }
+
+  /**
+   * Ensure the callback is only executed one at a time, and throttled to
+   * only once per 100ms.
+   */
+  private withLock(callback: OIDCTokenFunction): OIDCTokenFunction {
+    let lock: Promise<any> = Promise.resolve();
+    return async (credentials: MongoCredentials): Promise<AccessToken> => {
+      // We do this to ensure that we would never return the result of the
+      // previous lock, only the current callback's value would get returned.
+      await lock;
+      lock = lock
+        // eslint-disable-next-line github/no-then
+        .catch(() => null)
+        // eslint-disable-next-line github/no-then
+        .then(async () => {
+          const difference = Date.now() - this.lastExecutionTime;
+          if (difference <= THROTTLE_MS) {
+            await setTimeout(THROTTLE_MS - difference);
+          }
+          this.lastExecutionTime = Date.now();
+          return await callback(credentials);
+        });
+      return await lock;
+    };
+  }
+
+  /**
+   * Get the token from the environment or endpoint.
+   */
+  abstract getToken(credentials: MongoCredentials): Promise<AccessToken>;
+}

package/src/cmap/auth/mongodb_oidc/token_cache.ts

@@ -0,0 +1,62 @@
+import { MongoDriverError } from '../../../error';
+import type { IdPInfo, OIDCResponse } from '../mongodb_oidc';
+
+class MongoOIDCError extends MongoDriverError {}
+
+/** @internal */
+export class TokenCache {
+  private accessToken?: string;
+  private refreshToken?: string;
+  private idpInfo?: IdPInfo;
+  private expiresInSeconds?: number;
+
+  get hasAccessToken(): boolean {
+    return !!this.accessToken;
+  }
+
+  get hasRefreshToken(): boolean {
+    return !!this.refreshToken;
+  }
+
+  get hasIdpInfo(): boolean {
+    return !!this.idpInfo;
+  }
+
+  getAccessToken(): string {
+    if (!this.accessToken) {
+      throw new MongoOIDCError('Attempted to get an access token when none exists.');
+    }
+    return this.accessToken;
+  }
+
+  getRefreshToken(): string {
+    if (!this.refreshToken) {
+      throw new MongoOIDCError('Attempted to get a refresh token when none exists.');
+    }
+    return this.refreshToken;
+  }
+
+  getIdpInfo(): IdPInfo {
+    if (!this.idpInfo) {
+      throw new MongoOIDCError('Attempted to get IDP information when none exists.');
+    }
+    return this.idpInfo;
+  }
+
+  put(response: OIDCResponse, idpInfo?: IdPInfo) {
+    this.accessToken = response.accessToken;
+    this.refreshToken = response.refreshToken;
+    this.expiresInSeconds = response.expiresInSeconds;
+    if (idpInfo) {
+      this.idpInfo = idpInfo;
+    }
+  }
+
+  removeAccessToken() {
+    this.accessToken = undefined;
+  }
+
+  removeRefreshToken() {
+    this.refreshToken = undefined;
+  }
+}

package/src/cmap/auth/mongodb_oidc/token_machine_workflow.ts

@@ -0,0 +1,34 @@
+import * as fs from 'fs';
+
+import { MongoAWSError } from '../../../error';
+import { type AccessToken, MachineWorkflow } from './machine_workflow';
+import { type TokenCache } from './token_cache';
+
+/** Error for when the token is missing in the environment. */
+const TOKEN_MISSING_ERROR = 'OIDC_TOKEN_FILE must be set in the environment.';
+
+/**
+ * Device workflow implementation for AWS.
+ *
+ * @internal
+ */
+export class TokenMachineWorkflow extends MachineWorkflow {
+  /**
+   * Instantiate the machine workflow.
+   */
+  constructor(cache: TokenCache) {
+    super(cache);
+  }
+
+  /**
+   * Get the token from the environment.
+   */
+  async getToken(): Promise<AccessToken> {
+    const tokenFile = process.env.OIDC_TOKEN_FILE;
+    if (!tokenFile) {
+      throw new MongoAWSError(TOKEN_MISSING_ERROR);
+    }
+    const token = await fs.promises.readFile(tokenFile, 'utf8');
+    return { access_token: token };
+  }
+}

package/src/cmap/auth/mongodb_oidc.ts

@@ -5,64 +5,93 @@ import type { HandshakeDocument } from '../connect';
 import type { Connection } from '../connection';
 import { type AuthContext, AuthProvider } from './auth_provider';
 import type { MongoCredentials } from './mongo_credentials';
-import { AwsServiceWorkflow } from './mongodb_oidc/aws_service_workflow';
-import { AzureServiceWorkflow } from './mongodb_oidc/azure_service_workflow';
-import { CallbackWorkflow } from './mongodb_oidc/callback_workflow';
+import { AzureMachineWorkflow } from './mongodb_oidc/azure_machine_workflow';
+import { GCPMachineWorkflow } from './mongodb_oidc/gcp_machine_workflow';
+import { TokenCache } from './mongodb_oidc/token_cache';
+import { TokenMachineWorkflow } from './mongodb_oidc/token_machine_workflow';
 
 /** Error when credentials are missing. */
 const MISSING_CREDENTIALS_ERROR = 'AuthContext must provide credentials.';
 
 /**
+ * The information returned by the server on the IDP server.
  * @public
- * @experimental
  */
-export interface IdPServerInfo {
+export interface IdPInfo {
+  /**
+   * A URL which describes the Authentication Server. This identifier should
+   * be the iss of provided access tokens, and be viable for RFC8414 metadata
+   * discovery and RFC9207 identification.
+   */
   issuer: string;
+  /** A unique client ID for this OIDC client. */
   clientId: string;
+  /** A list of additional scopes to request from IdP. */
   requestScopes?: string[];
 }
 
 /**
+ * The response from the IdP server with the access token and
+ * optional expiration time and refresh token.
  * @public
- * @experimental
  */
 export interface IdPServerResponse {
+  /** The OIDC access token. */
   accessToken: string;
+  /** The time when the access token expires. For future use. */
   expiresInSeconds?: number;
+  /** The refresh token, if applicable, to be used by the callback to request a new token from the issuer. */
   refreshToken?: string;
 }
 
 /**
+ * The response required to be returned from the machine or
+ * human callback workflows' callback.
  * @public
- * @experimental
  */
-export interface OIDCCallbackContext {
+export interface OIDCResponse {
+  /** The OIDC access token. */
+  accessToken: string;
+  /** The time when the access token expires. For future use. */
+  expiresInSeconds?: number;
+  /** The refresh token, if applicable, to be used by the callback to request a new token from the issuer. */
   refreshToken?: string;
-  timeoutSeconds?: number;
-  timeoutContext?: AbortSignal;
-  version: number;
 }
 
 /**
+ * The parameters that the driver provides to the user supplied
+ * human or machine callback.
+ *
+ * The version number is used to communicate callback API changes that are not breaking but that
+ * users may want to know about and review their implementation. Users may wish to check the version
+ * number and throw an error if their expected version number and the one provided do not match.
  * @public
- * @experimental
  */
-export type OIDCRequestFunction = (
-  info: IdPServerInfo,
-  context: OIDCCallbackContext
-) => Promise<IdPServerResponse>;
+export interface OIDCCallbackParams {
+  /** Optional username. */
+  username?: string;
+  /** The context in which to timeout the OIDC callback. */
+  timeoutContext: AbortSignal;
+  /** The current OIDC API version. */
+  version: 1;
+  /** The IdP information returned from the server. */
+  idpInfo?: IdPInfo;
+  /** The refresh token, if applicable, to be used by the callback to request a new token from the issuer. */
+  refreshToken?: string;
+}
 
 /**
+ * The signature of the human or machine callback functions.
  * @public
- * @experimental
  */
-export type OIDCRefreshFunction = (
-  info: IdPServerInfo,
-  context: OIDCCallbackContext
-) => Promise<IdPServerResponse>;
+export type OIDCCallbackFunction = (params: OIDCCallbackParams) => Promise<OIDCResponse>;
+
+/** The current version of OIDC implementation. */
+export const OIDC_VERSION = 1;
 
-type ProviderName = 'aws' | 'azure' | 'callback';
+type EnvironmentName = 'test' | 'azure' | 'gcp' | undefined;
 
+/** @internal */
 export interface Workflow {
   /**
    * All device workflows must implement this method in order to get the access
@@ -71,32 +100,41 @@ export interface Workflow {
   execute(
     connection: Connection,
     credentials: MongoCredentials,
-    reauthenticating: boolean,
     response?: Document
-  ): Promise<Document>;
+  ): Promise<void>;
+
+  /**
+   * Each workflow should specify the correct custom behaviour for reauthentication.
+   */
+  reauthenticate(connection: Connection, credentials: MongoCredentials): Promise<void>;
 
   /**
    * Get the document to add for speculative authentication.
    */
-  speculativeAuth(credentials: MongoCredentials): Promise<Document>;
+  speculativeAuth(connection: Connection, credentials: MongoCredentials): Promise<Document>;
 }
 
 /** @internal */
-export const OIDC_WORKFLOWS: Map<ProviderName, Workflow> = new Map();
-OIDC_WORKFLOWS.set('callback', new CallbackWorkflow());
-OIDC_WORKFLOWS.set('aws', new AwsServiceWorkflow());
-OIDC_WORKFLOWS.set('azure', new AzureServiceWorkflow());
+export const OIDC_WORKFLOWS: Map<EnvironmentName, () => Workflow> = new Map();
+OIDC_WORKFLOWS.set('test', () => new TokenMachineWorkflow(new TokenCache()));
+OIDC_WORKFLOWS.set('azure', () => new AzureMachineWorkflow(new TokenCache()));
+OIDC_WORKFLOWS.set('gcp', () => new GCPMachineWorkflow(new TokenCache()));
 
 /**
  * OIDC auth provider.
- * @experimental
  */
 export class MongoDBOIDC extends AuthProvider {
+  workflow: Workflow;
+
   /**
    * Instantiate the auth provider.
    */
-  constructor() {
+  constructor(workflow?: Workflow) {
     super();
+    if (!workflow) {
+      throw new MongoInvalidArgumentError('No workflow provided to the OIDC auth provider.');
+    }
+    this.workflow = workflow;
   }
 
   /**
@@ -104,9 +142,15 @@ export class MongoDBOIDC extends AuthProvider {
    */
   override async auth(authContext: AuthContext): Promise<void> {
     const { connection, reauthenticating, response } = authContext;
+    if (response?.speculativeAuthenticate?.done) {
+      return;
+    }
     const credentials = getCredentials(authContext);
-    const workflow = getWorkflow(credentials);
-    await workflow.execute(connection, credentials, reauthenticating, response);
+    if (reauthenticating) {
+      await this.workflow.reauthenticate(connection, credentials);
+    } else {
+      await this.workflow.execute(connection, credentials, response);
+    }
   }
 
   /**
@@ -116,9 +160,9 @@ export class MongoDBOIDC extends AuthProvider {
     handshakeDoc: HandshakeDocument,
     authContext: AuthContext
   ): Promise<HandshakeDocument> {
+    const { connection } = authContext;
     const credentials = getCredentials(authContext);
-    const workflow = getWorkflow(credentials);
-    const result = await workflow.speculativeAuth(credentials);
+    const result = await this.workflow.speculativeAuth(connection, credentials);
     return { ...handshakeDoc, ...result };
   }
 }
@@ -133,17 +177,3 @@ function getCredentials(authContext: AuthContext): MongoCredentials {
   }
   return credentials;
 }
-
-/**
- * Gets either a device workflow or callback workflow.
- */
-function getWorkflow(credentials: MongoCredentials): Workflow {
-  const providerName = credentials.mechanismProperties.PROVIDER_NAME;
-  const workflow = OIDC_WORKFLOWS.get(providerName || 'callback');
-  if (!workflow) {
-    throw new MongoInvalidArgumentError(
-      `Could not load workflow for provider ${credentials.mechanismProperties.PROVIDER_NAME}`
-    );
-  }
-  return workflow;
-}

package/src/cmap/auth/providers.ts

@@ -8,7 +8,6 @@ export const AuthMechanism = Object.freeze({
   MONGODB_SCRAM_SHA1: 'SCRAM-SHA-1',
   MONGODB_SCRAM_SHA256: 'SCRAM-SHA-256',
   MONGODB_X509: 'MONGODB-X509',
-  /** @experimental */
   MONGODB_OIDC: 'MONGODB-OIDC'
 } as const);
 

package/src/cmap/connect.ts

@@ -91,7 +91,10 @@ export async function performInitialHandshake(
   if (credentials) {
     if (
       !(credentials.mechanism === AuthMechanism.MONGODB_DEFAULT) &&
-      !options.authProviders.getOrCreateProvider(credentials.mechanism)
+      !options.authProviders.getOrCreateProvider(
+        credentials.mechanism,
+        credentials.mechanismProperties
+      )
     ) {
       throw new MongoInvalidArgumentError(`AuthMechanism '${credentials.mechanism}' not supported`);
     }
@@ -146,7 +149,10 @@ export async function performInitialHandshake(
     authContext.response = response;
 
     const resolvedCredentials = credentials.resolveAuthMechanism(response);
-    const provider = options.authProviders.getOrCreateProvider(resolvedCredentials.mechanism);
+    const provider = options.authProviders.getOrCreateProvider(
+      resolvedCredentials.mechanism,
+      resolvedCredentials.mechanismProperties
+    );
     if (!provider) {
       throw new MongoInvalidArgumentError(
         `No AuthProvider for ${resolvedCredentials.mechanism} defined.`
@@ -218,7 +224,8 @@ export async function prepareHandshakeDocument(
       handshakeDoc.saslSupportedMechs = `${credentials.source}.${credentials.username}`;
 
       const provider = authContext.options.authProviders.getOrCreateProvider(
-        AuthMechanism.MONGODB_SCRAM_SHA256
+        AuthMechanism.MONGODB_SCRAM_SHA256,
+        credentials.mechanismProperties
       );
       if (!provider) {
         // This auth mechanism is always present.
@@ -228,7 +235,10 @@ export async function prepareHandshakeDocument(
       }
       return await provider.prepare(handshakeDoc, authContext);
     }
-    const provider = authContext.options.authProviders.getOrCreateProvider(credentials.mechanism);
+    const provider = authContext.options.authProviders.getOrCreateProvider(
+      credentials.mechanism,
+      credentials.mechanismProperties
+    );
     if (!provider) {
       throw new MongoInvalidArgumentError(`No AuthProvider for ${credentials.mechanism} defined.`);
     }

package/src/cmap/connection.ts

@@ -174,6 +174,7 @@ export class Connection extends TypedEventEmitter<ConnectionEvents> {
   public authContext?: AuthContext;
   public delayedTimeoutId: NodeJS.Timeout | null = null;
   public generation: number;
+  public accessToken?: string;
   public readonly description: Readonly<StreamDescription>;
   /**
    * Represents if the connection has been established:

package/src/cmap/connection_pool.ts

@@ -551,7 +551,8 @@ export class ConnectionPool extends TypedEventEmitter<ConnectionPoolEvents> {
 
     const resolvedCredentials = credentials.resolveAuthMechanism(connection.hello);
     const provider = this[kServer].topology.client.s.authProviders.getOrCreateProvider(
-      resolvedCredentials.mechanism
+      resolvedCredentials.mechanism,
+      resolvedCredentials.mechanismProperties
     );
 
     if (!provider) {

package/src/connection_string.ts

@@ -698,6 +698,9 @@ export const OPTIONS = {
       });
     }
   },
+  // Note that if the authMechanismProperties contain a TOKEN_RESOURCE that has a
+  // comma in it, it MUST be supplied as a MongoClient option instead of in the
+  // connection string.
   authMechanismProperties: {
     target: 'credentials',
     transform({ options, values }): MongoCredentials {