Skip to content

fastgeoapi

fastgeoapi logo 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) 🗺️🔒.

pygeoapi logo      Open Policy Agent logo

PyPI Status Python License

Documentation Tests Contract Tests ZAP Scan Codecov

pre-commit Ruff uv

Architecture

This diagram gives an overview of the basic architecture:

general architecture

Features

🔐 Security & Authentication

  • 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

🚀 Performance & Modern Stack

  • 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

🗺️ Geospatial API Standards

  • 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

🛡️ Security Testing & Quality

  • 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

📋 OGC API Conformance

  • 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

Live Demo

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.

Getting an Access Token

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"

Using the Access Token

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"

Requirements

  • pygeoapi
  • fastapi-opa
  • An OpenID Connect provider (Keycloak, WSO2, etc)
  • Open Policy Agent (OPA)

Installation

You can install fastgeoapi via pip from PyPI:

pip install fastgeoapi

Development

Prerequisites

Install UV - a fast Python package installer and resolver:

macOS / Linux:

curl -sSf https://install.ultraviolet.dev | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Setup

After cloning the repository, use UV to install dependencies:

git clone https://github.com/geobeyond/fastgeoapi.git
cd fastgeoapi
uv sync

This 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.

Activate the Virtual Environment

macOS / Linux:

source .venv/bin/activate

Windows (PowerShell):

.venv\Scripts\Activate.ps1

Running fastgeoapi

Once 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 --reload

Quick Start (Package Installation)

Install fastgeoapi:

pip install fastgeoapi

Create 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=false

Start the server:

fastgeoapi run

With options:

fastgeoapi run --host 0.0.0.0 --port 5000 --reload

See the Getting Started guide for complete setup instructions including authentication options and examples.

Common UV Commands

# 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 dev

For more details, see uv.md.

Release Workflow

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

Development Releases

Push to develop branch triggers automatic publishing to TestPyPI:

git checkout develop
# Make changes
git commit -m "feat: add new feature"
git push origin develop

The workflow automatically creates a dev version (e.g., 0.0.4.dev.1733912345) and publishes to TestPyPI.

Production Releases

To create a production release on PyPI:

  1. Update the version in pyproject.toml
  2. Merge to main branch
  3. 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 main

Both workflows use Trusted Publisher (OIDC) for secure, tokenless authentication with PyPI/TestPyPI.

Usage

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.

Contributing

Contributions are very welcome. To learn more, see the Contributor Guide.

License

Distributed under the terms of the MIT license, fastgeoapi is free and open-source software.

Issues

If you encounter any problems, please file an issue along with a detailed description.

MCP Server (Model Context Protocol)

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.

Features

  • 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

Enabling the MCP Server

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=true

The MCP server will be mounted at /mcp endpoint.

Configuration

Basic Configuration (No Authentication)

# .env file
ENV_STATE=dev
DEV_FASTGEOAPI_WITH_MCP=true
DEV_PYGEOAPI_CONFIG=pygeoapi-config.yml
DEV_PYGEOAPI_OPENAPI=pygeoapi-openapi.yml

With OAuth Authentication

To 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-secret

Security & Authentication Flows

The MCP server supports multiple security configurations depending on your deployment needs.

Supported OAuth 2.0 Flows

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

OAuth Proxy Architecture

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)      │
        │──────────────────────▶│──────────────────────▶│

Security Features

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

Supported Identity Providers

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

Using the MCP Server

With Claude Desktop

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/"]
    }
  }
}

With mcp-remote (OAuth)

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.

Direct SSE Connection

For clients that support Server-Sent Events directly:

http://localhost:5000/mcp/sse

Available Tools

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)

OAuth Discovery Endpoints

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)

Architecture

┌─────────────────────────────────────────────────────────┐
│                    Claude Desktop                        │
│                    or MCP Client                         │
└─────────────────────┬───────────────────────────────────┘
                      │ MCP Protocol (SSE/HTTP)
                      ▼
┌─────────────────────────────────────────────────────────┐
│                   fastgeoapi                             │
│  ┌───────────────────────────────────────────────────┐  │
│  │              MCP Server (/mcp)                     │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌───────────┐  │  │
│  │  │ OAuth Proxy │  │ Tool Router │  │ SSE/HTTP  │  │  │
│  │  └─────────────┘  └─────────────┘  └───────────┘  │  │
│  └───────────────────────────────────────────────────┘  │
│                          │                               │
│                          ▼                               │
│  ┌───────────────────────────────────────────────────┐  │
│  │           pygeoapi OGC API (/geoapi)              │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

Credits

This project was generated from \@cjolowicz\'s Hypermodern Python Cookiecutter template.

Back to top