\nCheck out our sample projects to get started with your own custom integration to Safeguard!\n
\n\n-----------\n\n## Support\n\nOne Identity open source projects are supported through [One Identity GitHub issues](https://github.com/OneIdentity/safeguard.js/issues) and the [One Identity Community](https://www.oneidentity.com/community/). This includes all scripts, plugins, SDKs, modules, code snippets or other solutions. For assistance with any One Identity GitHub project, please raise a new Issue on the [One Identity GitHub project](https://github.com/OneIdentity/safeguard.js/issues) page. You may also visit the [One Identity Community](https://www.oneidentity.com/community/) to ask questions. Requests for assistance made through official One Identity Support will be referred back to GitHub and the One Identity Community forums where those requests can benefit all users.\n\n## Introduction\n\nAll functionality in Safeguard is available via the Safeguard API. There is\nnothing that can be done in the Safeguard UI that cannot also be performed\nusing the Safeguard API programmatically.\n\nsafeguard.js is provided to facilitate calling the Safeguard API from\nJavaScript and TypeScript. It is meant to remove the complexity of dealing\nwith authentication via Safeguard's embedded secure token service (STS). The\nbasic usage is to create a `SafeguardClient` with your chosen authentication\nstrategy, call `connect()`, then call API methods using the same authenticated\nclient.\n\nsafeguard.js also provides an easy way to call Safeguard A2A from JavaScript.\nThe A2A service requires client certificate authentication for retrieving\npasswords for application integration. When Safeguard A2A is properly\nconfigured, specified passwords can be retrieved with a single method call\nwithout requiring access request workflow approvals.\n\nsafeguard.js includes an SDK for listening to Safeguard's powerful, real-time\nevent notification system. Safeguard provides role-based event notifications\nvia SignalR to subscribed clients. The `PersistentSafeguardEventListener`\nprovides automatic reconnection with token refresh for long-running listeners.\n\n### Features\n\n- **TypeScript-first** with full type declarations\n- **Dual ESM/CJS** — works with `import` and `require()`\n- **Node.js and Browser** support\n- **Multiple auth strategies** — Password, Certificate, PKCE (browser), PKCE Non-Interactive (headless), Device Code (Node + browser), Token, Anonymous\n- **A2A client** — retrieve/set passwords, SSH keys, API key secrets, broker access requests\n- **SignalR events** — one-shot and persistent event listeners with auto-reconnect\n- **Secure by default** — TLS verification enabled, no secrets in memory longer than needed\n\n## Installation\n\n```bash\nnpm install @oneidentity/safeguard\n```\n\nRequires Node.js 20 or later.\n\n## Getting Started\n\n### Password Authentication (Node.js)\n\n```typescript\nimport { SafeguardClient, PasswordAuth, Service } from '@oneidentity/safeguard';\n\nconst client = new SafeguardClient('safeguard.sample.corp', {\n auth: new PasswordAuth({\n username: 'Admin',\n password: 'Admin123',\n provider: 'Local',\n }),\n});\n\nawait client.connect();\n\nconst me = await client.get(Service.CORE, 'Me');\nconsole.log(me);\n\nawait client.disconnect();\n```\n\n### PKCE Authentication (Browser)\n\n```typescript\nimport { SafeguardClient, PkceAuth, handlePkceCallback, Service } from '@oneidentity/safeguard';\n\n// On your callback page, call this first:\nhandlePkceCallback();\n\n// On your main page:\nconst client = new SafeguardClient('safeguard.sample.corp', {\n auth: new PkceAuth({ redirectUri: window.location.href }),\n});\n\nawait client.connect(); // Redirects to Safeguard login if no stored tokens\n\nconst me = await client.get(Service.CORE, 'Me');\nconsole.log(me);\n```\n\n### PKCE Non-Interactive (Headless Automation)\n\nFor automated scenarios where no browser is available (CI/CD, scripts):\n\n```typescript\nimport { SafeguardClient, PkceNonInteractiveAuth, Service } from '@oneidentity/safeguard';\n\nconst client = new SafeguardClient('safeguard.sample.corp', {\n auth: new PkceNonInteractiveAuth({\n username: 'Admin',\n password: 'Admin123',\n provider: 'Local',\n }),\n});\n\nawait client.connect();\nconst me = await client.get(Service.CORE, 'Me');\nawait client.disconnect();\n```\n\n### Device Code Login (Node.js and Browser)\n\nFor headless and shared environments — containers, SSH sessions, CI/operator\nconsoles — where the SDK cannot open a browser. The SDK requests a device code\nand polls; the user authenticates in their own browser on any device. Your code\nowns all display I/O via the required `onDeviceCode` callback.\n\nThis strategy is platform-agnostic and works in both Node.js and the browser.\n\n**Appliance prerequisite:** the Device Code grant must be enabled in Safeguard\nsettings (`Settings -> OAuth 2.0 Grant Types`; API Settings/Allowed OAuth2 Grant\nTypes must include `DeviceCode`). If disabled, `DeviceCodeAuth` throws a\n`ConfigurationError`.\n\n```typescript\nimport { SafeguardClient, DeviceCodeAuth, Service } from '@oneidentity/safeguard';\n\nconst abort = new AbortController();\nconst client = new SafeguardClient('safeguard.sample.corp', {\n auth: new DeviceCodeAuth({\n signal: abort.signal,\n onDeviceCode: ({ verificationUriComplete, verificationUri, userCode, expiresIn, interval }) => {\n console.log(`Open: ${verificationUriComplete ?? verificationUri}`);\n console.log(`Code: ${userCode} (expires in ${expiresIn}s; poll ${interval}s)`);\n },\n }),\n});\n\nawait client.connect();\nconst me = await client.get(Service.CORE, 'Me');\nconsole.log(me);\n```\n\nIn the browser, import from `@oneidentity/safeguard/browser` and render the URL\nand code into the DOM instead of the console. Cancel with `abort.abort()`.\n\n### Client Certificate Authentication\n\n```typescript\nimport { SafeguardClient, CertificateAuth, Service } from '@oneidentity/safeguard';\n\nconst client = new SafeguardClient('safeguard.sample.corp', {\n auth: new CertificateAuth({\n certFile: '/path/to/client.pem',\n keyFile: '/path/to/client.key',\n passphrase: 'optional-key-passphrase',\n }),\n});\n\nawait client.connect();\nconst me = await client.get(Service.CORE, 'Me');\nawait client.disconnect();\n```\n\n### Anonymous Access\n\n```typescript\nimport { SafeguardClient, AnonymousAuth, Service } from '@oneidentity/safeguard';\n\nconst client = new SafeguardClient('safeguard.sample.corp', {\n auth: new AnonymousAuth(),\n});\n\nawait client.connect();\nconst status = await client.get(Service.NOTIFICATION, 'Status');\nconsole.log(status);\n```\n\n### Pre-existing API Token\n\n```typescript\nimport { SafeguardClient, TokenAuth, Service } from '@oneidentity/safeguard';\n\nconst client = new SafeguardClient('safeguard.sample.corp', {\n auth: new TokenAuth({ accessToken: 'your-token-here' }),\n});\n\nawait client.connect();\nconst me = await client.get(Service.CORE, 'Me');\n```\n\n## Calling the API\n\nThe client provides typed HTTP methods. Pass relative paths only — the SDK prepends the configured API version automatically (`v4` by default):\n\n```typescript\n// GET\nconst users = await client.get(Service.CORE, 'Users');\n\n// GET with query parameters\nconst filtered = await client.get(Service.CORE, 'Users', {\n query: { filter: \"Name eq 'Admin'\", fields: 'Id,Name' },\n});\n\n// POST (create)\nconst newUser = await client.post(Service.CORE, 'Users', {\n json: { Name: 'newuser', PrimaryAuthenticationProvider: { Id: -1 } },\n});\n\n// PUT (update)\nawait client.put(Service.CORE, `Users/${newUser.Id}/Password`, {\n json: 'NewPassword123',\n});\n\n// DELETE\nawait client.delete(Service.CORE, `Users/${newUser.Id}`);\n```\n\n### Services\n\n| Service | Description |\n|---------|-------------|\n| `Service.CORE` | Most product functionality — access requests, asset management, policy, users |\n| `Service.APPLIANCE` | Appliance-specific operations — IP address, maintenance, backups |\n| `Service.NOTIFICATION` | Anonymous/unauthenticated — status, availability |\n| `Service.A2A` | Application integration — credential retrieval, access request brokering |\n\n## A2A (Application to Application)\n\n```typescript\nimport { A2AClient, CertificateAuth, NodeHttpClient } from '@oneidentity/safeguard';\n\nconst auth = new CertificateAuth({\n certFile: 'client.pem',\n keyFile: 'client.key',\n});\nconst a2a = new A2AClient('safeguard.sample.corp', { auth });\n\n// A2A requires a client-cert HttpClient — it has no default and throws without one.\n// On SPP 9.0 this also auto-caps the connection at TLS 1.2 so certificate auth\n// works out of the box (see \"TLS 1.3 and SPP 9.0\").\na2a.setHttpClient(new NodeHttpClient(auth.getTlsOptions()));\n\n// Retrieve a password\nconst password = await a2a.retrievePassword(apiKey);\n\n// Retrieve an SSH private key\nconst sshKey = await a2a.retrievePrivateKey(apiKey);\n\n// Set a password (write-back)\nawait a2a.setPassword(apiKey, 'NewPassword123');\n\n// Discover retrievable accounts\nconst accounts = await a2a.getRetrievableAccounts();\n```\n\n## Event Listeners (SignalR)\n\nReal-time event support requires the optional `@microsoft/signalr` peer dependency:\n\n```bash\nnpm install @microsoft/signalr\n```\n\nEvent classes are imported from the `@oneidentity/safeguard/events` subpath:\n\n```typescript\nimport { SafeguardEventListener } from '@oneidentity/safeguard/events';\nimport { PasswordAuth, NodeHttpClient, MemoryStorage } from '@oneidentity/safeguard';\nimport * as signalR from '@microsoft/signalr';\n```\n\n### One-Shot Listener\n\n```typescript\n// Authenticate and build SignalR connection\nconst auth = new PasswordAuth({ username: 'Admin', password: 'Admin123', provider: 'Local' });\nconst httpClient = new NodeHttpClient();\nconst storage = new MemoryStorage();\nconst tokenSet = await auth.authenticate('safeguard.sample.corp', httpClient, storage);\n\nconst connection = new signalR.HubConnectionBuilder()\n .withUrl(`https://safeguard.sample.corp/service/event/signalr`, {\n accessTokenFactory: () => tokenSet.accessToken.expose(),\n })\n .withAutomaticReconnect()\n .build();\n\nconst listener = new SafeguardEventListener(connection);\n\nlistener.on('NotifyEventAsync', (event) => {\n console.log('Event received:', event);\n});\n\nawait listener.start();\n```\n\n### Persistent Listener (Auto-Reconnect)\n\nFor long-running processes that need to survive network interruptions and\ntoken expiration:\n\n```typescript\nimport { PersistentSafeguardEventListener } from '@oneidentity/safeguard/events';\n\nconst listener = new PersistentSafeguardEventListener(\n connection, auth, 'safeguard.sample.corp', httpClient, storage,\n);\n\nlistener.onStateChange((state) => {\n console.log('State:', state);\n});\n\nlistener.on('NotifyEventAsync', (event) => {\n console.log('Event:', event);\n});\n\nawait listener.start();\n```\n\nThe persistent listener automatically checks token lifetime and refreshes\ncredentials before they expire (with a 60-second safety margin).\n\n## Security\n\n### Token Storage (Browser)\n\nThe SDK stores access tokens **in memory only**. Tokens do not survive a page\nrefresh, which is the secure default for single-page applications without a\nbackend-for-frontend (BFF).\n\nIf your application requires persistence across page reloads, you may\nexplicitly store the token yourself — but be aware this exposes the token to\ncross-site scripting (XSS) attacks:\n\n```typescript\nawait client.connect();\n// ⚠️ Customer explicitly accepts the XSS risk:\nsessionStorage.setItem('my_token', client.accessToken.expose());\n```\n\nFor high-security environments, prefer in-memory tokens with re-authentication\non refresh, or implement a BFF pattern where tokens never reach the browser.\n\n### SecretValue\n\nCredentials and access tokens are wrapped in `SecretValue`, a class that\nredacts content from `toString()`, `toJSON()`, and `console.log()` output.\nThis prevents accidental logging of secrets.\n\nTo retrieve the raw string value (e.g., for HTTP headers or storage), call\n`.expose()`:\n\n```typescript\nconst tokenSet = await auth.authenticate(host, httpClient, storage);\nconst raw: string = tokenSet.accessToken.expose(); // explicit opt-in\n```\n\n### TLS Verification\n\nTLS certificate verification is **enabled by default** in this SDK. The\nNode-side `NodeHttpClient` constructs an `undici.Agent` with\n`rejectUnauthorized: true`, so connections to an appliance whose certificate\nchain does not validate are refused at the TLS layer.\n\n#### Production: provide a custom CA bundle\n\nThe correct way to talk to an appliance whose certificate is issued by a\nprivate / corporate CA is to provide the CA bundle to the SDK — not to\ndisable verification:\n\n```typescript\nimport { readFileSync } from 'node:fs';\nimport { SafeguardClient, NodeHttpClient, PasswordAuth } from '@oneidentity/safeguard';\n\nconst ca = readFileSync('/etc/ssl/corp-root-ca.pem');\n\nconst client = new SafeguardClient('safeguard.corp.example', {\n auth: new PasswordAuth({ /* ... */ }),\n});\nclient.setHttpClient(new NodeHttpClient({ ca, rejectUnauthorized: true }));\nawait client.connect();\n```\n\n`NodeHttpClient` accepts a PEM string or `Buffer` (single cert or\nconcatenated bundle). Verification stays on; only the trust anchor changes.\n\n#### Development / lab appliances (self-signed)\n\nFor local appliances with self-signed certificates the supported opt-out is\nthe per-instance `rejectUnauthorized: false` flag on the HTTP client:\n\n```typescript\n// Development only — never use in production\nclient.setHttpClient(new NodeHttpClient({ rejectUnauthorized: false }));\n```\n\nThis affects only this `SafeguardClient` instance.\n\n#### The `NODE_TLS_REJECT_UNAUTHORIZED` environment variable\n\nNode.js honours the process-wide\n[`NODE_TLS_REJECT_UNAUTHORIZED=0`](https://nodejs.org/api/cli.html#node_tls_reject_unauthorizedvalue)\nenvironment variable at the TLS layer below `undici`. If that variable is\nset when your program starts, **all TLS verification in the entire Node\nprocess is disabled** — including this SDK's connections, and any other\nHTTPS calls your application makes (telemetry, package mirrors, third-party\nAPIs, etc.). Node itself prints a one-time warning when the variable is\nhonoured.\n\nThis SDK deliberately does **not** override or unset this variable: it is a\ndocumented Node.js mechanism that operators sometimes set intentionally in\nCI or dev shells, and silently re-enabling verification from the library\nwould be surprising. But you should be aware that:\n\n- It is **process-wide**, not SDK-specific. Setting it to bypass a lab\n appliance also exposes every other outbound HTTPS call in the same\n process.\n- It cannot be re-enabled per-connection from JavaScript once set — even\n `new NodeHttpClient({ rejectUnauthorized: true })` is overridden by the\n env var.\n- It must not be set in production. Prefer the custom-CA approach above.\n\nIf you find `NODE_TLS_REJECT_UNAUTHORIZED=0` in a deployment environment,\ntreat it as a finding to remediate, not as a working configuration.\n\n### TLS 1.3 and SPP 9.0\n\nStarting with **SPP 9.0**, the appliance enables **TLS 1.3**. For\npassword/token authentication there is **nothing to change** — connections\nnegotiate TLS 1.3 automatically. Certificate-based auth needs a little care on\nNode, described below. safeguard.js handles the common case for you by default.\n\n#### The Node limitation: no client-side post-handshake auth\n\nTLS 1.3 moves client-certificate authentication to a **post-handshake**\nexchange (RFC 8446 §4.6.2): the server sends a `CertificateRequest` *after* the\nhandshake and the client must answer it. **Node.js does not implement\nclient-side post-handshake authentication** — the upstream request\n([nodejs/node#46120](https://github.com/nodejs/node/issues/46120)) was closed\n`NOT_PLANNED`, and `tls.connect` exposes no toggle for it. Over a plain TLS 1.3\nconnection the client therefore never presents its certificate, and certificate\n/ A2A auth fails against SPP 9.0 with `60094 Authorization is denied`.\n\n> This differs from PySafeguard, where Python's `ssl` module *can* answer the\n> post-handshake request (`post_handshake_auth = True`). No equivalent exists in\n> Node, so safeguard.js uses TLS-version control instead.\n\n#### What safeguard.js does by default\n\n`NodeHttpClient` accepts opt-in `minVersion` / `maxVersion` TLS pins. When you\nbuild a client for certificate/A2A auth (i.e. `TlsOptions` carries a\n`cert`/`key` or `pfx`) and you have **not** pinned a version, the connection is\n**automatically capped at TLS 1.2**. That keeps the certificate request\n*in-handshake*, so certificate and A2A auth work out of the box on SPP 9.0's\nStandard binding:\n\n```typescript\nimport { SafeguardClient, CertificateAuth, NodeHttpClient } from '@oneidentity/safeguard';\n\nconst auth = new CertificateAuth({ certFile: './client.pem', keyFile: './client.key' });\nconst client = new SafeguardClient('safeguard.corp.example', { auth });\n\n// cert present + no version pin ⇒ NodeHttpClient caps at TLS 1.2 for you\nclient.setHttpClient(new NodeHttpClient(auth.getTlsOptions()));\nawait client.connect();\n```\n\nPassword/token connections carry no client certificate and continue to\nnegotiate up to TLS 1.3.\n\n#### Reaching TLS 1.3 for certificate auth (Cert SNI)\n\nThe only way to do **certificate auth over TLS 1.3** from Node is the\nappliance's **Cert SNI** hostname, which requests the client certificate\n*during* the handshake (no post-handshake step). Target that hostname and pin\n`minVersion: 'TLSv1.3'`; pinning a bound explicitly disables the auto-cap:\n\n```typescript\nconst client = new SafeguardClient('cert-sni.safeguard.corp.example', { auth });\nclient.setHttpClient(\n new NodeHttpClient({ ...auth.getTlsOptions(), minVersion: 'TLSv1.3' }),\n);\nawait client.connect();\n```\n\n#### A2A on SPP 9.0\n\nA2A retrieval and write-back authenticate with a **client certificate only** —\nthere is no password/token alternative — so on SPP 9.0's Standard binding A2A is\n**always** subject to the same TLS 1.2 auto-cap as certificate auth. `A2AClient`\nhas no default HTTP client, so wire a cert-configured `NodeHttpClient` through\n`setHttpClient` (the auto-cap and HTTP/1.1 pin both apply through it):\n\n```typescript\nimport { A2AClient, CertificateAuth, NodeHttpClient } from '@oneidentity/safeguard';\n\nconst auth = new CertificateAuth({ certFile: './client.pem', keyFile: './client.key' });\nconst a2a = new A2AClient('safeguard.corp.example', { auth });\n\n// cert present + no version pin ⇒ NodeHttpClient caps at TLS 1.2 for you\na2a.setHttpClient(new NodeHttpClient(auth.getTlsOptions()));\nconst password = await a2a.retrievePassword(apiKey);\n```\n\nTo run A2A over **TLS 1.3**, use the appliance's Cert SNI hostname and pin\n`minVersion: 'TLSv1.3'` (which disables the auto-cap), exactly as for\ncertificate auth:\n\n```typescript\nconst a2a = new A2AClient('cert-sni.safeguard.corp.example', { auth });\na2a.setHttpClient(\n new NodeHttpClient({ ...auth.getTlsOptions(), minVersion: 'TLSv1.3' }),\n);\nconst password = await a2a.retrievePassword(apiKey);\n```\n\n#### Pinning the TLS version (opt-in)\n\n`NodeHttpClient` accepts `minVersion` and `maxVersion` (`TlsVersion` =\n`'TLSv1.3' | 'TLSv1.2' | 'TLSv1.1' | 'TLSv1'`, default unset = negotiate\nnormally):\n\n```typescript\n// Require TLS 1.3 (e.g. to enforce it against SPP 9.0)\nnew NodeHttpClient({ minVersion: 'TLSv1.3' });\n\n// Interim: cap the connection at TLS 1.2\nnew NodeHttpClient({ maxVersion: 'TLSv1.2' });\n```\n\nThe pins govern the client's request transport (all API, token, and A2A\ntraffic). Leaving them unset lets Node negotiate the highest mutually supported\nversion — the recommended default for password/token auth.\n\n#### Node/JS gotchas\n\n- **No client post-handshake auth.** There is no way to present a client\n certificate on a TLS 1.3 connection whose cert request is post-handshake. Use\n the TLS 1.2 default or the Cert SNI hostname — those are the only two options.\n- **Keep HTTP/1.1 for certificate auth — do not enable HTTP/2.** The\n post-handshake `CertificateRequest` is disallowed under HTTP/2, and the\n appliance's Standard binding rejects certificate auth over HTTP/2 with\n `HTTP_1_1_REQUIRED`. undici offers HTTP/2 via ALPN by default, so\n `NodeHttpClient` automatically pins HTTP/1.1 (`allowH2: false`) whenever a\n client certificate is present; password/token connections keep HTTP/2. Do not\n force `allowH2` on a certificate connection.\n- **The auto-cap only triggers when a client cert is present and no bound is\n pinned.** Setting `minVersion` *or* `maxVersion` yourself puts you fully in\n control and disables the TLS 1.2 default.\n- **Use the `TlsVersion` strings**, e.g. `'TLSv1.3'`, not Node's numeric\n constants.\n\n### Host Validation\n\nThe `SafeguardClient` constructor validates the `host` parameter to prevent\ninjection attacks. Only bare hostnames or IP addresses are accepted — URLs,\npaths, ports, query strings, and whitespace are rejected with a\n`ConfigurationError`.\n\n### Token Lifetime\n\n`client.getAccessTokenLifetimeRemaining()` decodes the JWT `exp` claim\nclient-side. This is a convenience for scheduling token refresh — never use it\nas an authorization decision. The server is the sole authority on token\nvalidity.\n\n## About the Safeguard API\n\nThe Safeguard API is a REST-based Web API. Safeguard API endpoints are called\nusing HTTP operators and JSON requests and responses. The Safeguard API is\ndocumented using Swagger. You may use Swagger UI to call the API directly or\nto read the documentation about URLs, parameters, and payloads.\n\nTo access the Swagger UI use a browser to navigate to:\n`https:///service/