Unified OIDC security & full documentation site

[afabiani]

Summary

GeoStore's authentication layer has been modernised. Instead of maintaining separate code for each identity provider (Keycloak, Google, Azure AD, etc.), all providers now go through a single, generic OpenID Connect integration. This makes it easier to add new providers, reduces maintenance overhead, and brings several enterprise features that were previously missing.

A complete documentation website has also been created so that administrators can configure and operate the system without reading source code.

---

What changed — at a glance

Area	Before	After
Identity providers	Separate code per provider (Keycloak adapter, Google adapter)	One generic OIDC integration — any compliant provider works
Multiple providers	Not supported	Supported — e.g. Keycloak + Azure AD simultaneously
Encrypted tokens (JWE)	Not supported	Supported — for Azure AD, ADFS, Keycloak
Large Azure AD groups (>200)	Failed silently	Resolved via Microsoft Graph API
Role/group extraction	Simple top-level claims only	Full JsonPath support for nested/complex claims
Error responses	Empty 401 bodies	Structured JSON error messages
Diagnostics	None	Admin-only REST endpoint for log levels, cache, and config inspection
Debug logging	Always on or always off	Opt-in logSensitiveInfo toggle
Documentation	Scattered/none	Full MkDocs site with guides, reference, and migration path

---

Key highlights

1. Works with any OIDC provider — Keycloak, Azure AD / Entra ID, Google, Okta, or any other standards-compliant provider. No provider-specific code needed.

2. Multiple providers at once — Organisations using more than one identity provider can configure them all; bearer tokens are routed to the right provider automatically.

3. Enterprise-ready token handling — Encrypted (JWE) tokens, configurable token age limits, and three validation strategies (local JWT verification, remote introspection, or automatic detection).

4. Azure AD groups at scale — When users belong to more than 200 groups, Azure AD omits the groups claim. GeoStore now detects this and resolves groups via the Microsoft Graph API.

5. Better troubleshooting — JSON error bodies on authentication failures, a diagnostics endpoint for live config/cache inspection, and a logSensitiveInfo toggle for safe debug logging.

6. Full documentation site — 20 pages covering installation, configuration, all security modules, provider-specific setup guides (Keycloak, Azure AD, Google), REST API reference, architecture overview, deployment guide, and a migration guide for upgrading.

---

Documentation

The documentation is built with MkDocs Material and lives in the docs/ directory.

Building the docs locally

# Install the dependency (once)
pip install mkdocs-material

# Serve locally with live reload
cd docs/
mkdocs serve

Then open http://127.0.0.1:8000 in a browser.

Documentation structure

• Getting Started — Installation, quickstart, configuration
• Security — OIDC/OAuth2, bearer tokens, roles & groups, LDAP, sessions, monitoring, property reference
• Guides — Step-by-step setup for Keycloak, Azure AD, and Google
• REST API — Complete endpoint reference for all 14 services
• Architecture — Module structure, data model, request pipeline
• Deployment — Production checklist, reverse proxy, TLS, scaling

---

Backward compatibility

All new features are opt-in and disabled by default. Existing configurations continue to work without changes. A migration guide is included for users upgrading from previous versions.

Changelog

• Consolidate Keycloak adapter into generic OIDC (remove 21 provider-specific source files)
• Consolidate Google OAuth2 adapter into generic OIDC (remove 7 provider-specific source files)
• Add multiple simultaneous OIDC provider support
• Add JWE (encrypted token) support for bearer tokens
• Add Microsoft Graph API integration for Azure AD groups overage
• Add JsonPath support for role/group claim extraction
• Add structured JSON error bodies to 401 responses
• Add admin-only diagnostics REST endpoint (log levels, cache, config)
• Add logSensitiveInfo toggle for debug-level security logging
• Add PKCE support for authorization code flow
• Add configurable token cache TTL and fix TimeUnit bug
• Add maxTokenAgeSecs (issued-at validation) for bearer tokens
• Add role/group extraction fallback from userinfo endpoint
• Fix userinfo endpoint to use spec-compliant Bearer header
• Fix NPE in OAuth REST template when token response omits scope
• Create full MkDocs documentation site (20 pages)