Skip to main content

Configure the node address for token validation

The REST API validates session tokens by calling the authorization server. That call must reach the node that issued the token, because nodes do not replicate tokens. In a multi-node installation, Bravura Security Fabric builds the address for that call from the BASE_IDSYNCH_URL system variable, with the host replaced by the name of the node.

Most installations need no configuration. Set the optional serverlocalurl registry value only when a node does not answer on the same protocol and port as the address that clients use.

Note

Session affinity (sticky sessions) is still required on the load balancer for multi-node installations. The node address setting corrects a server-to-server request that carries no session cookie. No load balancer setting can influence that request.

When you need serverlocalurl

Set serverlocalurl in either of these cases:

  • The load balancer terminates HTTPS on port 443 and forwards plain HTTP to the nodes on port 80. This arrangement is called TLS offload.

  • The load balancer listens on a port that the nodes do not share.

Without the value in these cases, token validation requests go to a protocol or port where the node is not listening, and every sign-in is invalidated.

Set serverlocalurl on each node

The value is different on every node. It is excluded from node-to-node registry synchronization on purpose, so do not distribute it with updinst.

  1. On the node, open the Windows Registry Editor.

  2. Navigate to HKEY_LOCAL_MACHINE\SOFTWARE\Bravura Security\Bravura Security Fabric\<instance>, where <instance> is the name of the instance.

  3. Create a REG_SZ value named serverlocalurl.

  4. Set the value to the address at which this node's own web endpoints are reachable, for example https://<node-fqdn>:8443.

  5. Repeat steps 1 to 4 on every other node, using the address of that node.

  6. On each node, restart IIS by running iisreset. The product reads the value once, at startup, so a change has no effect on a running node until IIS restarts.

Requirements for the value

  • The value must name this node. If it names another node, logins are invalidated, which is the defect that this setting corrects.

  • The value must include a scheme. Only http and https are accepted.

  • The value sets the scheme, host, and port. The path still comes from BASE_IDSYNCH_URL, and the issuer of the token never changes.

  • On HTTPS installations, the host must appear on the certificate of the node.

A value with no scheme, or with a scheme other than http or https, stops the node from starting. See Troubleshoot a node that does not start in this topic.

Cleartext token validation warning

If serverlocalurl uses plain HTTP on an installation where clients use HTTPS, the product writes a warning to the log each time the application pool starts. The warning does not stop the node from starting.

The validation request authenticates with the REST API client secret, and the transport is the only protection for that secret. Use an HTTPS address, or an address that does not leave the node.

How a node chooses its own name

When serverlocalurl is not set, the node calls itself by name to validate tokens. It picks the name in this order:

  1. The serveraddress registry value, if set.

  2. The host name of the computer, as reported by DNS.

  3. The computer name, which is the short name, if the DNS lookup fails.

On HTTPS installations, the name that the node picks must appear on the certificate of the node, as the subject or as a subject alternative name. If it does not, the TLS handshake between the node and itself fails and every REST API call returns HTTP 401. This applies to single-node installations too.

If the certificate covers only the load-balanced address, add the node names to the certificate, or set serverlocalurl to a name that the certificate covers.

The serveraddress registry value

The serveraddress registry value must be a bare host name, for example node1.example.com. It must not contain a scheme, port, or path. A bracketed IPv6 literal such as [::1] is accepted.

This requirement is not new. What is new is that a malformed value is reported and stops the node from starting, instead of being ignored. To specify a scheme, port, or path for a node, use serverlocalurl.

Important

The file replication configuration tells administrators to set serveraddress to the IP address of the node when other nodes cannot reach it by host name. The node also uses that value to call itself. On HTTPS installations, a certificate that covers only host names fails that call. Either use a host name that the certificate covers, or add the IP address to the certificate.

Verify the configuration

Each node writes the following lines to the instance log once for each application pool start. They are present after a plain iisreset, and no one needs to sign in first.

OpenIddictValidationOptionsConfig: Issuer set to: <balanced address>/<instance>/identity
[Local introspection address] [<node>] [serverlocalurl <value or (unset)>] [issuer <issuer>]
[Local introspection endpoint] [<scheme>://<node>[:port]/<path>/connect/introspect]

The issuer must be the load-balanced address. The introspection endpoint must name the node that wrote the line. If the endpoint names the load-balanced address, serveraddress or serverlocalurl is misconfigured on that node.

Troubleshoot a node that does not start

The product validates the address of the node during application startup. If the address is not valid, the REST API application refuses to start. Under IIS in-process hosting, the symptom is HTTP 500.30 on every request. After IIS rapid-fail protection trips, the symptom becomes HTTP 503. The symptom is not a login error.

Earlier releases ignored a bad value. The node started, and token validation silently returned to the load-balanced address. On a multi-node installation, that invalidates logins and looks the same as the original defect, so the product now stops instead.

The instance log names the setting, the value, and the remedy. For example:

The 'serverlocalurl' registry value [node2] is not a valid base address.
It must include a scheme, e.g. https://node1:8443. Cannot start REST API application.

The 'serverlocalurl' registry value [htp://node1] must use http or https, not 'htp'.
... Cannot start REST API application.

The 'serveraddress' registry value [node1:8443] must be a bare host name.
... Cannot start REST API application.

Important

The product logs the reason only for the first failed start. After rapid-fail protection stops retrying the application pool, requests still return HTTP 500, but nothing more is written to the instance log. If the log has no explanation, run iisreset. The restart reproduces the message.

A refused REST API application does not take the node out of service. The REST API is a separate IIS application from the web front end, and the front end keeps serving. Users can load the login page and sign in, and then see a dashboard that does not work.

The nodestatus resource that the load balancer documentation recommends does not check the REST API application. It checks services, replication queues, database connectivity, database commit suspension, and IIS timeouts, so it returns HTTP 200 on a node whose REST API application refused to start. A load balancer that uses nodestatus, or that probes only the site root, keeps sending traffic to that node. Users can load the login page, but the dashboard and every function that depends on the REST API fail.

To detect this condition, search the instance log for Cannot start REST API application after each restart, and check the startup lines described in Verify the configuration. For the checks that nodestatus runs and its plugin option, see Automated node check when using a load balancer.

In this section: