geeViz.eeAuth.server

FastAPI proxy for Earth Engine that injects per-tenant SA tokens.

The proxy receives requests from EE clients (browser JS, Python SDK via geeViz.eeAuth.client), looks up the requested tenant in the SA registry, mints a token (cached), and forwards to the real EE endpoint with the right Authorization and x-goog-user-project headers.

Two ways to use:

  1. Standalone:

    python -m geeViz.eeAuth --port 8888

    or programmatically:

    from geeViz.eeAuth.server import create_proxy_app
app = create_proxy_app()
# serve with uvicorn / etc.

  2. Mounted in an existing FastAPI app:

    from fastapi import FastAPI
from geeViz.eeAuth.server import build_proxy_router

app = FastAPI()
app.include_router(build_proxy_router(), prefix="/ee-api")

Tenant routing — the proxy picks the SA in this order:

  1. X-geeViz-Creds request header (server-side EE SDK; set by geeViz.eeAuth.client.TenantAwareHttp).

  2. ?tenant= query string parameter (browser map iframes).

  3. Default tenant (the registry’s default entry, loaded from GEE_SERVICE_ACCOUNT_B64).

Workload tagging — every POST is stamped with a workload tag ee-proxy__<tenant> in the query string for billing attribution. Pass workload_tag_builder=... to build_proxy_router if you want to construct your own tag (e.g. include user / session).

Functions

build_proxy_router([creds, upstream, ...])

Build a FastAPI APIRouter that handles {path:path} and proxies every request to upstream with the right SA token.

create_proxy_app([creds, upstream, ...])

Build a standalone FastAPI app with the proxy mounted at prefix.
geeViz.eeAuth.server.build_proxy_router(creds=None, upstream: str = 'https://content-earthengine.googleapis.com', tenant_header: str = 'X-geeViz-Creds', tenant_query_param: str = 'tenant', tenant_resolver: Callable[[Request, str], str] | None = None, workload_tag_builder: Callable[[Request, str], str] | None = None) → APIRouter[source]

Build a FastAPI APIRouter that handles {path:path} and proxies every request to upstream with the right SA token.

Parameters:

  • creds – Object exposing get_token(tenant, force_refresh=False) -> {access_token, project_id, tenant, ...}. Accepts an EECreds instance, an SARegistry, or any other object with the same interface. None (default) uses the process-wide env-var registry (legacy).

  • upstream – Base URL of the real EE API. content-earthengine.googleapis.com works for both maps and compute. earthengine.googleapis.com is also accepted for most endpoints.

  • tenant_header – Header name to read for routing. Default X-geeViz-Creds. Must match the client side.

  • tenant_query_param – Query string key to read for tenant routing (browser iframe pattern). Default "tenant". Stripped from the outbound URL so EE never sees it.

  • tenant_resolver – Custom function (request) -> str to pick the tenant. Override for richer auth schemes (e.g. resolve via IAP email lookup). Default reads tenant_header then tenant_query_param.

  • workload_tag_builder – Custom function (request, tenant) -> str that returns the workload tag for billing attribution. Returning "" disables tagging on this request. Default builds ee-proxy__<tenant>.

Mount the returned router on whatever prefix you like — typically /ee-api.

geeViz.eeAuth.server.create_proxy_app(creds=None, upstream: str = 'https://content-earthengine.googleapis.com', tenant_header: str = 'X-geeViz-Creds', tenant_query_param: str = 'tenant', tenant_resolver: Callable[[Request, str], str] | None = None, workload_tag_builder: Callable[[Request, str], str] | None = None, prefix: str = '/ee-api', serve_geeview: bool = True) → FastAPI[source]

Build a standalone FastAPI app with the proxy mounted at prefix. Suitable for direct serving via uvicorn or for testing.

creds accepts an EECreds / SARegistry-like object; None falls back to the env-var registry. See build_proxy_router() for the other parameters.

Use build_proxy_router directly if you want to mount in an existing FastAPI app and share its middleware / lifecycle.

Parameters:

serve_geeview – When True (default for standalone runs), also mount the geeView frontend bundle at /geeView/*. This makes the detached proxy the single long-lived server for both EE auth (/ee-api/*) and Map.view() HTML (/geeView/...). Same origin, same port — browser tabs survive script exits without a daemon-thread server inside each script. Set False to keep the proxy auth-only.