{"id":13666,"library":"node-sp-auth-config","title":"SharePoint Authentication Configuration Builder","description":"node-sp-auth-config is a utility package designed to simplify the creation and management of authentication configuration files for the node-sp-auth library, which handles unattended HTTP authentication to SharePoint from Node.js applications. It provides a wizard-like interactive CLI experience (`sp-auth`) and a programmatic API for building authentication options. The library supports a wide range of SharePoint versions, including SharePoint Online, 2019, 2016, 2013, and 2010, along with various authentication methods such as user credentials (SAML/ADFS, NTLM), Add-In Only permissions, and Form-Based Authentication. By default, it encrypts sensitive data like passwords using a machine-bound hash. The current stable version is 3.0.5 and it regularly releases updates in conjunction with its core dependency, node-sp-auth. Its primary differentiator is streamlining the often complex setup of SharePoint authentication credentials into a guided, persistent configuration process.","status":"active","version":"3.0.5","language":"javascript","source_language":"en","source_url":"https://github.com/koltyakov/node-sp-auth-config","tags":["javascript","sharepoint","config","authentication","node-sp-auth","wizard","typescript"],"install":[{"cmd":"npm install node-sp-auth-config","lang":"bash","label":"npm"},{"cmd":"yarn add node-sp-auth-config","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-sp-auth-config","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core library for which node-sp-auth-config generates authentication configurations.","package":"node-sp-auth","optional":false}],"imports":[{"note":"AuthConfig is a named export for ESM and TypeScript environments. Attempting a default import will result in an undefined value.","wrong":"import AuthConfig from 'node-sp-auth-config';","symbol":"AuthConfig","correct":"import { AuthConfig } from 'node-sp-auth-config';"},{"note":"For CommonJS modules, AuthConfig must be destructured from the module export, as it's a named export, not the default.","wrong":"const AuthConfig = require('node-sp-auth-config');","symbol":"AuthConfig","correct":"const { AuthConfig } = require('node-sp-auth-config');"},{"note":"The CLI tool `sp-auth` is executable directly via `npx` (if locally installed) or globally if installed with `npm install -g node-sp-auth-config`.","wrong":"node sp-auth init","symbol":"sp-auth CLI","correct":"npx sp-auth init --path ./config/my.json"}],"quickstart":{"code":"import { AuthConfig } from 'node-sp-auth-config';\nimport * as path from 'path';\nimport * as fs from 'fs';\n\n// This quickstart demonstrates how to programmatically use node-sp-auth-config\n// to generate authentication options in a non-interactive, headless mode.\n// In a real scenario, the environment variables would hold your actual credentials.\n// The generated configuration can then be passed to the 'node-sp-auth' library.\n\nasync function demonstrateAuthConfig() {\n  const configFileName = 'demonstration.config.json';\n  const configFilePath = path.join(__dirname, configFileName);\n\n  console.log(`Attempting to get SharePoint auth context in headless mode.`);\n  console.log(`Config will be saved (or updated) at: ${configFilePath}`);\n\n  try {\n    const authConfig = new AuthConfig({\n      configPath: configFilePath,\n      encryptPassword: true,\n      saveConfigOnDisk: true,\n      headlessMode: true, // Prevents interactive prompts, crucial for CI/CD or automated scripts\n      authOptions: { // Provide example authOptions for headless mode\n        siteUrl: process.env.SP_SITE_URL ?? 'https://yourtenant.sharepoint.com/sites/dev',\n        strategy: 'UserCredentials',\n        username: process.env.SP_USERNAME ?? 'your.user@yourtenant.onmicrosoft.com',\n        password: process.env.SP_PASSWORD ?? 'YourVerySecretPassword123!',\n      }\n    });\n\n    const context = await authConfig.getContext();\n    console.log('\\n--- Configuration Context Retrieved ---');\n    console.log(JSON.stringify(context, null, 2));\n    console.log('\\nThese are the authentication options to pass to node-sp-auth:');\n    console.log(JSON.stringify(context.authOptions, null, 2));\n\n    if (fs.existsSync(configFilePath)) {\n      console.log(`\\nConfig file was saved/updated at: ${configFilePath}`);\n      // For a clean demonstration, you might remove the file afterward:\n      // fs.unlinkSync(configFilePath);\n      // console.log(`Cleaned up temporary config file: ${configFilePath}`);\n    } else {\n      console('\\nNo new config file was explicitly saved as it was run in headlessMode with provided authOptions.');\n    }\n\n  } catch (error) {\n    console.error('Error in authentication configuration process:', error instanceof Error ? error.message : error);\n  }\n}\n\ndemonstrateAuthConfig();\n","lang":"typescript","description":"Demonstrates how to programmatically initialize `node-sp-auth-config` to retrieve SharePoint authentication options. It shows a non-interactive setup using pre-defined credentials, suitable for CI/CD environments, and how the resulting `authOptions` can be used with `node-sp-auth`."},"warnings":[{"fix":"Thoroughly evaluate the security implications of using `node-sp-auth` for your specific use case. Consider alternative, actively maintained SharePoint authentication solutions if continuous security patches are critical. Monitor the `node-sp-auth` GitHub repository for any future updates or community-led forks.","message":"The underlying `node-sp-auth` package, which `node-sp-auth-config` is designed to configure, has been flagged as 'Inactive' and 'Security review needed' by Snyk. This indicates a lack of recent maintenance and potential unaddressed security vulnerabilities in the core authentication mechanism.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"For cross-environment deployments (e.g., CI/CD), avoid relying on disk-saved encrypted passwords. Instead, provide authentication parameters programmatically via the `authOptions` constructor parameter, or use environment variables (e.g., `SPAUTH_SITEURL`, `SPAUTH_USERNAME`, `SPAUTH_PASSWORD`).","message":"Configuration files generated by `node-sp-auth-config` with encrypted passwords use a machine-bound hash. This means these configuration files are not portable and cannot be directly transferred and used on a different machine or environment.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"In headless environments, ensure all necessary `authOptions` are passed directly in the `AuthConfig` constructor, or that `configPath` points to a pre-existing, fully configured JSON file. Alternatively, ensure the relevant `SPAUTH_` environment variables are set.","message":"When `headlessMode: true` is enabled, the library will not prompt for missing configuration parameters. If `authOptions` are not explicitly provided and no valid configuration file exists at `configPath`, the process will terminate gracefully with an error.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'2010':78 '2013':76 '2016':75 '2019':74 '3.0.5':119 'add':91 'add-in':90 'along':79 'api':57 'applic':41 'auth':8,30,53,134,161 'authent':2,22,36,60,82,99,146,157 'base':98 'bound':112 'build':59 'builder':4 'cli':49 'complex':142 'config':9,156 'configur':3,23,152 'conjunct':126 'core':129 'creation':18 'credenti':87,147 'current':115 'data':105 'default':101 'depend':130 'design':14 'differenti':137 'encrypt':103 'experi':50 'file':24 'form':97 'form-bas':96 'guid':150 'handl':33 'hash':113 'http':35 'includ':71 'interact':48 'javascript':154 'librari':31,63 'like':47,106 'machin':111 'machine-bound':110 'manag':20 'method':83 'node':6,28,132,159 'node-sp-auth':27,131,158 'node-sp-auth-config':5 'node.js':40 'ntlm':89 'often':141 'onlin':73 'option':61 'packag':13 'password':107 'permiss':94 'persist':151 'primari':136 'process':153 'programmat':56 'provid':43 'rang':67 'regular':122 'releas':123 'saml/adfs':88 'sensit':104 'setup':143 'sharepoint':1,38,69,72,145,155 'simplifi':16 'sp':7,29,52,133,160 'sp-auth':51 'stabl':116 'streamlin':139 'support':64 'typescript':163 'unattend':34 'updat':124 'use':108 'user':86 'util':12 'various':81 'version':70,117 'wide':66 'wizard':46,162 'wizard-lik':45","created_at":"2026-04-20T01:55:40.827556+00:00","updated_at":"2026-04-20T01:55:40.827556+00:00","problems":[{"fix":"Provide all required `authOptions` in the `AuthConfig` constructor or ensure `configPath` points to a valid and complete configuration file. Set `headlessMode: false` to enable interactive prompts during development.","cause":"This typically occurs when `AuthConfig.getContext()` is called in `headlessMode` without a pre-existing config file or programmatic `authOptions`.","error":"Error: No auth options were provided and no existing config file found."},{"fix":"Try using a different Node.js LTS version (e.g., Node.js 16 or 18 if on newer, or Node.js 20+ if on older). For Node.js versions 17 and higher, you might need to run your script with `NODE_OPTIONS=--openssl-legacy-provider node your-script.js` to enable legacy OpenSSL support.","cause":"This Node.js error usually indicates an incompatibility between the Node.js version and underlying OpenSSL functionality used by `node-sp-auth` or its dependencies.","error":"Error: digital envelope routines::unsupported"},{"error":"The token audience is NOT valid."},{"error":"SharePoint online authentication failed"},{"fix":"Carefully review all authentication parameters, including `siteUrl`, `tenantId`, `clientId`, `clientSecret`, `username`, and `password`. Verify that the SharePoint Add-In or Azure AD application has the correct permissions and is properly registered and trusted within your SharePoint tenant. For ADFS, confirm the federation service configuration. Check `node-sp-auth`'s issue tracker for similar problems.","cause":"These errors, originating from the underlying `node-sp-auth` library, often point to incorrect SharePoint Online tenant settings, misconfigured Azure AD app registrations (for Add-In Only permissions), or invalid user credentials (username/password, ADFS)."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"sp-auth","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/koltyakov/node-sp-auth-config","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/node-sp-auth-config","openapi_spec":null,"status_page":null,"smithery":null,"categories":["auth-security","http-networking","crm-productivity"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}