Installing Scout Board

Note:

Scout Board is installed as a component of the Scout Enterprise Management Suite.

1. Download the latest version of the Scout Enterprise Management Suite and start the installation process. For further information, see Installing Scout Enterprise Management Suite.

2. Fresh installation: By default, the Scout Board is part of the installation. Upgrading a previous version without Scout Board: Activate the Scout Board component.

   

3. Then configure your Scout Board settings.

   

1. Follow the further instructions.

Note:

From 15.2609, an update to Scout Board keeps hand-made changes to the .env file. Before 15.2609, every update rewrote .env using only the installer’s own values, so any manual change — for example the settings described in the following sections — had to be reapplied after each update.

From 15.2609, five settings are still rewritten by every update regardless of your own values: USEHTTPS, DBLAYER_TIMEOUT, JWT_EXPIRATION, ZERO_MQ_IS_CURVE_ACTIVATED, and DOMAINS. The settings of a sign-in method you aren’t using are also removed. Comment lines in the file are not kept.

Configuring an individual HTTPS certificate for Scout Board

Self-signed certificates are not accepted as secure by the browser. To provide the browser with a valid SSL certificate for Scout Board perform the following steps:

1. Rename your certificate file to certificate.crt and the private key file to private.key

2. Copy both files into the Scout Board program directory. By default, this is C:\Program Files\Unicon\Scout\Scout Board

3. Still in the Scout Board program directory, edit the .env file and change the entry CERTIFICATE=SELFSIGN to CERTIFICATE=SIGN

4. Restart the Scout Board service.

For further information and detailed certificate configuration, see HTTPS Certificate Setup.

Configuring authentication options for Scout Board

During installation, you can choose which authentication method should be used for Scout Board.

The following authentication methods are supported:

• AD (Active Directory)
• Entra ID (SAML or OIDC)
• OKTA (SAML or OIDC)

After an authentication method has been configured during the installation, you can change or reconfigure it in the .env file. As a reference and an example, the template file .env.example can be used.

Note:

From 15.2609, a SAML sign-in must be one Scout Board itself started: it rejects a response sent straight from the identity provider, for example by launching Scout Board from an Okta app tile or a Microsoft Entra My Apps tile. Each rejected response is logged as a Login rejected event. When Scout Board is reached over HTTPS, it reacts by discarding the response and immediately starting a fresh sign-in of its own, so the tile still reaches Scout Board, just through an extra round trip. To avoid that round trip, point the tile at https://<Scout Board address>/api/v1/auth/login-saml instead, or set SAML_ALLOW_IDP_INITIATED=true (default false) to accept the tile’s response directly.

A SAML response is also single-use from 15.2609 on — Scout Board refuses a replay of the same response, whether or not SAML_ALLOW_IDP_INITIATED is set. GET /login-saml no longer accepts SAMLRequest as a query parameter.

Scout Board also applies three timing limits to a SAML sign-in:

• Up to 30 seconds of clock difference between the identity provider and Scout Board is tolerated.
• A response is accepted for at most 10 minutes after the identity provider issued it.
• The user has 45 minutes to finish signing in at the identity provider, once they start.

A refused sign-in shows Sign-in could not be completed with the reason, a reference code and a Sign in again link.

Configuring AD domains for Scout Board

The AD domain for the logon process is being used from the provided data during the installation process.

In the .env file, the configuration is available. If the domain changes or additional domains need to be added, these can be added manually.

The defined domains will be selectable in the Scout Board Logon dialog.

Example:

Note:

DOMAINS is one of the settings an update always rewrites (see the note above). Reapply this setting after every update, even from 15.2609 onward.

Note:

From 15.2609, Scout Board resolves the domain controller for a sign-in only from its own configuration — DOMAINS together with LDAPS_SERVERS, or AUTH_DOMAIN_MAP — instead of from a domain-controller address sent with the sign-in request or listed on the sign-in page. This applies to 15.2609 only; 15.2603 and 15.2607.x still use an address sent this way.

A sign-in for a domain that is neither in DOMAINS nor in AUTH_DOMAIN_MAP, and is not a subdomain of one of them, is refused with HTTP 412 and the message Unable to resolve domain. Please contact your administrator. The single-tenant sign-in page only ever offers a DOMAINS entry, so this mostly affects REST API callers and multi-tenant installations (TENANT_MODE=multi-tenant) that take the domain from the user name. A subdomain of a configured domain, for example child.corp.example.com under corp.example.com, signs in with no extra configuration.

To add a domain for REST API or multi-tenant sign-in without exposing it on the sign-in page, add it to AUTH_DOMAIN_MAP instead of to DOMAINS: AUTH_DOMAIN_MAP={"CORP":{"domain":"corp.example.com","ldapServer":"ldaps://dc01.corp.example.com"}}. The key (CORP above) is the short domain name used in CORP\user. ldapServer is optional; a plain string value names the domain only. Unlike DOMAINS, an update does not rewrite AUTH_DOMAIN_MAP.

If neither LDAPS_SERVERS nor a domain’s AUTH_DOMAIN_MAP entry names a domain controller, Scout Board connects to ldaps://<domain>. With the default LDAP_TLS_MODE=verify-full, this fails if the domain controller’s certificate names only its own host name. Set ldapServer in the domain’s AUTH_DOMAIN_MAP entry to an ldaps:// address with the domain controller’s FQDN, for example ldaps://dc01.corp.example.com, to fix this — for the server’s own domain only, the first LDAPS_SERVERS entry also works.

If you are using LDAPS,in the .env file, you can configure them: LDAPS_SERVERS=["ldaps://my.ldaps.server", "ldaps://my.other.ldaps.server"]

Note

Scout Board now uses ldaps:// only and validates the DC certificate chain (chain + hostname/SAN). Previously, this validation was turned off. LDAPS silently failed and used plaintext ldap://.

Affected: On-Premises AUTH_TYPE=AD deployments with an untrusted, expired or SAN-mismatched DC certificate, or a plaintext ldap:// entry in LDAPS_SERVERS / AUTH_DOMAIN_MAP.

Logins that worked in UniconOS Management version 15 2605 will fail. SSO modes and UniconOS Management Cloud deployments are not affected. The login screen will provide information on the cause, and the details will be in the backend.log log file.

Action required: In the Scout Board .env configuration file:

Perform configuration: LDAP_CA_PATH=<PEM CA bundle> or NODE_USE_SYSTEM_CA=1 You might need to set NODE_USE_SYSTEM_CA=1 as an environment variable, if the change in .env does not work.

Name mismatch: Use the DC FQDN in LDAPS_SERVERS / AUTH_DOMAIN_MAP, or LDAP_TLS_MODE=verify-ca

Temporary workaround only: Use LDAP_TLS_MODE=insecure.

This is not supported in production environments, and it does not restore plaintext. (ldap:// is refused in every mode)

The default is LDAP_TLS_MODE=verify-full Note:

After modifying the .env file, the windows service “Scout Board” needs to be restarted.

Signing in through the REST API

A REST API sign-in (loginData64) can request a token lifetime with expirationTime, but only to make the token shorter — the lifetime is always capped at JWT_EXPIRATION, one of the settings every update rewrites to its default of 4h (see the note near the top of this page). Give expirationTime a string holding a positive whole number with an optional unit m (minutes), h (hours) or d (days), for example "30m"; a number with no unit is read as hours. Any other value gets HTTP 400.

If AUTH_TYPE is not AD, a sign-in with a user name and password gets HTTP 404 with the message AD authentication is not enabled! — use the identity provider sign-in configured for this Scout Board instead.

Configuring the Database Layer key for Scout Board

Scout Board no longer fetches the Database Layer’s public key at startup. Instead, it reads ZERO_MQ_PUBLIC_KEY from its .env file, which the installer writes.

• Scout Board on the same server as the Database Layer: no action needed. If ZERO_MQ_PUBLIC_KEY is missing or outdated, Scout Board takes the key from the local dblayer.ini instead.
• Scout Board on a separate server from the Database Layer:
  1. On the Database Layer server, copy the value of [Certificates] DBLayerPublicKey from %PUBLIC%\Documents\Unicon\Scout\ScoutBoard\dblayer.ini.
  2. On the Scout Board server, set ZERO_MQ_PUBLIC_KEY=<key> in the .env file and restart the Scout Board service. On a new installation, you can instead pass UCPROP_SCOUTBOARD_REMOTE_DBLAYER_PUBLIC_KEY=<key> to the installer; an upgrade keeps whichever key is already in .env.
  3. Repeat these steps whenever the Database Layer’s key changes, for example after the Scout database is restored or Scout Board is re-pointed at a different Database Layer.

Without a usable key, Scout Board still starts, but cannot reach the Database Layer; its log names ZERO_MQ_PUBLIC_KEY as the setting to check.