Who these recommendations are for
The recommendations are addressed to the IT or OT administrator of the plant who is responsible for the InnerWeb installation and its integrations. They concern three elements: the machine token protecting the work history endpoint, the keys used to verify identity, and the identity token from the portal used at login.
Each element has a different role. The machine token opens read access to the work history for the portal. The set of public keys of the issuer allows the signature to be checked. The identity token proves that the portal has confirmed a given person. Confusing their roles ends in a gap that does not show up in a functional test.
Recommendation 1: an empty token means a closed endpoint
The work history endpoint is protected only by the machine token in a header. An empty token on the server side means that an installation without the integration enabled shares nothing. This is good news for plants that are not yet opening up to the portal: no configuration is a safe state.
We therefore recommend not entering the token in advance. Set it only on the day the integration starts, and record the date so that rotation can be planned. Before starting, check that a call without a token is rejected.
Recommendation 2: the token only in a header, never in the address
The machine token is not accepted in the URL, because addresses end up in server access logs, proxies and monitoring tools. A token in a log is a token leaked to everyone who can read the logs.
When configuring the portal side, make sure calls send the token in a header. Add to the checklist a review of the access logs after the first week of operation: they should contain no parameters with the token.
Recommendation 3: verify the identity token in full
The identity token from the portal is verified with an RS256 signature, using a key taken only from the public key set of the issuer, together with checks of the issuer, the audience, the validity period and a single-use nonce value. None of these elements may be switched off for the convenience of tests in production.
For IT this means two things. Make sure the plant server can reach the public key set of the issuer, and that the server clock is synchronised, because the validity check depends on the clock. A clock off by a few minutes can reject correct logins and is often mistaken for a portal failure.
- RS256 signature with a key from the public set of the issuer.
- Check of the issuer and the audience.
- Check of the validity period.
- Single-use nonce value.
Recommendation 4: token rotation covers registration from the poster
When registration from the poster is enabled, the machine token of the portal may create accounts and firms and issue passes. This is a broader scope than reading the work history alone. Token rotation and the risk assessment must therefore cover this scope as well.
We recommend treating the token as a key with administrative rights in the contractor area: keep it in a secrets manager, limit the number of people with access, and plan periodic rotation together with an emergency procedure for a suspected leak. The decision on rotation dates belongs to the plant's security owner.
Recommendations 5 and 6: login through the standard path and evidence in logs
Logging in through the portal goes through the plant's standard path, so two-factor authentication applies, and accounts that are blocked, disabled, deleted or expired are rejected just as with a password. Do not create exceptions for contractors and do not bypass this path for convenience.
For audit purposes keep the evidence: the date the token was set, the date of the last rotation, the result of the test rejecting a call without a token, and the record of the log review. The integration panel shows errors from the last 7 days, which helps spot anomalies, but it does not replace a review of the server logs.
Recommendation 7: a test before opening
Before opening the plant to the portal, run a short final test: a call without a token, a call with a wrong token and with a correct one, a login by a person with a blocked account, and a login with an expired identity token. Each of the five cases should produce the expected refusal or approval.
Record the results in the deployment protocol. This is the same document that will show an auditor in a year that access control of the integration was tested, not merely declared.
Checklist
Video
Frequently asked questions
Can I pass the token in the address if the portal prefers it?
No. The token is not accepted in the address, because addresses end up in access logs. Send it in a header.
What does the server check for the identity token?
The RS256 signature with a key from the public set of the issuer, the issuer, the audience, the validity period and the single-use nonce value.
Who decides on the token rotation date?
The plant's security owner. The documentation indicates the scope of risk, but the rotation period follows the plant's policy.
Sources
Let's talk about the contractor portal at your plant
We will show you on a live example how a contractor's request reaches the operator and how the plant keeps full control over entry to the site.
Let's talk