s-KaiNet / node-sp-auth

Unattended SharePoint http authentication with nodejs
MIT License
137 stars 57 forks source link
authentication javascript node node-sp nodejs saml sharepoint typescript

node-sp-auth - nodejs to SharePoint unattended http authentication

NPM npm version


[!CAUTION]

I don't use this module for many years and don't have time to actively maintain it. Thus no new versions are expected and no new features. Only your PR requests, if they are valid.

Also, with Azure ACS and SharePoint Add-in model retirement some authentication methods for SharePoint Online will stop working after April, 2026.

I strongly recommend to use msal-node for authentication purposes.

node-sp-auth allows you to perform SharePoint unattended (without user interaction) http authentication with nodejs using different authentication techniques. node-sp-auth also takes care about caching authentication data for performance (no need for you to think about how long authentication will be available, that's a task for node-sp-auth, as soon as authentication will be expired, node-sp-auth will renew it internally).

Versions supported:

Authentication options:

Wiki contains detailed steps you need to perform in order to use any of authentication options as well as sample using.


How to use

Install

npm install node-sp-auth --save-dev

Create authentication headers and perform http request

import * as spauth from 'node-sp-auth';
import * as request from 'request-promise';

//get auth options
spauth.getAuth(url, credentialOptions)
  .then(options => {

    //perform request with any http-enabled library (request-promise in a sample below):
    let headers = options.headers;
    headers['Accept'] = 'application/json;odata=verbose';

    request.get({
      url: 'https://[your tenant].sharepoint.com/sites/dev/_api/web',
      headers: headers
    }).then(response => {
      //process data
    });
  });

API

getAuth(url, credentialOptions)

return value

Promise resolving into object with following properties:

params

Possible values for credentialOptions (depending on authentication strategy):

Please, use Wiki to see how you can configure your environment in order to use any of this authentication options.

setup(configuration)

params

Development

I recommend using VS Code for development. Repository already contains some settings for VS Code editor.

Before creating Pull Request you need to create an appropriate issue and reference it from PR.

  1. git clone https://github.com/s-KaiNet/node-sp-auth.git
  2. npm run build - runs linting and typescript compilation
  3. npm run dev - setup watchers and automatically runs typescript compilation, tslint and tests when you save files

Integration testing

  1. Rename file /test/integration/config.sample.ts to config.ts.
  2. Update information in config.ts with appropriate values (urls, credentials).
  3. Run npm run test:integration.
  4. For tests debugging put a breakpoint and press F5 (works in VSCode only).