# Webserver for ioBroker adapters ## Description This module provides a webserver, which automatically takes care of certificate handling using the ioBroker certificates. ## How-To Install via `npm i @iobroker/webserver`. Use the webserver in your ioBroker adapter as the following: - TypeScript: ```typescript import { WebServer } from '@iobroker/webserver'; const webServer = new WebServer({ app, adapter, secure: true }); // initialize and you can use your server as known const server = await webServer.init(); ``` - JavaScript: ```javascript const { WebServer } = require('@iobroker/webserver'); const webServer = new WebServer({ app, adapter, secure: true }); // initialize and you can use your server as known const server = await webServer.init(); ``` And so you can use `CertificateManager` that is used in the WebServer already: - TypeScript: ```typescript import { CertificateManager } from '@iobroker/webserver'; // Not required for server const certManager = new CertificateManager({ adapter }); // get all collections const collections = await certManager.getAllCollections(); ``` - JavaScript: ```javascript const { CertificateManager } = require('@iobroker/webserver'); // Not required for server const certManager = new CertificateManager({ adapter }); // get all collections const collections = await certManager.getAllCollections(); ``` ## OAuth2 support You can activate the OAuth2 support for the webserver. To do this, add the following code after the server is initialized: ```typescript // ... initialization of the webserver this.webServer.app.use(cookieParser()); this.webServer.app.use(bodyParser.urlencoded({ extended: true })); this.webServer.app.use(bodyParser.json()); this.webServer.app.use(bodyParser.text()); // Install oauth2 server (Only this line is required) createOAuth2Server(this, { app: this.webServer.app, secure: this.config.secure, withSession: true }); // Old authentication method this.webServer.app.use( session({ secret: this.secret, saveUninitialized: true, resave: true, cookie: { maxAge: (parseInt(this.config.ttl as string, 10) || 3600) * 1000, httpOnly: false }, // default TTL // @ts-expect-error missing typing store: this.store!, }), ); ``` If you want to completely disable old authentication method, the code should looks like: ```typescript // ... initialization of the webserver this.webServer.app.use(cookieParser()); this.webServer.app.use(bodyParser.urlencoded({ extended: true })); this.webServer.app.use(bodyParser.json()); this.webServer.app.use(bodyParser.text()); // Install oauth2 server (Only this line is required) createOAuth2Server(this, { app: this.webServer.app, secure: this.config.secure }); ``` Login with OAuth2 is available under `/oauth/token` URL: ```http POST /oauth/token HTTP/1.1 Host: IP:PORT Content-Type: application/x-www-form-urlencoded Data: grant_type=password&username=&password=&client_id=ioBroker&stayloggedin= ``` `stayloggedin=true` means that the token will be stored in the browser and will be used for the next requests and is optional. The answer is like: ```json { "access_token": "21f89e3eee32d3af08a71c1cc44ec72e0e3014a9", "expires_in": 3600, "refresh_token": "66d35faa5d53ca8242cfe57367210e76b7ffded7", "refresh_token_expires_in": "600000", "token_type": "Bearer" } ``` Refresh token is available under `/oauth/token` URL: ```http POST /oauth/token HTTP/1.1 Host: IP:PORT Content-Type: application/x-www-form-urlencoded Data: grant_type=refresh_token&refresh_token=&client_id=ioBroker&stayloggedin= ``` The answer is the same as for the login but with new tokens. ## Changelog ### 1.4.0 (2026-04-13) - (@GermanBluefox) Fixed possible errors - (@GermanBluefox) Updated packages ### 1.3.3 (2026-02-12) - (@GermanBluefox) Added missing types for the acme adapter ### 1.3.1 (2025-06-17) - (@foxriver76) Implemented (for now - inofficial) Keycloack SSO support ### 1.2.8 (2025-04-29) - (@GermanBluefox) Corrected time to live for the access token ### 1.2.7 (2025-04-21) - (@GermanBluefox) Corrected a problem with authentication, as type-is was too old. ### 1.2.6 (2025-04-01) - (@GermanBluefox) Changed the order of authentications. Basic authentication will be checked as the last one. - (@GermanBluefox) Added the setting to disable basic authentication ### 1.2.4 (2025-03-25) - (@GermanBluefox) Added the possibility to give tokens for internal use (like node-red) ### 1.2.0 (2025-03-05) - (@GermanBluefox) Added the log output for invalid password in OAuth2 - (@GermanBluefox) A minimal Node.js version is 16 (Not breaking, as no one uses node 14) - (@GermanBluefox) Updated TypeScript to 5.8 ### 1.1.7 (2025-02-27) - (@GermanBluefox) Added support for OAuth2 authentication with brute force ### 1.0.8 (2025-02-07) - (@GermanBluefox) Updated packages and typing ### 1.0.6 (2024-09-14) - (@GermanBluefox) Added access control options for server - (@GermanBluefox) Used `@iobroker/eslint-config` for linting ### 1.0.3 (2023-10-16) - (@GermanBluefox) Extend the security checker with the pattern detection and custom URL ### 1.0.1 (2023-10-11) - (@GermanBluefox) Changed the error text of the security checker ### 1.0.0 (2023-10-11) - (@GermanBluefox) added the security checker ### 0.3.7 (2023-09-24) - (raintonr) Fix contexts for SNICallback ([#3](https://github.com/ioBroker/webserver/issues/3)). ### 0.3.6 (2023-07-07) - (@GermanBluefox) Update packages ### 0.3.4 (2023-03-27) - (@GermanBluefox) Corrected small error with CA certificate ### 0.3.3 (2023-03-24) - (@GermanBluefox) Added check of the cert files ### 0.3.1 (2023-03-20) - (@GermanBluefox) Corrected error with `getCertificatesAsync` ### 0.3.0 (2023-03-20) - (@GermanBluefox) Added support for user-configured certificates for fallback ### 0.2.1 (2023-03-20) - (@GermanBluefox) Rename `Webserver` to `WebServer` ### 0.1.0 (2023-03-13) - (foxriver76) initial release based on https://github.com/ioBroker/ioBroker.js-controller/pull/2104 by @raintonr