Access Control: maintenance, IP rules, and username and password protection

The Access Control page controls access to an HTTP or HTTPS port through three tabs: IP rules, Username & password, and Maintenance. Open it from the port's menu or filtering settings.

Each tab has an On or Off indicator. IP rules is On when the port has configured IP rules. Username & password and Maintenance follow their respective enable settings. The indicators describe separate controls: an IP allowance does not satisfy password authentication or a maintenance exclusion.

Maintenance

Use Access Control → Maintenance to enable maintenance mode. Eligible requests receive a maintenance page instead of reaching your backend. Turn it off to restore normal backend access.

The default maintenance page works without additional configuration. To customize it, enable the custom page and enter HTML or an optional redirect URL, then choose Submit. The page content and redirect settings are retained independently of the maintenance enable switch. See Error Pages for supported redirect variables.

Maintenance Exclusions opens an ordered IP rule list for clients allowed to reach the backend during maintenance. Without exclusions, maintenance applies to everyone. An exclusion only bypasses maintenance: the main IP rules and any enabled username and password protection still apply.

Existing links to the separate maintenance page open this tab automatically.

IP rules

IP rules allow or deny individual client addresses and CIDR ranges. By default, no custom rules are deployed and IP access is allowed. Other filtering and authentication settings still apply.

HTTP and HTTPS rule ordering

HTTP rules are evaluated from top to bottom. The first matching rule wins. Use the Up and Down actions to retain the intended order, and place specific exceptions before broader rules.

For example:

1) deny   192.168.1.1/32
2) allow  10.1.0.0/16
3) allow  192.168.1.0/24
4) deny   0.0.0.0/0

This denies 192.168.1.1, allows the two listed networks except that address, and denies other IPv4 clients. Add appropriate IPv6 rules when your service uses IPv6.

Choose Add Rule, enter its type, CIDR and optional comment, and save it. Use Test an IP to check how the current IP rules classify a client. An allowed result does not confirm authentication: when password protection is enabled, the tester states that username and password authentication is still required.

Valid credentials never override an IP denial. IP allow rules do not whitelist a client from authentication or bypass other filtering.

Address and CIDR format

CIDR notation combines an IP address with a prefix length:

An IPv4 address without a prefix defaults to /32. Use /128 for an individual IPv6 address. See CIDR for more examples.

TCP and UDP access lists

TCP and UDP ports retain their Layer 4 ACL interface. In Allow mode, only listed addresses or networks can connect. In Deny mode, listed addresses or networks are blocked and other clients can connect. The HTTP maintenance and password tabs do not apply to these ports.

Use Layer 4 Rules for packet inspection, BPF matching, rate limiting, or TCP option matching. For HTTP request matching, see Layer 7 Rules.

Blocklists

Preset IP blocklists cover sources such as TOR exit nodes, VPN providers, and hosting networks. Manage these through the port's filtering settings. They remain separate from the main IP rules and the On/Off badge on this tab. See IP Blocklists.

Username & password

On an HTTPS port, enable protection and choose a sign-in method:

Login Page & Basic Authentication is the default and accepts either method. Visitors do not need to complete both. In combined mode, explicit Basic credentials take precedence over a session cookie; invalid credentials do not fall back to a valid cookie.

Navigation means a GET accepting HTML, with Fetch Metadata indicating navigation when supplied. An unauthenticated POST is rejected without forwarding its body or replaying it after login. Login pages never add a Basic challenge of their own.

Allowed users and saving

All users have the same access to the protected port. Choose Add user and enter a unique, case-sensitive username, password, and optional comment. Usernames are immutable. They cannot contain :, control characters, or start with #.

Passwords are write-only and stored as bcrypt hashes. They must contain 1–72 bytes (multibyte characters can use more than one byte). Show/Hide only reveals a password currently being entered. Configured means a saved password exists; it cannot be retrieved. Use Change password to replace it or Remove to delete the user.

Removing a saved user opens a confirmation with Revoke all authorised tokens unticked by default, preserving other users' sessions. Tick it to also sign out everyone else on this port; the removed user's sessions become invalid either way. Removal and optional revocation happen together when you Save changes, as deployment reaches each edge. Discard cancels both.

Changes remain staged until Save changes. Discard restores saved values and clears entered passwords. At least one user is required while HTTPS protection is enabled. Turning protection off retains saved users and preferences.

Portal passkeys

Portal passkeys let an allowed user sign in to the protected website with a device PIN, biometrics, or a security key instead of entering their password. They belong to that port user: adding one does not register a passkey for an X4B dashboard account or for your backend application's own login. Register credentials separately for each protected port user.

Requirements

• Select Login page mode. Passkeys are not available in Basic Authentication or Login Page & Basic Authentication, even though the combined method includes a login page.
• Use a configured HTTPS hostname with a working certificate. Enrollment does not support a raw IP address. The passkey is registered for the protected hostname, not the dashboard hostname.
• Save the allowed user and authentication settings first. Each user may have up to five passkeys. A password is still required when creating the user and remains available for fallback sign-in.
• Use a browser and authenticator that support passkeys, and allow JavaScript and first-party cookies on the protected site.

Add a passkey

1. On the HTTPS port, open Access Control → Username & password, enable protection, select Login page, and add the allowed user if needed. Choose Save changes and allow the deployment to finish.
2. In the saved user's row, enter a recognizable passkey label, such as Work laptop, and choose Add passkey. Save or discard any pending edits before starting.
3. The enrollment page opens on the protected hostname. Choose Create passkey and complete your device or security-key prompt. If the popup is blocked, use the displayed Open enrollment link in the same browser.
4. Complete enrollment within two minutes, using the same browser and source IP address that started it. Keep the dashboard session available. The link is not an invitation to forward to another person or device; changing networks or enabling a VPN can invalidate it. If it expires or fails after settings change, start again with Add passkey.
5. Confirm Passkey saved and the new entry in the user's row. Enrollment saves the key immediately; it becomes usable as the configuration update reaches each edge.

Sign in and manage access

Visit the protected site and choose Sign in with a passkey on its login page. The button appears when passkeys are available for the port and supported by the browser. Complete the authenticator prompt; password sign-in remains available if the key is unavailable or the prompt is cancelled. Passkey sign-in uses the port's configured session expiry and revocation policy.

To remove a key, choose Remove passkey beside its label and then Save changes. Removal is staged until saved; Discard cancels it. Once deployed, the removed key can no longer sign in and that user's existing login-page sessions are invalidated. Other users' sessions are unaffected unless you also request port-wide revocation.

If a device is lost, remove its passkey and use the user's password or another registered key to regain access. If neither is available, ask an authorized administrator to replace the password. Changing a password or revoking sessions does not delete registered passkeys; remove a lost or compromised key separately so it cannot sign in again.

Switching to Basic or combined mode retains saved passkeys but makes them unavailable for sign-in. Switching back to Login page makes compatible saved keys available again. A key registered for a different hostname cannot authenticate the new hostname; enroll a new key there.

Session expiry and logout

Login-page sessions default to Rolling / 7 days. Choose Rolling or Fixed and a validity of 1 hour, 8 hours, 1 day, 7 days, or 30 days. Session controls are hidden for Basic-only authentication.

• Fixed: expires after the selected duration from sign-in.
• Rolling: renews on authenticated activity, at most once per minute, with no absolute session-age limit.

Replacing a password revokes that user's sessions; removing a user invalidates that identity. Changing the sign-in method or session policy, or disabling and re-enabling protection, invalidates the port's existing sessions. These changes take effect as ordinary configuration deployment reaches each edge.

Use Revoke all sessions to sign out every login-page session for this port while keeping saved users and passwords. Save or discard pending edits first. Revocation rotates a random per-port security ID and deploys it through the normal configuration process; each edge rejects earlier tokens once it receives the update. Other ports keep their sessions, and visitors can sign in again with their existing credentials.

Visit /cdn-bin/x4b/auth/logout for the confirmation form. Logout uses a protected POST and clears this browser's session cookie. It does not clear browser-cached Basic credentials or revoke copied tokens. An actively renewed rolling token can remain usable until a credential, configuration, or signing-key change revokes it.

HTTPS and application credentials

Plaintext HTTP protection requires a protected HTTPS counterpart on the same service and hostname. Select that destination and manage its users and authentication preferences on the HTTPS port. Safe HTML navigation redirects there; insecure credential submissions and unsafe requests are rejected. Disable dependent HTTP entrypoints before disabling their HTTPS destination.

Edge Basic credentials and this feature's cookies are removed before proxying. Unrelated application authorization and cookies are retained. An upstream application cannot independently use the same Authorization header for its own Basic credentials while edge Basic Authentication is enabled.

Custom login pages

Use the dedicated Login page entry in Error Pages, internal identifier 525. It serves HTML with HTTP 200 and does not allow external redirect overrides. The override contract documents the POST form fields and the shared portal script that supplies CSRF context and the local return destination. Custom pages need that integration for password sign-in and the optional passkey control.

The default template shows Incorrect username or password. when its URL contains #login-failed, on initial loading and when the fragment changes. Custom templates should support the same fragment.

API access

APIv2 HttpOption/get_authentication and POST-only HttpOption/save_authentication use existing service permissions and a port ID. Save accepts value as an object or JSON-encoded object containing the current revision and settings. A complete users list may be included for an atomic staged save; omitting it preserves existing users.

POST HttpOption/revoke_authentication with port set to the protected HTTPS port ID revokes all of that port's current login-page sessions. It requires service write permission, takes effect through normal deployment, and returns the current settings and user summaries with a new revision. Use that revision for later settings saves. No settings or password changes are submitted by this action.

For an atomic user removal and revocation, include revoke_sessions: true in the value object sent to HttpOption/save_authentication, together with the current revision and the remaining users. This optional write-only field must be a boolean and defaults to false.

HttpAuthentication/all lists users for query.port. get, POST-only update, and POST-only delete require query.port and query.id. POST-only create accepts value.port, username, password, and optional comment. Update accepts a replacement password or comment; usernames remain immutable. Each port permits at most 50 users. Passwords are write-only. Disable protection before removing its last user.

Portal passkey enrollment uses POST-only HttpAuthentication/passkey_begin and HttpAuthentication/passkey_finish, with query.port and query.id identifying a saved user. Begin accepts an optional label and local dashboard return_path; finish accepts the browser's WebAuthn credential object. Enrollment still requires the same browser, source IP, protected hostname, and two-minute window described above; it is not a server-to-server credential-creation API.

User responses include a passkeys list with each key's id, label, and rp_id. To remove keys, send their IDs in value.remove_passkeys through HttpAuthentication/update, or include remove_passkeys in the corresponding user record in an atomic HttpOption/save_authentication save. Private keys are held by the authenticator and are never sent to these management endpoints.

Login-page password checks produce success/failure events in HTTP error logs, including the configured username (or an unknown-user indicator). Basic checks, rejected CSRF requests, and throttled submissions do not produce login outcome events.

User fields are id (existing users only), username, comment, and an optional new or replacement password. Responses include password_configured; passwords and hashes are never returned.