# 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)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://node.spflow.com/packages/node-sp-auth-config.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.