# node-opcua-server-configuration

> pure nodejs OPCUA SDK - module server-configuration

Latest version **2.187.31** (published 2026-11-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install node-opcua-server-configuration
pnpm add node-opcua-server-configuration
yarn add node-opcua-server-configuration
bun add node-opcua-server-configuration
```

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 2.187.31 |
| Published | 2026-11-17 |
| First published | 2019-04-06 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1664 |
| Author | Etienne Rossignon |
| Maintainers | erossignon |
| Keywords | OPCUA, opcua, m2m, iot, opc ua, internet of things |

## Links

- npm: https://www.npmjs.com/package/node-opcua-server-configuration
- Repository: https://github.com/node-opcua/node-opcua
- Homepage: http://node-opcua.github.io/
- Issues: https://github.com/node-opcua/node-opcua/issues
- npm.io page: https://npm.io/package/node-opcua-server-configuration

## Recent versions

- 2.187.31 (latest) — 2026-11-17
- 2.113.2 (patch) — 2023-12-23
- 2.67.1 (v2.67) — 2022-05-21
- 2.6.0-alpha.5 (canary) — 2020-05-19
- 2.187.30 — 2026-11-17
- 2.187.29 — 2026-11-16
- 2.187.28 — 2026-11-16
- 2.187.27 — 2026-11-13
- 2.187.26 — 2026-11-10
- 2.187.25 — 2026-11-08
- 2.187.24 — 2026-11-07
- 2.187.23 — 2026-11-06
- 2.187.22 — 2026-11-03
- 2.187.21 — 2026-11-03
- 2.187.20 — 2026-11-03
- … 343 more at https://npm.io/package/node-opcua-server-configuration/versions

## README

# node-opcua-server-configuration

Part of [node-opcua](http://node-opcua.github.io/), the OPC UA SDK for Node.js written in TypeScript.

This package implements the `ServerConfiguration` object of OPC 10000-12
(Part 12, "Discovery and Global Services") for node-opcua servers, that is the
**push model** of certificate management: a CertificateManager (a GDS, or any
administration tool) connects to the server and

- asks it for a certificate signing request (`CreateSigningRequest`),
- installs the certificate signed by its CA (`UpdateCertificate`),
- updates its trust lists (the `TrustList` objects of the certificate groups),
- and makes the changes effective (`ApplyChanges`).

It also provides the client side of these calls (`ClientPushCertificateManagement`).

```bash
npm install node-opcua node-opcua-server-configuration
```

## Server side

Call `installPushCertificateManagementOnServer(server, options)` after
`server.initialize()` (the address space must exist; the function throws
otherwise) and before `server.start()`:

```typescript
import { OPCUACertificateManager, OPCUAServer, WellKnownRoles, makeRoles } from "node-opcua";
import { installPushCertificateManagementOnServer } from "node-opcua-server-configuration";

const serverCertificateManager = new OPCUACertificateManager({
    rootFolder: "/var/lib/my-server/PKI", // application certificate and trust list
    automaticallyAcceptUnknownCertificate: false
});
const userCertificateManager = new OPCUACertificateManager({
    rootFolder: "/var/lib/my-server/UserPKI", // trust list for X.509 user tokens
    automaticallyAcceptUnknownCertificate: false
});

const server = new OPCUAServer({
    port: 4840,
    serverCertificateManager,
    userCertificateManager,
    userManager: {
        isValidUser: (userName: string, password: string) =>
            userName === "admin" && password === process.env.ADMIN_PASSWORD,
        // the CertificateManager must log in with a user that has the SecurityAdmin role
        getUserRoles: (userName: string) =>
            userName === "admin"
                ? makeRoles([WellKnownRoles.AuthenticatedUser, WellKnownRoles.SecurityAdmin])
                : makeRoles([WellKnownRoles.AuthenticatedUser])
    }
});

await server.initialize();
await installPushCertificateManagementOnServer(server, {
    closeChannelsOnApplyChanges: true,
    applicationSetup: { leaveWhenConfigured: false }
});
await server.start();
```

The installer also adds the Global Certificate Management facet
(`GLOBAL_CERTIFICATE_MANAGEMENT_PROFILE_URI`) to
`ServerCapabilities.ServerProfileArray`.

### Options (`InstallPushCertificateManagementOnServerOptions`)

| Option | Default | Meaning |
| --- | --- | --- |
| `closeChannelsOnApplyChanges` | `true` | When `ApplyChanges` puts a new server certificate (and possibly a new private key) into service, every open secure channel is closed once the response is sent, so all clients reconnect with the new certificate. Use this when the rotation answers a compromised or revoked key. With `false`, open channels keep running under the certificate and key they were created with (seamless planned rotation); new connections use the new pair. |
| `applicationSetup.leaveWhenConfigured` | `false` | Only matters while the server reports `ServerState.NoConfiguration` (see below). When `true`, the server moves to `Running` by itself once `ApplyChanges` has put a CA-issued certificate into service and the TrustList holds a certificate that was not trusted automatically; on leaving `NoConfiguration`, the certificates trusted automatically during the setup are removed again, except those a TrustList write kept. When `false`, the application decides when the setup ends, and those certificates stay trusted. |

### Security requirements

What the code enforces, for every session:

- **Encrypted channel.** `CreateSigningRequest`, `UpdateCertificate`,
  `GetRejectedList`, `ApplyChanges`, and the TrustList `AddCertificate` /
  `RemoveCertificate` methods check that the session's secure channel uses
  `MessageSecurityMode.SignAndEncrypt`, and return `BadSecurityModeInsufficient`
  otherwise. These methods, the certificate groups and the TrustList methods
  (`Open`, `OpenWithMasks`, `Read`, `Write`, `Close`, `CloseAndUpdate`, ...)
  also carry the `SigningRequired | EncryptionRequired` access restrictions.
- **SecurityAdmin role.** The same methods check that the session user has
  the `SecurityAdmin` well-known role, and return `BadUserAccessDenied`
  otherwise (an anonymous session never qualifies). Their RolePermissions grant
  everything to `SecurityAdmin` only; `ServerConfiguration` and
  `CertificateGroups` can be browsed by anybody, and read by `ConfigureAdmin`.
  Roles come from your `userManager.getUserRoles()`.
- **Disk based PKI.** `serverCertificateManager` must be an
  `OPCUACertificateManager` (the function throws otherwise): push management
  writes certificates and keys to its folders.
- **Private keys.** A key held by an HSM/KMS (opaque key) cannot be
  regenerated or replaced: `CreateSigningRequest` with `regeneratePrivateKey`
  and `UpdateCertificate` with a private key answer `BadNotSupported`.

### Where the PKI and trust lists live

| Certificate group | Certificate manager | Content |
| --- | --- | --- |
| `DefaultApplicationGroup` | `serverCertificateManager` | server certificate (`own/certs/certificate.pem`), private key (`own/private/private_key.pem`), trusted and issuer certificates and CRLs (`trusted/`, `issuers/`), rejected certificates (`rejected/`) |
| `DefaultUserTokenGroup` | `userCertificateManager` | trust list used to validate X.509 user identity tokens |

Without explicit managers, OPCUAServer uses the default ones, in
`<config>/node-opcua-default-nodejs/PKI` and `.../UserPKI` (on Linux,
`~/.config/node-opcua-default-nodejs/`).

A change of the TrustList re-evaluates open secure channels and sessions
(OPC 10000-12 7.8.2.5): those whose certificate is no longer trusted are
closed shortly after the method returns.

### First configuration (`NoConfiguration`)

A server that has never been provisioned can be put in the application setup
state by the application: `server.setServerState(ServerState.NoConfiguration)`
(the server is otherwise `Running` after `initialize()`). While in that state,
and only when push management is installed, the server admits a client whose
certificate is untrusted, whose chain is incomplete or whose revocation status
is unknown, and trusts its leaf certificate, so that a CertificateManager can connect the first time. Revoked,
expired or invalid certificates are never admitted. Leave the state as soon as
the server is configured (`applicationSetup.leaveWhenConfigured`, or set the
state yourself).

## Client side (GDS or administration tool)

```typescript
import { readFile } from "node:fs/promises";
import { MessageSecurityMode, OPCUAClient, SecurityPolicy, UserTokenType } from "node-opcua";
import { ClientPushCertificateManagement, rsaCertificateTypes, TrustListMasks } from "node-opcua-server-configuration";

/** your CA: turns a DER certificate signing request into a DER certificate and its issuer chain */
declare function signWithMyCA(csr: Buffer): Promise<{ certificate: Buffer; issuerCertificates: Buffer[] }>;

const client = OPCUAClient.create({
    securityMode: MessageSecurityMode.SignAndEncrypt, // required by the server
    securityPolicy: SecurityPolicy.Basic256Sha256
});

await client.withSessionAsync(
    {
        endpointUrl: "opc.tcp://my-server:4840",
        userIdentity: {
            type: UserTokenType.UserName,
            userName: "admin", // a user with the SecurityAdmin role
            password: process.env.ADMIN_PASSWORD ?? ""
        }
    },
    async (session) => {
        const pushManagement = new ClientPushCertificateManagement(session);

        // 1. ask the server for a certificate signing request
        const csr = await pushManagement.createSigningRequest(
            "DefaultApplicationGroup",
            rsaCertificateTypes.RsaSha256ApplicationCertificateType,
            "", // empty subject: the server proposes its own
            false // keep the current private key
        );
        if (csr.statusCode.isNotGood() || !csr.certificateSigningRequest) {
            throw new Error(`CreateSigningRequest failed: ${csr.statusCode.toString()}`);
        }

        // 2. sign it with your CA, then install the certificate
        const { certificate, issuerCertificates } = await signWithMyCA(csr.certificateSigningRequest);
        const update = await pushManagement.updateCertificate(
            "DefaultApplicationGroup",
            rsaCertificateTypes.RsaSha256ApplicationCertificateType,
            certificate,
            issuerCertificates
        );
        if (update.statusCode.isNotGood()) {
            throw new Error(`UpdateCertificate failed: ${update.statusCode.toString()}`);
        }

        // 3. update the trust list of the application group
        const applicationGroup = await pushManagement.getApplicationGroup();
        const trustList = await applicationGroup.getTrustList();
        const current = await trustList.readTrustedCertificateListWithMasks(TrustListMasks.All);
        current.trustedCertificates = [
            ...(current.trustedCertificates ?? []),
            await readFile("partner_certificate.der") // DER encoded certificate to trust
        ];
        const applyChangesRequired = await trustList.writeTrustedCertificateList(current);

        // 4. make the changes effective
        if (update.applyChangesRequired || applyChangesRequired) {
            const status = await pushManagement.applyChanges();
            if (status.isNotGood()) {
                throw new Error(`ApplyChanges failed: ${status.toString()}`);
            }
        }
    }
);
```

`writeTrustedCertificateList` opens the TrustList with `WriteEraseExisting`,
writes the whole `TrustListDataType` and calls `CloseAndUpdate`: lists that
are not set are cleared, so read the current content first, as above, and
modify it. For a single certificate, `trustList.addCertificate(certificate, true)`
and `trustList.removeCertificate(thumbprint, true)` are simpler.

With the default `closeChannelsOnApplyChanges: true`, the server closes the
channel of this client too after `ApplyChanges`: reconnect to continue.

Other helpers of `ClientPushCertificateManagement`: `getRejectedList()`,
`getSupportedPrivateKeyFormats()`, `getUserTokenGroup()` (trust list for X.509
user tokens), and `updateCertificate(..., privateKeyFormat, privateKey)` to
install a key pair generated outside the server.

---
_Source: https://npm.io/package/node-opcua-server-configuration · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
