SharePoint Unattended HTTP Authentication

3.0.9 verified Thu Apr 23 auth: no javascript deprecated

node-sp-auth is a JavaScript/TypeScript library designed for performing unattended (non-interactive) HTTP authentication against SharePoint environments, supporting SharePoint 2013 and newer, as well as SharePoint Online. It automatically determines the appropriate authentication strategy (e.g., NTLM, FBA, SAML, ADFS, Add-in only) based on provided credentials and handles credential caching for performance. The current stable version is 3.0.9. However, the package is no longer actively maintained, with no new features or versions expected. Developers are strongly advised to migrate to `@azure/msal-node` for modern SharePoint Online authentication, especially as some authentication methods, particularly those relying on the SharePoint Add-in model, will cease to function after April 2026 due to Microsoft's retirement of Azure ACS and the Add-in model.

Common errors

error Access denied. You do not have permission to perform this action or access this resource. ↓

cause Attempting to use SharePoint Add-in based authentication methods after April 2026, which are deprecated and will be retired by Microsoft.

fix

Update your authentication strategy to use modern flows supported by @azure/msal-node, such as client credentials or device code flow, for SharePoint Online.

error Error: NTLM authentication failed: unable to negotiate ↓

cause For SharePoint on-premise NTLM, the custom HTTP `agent` provided by `node-sp-auth` was not correctly passed to the HTTP client making the request.

fix

When using request-promise or similar, ensure the agent property from authResult.options.agent is included in your request configuration object.

error Could not authenticate to SharePoint. Invalid credentials provided. ↓

cause Incorrect or malformed `credentialOptions` object provided to `spauth.getAuth()`, or the credentials themselves are invalid.

fix

Carefully review the credentialOptions object structure and values against the node-sp-auth Wiki for the specific authentication strategy (e.g., SAML, FBA, NTLM) you are attempting to use. Verify usernames, passwords, client IDs, and secrets.

Warnings

deprecated The `node-sp-auth` package is no longer actively maintained by its author. No new features or versions are expected. Development is primarily limited to community-contributed PRs. ↓

fix Developers are strongly encouraged to migrate to modern, actively maintained alternatives like `@azure/msal-node` for SharePoint Online authentication or evaluate other solutions for on-premises SharePoint.

breaking Some authentication methods, particularly those relying on the SharePoint Add-in model and Azure ACS, will cease to function after April 2026 due to Microsoft's retirement of these services. This will directly impact `node-sp-auth` users relying on these specific flows. ↓

fix Review your authentication strategy immediately. Migrate to modern SharePoint Online authentication flows (e.g., client credentials, device code flow) using `@azure/msal-node` or other Microsoft-recommended libraries. Consult official SharePoint documentation for updated guidance.

gotcha For SharePoint on-premise NTLM authentication, the `getAuth` method might return an `agent` property within the `options` object (i.e., `authResult.options.agent`). This custom HTTP agent *must* be passed to the underlying HTTP client for successful authentication; otherwise, requests will fail. ↓

fix Ensure your HTTP client (e.g., `request-promise`, `axios`) is configured to use the `agent` property provided by `node-sp-auth` for all requests requiring NTLM. For `request-promise`, this is done via the `agent` option in the request configuration.

Install

npm install node-sp-auth

yarn add node-sp-auth

pnpm add node-sp-auth

Imports

spauth
wrong
```
import spauth from 'node-sp-auth';
```
correct
```
import * as spauth from 'node-sp-auth';
```
The library primarily exports a namespace object containing the `getAuth` method.
getAuth
wrong
```
import { getAuth } from 'node-sp-auth';
```
correct
```
import * as spauth from 'node-sp-auth';
const authOptions = await spauth.getAuth(url, credentials);
```
While `getAuth` is the primary function, it's typically accessed as a member of the `spauth` namespace object, not as a direct named export.
spauth (CommonJS)
wrong
```
const { getAuth } = require('node-sp-auth');
```
correct
```
const spauth = require('node-sp-auth');
```
For CommonJS, the entire module is imported as an object containing `getAuth`.

Quickstart

This example demonstrates how to use `node-sp-auth` to obtain authentication headers for a SharePoint site and then use them with `request-promise` to fetch data from the SharePoint REST API.

import * as spauth from 'node-sp-auth';
import * as request from 'request-promise'; // Ensure request-promise is installed

async function authenticateAndFetch() {
  const url = process.env.SP_SITE_URL ?? 'https://yourtenant.sharepoint.com/sites/dev';
  const username = process.env.SP_USERNAME ?? '';
  const password = process.env.SP_PASSWORD ?? '';

  if (!username || !password) {
    console.warn("SP_USERNAME or SP_PASSWORD environment variables are not set. This example might fail without proper credentials.");
  }

  const credentialOptions = {
    username: username,
    password: password
    // Add other credential options (e.g., tenant ID, client ID, client secret) as needed
    // for specific authentication types like SAML or ADFS.
  };

  try {
    const authResult = await spauth.getAuth(url, credentialOptions);

    const headers = authResult.headers;
    headers['Accept'] = 'application/json;odata=verbose';

    console.log('Authentication successful. Making request...');

    const response = await request.get({
      url: `${url}/_api/web`,
      headers: headers,
      // IMPORTANT: For NTLM authentication, pass the 'agent' property if it exists
      agent: authResult.options?.agent
    });

    console.log('Successfully fetched web data:');
    console.log(JSON.parse(response));

  } catch (error) {
    console.error('Authentication or request failed:', error);
  }
}

authenticateAndFetch();