Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 12 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -167,10 +167,14 @@ The issuer has to match exactly, because it's compared against the `iss` claim o
inbound token. The resource URL has to differ from the issuer; startup refuses otherwise,
since equal audiences would let a token minted for one resource be accepted by the other.

Both must use `https` unless they point at loopback. The client secret travels to the issuer
as HTTP Basic and the resource URL is this server's advertised identity, so cleartext to a
remote host is refused at startup. `OPENOPS_API_URL` is exempt, because tool calls are
pod-to-pod inside a cluster.
Both must use `https` unless they point at loopback. They are published to clients: the
issuer through discovery and as the `iss` every token carries, the resource URL as this
server's advertised identity, so cleartext to a remote host is refused at startup.

The issuer is never dialled. The signing keys and the token exchange are fetched from
`OPENOPS_API_URL`, the same internal route tool calls take, so it has to name the API
instance the issuer stands for. That is also why `OPENOPS_API_URL` is exempt from the
`https` rule: everything sent to it stays inside the cluster.

## Docker

Expand All @@ -193,10 +197,10 @@ docker run --rm -p 3020:3020 \
defaults. The environment comes from `uv.lock` with the same `uv sync --frozen --no-dev` CI
runs; the Dockerfile explains the rest of its choices inline.

To test against an API on your machine, the issuer has to be `localhost`, and inside a
container that's the container. Run with `--network host` (on Docker Desktop, enable it under
Resources → Network) and point `OPENOPS_API_URL` and `OPENOPS_MCP_ISSUER` at
`http://localhost:3000`.
To test against an API on your machine, point `OPENOPS_API_URL` at where the container can
reach it (`http://host.docker.internal:3000` on Docker Desktop) and keep `OPENOPS_MCP_ISSUER`
at the public `http://localhost:3000` the API is configured with. The issuer is only compared
against tokens, so it does not matter that `localhost` inside the container is the container.

Published images (multi-arch, amd64 and arm64) come from the Publish workflow: releases go to
`openops.azurecr.io/openops-mcp:<version>` (and `latest`), pullable anonymously; pushes to
Expand Down
8 changes: 5 additions & 3 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -144,9 +144,11 @@ that doesn't exist. For the same reason an ingress must not rewrite the mount pa
prefix makes the advertised resource and the actual audience diverge.

`OPENOPS_MCP_ISSUER` and `OPENOPS_MCP_RESOURCE_URL` have to be `https` unless they name
loopback. The first receives the client secret as HTTP Basic, and the second is the identity
this server advertises. `OPENOPS_API_URL` is exempt, since tool calls stay inside the cluster
and only the OAuth endpoints are public.
loopback. Both are published to clients: the first through discovery and as the `iss` every
token must carry, the second as the identity this server advertises. Neither is dialled. The
signing keys and the token exchange come from `OPENOPS_API_URL`, the same internal route tool
calls take, which is why that one is exempt and why a public URL of `http://localhost` (this
container, from the inside) still authenticates.
Comment thread
ravikiranvm marked this conversation as resolved.
Resolved

**Exchanging it.** The client's token is addressed to this server rather than the API, so it's
never forwarded, following the MCP authorization spec's no-token-passthrough rule.
Expand Down
7 changes: 4 additions & 3 deletions openops_mcp/auth/oauth.py
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
"""HTTP authentication: verify the caller, then act as them against the API.

Inbound tokens are verified locally against the authorization server's published keys,
so no request costs a round trip to it. The verified token is then exchanged for a
separate API-audience token, which is what reaches the API — the caller's own token
never does.
so no request costs a round trip to it. The keys are fetched from the API over its
internal URL; the public issuer is only what the `iss` claim is checked against. The
verified token is then exchanged for a separate API-audience token, which is what
reaches the API — the caller's own token never does.
"""

from __future__ import annotations
Expand Down
17 changes: 12 additions & 5 deletions openops_mcp/config.py
Original file line number Diff line number Diff line change
Expand Up @@ -58,20 +58,27 @@ class StdioSettings:
@dataclass(frozen=True)
class HttpSettings:
common: CommonSettings
# The authorization server's public identity: what the `iss` claim on every token
# must equal and what discovery metadata advertises. It is never dialled.
issuer: str
resource_url: str
client_secret: str
host: str = DEFAULT_HTTP_HOST
port: int = DEFAULT_HTTP_PORT
transport: Transport = "http"

# The OAuth endpoints live on the same API the tools call, so they are reached over
# the same internal route. Going through the public issuer instead fails wherever
# this container cannot reach its own public URL: with OPS_PUBLIC_URL=http://localhost
# that address is this container, and a private ingress or a network without hairpin
# NAT is no better.
@property
def jwks_uri(self) -> str:
return f"{self.issuer}/v1/oauth/jwks.json"
return f"{self.common.api_url}/v1/oauth/jwks.json"

@property
def token_endpoint(self) -> str:
return f"{self.issuer}/v1/oauth/token"
return f"{self.common.api_url}/v1/oauth/token"


Settings = StdioSettings | HttpSettings
Expand All @@ -97,10 +104,10 @@ def _require_url(name: str, env: dict[str, str]) -> str:


def _require_public_url(name: str, env: dict[str, str]) -> str:
"""A URL that leaves the cluster, so cleartext is only acceptable to loopback.
"""A URL published to clients, so cleartext is only acceptable to loopback.

The client secret travels to the issuer as HTTP Basic, and the resource URL is
advertised to clients as this server's identity. The API applies the same rule.
The issuer is what clients discover and what every token's `iss` must match, and the
resource URL is advertised as this server's identity. The API applies the same rule.
"""
value = _require_url(name, env)
parsed = urlparse(value)
Expand Down
36 changes: 29 additions & 7 deletions tests/unit/test_config.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,8 @@

HTTP_ENV = {
"MCP_TRANSPORT": "http",
"OPENOPS_API_URL": "https://app.example.com/api",
# The address this server reaches the API at, distinct from the public issuer.
"OPENOPS_API_URL": "http://openops-app/api",
"OPENOPS_MCP_ISSUER": "https://app.example.com/api",
"OPENOPS_MCP_RESOURCE_URL": "https://app.example.com/mcp",
"OPENOPS_MCP_CLIENT_SECRET": "s" * 32,
Expand Down Expand Up @@ -50,12 +51,30 @@ def test_treats_whitespace_as_missing(self) -> None:


class TestHttp:
def test_builds_settings_and_derives_the_oauth_endpoints(self) -> None:
def test_builds_settings_and_derives_the_oauth_endpoints_from_the_api_url(self) -> None:
# The issuer is what tokens are checked against; the keys and the exchange come
# from the API over the same route tool calls take.
settings = load_settings(HTTP_ENV)

assert isinstance(settings, HttpSettings)
assert settings.jwks_uri == "https://app.example.com/api/v1/oauth/jwks.json"
assert settings.token_endpoint == "https://app.example.com/api/v1/oauth/token"
assert settings.issuer == "https://app.example.com/api"
assert settings.jwks_uri == "http://openops-app/api/v1/oauth/jwks.json"
assert settings.token_endpoint == "http://openops-app/api/v1/oauth/token"

def test_reaches_the_api_even_when_the_public_url_is_loopback(self) -> None:
# A compose install with OPS_PUBLIC_URL=http://localhost: inside this container
# localhost is this container, so the issuer must never be dialled.
settings = load_settings(
{
**HTTP_ENV,
"OPENOPS_MCP_ISSUER": "http://localhost/api",
"OPENOPS_MCP_RESOURCE_URL": "http://localhost/mcp",
}
)

assert isinstance(settings, HttpSettings)
assert settings.jwks_uri == "http://openops-app/api/v1/oauth/jwks.json"
assert settings.token_endpoint == "http://openops-app/api/v1/oauth/token"

def test_defaults_the_bind_address(self) -> None:
settings = load_settings(HTTP_ENV)
Expand Down Expand Up @@ -161,8 +180,9 @@ class TestTransportSecurity:
"name", ["OPENOPS_MCP_ISSUER", "OPENOPS_MCP_RESOURCE_URL"]
)
def test_refuses_cleartext_to_a_remote_host(self, name: str) -> None:
# The client secret travels to the issuer as HTTP Basic, and the resource URL is
# advertised to clients. The API refuses this configuration too.
# Both are published to clients: the issuer in discovery metadata and as the `iss`
# every token must carry, the resource URL as this server's identity. The API
# refuses this configuration too.
with pytest.raises(ConfigError, match="https"):
load_settings({**HTTP_ENV, name: "http://app.example.com/elsewhere"})

Expand All @@ -181,7 +201,9 @@ def test_allows_cleartext_to_loopback_for_local_development(self, issuer: str) -
assert settings.issuer == issuer

def test_still_allows_a_cleartext_api_url(self) -> None:
# Tool calls are pod-to-pod inside a cluster; only the OAuth endpoints are public.
# Tool calls, the key fetch and the token exchange are all pod-to-pod inside a
# cluster; only the identities above are public.
settings = load_settings({**HTTP_ENV, "OPENOPS_API_URL": "http://openops-api:3000"})

assert settings.common.api_url == "http://openops-api:3000"
assert settings.jwks_uri == "http://openops-api:3000/v1/oauth/jwks.json"
Loading