sharepoint-nodejs / pnp-auth

node-sp-auth with pnp/pnpjs (aka PnPjs) integration

pnp-auth adds additional authentication options for PnPjs library via implementing custom NodeFetchClient

!Important: as library implements NodeFetchClient and depends on node-sp-auth module, you can use pnp-auth only in nodejs environment

pnp-auth uses node-sp-auth as authentication library, thus making all authentication options from node-sp-auth available for pnp-auth.

Supported versions:

• SharePoint 2013 and onwards
• SharePoint Online

For full list of authentication options check out node-sp-auth readme.

How to use

Install

Note on PnPjs v1 usage

If you need support for the previous version of PnPjs, simply install the version of pnp-auth, which supports PnPjs v1:

npm install [email protected]

Install @pnp/sp libraries (they are listed as peer dependencies for pnp-auth, that's why you should install them separately). We need more than just @pnp/sp because it depends on some other @pnp/ packages:

npm install @pnp/logging @pnp/common @pnp/odata @pnp/sp --save

Install pnp-auth

npm install pnp-auth --save

Bootstrap

Before using PnPjs library, you should make it aware of your authentication data. That should be performed at the start of your application. The code is fairly simple:

import { bootstrap } from 'pnp-auth';
import { sp } from '@pnp/sp-commonjs';

bootstrap(sp, authData, siteUrl);
// That's it! Now you can use pnp-sp library:

sp.web.get().then(...);

OR with factory methods:

import { bootstrap } from 'pnp-auth';
import { sp, Web } from '@pnp/sp-commonjs';

bootstrap(sp, authData); 
// That's it! Now you can use pnp-sp library:

let web = Web(siteUrl);
web.get().then(...)

API:

bootstrap(sp, authData, siteUrl)

• sp - "sp" object obtained from @pnp/sp-commonjs library via import: import { sp } from '@pnp/sp-commonjs';
• authData - can be a string, AuthConfig object or raw node-sp-auth credentials:
  • string - absolute or relative path to your file with authentication data. File should be generated using node-sp-auth-config CLI. When string is provided, pnp-auth internally creates AuthConfig with below default parameters:

  let authConfig = new AuthConfig({
    configPath: <your path to file>,
    encryptPassword: true,
    saveConfigOnDisk: true
  });

  • AuthConfig - you can provide AuthConfig directly. To learn more checkout node-sp-auth-config repository
  • raw credentials - you can pass any credential options which are supported by node-sp-auth. For more information checkout node-sp-auth repository as well as wiki
• siteUrl - your SharePoint site url. You have two options when working with SharePoint data. When using siteUrl parameter, you can write a code sp.web.get() etc., in that case your sp.web object will be attached to your siteUrl. If you want to work with different webs, you can use factory method: Web(<url to SharePoint>)

Manual bootstrap

Of course, you can do bootstrap manually, if you want. pnp-auth exports NodeFetchClient which you can use in pnp's setup method:

import NodeFetchClient from 'pnp-auth';
import { sp } from '@pnp/sp-commonjs';

sp.setup({
  sp: {
    fetchClientFactory: () => {
      return new NodeFetchClient(authData, siteUrl);
    }
  }
});

Development

1. npm install
2. npm run build - tslint & TS compile

Testing

Library has a few integration tests:

1. npm install
2. Rename settings.sample.ts to settings.ts. Update webTitle and subsiteUrl to your real data.
3. Use node-sp-auth-config to generate credentials inside ./config/private.json file. Site url in credentials should point to site with webTitle from step #2.
4. Run npm test