> For the complete documentation index, see [llms.txt](https://node.spflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://node.spflow.com/packages/node-sp-auth-config.md).

# node-sp-auth-config

![NPM](https://camo.githubusercontent.com/53a2713b1880bc804da27bb4452701de6695defe/68747470733a2f2f6e6f6465692e636f2f6e706d2f6e6f64652d73702d617574682d636f6e6669672e706e673f6d696e693d7472756526646f776e6c6f6164733d7472756526646f776e6c6f616452616e6b3d747275652673746172733d74727565)

[![npm version](https://camo.githubusercontent.com/8d9337db24e2755423f755ba6c26e2d05c84ebf0/68747470733a2f2f62616467652e667572792e696f2f6a732f6e6f64652d73702d617574682d636f6e6669672e737667)](https://badge.fury.io/js/node-sp-auth-config) [![Downloads](https://camo.githubusercontent.com/f28fe971c6f3744976bb5ebd9d5cf32e554055aa/68747470733a2f2f696d672e736869656c64732e696f2f6e706d2f646d2f6e6f64652d73702d617574682d636f6e6669672e737667)](https://www.npmjs.com/package/node-sp-auth-config) [![Actions Status](https://github.com/koltyakov/node-sp-auth-config/workflows/Node%20CI/badge.svg)](https://github.com/koltyakov/node-sp-auth-config/actions) [![FOSSA Status](https://camo.githubusercontent.com/51c15142111765a8add3e63e51566c0ff6c418bd/68747470733a2f2f6170702e666f7373612e696f2f6170692f70726f6a656374732f6769742532426769746875622e636f6d2532466b6f6c7479616b6f762532466e6f64652d73702d617574682d636f6e6669672e7376673f747970653d736869656c64)](https://app.fossa.io/projects/git%2Bgithub.com%2Fkoltyakov%2Fnode-sp-auth-config?ref=badge_shield) [![Gitter chat](https://camo.githubusercontent.com/20d7543bc8280bf8134b686c46c7b7e2c0a467fd/68747470733a2f2f6261646765732e6769747465722e696d2f67697474657248512f6769747465722e706e67)](https://gitter.im/sharepoint-node/Lobby)

`node-sp-auth-config` provides wizard-like approach for building and managing config files for [node-sp-auth](https://github.com/s-KaiNet/node-sp-auth) (Node.js to SharePoint unattended http authentication). Includes CLI for generating config files from command prompt.

**Versions supported**:

* SharePoint Online
* SharePoint On-Prem (2019, 2016, 2013)
* SharePoint On-Prem 2010

**Authentication options**:

* SharePoint Online:
  * User credentials (SAML/ADFS)
  * Add-In Only permissions
  * On-Demand authentication (using Electron popup)
* SharePoint 2019, 2016, 2013:
  * User credentials (NTLM, NTLM v2)
  * ADFS user credentials
  * Form-based authentication (FBA)
  * Form-based authentication (Forefront TMG)
  * Add-In Only permissions
  * On-Demand authentication (using Electron popup)
* SharePoint 2010:
  * User credentials (NTLM, NTMLv2)
  * Form-based authentication (FBA)
  * Form-based authentication (Forefront TMG)

Config layer and auth supports Office 365 Dedicated (SPO on custom domain) as well.

### How to use

#### Install

```
npm install node-sp-auth-config
```

or install globally to use as CLI:

```
npm install node-sp-auth-config -g
```

#### Usage as CLI

```
sp-auth init --path ./config/private.config.json
sp-auth --help # for help about parameters
```

#### Usage in TypeScript

```typescript
import { AuthConfig } from 'node-sp-auth-config';

const authConfig = new AuthConfig({
  configPath: './config/private.json',
  encryptPassword: true,
  saveConfigOnDisk: true
});

authConfig.getContext()
  .then((context) => {
    console.log(JSON.stringify(context, null, 2));
    // context.authOptions - node-sp-auth authentication options
  })
  .catch(console.warn);
```

#### Usage in JavaScript

```typescript
const AuthConfig = require('node-sp-auth-config').AuthConfig;

const authConfig = new AuthConfig({
  configPath: './config/private.json',
  encryptPassword: true,
  saveConfigOnDisk: true
});

authConfig.getContext()
  .then((context) => {
    console.log(JSON.stringify(context, null, 2));
    // context.authOptions - node-sp-auth authentication options
  })
  .catch(console.warn);
```

**Initiation parameters**

| Parameter         | Default value             | Description                                                          |
| ----------------- | ------------------------- | -------------------------------------------------------------------- |
| configPath        | '`./config/private.json`' | Path to auth config `.json`                                          |
| encryptPassword   | `true`                    | Encrypt password to a machine-bind hash                              |
| saveConfigOnDisk  | `true`                    | Save config `.json` to disk                                          |
| forcePrompts      | `false`                   | Force parameters prompts                                             |
| headlessMode      | `false`                   | Prevents interactive prompts - for headless, CI/CD processes         |
| defaultConfigPath | empty                     | Path to `.json` config, parameters from which are placed as defaults |
| authOptions       | empty                     | Any valid `node-sp-auth` options                                     |

#### Production runtime

**Headless mode**

When using in a headless mode, in case of missing parameters, one can expect non-interactive behavior with no prompts but graceful exit with corresponding error output.

This can be achieved by providing `headlessMode` settings property is equal to `true`.

The headless mode also automatically configured when `NODE_ENV` (or `SPAUTH_ENV`) environment variable is equal to `production`.

**Environment variables**

All the parameters which are usually stored in `private.json` can be defined also using environment variables. Environment variables started with `SPAUTH_` prefix are recognized with the library. Second part of the name is an actual name of the `node-sp-auth` credentials property yet in uppercase (e.g. `SPAUTH_SITEURL`, `SPAUTH_USERNAME`, `SPAUTH_PASSWORD`).

Along with credentials props these service variables are used:

| Variable       | Description                                                                                          |
| -------------- | ---------------------------------------------------------------------------------------------------- |
| `NODE_ENV`     | When equal to `production` forces `headlessMode`.                                                    |
| `SPAUTH_ENV`   | When equal to `production` forces `headlessMode`. Overwrites `NODE_ENV`.                             |
| `SPAUTH_FORCE` | Makes `SPAUTH_{CREDENTIALS}` variables take precedence over those possibly stored in `private.json`. |

### Configuring CI/CD

Checkout [this end-to-end sample](https://github.com/koltyakov/sppp-cicd-sample).

### License

[![FOSSA Status](https://camo.githubusercontent.com/36a65ec89e5559545f5ccc355df96e3ff3433d5c/68747470733a2f2f6170702e666f7373612e696f2f6170692f70726f6a656374732f6769742532426769746875622e636f6d2532466b6f6c7479616b6f762532466e6f64652d73702d617574682d636f6e6669672e7376673f747970653d6c61726765)](https://app.fossa.io/projects/git%2Bgithub.com%2Fkoltyakov%2Fnode-sp-auth-config?ref=badge_large)