Implementation Guide · Stage 2
Give an organisation cryptographic access to entityOS without putting a client certificate on every device. One gateway holds the certificate and connects over mTLS; staff use ordinary HTTPS; entityOS still signs in every person individually.
mTLS gives entityOS a cryptographic answer to which organisation is connecting. Placing the certificate on a gateway the organisation controls keeps that answer — without distributing certificates to every laptop and phone.
Ordinary HTTPS. No client certificates to install, renew, back up or lose.
Holds the one client certificate and its private key, and connects to entityOS using mTLS.
Validates the certificate, maps it to an organisation, then authenticates each person in the application.
mTLS proves which organisation.
The login proves which person.
The gateway sits between staff and entityOS. Staff talk to it over ordinary HTTPS; it talks to entityOS over mTLS. entityOS then makes two separate decisions: is this a known organisation — and, independently, is this a known person?
Use normal HTTPS to reach the gateway. No client certificates are required on laptops, phones or tablets.
HTTPSHolds the client certificate and private key, and connects to entityOS using mTLS on behalf of the people allowed through it.
mTLS clientValidates the certificate against the entityOS trust store, enforces revocation, and maps the certificate to an organisation.
certificate → organisationAuthenticates individual users and applies their permissions. Every action is recorded against a person.
login → person → permissionsThe certificate establishes the organisation at the entry point. It never signs anyone in. Every person still authenticates to the entityOS application, and their permissions come from their own account — not from the fact that they came through the gateway.
Both models put one certificate in one controlled place. They differ in where that place is — and in what staff must pass through before they reach it.
A small appliance or VM inside the office. Staff reach it over the local network. Remote staff connect to the office through a VPN first, then use the gateway exactly as if they were on site.
A dedicated gateway in the cloud. Staff must first authenticate to it — through an identity-aware access service or a VPN — before it will use the organisation’s certificate on their behalf.
Anyone allowed through the gateway benefits from its mTLS identity. The certificate does not know who is behind it — it only proves that the request came from the gateway. So the gateway’s front door is the real security boundary of this design.
A publicly accessible gateway that automatically forwards everyone would turn an organisation credential into a public one. Gate the gateway first; then the certificate carries the organisation’s trust.
Stage 2 can issue a certificate to every device, or to the organisation’s gateway. The gateway trades a per-device cryptographic binding for central management — a good trade when device trust is handled by a separate control.
| Capability | Certificate per device | Office gateway | Hosted gateway |
|---|---|---|---|
| Client certificates to manage | One per device | One per gateway | One per gateway |
| Staff device setup | Certificate on each | None — HTTPS | None — HTTPS |
| Remote staff | Direct | VPN to the office | Access service or VPN |
| What mTLS identifies | The device’s key | The organisation | The organisation |
| Disable the whole organisation | Every certificate | One switch | One switch |
| Remove one person | Revoke their certificate | Remove access + login | Remove access + login |
| Individual login & audit | Yes | Yes | Yes |
| Gateway session logs | No | Yes | Yes |
| Device trust | Key on device only | Separate control | Separate control |
| Single point of failure | None | Yes — run two | Yes — run two |
| Infrastructure to run | Issuance at scale | Appliance or VM | Gateway + access layer |
A certificate on a device proves the device holds a key — not that it is healthy. A gateway proves the organisation. Neither replaces the individual login, and neither replaces device trust where the risk warrants it.
The gateway model works because each layer answers one question, and none of them is asked to answer another’s.
mTLS proves the gateway’s identity — not the health of the device behind it. If device trust matters, add it as its own control: managed-device checks at the access layer, or posture signals from your MDM, evaluated before the gateway forwards anything.
Seven decisions, in order. The gateway software varies; the shape does not.
Create the gateway as a named record under the organisation in entityOS. The rule is one certificate per gateway: a second gateway — for redundancy, or one office and one hosted — gets its own certificate, mapped to the same organisation and revocable on its own.
Create the key pair on the gateway and request the certificate from the entityOS CA with a CSR, so the private key never leaves the machine that uses it. Keep the key readable only by the gateway process, use hardware-backed or managed secret storage where the platform supports it, and prefer a short validity — renewal is automated in step 7.
Office gateway: listen on the office network only; remote staff come in over the VPN. Hosted gateway: never expose it directly — put an identity-aware access service or VPN in front, with SSO and phishing‑resistant MFA, and accept inbound connections only from that layer. If someone can reach the gateway without authenticating, they hold the organisation’s mTLS identity.
Run the gateway as a reverse proxy with fixed upstreams — the approved entityOS hostnames and nothing else. It must not be a general-purpose forward proxy, and must never accept a destination chosen by the client. Nor should it vouch for users: the gateway proves the organisation; the application proves the person.
Illustrative nginx configuration; HAProxy, Envoy or a managed proxy follow the same shape. The upstream is fixed in configuration, so the gateway cannot be pointed anywhere else.
At entityOS, the entry point verifies the certificate chain against the trust store, enforces revocation, and maps the certificate to the organisation. On AWS this is an Application Load Balancer listener in mTLS verify mode with a trust store, which passes the verified certificate details to the target.
Then close every other route — a default service endpoint, a second listener, a directly reachable origin. Certificate details forwarded by the edge are only trustworthy if nothing else can reach the target; any path that skips the edge skips the check.
Each person signs in to the entityOS application with their own account; permissions come from their role, never from having come through the gateway. Keep gateway session logs — who, when, which destination — and correlate them with the entityOS audit trail. No shared accounts behind a shared certificate.
The gateway’s egress address is fixed and known, so it can also be allowlisted under Stage 1 — and the organisation’s certificate arriving from any other address is a signal worth alerting on.
Renew automatically, well before expiry, with overlap: install the new certificate, confirm it connects, then retire the old one. Make revocation work in two places — the certificate on the trust store’s revocation list, and an organisation or gateway disable switch in entityOS that takes effect at once, even while the certificate is still valid. Test both before you need them.
Staff browse to the gateway’s hostname, not entityOS’s. Redirects, cookies and sign-in callbacks must resolve back through the gateway; anything that sends the browser straight to entityOS will be refused at the edge — which is the edge working correctly. And once the organisation depends on one gateway, it is a single point of failure: run a second, with its own certificate, or keep a tested break‑glass path.
The gateway’s certificate tells entityOS which organisation’s controlled access path a request came through.
The application login tells entityOS who is acting; permissions and the audit trail follow their account.
Neither of the above says the device behind the request is healthy. Where that matters, check it at the access layer.
Centrally managed organisation access — one certificate per gateway, instead of one on every device.
The boundary is the gateway’s front door — anyone allowed through it inherits its mTLS identity, so it must never forward the open internet.
mTLS proves the gateway’s identity; the application login keeps every action attributable to a person; device trust, where required, is its own control. Layered with Stage 1 allowlisting of the gateway’s fixed address, they are independent barriers rather than one wall.