@beyond-sharepoint/ntlm-remote-auth

Provides a ntlm remote authentication implementation against SharePoint on-prem.

To use, simply import the module and supply the tenant url and credentials.

const sp = require("@beyond-sharepoint/ntlm-remote-auth");

sp.authenticate("http://mysharepointfarm", "myworkstation", "mydomain", "myusername", "mypassword")
    .then(function(ctx) {
        console.log("Success!!");
    }, function() {
        console.log("something went wrong.");
    });

The object that is returned when authentication succeeds contains the following properties:

contextInfo

Object that contains the context info returned by mysharepointfarm/_api/contextinfo

ensureContextInfo

Helper function that renews the context info if it has expired.

request

A request instance with the defaults set to what needs to be passed to SP.

Use this to make further authenticated calls with your SharePoint farm.

For instance, to upload a file to a document library:

const sp = require("@beyond-sharepoint/ntlm-remote-auth");
const URI = require("urijs");

sp.authenticate("http://mysharepointfarm", "myworkstation", "mydomain", "myusername", "mypassword")
    .then(function(ctx) {
        //upload a file to 'documents' library.

        let docLibUrl = "documents";
        let fileName = "test1234.txt";

        ctx.request({
            method: "POST",
            url: URI.joinPaths("/_api/web/", `GetFolderByServerRelativeUrl('${URI.encode(docLibUrl)}')/`, "files/", `add(url='${URI.encode(fileName)}',overwrite=true)`).href(),
            body: "Hello, world!"
        });
    });

Other packages on Beyond SharePoint provide concerted functionality.

Unit Testing

ntlm-remote-auth uses mocha/chai based unit tests to ensure quality.

By default, the unit tests use mock service responses via nock.

just run npm test at the cli to run the tests:

$ npm test

    ✓ should contain an authenticate method
    ✓ should fail with invalid user
    ✓ should fail with invalid password
    ✓ should authenticate and contain a context info that expires in the future.

Unit Test Options

--live

To test against your SharePoint farm instead of the mocks, use the --live option.

ex:

$ npm test -- --live https://mysharepointfarm

    ✓ should contain an authenticate method
    ✓ should fail with invalid user
    ✓ should fail with invalid password
    ✓ should authenticate and contain a context info that expires in the future.

--settings

You'll quickly find that you'll need to supply your own credentials and tenant name in order to test live, to do so, you can modify the values in /test/fixtures/settings-test.json.

However, a better way is to use the --settings option to specify the name of a settings file that you provide. Note that this file is relative to the /test/fixtures folder.

$ npm test -- --settings settings-prod.json --live

settings-prod.json is included in .gitignore by default.

--record

To aid in debugging, the --record option records all interaction with SP and places it in /test/tmp/nock-test.json. It is expected that the live option is specified.

$ npm test --  --record --live

--recordOutput

To override the default record file name, use --recordOutput

$ npm test --  --record --live --recordOutput nock-ensureContext.json

Note to self:

When updating the recorded nock fixtures:

1. Update the scope url to be http://mysharepointfarm:80
2. Update all urls to {{{valid.url}}} including absoute paths in response bodies
3. Remove all expires/last-modified/date headers
4. Change X-RequestDigest responses to be "0x12345,{{{currentDate}}}"
5. Change response bodies to "*"

this is scripted out in bootstrap.js after(...)