Added OIDC Authentication by mlgupta · Pull Request #1341 · gotenberg/gotenberg

mlgupta · 2025-09-30T16:26:59Z

Summary

This PR adds comprehensive OIDC (OpenID Connect) authentication support to Gotenberg, enabling integration with Auth0 and other OIDC providers. This enhancement provides a modern, secure alternative to basic authentication for protecting Gotenberg API endpoints.

🚀 Features Added

Full JWT Token Validation: RS256 signature verification with JWKS support
Auto-Discovery: Automatic JWKS endpoint discovery from OIDC issuer
Token Caching: Configurable JWKS key caching for optimal performance
Comprehensive Validation: Issuer, audience, expiration, and issued-at claims validation
Mutual Exclusion: Cannot enable both basic auth and OIDC auth simultaneously
Environment Variable Support: All settings configurable via environment variables

🔧 Configuration

Command Line Flags

--api-enable-oidc-auth                    # Enable OIDC authentication  
--api-oidc-issuer                        # OIDC issuer URL
--api-oidc-audience                      # OIDC audience
--api-oidc-jwks-url                      # JWKS URL (optional, auto-discovered)
--api-oidc-jwks-cache-duration          # JWKS cache duration (default: 1h)

Environment Variables

GOTENBERG_API_OIDC_ISSUER
GOTENBERG_API_OIDC_AUDIENCE
GOTENBERG_API_OIDC_JWKS_URL

📋 Usage Example

# Start Gotenberg with OIDC authentication
docker run -p 3000:3000 \
  -e GOTENBERG_API_OIDC_ISSUER="https://your-tenant.auth0.com/" \
  -e GOTENBERG_API_OIDC_AUDIENCE="your-api-identifier" \
  gotenberg/gotenberg:8 \
  gotenberg --api-enable-oidc-auth

# Make authenticated requests
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "[email protected]" \
  http://localhost:3000/forms/chromium/convert/html

📁 Files Changed

Core Implementation

pkg/modules/api/api.go: Added OIDC configuration fields, flags, and provisioning logic
pkg/modules/api/middlewares.go: Implemented OIDC JWT validation middleware
go.mod: Added JWT and JWKS dependencies

Documentation

OIDC_USAGE.md: Comprehensive usage guide with Docker examples and Auth0 setup

🔒 Security Features

RS256 Signature Validation: Only accepts RS256 signed tokens
Multi-layer Validation: Validates issuer, audience, expiration, and issued-at claims
Key Rotation Support: Handles Auth0 key rotation via cached JWKS
No Secrets in Code: All sensitive configuration via runtime environment variables

✅ Backward Compatibility

Zero Breaking Changes: Existing functionality unchanged
Optional Feature: OIDC authentication is opt-in via flag
Mutual Exclusion: Clear separation from existing basic auth
Default Behavior: No authentication required when neither basic nor OIDC auth enabled

🧪 Testing

Built and tested with real Auth0 integration
Comprehensive error handling for invalid tokens
Debug logging for troubleshooting authentication issues
Docker container compatibility verified

Dependencies Added

github.com/golang-jwt/jwt/v5 v5.2.1 - JWT parsing and validation
github.com/lestrrat-go/jwx/v2 v2.0.21 - JWKS handling and caching

This addition enables enterprise-grade authentication for Gotenberg while maintaining full backward compatibility and following the project's existing architectural patterns.

gulien · 2026-08-14T15:14:28Z

Thanks for this, and for the detailed writeup. OIDC was worth adding.

I ended up implementing it fresh in c0f487e rather than merging here, mostly because this branch predates the api module's move from zap to log/slog (and had drifted into conflicts). The new version keeps the same shape you proposed (opt-in flag, mutual exclusion with basic auth, RS256 + JWKS with rotation) but fits the current codebase: a single library (coreos/go-oidc), the library's own issuer/audience/expiry validation, an instrumented HTTP client for the JWKS fetch, unit and integration tests, and the config documented on gotenberg.dev.

Closing in favor of that. Thanks for pushing the feature forward.

… 8.36.0) (#625) This PR contains the following updates: | Package | Update | Change | |---|---|---| | [docker.io/gotenberg/gotenberg](https://github.com/gotenberg/gotenberg) | minor | `8.35.0` → `8.36.0` | --- > ⚠️ **Warning** > > Some dependencies could not be looked up. Check the [Dependency Dashboard](issues/7) for more information. --- ### Release Notes <details> <summary>gotenberg/gotenberg (docker.io/gotenberg/gotenberg)</summary> ### [`v8.36.0`](https://github.com/gotenberg/gotenberg/releases/tag/v8.36.0): 8.36.0 [Compare Source](gotenberg/gotenberg@v8.35.0...v8.36.0) ##### Security Fixes ⚠️ - **Filter WebSocket handshakes against the outbound policy.** Chromium could open WebSocket connections to hosts the SSRF policy otherwise blocks. ##### New Features - **OIDC bearer token authentication.** Opt-in via `--api-enable-oidc-auth`, mutually exclusive with basic auth ([#1341](gotenberg/gotenberg#1341)). Thanks [@mlgupta](https://github.com/mlgupta). - **Optimize PDF images to reduce file size** ([#359](gotenberg/gotenberg#359)). A `/forms/pdfengines/optimize` route, plus an `optimizeImages` option on the Chromium, LibreOffice, merge, and split routes. Thanks [@spointecker](https://github.com/spointecker). - **Apply multiple stamps and watermarks in one request** by repeating the fields, on every route that supports them ([#1601](gotenberg/gotenberg#1601)). Thanks [@Kobe-Kwanten](https://github.com/Kobe-Kwanten). - **Screenshot a single element** via the `selector` form field ([#947](gotenberg/gotenberg#947)). Thanks [@human211](https://github.com/human211). - **Table-of-contents bookmarks when merging.** `titleBookmarks` adds one bookmark per input, labeled by its title ([#867](gotenberg/gotenberg#867)). Thanks [@gnapse](https://github.com/gnapse). - **Clear storage between conversions** with `--chromium-clear-storage` ([#919](gotenberg/gotenberg#919)). Thanks [@befresh-mweimerskirch](https://github.com/befresh-mweimerskirch). - **Await async `waitForExpression`.** A Promise-returning expression is now awaited ([#1617](gotenberg/gotenberg#1617)). Thanks [@nhh](https://github.com/nhh). ##### Bug Fixes - **Landscape single-page now fits the page to its content** ([#1390](gotenberg/gotenberg#1390)). Thanks [@JhnBer](https://github.com/JhnBer). - **Accept the OOXML PowerPoint show extensions** `.ppsx` and `.ppsm` ([#1626](gotenberg/gotenberg#1626)). Thanks [@lyarov22](https://github.com/lyarov22). - **Client-cancelled requests are classified as `499`, not `500`** ([#1627](gotenberg/gotenberg#1627)). Thanks [@yngvar](https://github.com/yngvar). - **Render scrolled workbooks in full** for `singlePageSheets`. - **Return `403` instead of `500` for an unresolvable outbound host.** - **Hint at `--chromium-start-timeout`** when Chromium fails to start. ##### Chore - Updated `pdfcpu` to `v0.15.0` ([#1628](gotenberg/gotenberg#1628)). Thanks [@doronbehar](https://github.com/doronbehar). - Bumped golangci-lint to `v2.12.2`. - Updated Go and npm dependencies. </details> --- ### Configuration 📅 **Schedule**: (in timezone Europe/Warsaw) - Branch creation - At any time (no schedule defined) - Automerge - At any time (no schedule defined) 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about these updates again. --- - [ ] If you want to rebase/retry this PR, check this box --- This PR has been generated by [Mend Renovate CLI](https://github.com/renovatebot/renovate).  Reviewed-on: https://git.ajgon.casa/deedee/mark13/pulls/625

… 8.36.0) (#1889) This PR contains the following updates: | Package | Update | Change | |---|---|---| | [docker.io/gotenberg/gotenberg](https://github.com/gotenberg/gotenberg) | minor | `8.35.0` → `8.36.0` | --- > ⚠️ **Warning** > > Some dependencies could not be looked up. Check the [Dependency Dashboard](issues/567) for more information. --- ### Release Notes <details> <summary>gotenberg/gotenberg (docker.io/gotenberg/gotenberg)</summary> ### [`v8.36.0`](https://github.com/gotenberg/gotenberg/releases/tag/v8.36.0): 8.36.0 [Compare Source](gotenberg/gotenberg@v8.35.0...v8.36.0) ##### Security Fixes ⚠️ - **Filter WebSocket handshakes against the outbound policy.** Chromium could open WebSocket connections to hosts the SSRF policy otherwise blocks. ##### New Features - **OIDC bearer token authentication.** Opt-in via `--api-enable-oidc-auth`, mutually exclusive with basic auth ([#1341](gotenberg/gotenberg#1341)). Thanks [@mlgupta](https://github.com/mlgupta). - **Optimize PDF images to reduce file size** ([#359](gotenberg/gotenberg#359)). A `/forms/pdfengines/optimize` route, plus an `optimizeImages` option on the Chromium, LibreOffice, merge, and split routes. Thanks [@spointecker](https://github.com/spointecker). - **Apply multiple stamps and watermarks in one request** by repeating the fields, on every route that supports them ([#1601](gotenberg/gotenberg#1601)). Thanks [@Kobe-Kwanten](https://github.com/Kobe-Kwanten). - **Screenshot a single element** via the `selector` form field ([#947](gotenberg/gotenberg#947)). Thanks [@human211](https://github.com/human211). - **Table-of-contents bookmarks when merging.** `titleBookmarks` adds one bookmark per input, labeled by its title ([#867](gotenberg/gotenberg#867)). Thanks [@gnapse](https://github.com/gnapse). - **Clear storage between conversions** with `--chromium-clear-storage` ([#919](gotenberg/gotenberg#919)). Thanks [@befresh-mweimerskirch](https://github.com/befresh-mweimerskirch). - **Await async `waitForExpression`.** A Promise-returning expression is now awaited ([#1617](gotenberg/gotenberg#1617)). Thanks [@nhh](https://github.com/nhh). ##### Bug Fixes - **Landscape single-page now fits the page to its content** ([#1390](gotenberg/gotenberg#1390)). Thanks [@JhnBer](https://github.com/JhnBer). - **Accept the OOXML PowerPoint show extensions** `.ppsx` and `.ppsm` ([#1626](gotenberg/gotenberg#1626)). Thanks [@lyarov22](https://github.com/lyarov22). - **Client-cancelled requests are classified as `499`, not `500`** ([#1627](gotenberg/gotenberg#1627)). Thanks [@yngvar](https://github.com/yngvar). - **Render scrolled workbooks in full** for `singlePageSheets`. - **Return `403` instead of `500` for an unresolvable outbound host.** - **Hint at `--chromium-start-timeout`** when Chromium fails to start. ##### Chore - Updated `pdfcpu` to `v0.15.0` ([#1628](gotenberg/gotenberg#1628)). Thanks [@doronbehar](https://github.com/doronbehar). - Bumped golangci-lint to `v2.12.2`. - Updated Go and npm dependencies. </details> --- ### Configuration 📅 **Schedule**: (in timezone Europe/Paris) - Branch creation - At any time (no schedule defined) - Automerge - At any time (no schedule defined) 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about these updates again. --- - [ ] If you want to rebase/retry this PR, check this box --- This PR has been generated by [Mend Renovate CLI](https://github.com/renovatebot/renovate).  Reviewed-on: https://git.erwanleboucher.dev/eleboucher/homelab/pulls/1889

…314) This PR contains the following updates: | Package | Update | Change | |---|---|---| | [gotenberg/gotenberg](https://github.com/gotenberg/gotenberg) | minor | `8.34.0` → `8.36.0` | --- > ⚠️ **Warning** > > Some dependencies could not be looked up. Check the [Dependency Dashboard](issues/141) for more information. --- ### Release Notes <details> <summary>gotenberg/gotenberg (gotenberg/gotenberg)</summary> ### [`v8.36.0`](https://github.com/gotenberg/gotenberg/releases/tag/v8.36.0): 8.36.0 [Compare Source](gotenberg/gotenberg@v8.35.0...v8.36.0) ##### Security Fixes ⚠️ - **Filter WebSocket handshakes against the outbound policy.** Chromium could open WebSocket connections to hosts the SSRF policy otherwise blocks. ##### New Features - **OIDC bearer token authentication.** Opt-in via `--api-enable-oidc-auth`, mutually exclusive with basic auth ([#1341](gotenberg/gotenberg#1341)). Thanks [@mlgupta](https://github.com/mlgupta). - **Optimize PDF images to reduce file size** ([#359](gotenberg/gotenberg#359)). A `/forms/pdfengines/optimize` route, plus an `optimizeImages` option on the Chromium, LibreOffice, merge, and split routes. Thanks [@spointecker](https://github.com/spointecker). - **Apply multiple stamps and watermarks in one request** by repeating the fields, on every route that supports them ([#1601](gotenberg/gotenberg#1601)). Thanks [@Kobe-Kwanten](https://github.com/Kobe-Kwanten). - **Screenshot a single element** via the `selector` form field ([#947](gotenberg/gotenberg#947)). Thanks [@human211](https://github.com/human211). - **Table-of-contents bookmarks when merging.** `titleBookmarks` adds one bookmark per input, labeled by its title ([#867](gotenberg/gotenberg#867)). Thanks [@gnapse](https://github.com/gnapse). - **Clear storage between conversions** with `--chromium-clear-storage` ([#919](gotenberg/gotenberg#919)). Thanks [@befresh-mweimerskirch](https://github.com/befresh-mweimerskirch). - **Await async `waitForExpression`.** A Promise-returning expression is now awaited ([#1617](gotenberg/gotenberg#1617)). Thanks [@nhh](https://github.com/nhh). ##### Bug Fixes - **Landscape single-page now fits the page to its content** ([#1390](gotenberg/gotenberg#1390)). Thanks [@JhnBer](https://github.com/JhnBer). - **Accept the OOXML PowerPoint show extensions** `.ppsx` and `.ppsm` ([#1626](gotenberg/gotenberg#1626)). Thanks [@lyarov22](https://github.com/lyarov22). - **Client-cancelled requests are classified as `499`, not `500`** ([#1627](gotenberg/gotenberg#1627)). Thanks [@yngvar](https://github.com/yngvar). - **Render scrolled workbooks in full** for `singlePageSheets`. - **Return `403` instead of `500` for an unresolvable outbound host.** - **Hint at `--chromium-start-timeout`** when Chromium fails to start. ##### Chore - Updated `pdfcpu` to `v0.15.0` ([#1628](gotenberg/gotenberg#1628)). Thanks [@doronbehar](https://github.com/doronbehar). - Bumped golangci-lint to `v2.12.2`. - Updated Go and npm dependencies. ### [`v8.35.0`](https://github.com/gotenberg/gotenberg/releases/tag/v8.35.0): 8.35.0 [Compare Source](gotenberg/gotenberg@v8.34.0...v8.35.0) ##### Security Fixes ⚠️ - **Sanitize the `Gotenberg-Output-Filename` header.** `filepath.Base` ignores `\` on Linux, so a crafted header reached archive entry names on `splitMode` conversions, giving a Windows-side Zip Slip. - **Bound scope matching per conversion.** The `extraHttpHeaders` match timeout capped one match, not their number. Matching now shares a per-conversion budget, and `extraHttpHeaders` accepts at most 64 headers with a 1024-character `scope`. ##### New Features - **Authenticated proxy from environment variables.** Four opt-in flags route outbound traffic through `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`, credentials included: `--chromium-enable-environment-proxy`, `--libreoffice-enable-environment-proxy`, `--api-download-from-enable-environment-proxy`, and `--webhook-enable-environment-proxy`. All default to `false`. Breaking: the outbound client no longer inherits `HTTP_PROXY` and `HTTPS_PROXY` implicitly. ##### Bug Fixes - **LibreOffice returned `400` for server-side failures** ([#1588](gotenberg/gotenberg#1588)). `400` now requires an implicated client input, `nativePageRanges`, `password`, or an unreadable document; everything else is `500`. Thanks [@ctunon-align](https://github.com/ctunon-align). - **`generateDocumentOutline` was a silent no-op** ([#1579](gotenberg/gotenberg#1579)). It now enables `generateTaggedPdf`, which Chromium needs to build the outline. Thanks [@paradoxloop](https://github.com/paradoxloop). - **Pinning proxy latched after a Chromium start timeout.** Starts are now serialized. - **LibreOffice leaked a document after a failed export.** `unoconverter` now releases it. ##### Chore - Updated Chromium to `151.0.7922.71`. - Updated `pdfcpu` to `v0.13.0`. - Updated `unoconverter` to `v0.4.0`. - Bumped Go to `1.26.5`. - Updated Go dependencies. </details> --- ### Configuration 📅 **Schedule**: (in timezone Europe/London) - Branch creation - At any time (no schedule defined) - Automerge - At any time (no schedule defined) 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about these updates again. --- - [ ] If you want to rebase/retry this PR, check this box --- This PR has been generated by [Mend Renovate](https://github.com/renovatebot/renovate).  Reviewed-on: https://forgejo.hayden.moe/hayden/phoebe/pulls/314

Added OIDC Authentication

4f89ca2

gulien added enhancement New feature or request maybe labels Oct 4, 2025

mlgupta added 2 commits October 17, 2025 12:46

Merge changes from upstream

4391ab9

Merge from upstream

a7e8821

gulien closed this Aug 14, 2026

This was referenced Aug 17, 2026

Bump Gotenberg to 8.36.0 MaikuMori/helm-charts#106

Merged

Bump Gotenberg to 8.36.0 teknatha136/helm-charts#3

Closed

github-actions Bot mentioned this pull request Oct 19, 2026

Bump Gotenberg to 8.38.1 teknatha136/helm-charts#4

Open

4 tasks

Navigation Menu

Repository navigation

Added OIDC Authentication - #1341

Added OIDC Authentication#1341
mlgupta wants to merge 3 commits into
gotenberg:mainfrom
mlgupta:oidc-auth

mlgupta commented Sep 30, 2025

Uh oh!

gulien commented Aug 14, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

mlgupta commented Sep 30, 2025

Summary

🚀 Features Added

🔧 Configuration

Command Line Flags

Environment Variables

📋 Usage Example

📁 Files Changed

Core Implementation

Documentation

🔒 Security Features

✅ Backward Compatibility

🧪 Testing

Dependencies Added

Uh oh!

gulien commented Aug 14, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants