Repository navigation
v0.2.0
byward v0.2.0
byward puts any MCP server, HTTP or stdio, behind OAuth 2.1 and your identity provider: Microsoft Entra ID first-class, and now Okta, Keycloak, Google, Auth0 or any other OpenID Connect provider.
Pre-1.0, and no independent security audit yet. Read the security posture before deploying it.
If you run v0.1.x, upgrade. Several fixes below also apply to v0.1.0 and v0.1.1 and are not backported. Notably, with a malformed HTTPS_PROXY or HTTP_PROXY setting (credentials with an unescaped /, ? or #), byward's logs could show part of the proxy's credentials.
The code is the same as v0.2.0-rc.1; only the docs changed since.
New
-
Any OIDC identity provider, with presets for Okta, Keycloak, Google and Auth0, each verified in a live sign-in run. Guides: any OIDC IdP and its presets and Keycloak. Step-by-step Okta, Google and Auth0 guides are on
mainand come with v0.3. -
The upstream knows who the user is. Every request carries a signed identity assertion (an ES256 JWT, valid for 60 s,
aud= the upstream). Its keys are published for verifiers that use discovery (jwks_uri). An upstream that can't verify a JWT can use plainX-Byward-*identity headers instead. An email is asserted only when the IdP verified it. -
On-Behalf-Of tokens for downstream APIs. byward exchanges the user's sign-in for a token to an API such as Microsoft Graph, and hands it to the upstream:
- for an HTTP upstream, in a header (it may be
Authorizationonce the assertion has moved); - for a stdio upstream, over a per-process token socket.
A missing admin consent is reported to the operator with the admin-consent URL. Guide: Microsoft 365 data for each signed-in user.
- for an HTTP upstream, in a header (it may be
-
Entra app-only tokens for headless callers, gated by app roles and an optional client allowlist, and cut off with
byward revoke-user. -
More Entra credentials: a certificate, or a federated token file (workload identity), instead of a client secret. Set exactly one of the three. A scheduled real-Entra CI lane checks the federated path every night.
-
stdio upstreams in the modern MCP era:
- one upstream process per user;
subscriptions/listen;- keep-alive on long-lived streams;
- quiet streams give up their process when the process cap is full.
-
Operator controls:
- the operator's own credential for the HTTP upstream;
- a list of request headers stripped before the upstream (DPoP is always stripped);
- a warning when an HTTP upstream gets tokens over plain http at a public address.
-
IdP alerts: an IdP error only the operator can fix (a rejected or unusable credential, a protocol error) logs
IdP alert: the operator must actand counts inbyward_idp_alerts_total. -
Strict-Transport-Security on every answer when the public URL is https.
Fixed
- Logs never show part of a malformed proxy setting: not from the relay, the IdP calls,
byward doctor's self-probe or trace export (#240, #252, #258). - OpenTelemetry's own messages about a rejected
OTEL_*setting no longer print the value, such asOTEL_EXPORTER_OTLP_HEADERS, to stderr (#267). - Redaction: a Bearer or Basic credential is redacted, not an auth method name that ends in "basic" (#242). A JWT is recognised by its shape (#230).
- A typed-nil or panicking error or Stringer never panics the logger (#239).
- The stdio token socket reads a refused peer's request before answering (#244).
- Built with Go 1.27.4 (GO-2026-6859), as v0.1.1 was.
Upgrade notes
- Only one Entra credential may be set:
BYWARD_ENTRA_CLIENT_SECRET_FILE,…_CERTIFICATE_FILEor…_FEDERATED_TOKEN_FILE. Two together stop startup. - Strict-Transport-Security is now sent when
BYWARD_PUBLIC_URLis https. - A request with a top-level
idin another letter case is refused. - With On-Behalf-Of on, a user without a downstream token (for example, because admin consent is missing) can't open an MCP session at all:
initializeis refused too, withdata.downstreamnaming the reason (downstream APIs). - Granting admin consent through the admin-consent URL also assigns the consenting admin to the app with default access. Set
BYWARD_GATE_ROLESif only role holders may sign in.
Verified
Against a real Entra tenant on 2026-11-13, on this code:
- the identity assertion;
- On-Behalf-Of to Microsoft Graph over HTTP and stdio (consent missing, then granted);
- app-only tokens, with the allowlist and revocation;
- the certificate credential;
- IdP alerts.
Okta, Keycloak, Google and Auth0 were each verified in a live sign-in run on v0.2.0-rc.1.
| Client | How it registers |
|---|---|
| Claude Code 2.1.311 | CIMD (or a static client) |
| claude.ai | CIMD |
| ChatGPT (developer mode) | CIMD |
| VS Code 1.142.0 | CIMD |
| Cursor 3.29.9 (2.6.22 does not work) | DCR |
The TypeScript, Python and Go MCP SDK clients and MCP Inspector run against byward in CI on every change. The MCP conformance authorization suite runs against the broker.
Install
docker pull ghcr.io/byward-dev/byward:v0.2.0latest now points at v0.2.0. Verify the release as in packaging.
Known gaps
All of these except the first are fixed on main, for v0.3.
- OpenTelemetry SDK settings (
OTEL_RESOURCE_ATTRIBUTES,OTEL_TRACES_SAMPLER_ARG, attribute limits) can echo a malformed value in logs. One of them does so at startup, from an OpenTelemetry package byward can't intercept (#274). - Denying an app doesn't end its grants (#338).
BYWARD_CLIENT_DENYLISTrefuses new sign-ins, but an app that already signed in keeps refreshing until its grant ends (at most 30 days). Until v0.3, cut it off withbyward revoke-userfor its users, or withbyward revoke-all. - After
byward revoke-user, an app-only caller stays out only once the tokens it already holds expire (up to about an hour): Entra keeps returning them. - No refresh token for some SDK clients (#287). Clients that don't ask for
offline_access, such as Pythonmcp1.x and the TypeScript SDK 1.x, sign in again every hour. Claude Code, claude.ai and VS Code ask for it and aren't affected. - Okta with
private_key_jwt: an RSA key signs with PS256, which Okta refuses. Use an EC P-256 key with Okta (#306). - Auth0:
- With
--dev, an http IdP issuer on loopback isn't listed among the startup log's relaxations (#355).
MCP is a trademark of LF Projects, LLC. byward is an independent project.