Skip to content

v0.2.0

Choose a tag to compare

@github-actions github-actions released this 14 Nov 21:36
· 142 commits to main since this release
d7db92b

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 main and 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 plain X-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 Authorization once 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.

  • 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 act and counts in byward_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 as OTEL_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_FILE or …_FEDERATED_TOKEN_FILE. Two together stop startup.
  • Strict-Transport-Security is now sent when BYWARD_PUBLIC_URL is https.
  • A request with a top-level id in 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: initialize is refused too, with data.downstream naming 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_ROLES if 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.0

latest 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_DENYLIST refuses 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 with byward revoke-user for its users, or with byward 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 Python mcp 1.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:
    • The access gate can't read roles or groups from Auth0's namespaced claims (#286); gate by email domain instead.
    • A wrong client secret shows as "the user declined to sign in", with no IdP alert (#315).
  • 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.


Changelog