Authentication

Wirebench separates two kinds of authentication: request auth — credentials attached to the HTTP request itself, on the Auth tab or inspector — and WS-Security, which signs or encrypts parts of a SOAP envelope. Client certificates cover a third case: proving your identity at the TLS layer, before any request-level auth applies. Every credential you type goes through the secret store; see Secrets for what that means.

Request auth (REST and SOAP)

A REST request, folder or API — and a SOAP interface, endpoint or request — can each configure their own auth. Every scheme below is available at all six levels.

Scheme	Fields
Basic	Username, password, and send credentials preemptively (skip waiting for a 401)
NTLM	Username, password, domain, workstation
Bearer token	Token, and the scheme word sent before it (default `Bearer`)
API key	Name, value, and whether it’s sent as a header or a query parameter
OAuth 2	See below
Kerberos	Your Windows sign-in or `kinit` ticket; optional SPN; on Windows, another account

Open the request, folder or API and go to its Auth tab.
Pick a type from the dropdown, or leave it on Inherit (REST) or Not configured (SOAP) — REST requests and folders show what they’d inherit from, right above the form.
Fill in the fields. Anything that stores a secret (password, token, client secret) opens the secret entry dialog instead of a plain text box.

A SOAP request’s Auth inspector also reports which level actually supplies the credentials it will send — its own, its endpoint’s, or its interface’s — so you can tell at a glance why a request authenticates the way it does.

SOAP: request, endpoint, interface

SOAP has no Inherit type: the endpoint’s mode decides how a request and its endpoint combine, and the interface’s credentials apply when neither configures any. An endpoint in Override mode replaces the request’s credentials with its own whenever it has some. In Complement mode, the request’s own credentials come first. If both sides are Basic or NTLM, the endpoint fills in only the fields the request leaves blank. With any other scheme, the endpoint’s credentials apply only when the request has none, or has None.

A Bearer token or header API key is added to the HTTP request, next to the SOAP headers. An explicit Authorization header on the request still wins, so a request never sends two credentials. A query-string API key is appended to the endpoint URL; the envelope, and its WS-Addressing To, are unchanged. The key is masked everywhere Wirebench shows the URL (History, the HTTP log, HAR exports), and a cURL export includes it only while show-secrets is on. OAuth 2 works as described below, with the token status panel under the fields.

WS-Security is separate and combines with any of these schemes.

Folder-level auth (REST)

A REST folder has no editor tab of its own, so its credentials live behind a dialog: right-click the folder and choose its auth entry. It configures the same form as a request or an API, and every request in that folder that inherits picks it up.

OAuth 2

Two grants are supported:

Client credentials — a token URL, client ID and client secret; Wirebench requests a token directly, no browser involved.
Authorization code, with optional PKCE (on by default) — Wirebench opens your browser to the authorize URL and completes the flow through a local loopback listener. Register the redirect URI the status panel shows with your OAuth provider; if it needs a fixed port rather than a random one, set it under Preferences → REST.

Both grants also take scopes (space-separated), an audience, and whether the client is authenticated with a Basic header or in the request body.

The status panel below the fields shows whether a token is held and when it expires. Get token starts the flow (or requests one directly, for client credentials); Clear discards the held token. The token value itself is only shown when the session’s show-secrets switch is on — otherwise the panel just says a token exists and when it expires.

Turn on Remember the refresh token to keep a refresh token in the secret store across sessions, so re-opening the project doesn’t force a fresh sign-in. Turning it off deletes the stored refresh token.

The CLI runner (wirebench run) obtains a client-credentials token itself, for REST, gRPC and SOAP alike, reading the client secret from the request’s environment variable. It refuses the authorization-code grant, since a pipeline has no browser to sign in with.

Kerberos

Kerberos gives single sign-on to servers that use HTTP Negotiate: Wirebench sends the ticket of the account you are signed in with, and you type no password. On Windows that is your domain sign-in. On macOS and Linux, get a ticket first with kinit user@REALM; Wirebench reads the ticket cache the same way any other Kerberos client on the machine does.

How the token is sent depends on where it goes:

REST and SOAP requests use two legs on one connection. Wirebench sends the request, and only after the server answers with a Negotiate challenge does it send the token. When the server’s answer carries a reply token, Wirebench verifies it (mutual authentication). There is no preemptive mode for these requests. Once a challenge succeeded, a SOAP response line reads “Authenticated with Kerberos as” and the SPN, in the platform’s form (HTTP/host on Windows, HTTP@host elsewhere); the REST status line does not change. When the request follows a redirect before the server challenges, the token is made for the host that challenged and sent straight to it, with the method and body that host received (a 302 or 303 turns a POST into a bodyless GET). That host must be on the request’s own origin: a challenge from a redirect target on another origin gets no token, and the send fails with kerberos-cross-origin, naming that target. NTLM follows the same rule, failing with ntlm-cross-origin. A same-host http:// → https:// upgrade is not another origin for this rule: the handshake continues on the https:// URL.
Definition fetches (OpenAPI, AsyncAPI, WSDL) send one preemptive token, to the definition’s own origin only, never to a redirect target on another origin.
WebSocket upgrades and gRPC calls send one preemptive token.
Webhooks do not offer Kerberos.

Service principal name (SPN). Leave it blank and Wirebench asks for HTTP plus the URL’s host name, without the port. Set it when the URL is an alias (a load-balancer name or a CNAME), or when the service is registered under another name; use the name the service is registered under. Write it as HTTP/host. Wirebench converts it to the form the platform expects (HTTP/host on Windows, HTTP@host elsewhere), and on macOS and Linux an HTTP/host@REALM is accepted with the realm dropped.

Use another account (Windows only). Fill in a username, a domain and a password, which is kept in the secret store like any other. Blank fields count as unset. macOS and Linux refuse an explicit account with kerberos-explicit-credentials-unsupported; run kinit user@REALM there instead.

Kerberos is the only mechanism. Nothing falls back to NTLM, so if the server needs NTLM, choose NTLM instead. Kerberos is not available on Windows on ARM. On Linux, Kerberos needs the deb, rpm or AppImage build: the snap’s confinement keeps it away from /etc/krb5.conf and the ticket cache, so Kerberos is not supported there. It also needs the system’s GSSAPI library (libgssapi-krb5-2 on Debian and Ubuntu, krb5-libs on Fedora and RHEL), which the deb and rpm install as a recommended package; an AppImage uses the one already on the machine. Where the Kerberos support cannot load, the type is shown disabled with the reason.

A cURL export of a REST or SOAP request uses curl --negotiate -u :. A gRPC or WebSocket command export leaves Kerberos out and says so in a note.

Waiting for a ticket counts against the request’s own timeout, and Cancel stops the wait at once. For a WebSocket, that is the handshake timeout. For gRPC it is the deadline, and for a definition download, the 20-second limit on each request.

Code	Message	Fix
`kerberos-unavailable`	The reason Kerberos support could not load.	Use a build for a supported platform (not Windows on ARM; on Linux the deb, rpm or AppImage build, not the snap). On Linux, install the GSSAPI library if the reason names it.
`kerberos-explicit-credentials-unsupported`	Explicit Kerberos credentials are Windows-only. Run `kinit user@REALM` and leave username and password empty.	Clear the username and password, and run `kinit`.
`kerberos-no-credentials`	No Kerberos ticket. Sign in to the domain, or run `kinit`.	Sign in to the domain, or run `kinit user@REALM`, then send again.
`kerberos-unknown-spn`	The KDC does not know the SPN. Set the SPN to the name the service is registered under. Also shown for a blank or unparseable SPN.	Set the SPN to the registered name, or clear it to use the default.
`kerberos-clock-skew`	This machine’s clock differs from the domain’s by more than allowed.	Sync the system clock.
`kerberos-mutual-auth-failed`	The server’s Kerberos reply could not be verified.	Check that the server is the service the SPN names.
`kerberos-rejected`	The server at the URL that challenged refused the Kerberos token (HTTP 401).	Ask the service owner whether your account may use it.
`kerberos-cross-origin`	A redirect target on another origin asked for Kerberos; credentials go to the request’s own origin only.	Send the request to the URL the message names.
`kerberos-failed`	Kerberos failed, with the operating system’s own text.	Read the text; it is what the OS reported.
`timeout`	Timed out waiting for a Kerberos ticket for the SPN.	Check that this machine can reach the domain’s KDC, or raise the request’s timeout.
`kerberos-failed` (busy)	Kerberos is still waiting on earlier requests to the Kerberos server; try again shortly.	Wait for the KDC to answer or time out, then send again.

WS-Security (SOAP)

WS-Security lives in its own sidebar view, WS-Security, alongside Keystores (see below). A project holds a list of Outgoing configurations, each an ordered list of entries applied to a request’s envelope before it’s sent:

Timestamp — a Created/Expires window, with a configurable time-to-live.
Username Token — a username and password (plain text or digest), optionally with a nonce and a Created timestamp.
Signature — signs the parts you choose (Body and Timestamp by default) using a keystore’s private key, with a choice of algorithm and canonicalization.
Encryption — encrypts the parts you choose using a keystore, with a choice of symmetric and key-transport algorithm.
SAML token — places a SAML assertion, built from a form or supplied as XML; see SAML tokens.

Open the WS-Security view in the activity bar.
Add or select an Outgoing configuration, then add entries with Add and reorder them with the up/down arrows — order matters, since a signature normally has to cover a timestamp that was already added.
Assign the configuration to the interface, endpoint or request that should apply it.
A Username Token’s password is entered through the same secret dialog as any other credential; only its reference is ever saved to the project.

From the WSDL’s security policy

When the WSDL attaches a WS-SecurityPolicy to an operation, the request’s Auth inspector shows what it asks for: the tokens, which parts are signed and encrypted, the algorithm suite, whether TLS is required and whether a timestamp is included. A badge next to it says Satisfies policy, or how many requirements the request does not meet yet, with each one listed underneath. It follows every change to the selected configuration and to the endpoint.

Apply policy creates an outgoing configuration named after the operation (Add policy, say) with the entries the policy needs, in the order it needs them, and selects it for the request. Keystores, usernames and passwords are left for you to fill in, in the WS-Security view. Applying again refreshes that configuration and keeps what you filled in.

Some policies ask for more than a configuration can express: a symmetric binding, parts named by XPath, a Kerberos token. Those are listed as unmet, so the badge never claims a fit it cannot check.

An Incoming configuration works the other way: it states what a response must satisfy — a valid signature, a decrypted body, a timestamp within tolerance — so a response that doesn’t meet it is flagged rather than silently accepted.

Why a response failed, and what a request will send

The response pane’s WSS inspector explains a failure instead of only reporting it:

A signature that does not verify lists every part it signed. For each part it shows whether the digest matched, the transforms and digest algorithm used, and for a part that changed, the digest the message carries beside the one computed from what arrived. When every part matches but the signature itself does not, it says so: the signed information was changed, or the message names the wrong certificate.
A signer that cannot be found names what the message asked for: the token id, the thumbprint or subject key identifier, or the issuer and serial number to look up in the truststore.
A message that cannot be decrypted names the certificate it was encrypted for beside the one the decryption keystore holds.
A timestamp shows the clock skew in seconds and how much is tolerated.
Security header lists the header step by step in header order: the timestamp, each token, each signature with what it covers, and each encryption with what it hides. Senders that follow the WS-Security standard add each step at the top, so their last step is usually listed first.

Under Outgoing, Preview secured request applies the request’s outgoing configuration to the envelope on screen and shows the result without sending it or changing the editor. The steps are listed in the order they were applied, and passwords are masked. An issued token is not fetched for a preview; a placeholder stands in for it.

Client certificates and keystores

Under WS-Security → Keystores, add a PKCS#12 (.p12) or PEM keystore. Each row shows whether it loaded (a wrong password shows as Wrong password, a missing file as File missing), and its certificate aliases once it did. A keystore’s password is entered through the secret dialog, same as any other credential — Wirebench holds no key material or password in the renderer.

Keystores serve two purposes:

WS-Security signing and encryption — a Signature or Encryption entry above references one.
TLS client certificates — under Preferences → SSL, set a Client keystore to present by default whenever a server asks for one. A request can also select its own keystore, which always wins over the default.

The SSL inspector on a sent request’s response shows the negotiated protocol, cipher, and the peer’s certificate chain, including expiry — and, when a client certificate was presented, its subject. A certificate that expires within the warning window reads in amber, one that has expired in red.

Certificate expiry warnings

Wirebench warns before a certificate your workspace relies on runs out. Every expired certificate is an error in Problems, and every one that expires within the warning window (30 days by default; Preferences → SSL → Expiry warning) is a warning, so the problem count in the status bar shows it wherever you are. Each row names the certificate’s subject, the days left, and where it is: a keystore and alias, the CA bundle, or an endpoint’s host:port.

Keystores and the CA bundle are checked on their own — when a workspace opens, when a keystore is added or changed, and when the warning window changes. This only reads files on your machine.
Endpoints are checked when you run Check Certificate Expiry from the command palette. Wirebench reaches every TLS endpoint the open projects name — SOAP endpoints, REST base URLs and servers, WebSocket and gRPC targets, and the endpoint overrides of every environment, with ${…} properties resolved under each one — and reads the chain each presents. It opens a TLS connection through the proxy a send would use, verifies the chain as a send would (including your CA bundle), and closes it once the certificates arrive; no request is sent. Each host:port is reached once, however many projects name it. An endpoint whose chain doesn’t verify — already expired, untrusted, or issued for another host — is an error in Problems with the reason. An endpoint that doesn’t answer is listed in the summary rather than in Problems.

Secrets — how passwords, tokens and keystore passphrases are stored, and what never leaves your machine.
Environments and properties — reference a variable from an auth field, for example a per-environment API key.
SOAP and WSDL — endpoints and interfaces that auth attaches to.