OpenClaw documents an SSO integration path through an identity-aware reverse proxy. A useful business evaluation goes beyond the login screen: establish who can enter, what their connection can do, which devices retain access, and how offboarding closes every relevant route.
1. Decide whether the trust model fits
Consider an illustrative operations team sharing an assistant for internal work. Company sign-in could simplify onboarding, but the team still needs an explicit access design. OpenClaw supports one trust boundary per gateway: a single operator or mutually trusting teammates. Operator roles are collaboration guardrails, not isolation between adversarial tenants.
If customers, contractors, or departments must not share that trust, evaluate separate gateways and operating-system or host boundaries before configuring SSO. A separate conversation or agent name is not that boundary.
In the documented trusted-proxy design, the proxy authenticates the person using its identity-provider integration, then forwards a verified identity header. OpenClaw checks the trusted source and configured identity rules. This is evidence of proxy-based integration, not proof of native SAML service-provider functionality, SCIM provisioning, or automatic directory-group synchronization. Require separate evidence for those procurement requirements.
2. Write down the identity contract
Assign the identity owner responsibility for sign-in policy, multifactor authentication, account lifecycle, and the proxy session. Assign the gateway owner responsibility for trusted proxy addresses, accepted identities, and operator grants. Neither owner should assume the other has configured authorization.
The official guide recommends a verified immutable identity, such as an issuer-qualified OIDC subject, for a single-owner boundary. Decide how your proxy maps that identity into userHeader and how changes are reviewed. allowUsers compares the trimmed header value exactly; it does not validate a JWT or turn an email address into an immutable account identifier.
Configure an intentional allowlist: an empty allowUsers list permits all proxy-authenticated users. requiredHeaders only checks for nonblank headers. It does not independently prove that the proxy authenticated the person.
3. Make the proxy the enforced entry point
Inventory the public hostname, gateway port, internal network routes, plugin endpoints, and WebSocket upgrades. Restrict gateway ingress to the intended proxy and have it overwrite client-supplied identity and forwarding headers. Test authentication on upgraded WebSocket connections, not just the initial web page.
Same-host proxies need particular care. Trusted-proxy authentication rejects loopback sources by default; allowLoopback is an explicit opt-in, and the loopback address must also be trusted. Enabling it extends trust to local processes that can send the same headers. Document that host-level assumption instead of treating loopback as proof of proxy identity.
Use HTTPS and the intended browser-origin policy. Review every exception, including local maintenance authentication and separately authenticated integration routes. A working corporate login does not demonstrate that direct access is closed.
4. Separate login, device enrollment, and permissions
Choose manual device approval or deliberate automatic enrollment. deviceAutoApprove is disabled by default. When enabled, proxy identity can authorize eligible new UI operator devices and same-key scope upgrades. These are persistent device grants; adding operator.admin to the automatic scope list allows every eligible proxy-authenticated user to request full administrator enrollment.
identityScopes is different: it adds connection-only scopes for a verified identity without changing the paired device record. It is additive, not a replacement that automatically removes broader device permissions. Review both grants together.
Have the proxy derive and overwrite scope headers from its authorization policy; do not trust a caller-selected scope list. The same header has different effects across interfaces. Treat the distinction below as an acceptance-test requirement, and verify it against your installed version.
| Surface | Permission behavior to verify |
|---|---|
| Control UI WebSocket | x-openclaw-scopes caps the combined device and identity scopes; it does not grant them. |
| Normal identity-bearing HTTP API | x-openclaw-scopes declares scopes. If absent, the documented defaults include operator.admin. |
| Gateway-authenticated plugin HTTP route | Without the header, the documented runtime default is operator.write; validate the route's own checks. |
5. Design offboarding as several revocations
Begin by denying the departing identity at the proxy for every protected route. Define how the identity provider and proxy terminate existing sessions; do not assume disabling a directory account immediately closes an established WebSocket.
Review gateway allowUsers and identityScopes, paired devices, bootstrap credentials, active connections, and any maintenance access separately. The proxy guide explicitly warns that allowUsers alone is not sufficient revocation because valid device or bootstrap credentials have their own WebSocket authentication paths. Removing the final allowlist entry is especially important to review: an empty list is permissive, not deny-all.
The devices CLI documents inventory, targeted token revocation, rotation, and device removal. Select the exact affected devices and roles instead of treating a broad cleanup command as the offboarding procedure. Revoking a creator's device token does not cancel existing schedules or undo committed actions; assign or retire that work explicitly.
6. Run a disposable access drill
Before production, use test identities and harmless operations. The following are proposed acceptance checks, not a report of tests performed for a customer. Capture the deployed version, sanitized configuration, client surface, expected decision, and observed result.
- Allowed teammate: sign in, enroll as intended, and perform one permitted operation; confirm an out-of-scope action fails.
- Unlisted identity: attempt the page, WebSocket upgrade, and each protected API route; confirm rejection.
- Header spoofing and direct access: submit client-chosen identity headers and try the gateway port from an untrusted location; confirm neither grants access.
- Scope differences: compare HTTP and WebSocket behavior, including absent and empty scope headers; have the proxy set or remove headers deliberately.
- Departing teammate: deny proxy access, revoke the relevant device authority, and test both an existing connection and cached-device reconnect.
- Proxy or identity-provider failure: verify the agreed failure behavior and a separately controlled administrative recovery path.
7. Keep a reviewable operating record
Store the identity mapping, route inventory, grant decisions, enrollment policy, and offboarding evidence with named owners. Review them after identity-provider, proxy, gateway, or client changes.
Accept the integration when the intended team can work and the unwanted access paths fail in observed tests. SSO can centralize sign-in, but it does not replace tool policy, credential management, tenant-boundary design, or deployment-specific compliance review.
Sources and further reading
- OpenClaw: trusted proxy authentication
Checked October 22, 2026 - OpenClaw: security trust model
Checked October 22, 2026 - OpenClaw: device pairing and token revocation
Checked October 22, 2026
Research-assisted writing by Santuri. Technical statements are grounded in the sources above, checked on the dates shown. Deployment requirements depend on your environment and installed version. Workflow examples are illustrations, not customer case studies.
Planning a deployment? Start with our enterprise OpenClaw guide and business workflow examples, or review our deployment approach.