Skip to content

Tips

CORS

By default, the STAC Auth Proxy handles CORS locally. OPTIONS preflight requests are answered directly by the proxy, and CORS headers are included on all responses — including 401 and 403 errors — so that browser clients can read error details. This behavior is configured with the CORS_* environment variables (see Configuration).

The defaults are designed to work out of the box for browser-based clients that send Authorization headers:

  • CORS_ALLOW_ORIGINS=* — all origins are accepted
  • CORS_ALLOW_CREDENTIALS=true — required because frontends will send Authorization headers
  • CORS_ALLOW_METHODS=* and CORS_ALLOW_HEADERS=* — all methods and headers are accepted

Because the CORS specification forbids Access-Control-Allow-Origin: * when credentials are enabled, the proxy automatically reflects the request's Origin header back in the response instead of sending a literal *.1

To restrict access to specific origins:

CORS_ALLOW_ORIGINS=https://my-app.example.com,https://staging.example.com

Upstream CORS handling

If you prefer the upstream API to handle CORS instead, set PROXY_OPTIONS=true. In this mode, OPTIONS requests are forwarded to the upstream API and the proxy does not add CORS headers.

Because the STAC Auth Proxy introduces authentication, the upstream API's CORS settings may need adjustment to support credentials. In most cases, this means:

Root Paths

The proxy can be optionally served from a non-root path (e.g., /api/v1). Additionally, the proxy can optionally proxy requests to an upstream API served from a non-root path (e.g., /stac). To handle this, the proxy will:

  • Remove the ROOT_PATH from incoming requests before forwarding to the upstream API
  • Remove the proxy's prefix from all links in STAC API responses
  • Add the ROOT_PATH prefix to all links in STAC API responses
  • Update the OpenAPI specification to include the ROOT_PATH in the servers field
  • Handle requests that don't match the ROOT_PATH with a 404 response

Non-OIDC Workaround

If the upstream server utilizes RS256 JWTs but does not utilize a proper OIDC server, the proxy can be configured to work around this by setting the OIDC_DISCOVERY_URL to a statically-hosted OIDC discovery document that points to a valid JWKS endpoint.

Swagger UI Direct JWT Input

Rather than performing the login flow, the Swagger UI can be configured to accept direct JWT as input with the the following configuration:

OPENAPI_AUTH_SCHEME_NAME=jwtAuth
OPENAPI_AUTH_SCHEME_OVERRIDE='{
  "type": "http",
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "description": "Paste your raw JWT here. This API uses Bearer token authorization."
}'

Non-proxy Configuration

While the STAC Auth Proxy is designed to work out-of-the-box as an application, it might not address every projects needs. When the need for customization arises, the codebase can instead be treated as a library of components that can be used to augment a FastAPI server.

This may look something like the following:

from fastapi import FastAPI
from stac_fastapi.api.app import StacApi
from stac_auth_proxy import configure_app, Settings as StacAuthSettings

# Create Auth Settings
auth_settings = StacAuthSettings(
  upstream_url='https://stac-server',  # Dummy value, we don't make use of this value in non-proxy mode
  oidc_discovery_url='https://auth-server/.well-known/openid-configuration',
)

# Setup App
app = FastAPI( ... )

# Apply STAC Auth Proxy middleware
configure_app(app, auth_settings)

# Setup STAC API
api = StacApi( app, ... )

Important

Avoid using build_lifespan() when operating in non-proxy mode, as we are unable to check for the non-existent upstream API.

  1. developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS/Errors/CORSNotSupportingCredentials ↩↩