Dataverse On-Behalf-Of Authentication

1.0.9 · maintenance · verified Wed Apr 22

The `dataverse-auth` package provides on-behalf-of (OBO) authentication capabilities against Microsoft Dataverse environments, specifically designed for NodeJS applications. It facilitates the process of obtaining and securely storing access tokens locally, which can then be utilized by other applications, such as code generation tools (`dataverse-gen`) or API clients (`dataverse-ify`). The library primarily leverages OAuth 2.0 for its authentication flows, handling interactive logins. The current stable version on npm is 1.0.9. Despite this version being last published over five years ago, the author maintains related Dataverse ecosystem packages, suggesting a maintenance status for `1.x` while newer approaches or specific platform requirements (like for Apple Silicon, which mentions `dataverse-auth@2`) may exist outside of the npm `1.x` release line. Its key differentiator is simplifying the token management for Dataverse within Node.js applications, abstracting away some complexities of Microsoft Entra ID (formerly Azure AD) authentication flows.

Common errors

Warnings

Install

Imports

Quickstart

Demonstrates how to programmatically authenticate with Dataverse and retrieve an access token using the `dataverse-auth` library, handling various authentication types.

import auth from 'dataverse-auth';
import { TokenResponse } from '@azure/msal-node';

const DATAVERSE_URL = process.env.DATAVERSE_URL ?? 'https://yourorg.crm.dynamics.com';
const TENANT_ID = process.env.TENANT_ID;
const CLIENT_ID = process.env.CLIENT_ID;
const CLIENT_SECRET = process.env.CLIENT_SECRET; // Required for confidential client flows

async function authenticateAndGetToken(): Promise<TokenResponse | undefined> {
  try {
    console.log(`Attempting to authenticate against Dataverse: ${DATAVERSE_URL}`);

    // This function can trigger an interactive browser login if needed,
    // or use cached credentials if available.
    // For automation, consider 'AuthType.ClientSecret' with CLIENT_ID/CLIENT_SECRET
    // or 'AuthType.DeviceCode' with a callback for user interaction.
    const tokenResponse = await auth(
      DATAVERSE_URL,
      TENANT_ID, // Optional: specify tenant ID
      CLIENT_SECRET ? 'ClientSecret' : undefined, // Example: use ClientSecret if provided
      CLIENT_ID,
      CLIENT_SECRET,
      // For 'DeviceCode' flow, you might provide a callback:
      // undefined, undefined, (deviceCode) => {
      //   console.log(`Open ${deviceCode.verificationUri} and enter code ${deviceCode.userCode}`);
      // }
    );

    if (tokenResponse) {
      console.log('Authentication successful!');
      console.log('Access Token:', tokenResponse.accessToken.substring(0, 30) + '...');
      console.log('Expires On:', new Date(tokenResponse.expiresOn! * 1000));
      return tokenResponse;
    } else {
      console.log('Authentication flow completed, but no token response was returned.');
      return undefined;
    }
  } catch (error) {
    console.error('Authentication failed:', error);
    throw error;
  }
}

authenticateAndGetToken()
  .then(token => {
    if (token) {
      console.log('\nReady to use the token for Dataverse API calls.');
      // Example: Use the token with another Dataverse client library
      // const dataverseClient = new DataverseClient(token.accessToken, DATAVERSE_URL);
    }
  })
  .catch(err => {
    console.error('An unhandled error occurred:', err);
    process.exit(1);
  });

view raw JSON →