A modern, high-performance geospatial API framework that extends pygeoapi with authentication, authorization, and security features using FastAPI, OpenID Connect, and Open Policy Agent (OPA) 🗺️🔒.
This diagram gives an overview of the basic architecture:
- OpenID Connect (OIDC) Integration - OAuth2/JWT Bearer token authentication with JWKS support
- API Key Authentication - Flexible API key-based authentication for programmatic access
- Open Policy Agent (OPA) - Policy-based authorization with fine-grained access control
- Multi-scheme Support - Seamlessly switch between authentication methods based on your needs
- FastAPI Framework - High-performance async API built on Starlette and Pydantic
- Async I/O - Non-blocking operations for better scalability
- Modern Python - Python 3.12+ with type hints and modern language features
- Fast Dependency Management - UV-based tooling for lightning-fast installations
- OGC API Compliance - Full support for OGC API - Features, Processes, and more
- OpenAPI Integration - Auto-generated, security-enhanced OpenAPI specifications
- Geospatial Data Access - Seamless access to vector and raster geospatial data
- pygeoapi Extension - Extends vanilla pygeoapi with enterprise-ready security
- Contract Testing - Automated OpenAPI contract validation with Schemathesis
- Security Scanning - OWASP ZAP integration for continuous security testing
- Pre-commit Hooks - Code quality checks with Ruff formatting and linting
- Comprehensive Test Coverage - Full test suite with pytest and coverage reporting
- Specification Validation - Automated validation against OGC API standards using ogcapi-registry
- OpenAPI Document Verification - Ensures generated OpenAPI documents conform to OGC API specifications
- Conformance Class Reporting - Detailed reports on declared conformance classes (OGC API - Features, Common, GeoJSON, etc.)
- CI/CD Integration - Continuous validation on every deployment to the demo server
A public demo server is available at https://fastgeoapi.fly.dev/geoapi.
🔐 The API endpoints are protected with OAuth2 client-credentials flow, showcasing fastgeoapi's enterprise-ready security features. This allows you to test the full authentication workflow in a real environment.
The Swagger UI documentation is publicly accessible without authentication at https://fastgeoapi.fly.dev/geoapi/openapi, allowing you to explore the API specification and available endpoints before authenticating.
The demo server requires OAuth2 authentication. To obtain an access token:
curl -X POST https://76hxgq.logto.app/oidc/token \
-H "Authorization: Basic czRyZjIzbnlucmNvdGM4NnhuaWVxOlc2RHJhQWJ1MTZnb29yR0xWSE02WFlSUnI4aWpObUww" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&resource=http://localhost:5000/geoapi/&scope=openid profile ci"Once you have the token, include it in your requests:
# Get the landing page
curl -H "Authorization: Bearer <your_access_token>" \
"https://fastgeoapi.fly.dev/geoapi/?f=json"
# List collections
curl -H "Authorization: Bearer <your_access_token>" \
"https://fastgeoapi.fly.dev/geoapi/collections?f=json"
# Check conformance
curl -H "Authorization: Bearer <your_access_token>" \
"https://fastgeoapi.fly.dev/geoapi/conformance?f=json"- pygeoapi
- fastapi-opa
- An OpenID Connect provider (Keycloak, WSO2, etc)
- Open Policy Agent (OPA)
You can install fastgeoapi via pip from PyPI:
pip install fastgeoapiInstall UV - a fast Python package installer and resolver:
macOS / Linux:
curl -sSf https://install.ultraviolet.dev | shWindows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"After cloning the repository, use UV to install dependencies:
git clone https://github.com/geobeyond/fastgeoapi.git
cd fastgeoapi
uv syncThis automatically:
- Creates a virtual environment in
.venv - Installs all required dependencies including git-based packages from
[tool.uv.sources](pygeoapi master, pygeofilter, fencer) - Sets up fastgeoapi in development mode
Note: For development, UV uses git-based dependencies defined in
[tool.uv.sources]to get the latest features from upstream projects. The PyPI release uses stable published versions. See uv.md for more details.
macOS / Linux:
source .venv/bin/activateWindows (PowerShell):
.venv\Scripts\Activate.ps1Once Keycloak and OPA have been started, configure the required environment variables:
export PYGEOAPI_CONFIG=pygeoapi-config.yml
export PYGEOAPI_OPENAPI=pygeoapi-openapi.yml
export FASTGEOAPI_CONTEXT='/geoapi'Start fastgeoapi in development mode:
uv run fastapi run app/main.py --app app --host 0.0.0.0 --port 5000 --reloadInstall fastgeoapi:
pip install fastgeoapiCreate a .env file with the required configuration:
# Environment state: 'dev' or 'prod'
ENV_STATE=dev
# Server configuration
HOST=0.0.0.0
PORT=5000
# Logging (required)
DEV_LOG_PATH=/tmp
DEV_LOG_FILENAME=fastgeoapi.log
DEV_LOG_LEVEL=debug
DEV_LOG_ENQUEUE=true
DEV_LOG_ROTATION=1 days
DEV_LOG_RETENTION=1 months
# Pygeoapi configuration
DEV_PYGEOAPI_BASEURL=http://localhost:5000
DEV_PYGEOAPI_CONFIG=pygeoapi-config.yml
DEV_PYGEOAPI_OPENAPI=pygeoapi-openapi.yml
DEV_FASTGEOAPI_CONTEXT=/geoapi
# Authentication (choose one, all others must be false)
DEV_API_KEY_ENABLED=false
DEV_JWKS_ENABLED=false
DEV_OPA_ENABLED=falseStart the server:
fastgeoapi runWith options:
fastgeoapi run --host 0.0.0.0 --port 5000 --reloadSee the Getting Started guide for complete setup instructions including authentication options and examples.
# Update dependencies
uv sync --upgrade
# View installed packages
uv pip list
# Install a new package
uv pip install package-name
# Install dev dependencies
uv pip install --group devFor more details, see uv.md.
This project uses a branching strategy with automated releases:
| Branch | Target | Description |
|---|---|---|
develop |
TestPyPI | Development releases with .dev suffix |
main |
PyPI | Production releases when version is bumped |
Push to develop branch triggers automatic publishing to TestPyPI:
git checkout develop
# Make changes
git commit -m "feat: add new feature"
git push origin developThe workflow automatically creates a dev version (e.g., 0.0.4.dev.1733912345) and publishes to TestPyPI.
To create a production release on PyPI:
- Update the version in
pyproject.toml - Merge to
mainbranch - The workflow detects the version change, creates a git tag, and publishes to PyPI
# Update version in pyproject.toml to e.g., 0.0.4
git checkout main
git merge develop
git push origin mainBoth workflows use Trusted Publisher (OIDC) for secure, tokenless authentication with PyPI/TestPyPI.
Please see the Command-line Reference for details.
Please have a look at the docker-compose.yml file under scripts/iam to start the stack with Keycloak and Open Policy Agent locally. There is a README.md file that explains how to use it.
The file scripts/iam/keycloak/realm-export.json can be used to import an already configured realm into Keycloak.
The files under scripts/postman can be used to setup Postman with a configuration that is ready to perform the requests for the whole stack.
Contributions are very welcome. To learn more, see the Contributor Guide.
Distributed under the terms of the MIT license, fastgeoapi is free and open-source software.
If you encounter any problems, please file an issue along with a detailed description.
fastgeoapi includes an optional integrated MCP server that exposes OGC API endpoints as tools for AI assistants and LLM-based applications. The MCP server is built using FastMCP and automatically generates tools from the pygeoapi OpenAPI specification.
- Automatic Tool Generation - Tools are generated from the OGC API OpenAPI spec
- OAuth Authentication - Supports OIDC authentication with any OAuth provider (Logto, Auth0, Keycloak, etc.)
- RFC 9728 Compliant - Implements OAuth 2.0 Protected Resource Metadata
- Dynamic Client Registration - Compatible with mcp-remote and other MCP clients
- Provider Agnostic - Uses mcpauth for multi-IdP support
To enable the MCP server, set the FASTGEOAPI_WITH_MCP environment variable:
# In your .env file
DEV_FASTGEOAPI_WITH_MCP=true
# Or for production
PROD_FASTGEOAPI_WITH_MCP=trueThe MCP server will be mounted at /mcp endpoint.
# .env file
ENV_STATE=dev
DEV_FASTGEOAPI_WITH_MCP=true
DEV_PYGEOAPI_CONFIG=pygeoapi-config.yml
DEV_PYGEOAPI_OPENAPI=pygeoapi-openapi.ymlTo enable OAuth authentication for the MCP server, configure JWKS:
# .env file
ENV_STATE=dev
DEV_FASTGEOAPI_WITH_MCP=true
DEV_JWKS_ENABLED=true
DEV_OIDC_WELL_KNOWN_ENDPOINT=https://your-idp.example.com/.well-known/openid-configuration
DEV_OIDC_CLIENT_ID=your-client-id
DEV_OIDC_CLIENT_SECRET=your-client-secretThe MCP server supports multiple security configurations depending on your deployment needs.
| Flow | Use Case | Configuration |
|---|---|---|
| Authorization Code + PKCE | Interactive clients (Claude Desktop, mcp-remote) | JWKS_ENABLED=true with OIDC config |
| Client Credentials | Machine-to-machine, service accounts | JWKS_ENABLED=true with OIDC config |
| Dynamic Client Registration (DCR) | Auto-registration for MCP clients | Enabled automatically with OIDC |
When OAuth is enabled, the MCP server acts as an OAuth Proxy implementing:
- RFC 8414 - OAuth 2.0 Authorization Server Metadata
- RFC 9728 - OAuth 2.0 Protected Resource Metadata
- RFC 7636 - Proof Key for Code Exchange (PKCE)
- RFC 7591 - OAuth 2.0 Dynamic Client Registration
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ MCP Client │────▶│ MCP Server │────▶│ Identity │
│ (mcp-remote) │ │ (OAuth Proxy) │ │ Provider │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
│ 1. Discovery │ │
│──────────────────────▶│ │
│ /.well-known/... │ │
│ │ │
│ 2. DCR (register) │ │
│──────────────────────▶│ │
│ │ │
│ 3. Authorization │ 4. Redirect to IdP │
│──────────────────────▶│──────────────────────▶│
│ │ │
│ │ 5. Auth Code │
│ │◀──────────────────────│
│ 6. Token Exchange │ │
│◀──────────────────────│ │
│ │ │
│ 7. MCP Requests │ 8. Internal API call │
│ (with Bearer token) │ (bypasses auth) │
│──────────────────────▶│──────────────────────▶│
| Feature | Description |
|---|---|
| JWT Validation | Tokens are validated using JWKS from the IdP |
| Opaque Token Support | Supports IdPs that return opaque tokens (e.g., Logto without API Resources) |
| RFC 6750 Compliance | Proper error handling for missing vs invalid tokens |
| Internal API Bypass | MCP-to-API calls use an internal key to bypass authentication |
| Scope Validation | Configurable required scopes for access control |
The MCP server is provider-agnostic and works with any OIDC-compliant IdP:
- Logto - Tested with OAuth proxy and DCR
- Auth0 - Full OIDC support
- Keycloak - Full OIDC and OPA integration
- Okta - Standard OIDC flows
- Azure AD - Microsoft identity platform
- Google - Google OAuth 2.0
Add the following to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"fastgeoapi": {
"command": "npx",
"args": ["mcp-remote", "http://localhost:5000/mcp/"]
}
}
}When OAuth is enabled, mcp-remote handles authentication automatically:
{
"mcpServers": {
"fastgeoapi": {
"command": "npx",
"args": ["mcp-remote", "http://localhost:5000/mcp/", "--allow-http"]
}
}
}The --allow-http flag is needed for local development. In production with HTTPS, remove this flag.
For clients that support Server-Sent Events directly:
http://localhost:5000/mcp/sse
The MCP server exposes all OGC API endpoints as tools, including:
| Tool | Description |
|---|---|
getLandingPage |
Get the API landing page |
getConformance |
Get OGC API conformance classes |
getCollections |
List all feature collections |
getCollection |
Get metadata for a specific collection |
getItems |
Query features from a collection |
getItem |
Get a specific feature by ID |
getProcesses |
List available processes (if OGC API - Processes is enabled) |
When OAuth is enabled, the following RFC-compliant endpoints are available:
| Endpoint | Description |
|---|---|
/.well-known/oauth-protected-resource/mcp/ |
Protected resource metadata (RFC 9728) |
/mcp/.well-known/oauth-authorization-server |
Authorization server metadata (RFC 8414) |
┌─────────────────────────────────────────────────────────┐
│ Claude Desktop │
│ or MCP Client │
└─────────────────────┬───────────────────────────────────┘
│ MCP Protocol (SSE/HTTP)
▼
┌─────────────────────────────────────────────────────────┐
│ fastgeoapi │
│ ┌───────────────────────────────────────────────────┐ │
│ │ MCP Server (/mcp) │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌───────────┐ │ │
│ │ │ OAuth Proxy │ │ Tool Router │ │ SSE/HTTP │ │ │
│ │ └─────────────┘ └─────────────┘ └───────────┘ │ │
│ └───────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────────────────────────────────┐ │
│ │ pygeoapi OGC API (/geoapi) │ │
│ └───────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
This project was generated from @cjolowicz's Hypermodern Python Cookiecutter template.