mongodb/node-mongodb-native · error · MongoAzureError

TOKEN_RESOURCE must be set in the auth mechanism properties

Error message

TOKEN_RESOURCE must be set in the auth mechanism properties when ENVIRONMENT is azure.

What it means

Thrown by the Azure machine OIDC workflow when ENVIRONMENT is set to 'azure' but the TOKEN_RESOURCE mechanism property is missing (src/cmap/auth/mongodb_oidc/azure_machine_workflow.ts:27). TOKEN_RESOURCE becomes the token audience passed to the Azure IMDS endpoint and is required to request a token scoped for the MongoDB cluster. Surfaced as a MongoAzureError.

Source

Thrown at src/cmap/auth/mongodb_oidc/azure_machine_workflow.ts:28

const ENDPOINT_RESULT_ERROR =
  'Azure endpoint did not return a value with only access_token and expires_in properties';

/** Error for when the token audience is missing in the environment. */
const TOKEN_RESOURCE_MISSING_ERROR =
  'TOKEN_RESOURCE must be set in the auth mechanism properties when ENVIRONMENT is azure.';

/**
 * The callback function to be used in the automated callback workflow.
 * @param params - The OIDC callback parameters.
 * @returns The OIDC response.
 */
export const azureCallback: OIDCCallbackFunction = async (
  params: OIDCCallbackParams
): Promise<OIDCResponse> => {
  const tokenAudience = params.tokenAudience;
  const username = params.username;
  if (!tokenAudience) {
    throw new MongoAzureError(TOKEN_RESOURCE_MISSING_ERROR);
  }
  const response = await getAzureTokenData(tokenAudience, username);
  if (!isEndpointResultValid(response)) {
    throw new MongoAzureError(ENDPOINT_RESULT_ERROR);
  }
  return response;
};

/**
 * Hit the Azure endpoint to get the token data.
 */
async function getAzureTokenData(tokenAudience: string, username?: string): Promise<OIDCResponse> {
  const url = new URL(AZURE_BASE_URL);
  addAzureParams(url, tokenAudience, username);
  const response = await get(url, {
    headers: AZURE_HEADERS
  });
  if (response.status !== 200) {

View on GitHub (pinned to 3366c21a63)

Solutions

1. Add TOKEN_RESOURCE to authMechanismProperties, e.g. ENVIRONMENT:azure,TOKEN_RESOURCE:<mongodb-cluster-audience>.
2. Confirm the TOKEN_RESOURCE value matches the audience configured on the MongoDB server for OIDC.
3. Use the exact property names and casing shown in the driver documentation; separate multiple properties with commas.

Example fix

// before
const c = new MongoClient('mongodb://host/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:azure');

// after
const c = new MongoClient(
  'mongodb://host/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:azure,TOKEN_RESOURCE:https://cluster.example.com'
);

function validateAzureOidcProps(props: Record<string, unknown>): void {
  if (props.ENVIRONMENT === 'azure' && !props.TOKEN_RESOURCE) {
    throw new Error('TOKEN_RESOURCE is required when ENVIRONMENT=azure');
  }
}
validateAzureOidcProps(parsedMechanismProperties);

function isAzureOidcConfig(props: unknown): props is { ENVIRONMENT: 'azure'; TOKEN_RESOURCE: string } {
  return !!props && typeof props === 'object'
    && (props as any).ENVIRONMENT === 'azure'
    && typeof (props as any).TOKEN_RESOURCE === 'string';
}

When it happens

Trigger: Connecting with MONGODB-OIDC and authMechanismProperties=ENVIRONMENT:azure but omitting TOKEN_RESOURCE, or misspelling the property name. The azureCallback checks params.tokenAudience (derived from TOKEN_RESOURCE) and throws before contacting Azure IMDS.

Common situations: Copy-paste error from docs that omitted TOKEN_RESOURCE, assumption that Azure IMDS does not require an audience, or using the wrong property casing (Token-Resource, token_resource) in the connection string.

Related errors

• TOKEN_RESOURCE must be set in the auth mechanism properties
• User provided OIDC callbacks must return a valid object with
• TOKEN_RESOURCE must be set in the auth mechanism properties
• No workflow provided to the OIDC auth provider.
• AuthContext must provide credentials.

AI-assisted analysis of mongodb/node-mongodb-native@3366c21a63 (2026-08-04). Data as JSON: /data/errors/700ec1ee2269d8ac.json. Report an issue: GitHub.