Add OAuth2 authorization server for delegated read-only API access #6172

Open

poulpreben wants to merge 2 commits from poulpreben/bookstack:oauth-authorization-server into development

pull from: poulpreben/bookstack:oauth-authorization-server

merge into: bookstack:development

bookstack:development

bookstack:l10n_development

bookstack:release

bookstack:v26-05-branch

bookstack:progress_indicator

bookstack:mfa_key

bookstack:phpstan_june26

bookstack:llm_only

bookstack:vectors

bookstack:captcha_example

Conversation 0 Commits 2 Files changed 43 +2585 -6

poulpreben commented 2026-07-15 11:41:09 +02:00

First-time contributor

Copy link

Closes #5614

User story: As a user, I want to securely grant applications read access to BookStack on my behalf, without handing out long-lived API tokens. This unlocks use cases like MCP servers and CLI tools that authenticate as the actual user with their normal permissions.

What this adds:

• GET/POST /oauth/authorize with a consent screen (uses the normal BookStack login, works with all auth methods)
• POST /oauth/token with authorization code + refresh token grants, PKCE (S256) required
• Bearer token support in the existing API guard; read scope enforced server-side (safe HTTP methods only)
• Confidential clients (server apps, bcrypt secret) and public clients (CLIs, no secret) - both managed in Settings under "App connections", nothing via env vars
• Refresh token rotation with reuse detection; users can revoke connections from their account page
• Tokens stored hashed (SHA-256), auth codes are short-lived (60s) single-use cache entries - same pattern as the SAML2 ACS hand-off

Deliberately kept small: hand-rolled minimal OAuth2 following existing BookStack patterns (no league/oauth2-server dependency), one read scope for now, no dynamic client registration. Happy to adjust scope or approach to whatever fits the project best.

Screenshots

Consent screen (as seen by the authorizing user)

My Account: connected applications with revoke

Settings: app connections list

Create form with confidential/public toggle

One-time client secret reveal after creation

Closes #5614 **User story:** As a user, I want to securely grant applications read access to BookStack on my behalf, without handing out long-lived API tokens. This unlocks use cases like MCP servers and CLI tools that authenticate as the actual user with their normal permissions. **What this adds:** - `GET/POST /oauth/authorize` with a consent screen (uses the normal BookStack login, works with all auth methods) - `POST /oauth/token` with authorization code + refresh token grants, PKCE (S256) required - Bearer token support in the existing API guard; `read` scope enforced server-side (safe HTTP methods only) - Confidential clients (server apps, bcrypt secret) and public clients (CLIs, no secret) - both managed in Settings under "App connections", nothing via env vars - Refresh token rotation with reuse detection; users can revoke connections from their account page - Tokens stored hashed (SHA-256), auth codes are short-lived (60s) single-use cache entries - same pattern as the SAML2 ACS hand-off **Deliberately kept small:** hand-rolled minimal OAuth2 following existing BookStack patterns (no league/oauth2-server dependency), one `read` scope for now, no dynamic client registration. Happy to adjust scope or approach to whatever fits the project best. <details> <summary><strong>Screenshots</strong></summary> **Consent screen (as seen by the authorizing user)**  **My Account: connected applications with revoke**  **Settings: app connections list**  **Create form with confidential/public toggle**  **One-time client secret reveal after creation**  </details>

01-consent-screen.png

34 KiB

02-my-account-connections.png

75 KiB

03-settings-app-connections.png

44 KiB

04-create-app-connection.png

58 KiB

05-one-time-secret.png

62 KiB

poulpreben added 1 commit 2026-07-15 11:41:13 +02:00

Add OAuth2 authorization server for delegated read-only API access ... 8ea887f799

Adds authorization code + refresh token grants with mandatory PKCE (S256),
allowing applications (MCP servers, CLIs) to call the API on behalf of a
user with their normal permissions, without long-lived static tokens.

- GET/POST /oauth/authorize with consent screen, using normal login
- POST /oauth/token, stateless, with refresh rotation + reuse detection
- Bearer token support in the existing API token guard
- read scope enforced server-side (safe HTTP methods only)
- Confidential and public client types, managed in settings UI
- Per-user connection revocation from the account security page
- Tokens stored as SHA-256 hashes; auth codes as short-lived cache entries

For #5614

poulpreben referenced this pull request 2026-07-15 11:43:00 +02:00

Use OIDC token to authenticate API calls #5614

poulpreben added 1 commit 2026-07-15 12:48:26 +02:00

OAuth: Harden delegated auth flows cf19d1e0ec

Some checks are pending

Hide checks

analyse-php / build (pull_request) Blocked by required conditions

Details

lint-php / build (pull_request) Blocked by required conditions

Details

test-migrations / build (8.2) (pull_request) Blocked by required conditions

Details

test-migrations / build (8.3) (pull_request) Blocked by required conditions

Details

test-migrations / build (8.4) (pull_request) Blocked by required conditions

Details

test-migrations / build (8.5) (pull_request) Blocked by required conditions

Details

test-php / build (8.2) (pull_request) Blocked by required conditions

Details

test-php / build (8.3) (pull_request) Blocked by required conditions

Details

test-php / build (8.4) (pull_request) Blocked by required conditions

Details

test-php / build (8.5) (pull_request) Blocked by required conditions

Details

This pull request can be merged automatically.

Some workflows are waiting to be reviewed.

This branch is out-of-date with the base branch

You are not authorized to merge this pull request.

View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.

git fetch -u oauth-authorization-server:poulpreben-oauth-authorization-server

git switch poulpreben-oauth-authorization-server

Merge

Merge the changes and update on Forgejo.

git switch development

git merge --no-ff poulpreben-oauth-authorization-server

git switch poulpreben-oauth-authorization-server

git rebase development

git switch development

git merge --ff-only poulpreben-oauth-authorization-server

git switch poulpreben-oauth-authorization-server

git rebase development

git switch development

git merge --no-ff poulpreben-oauth-authorization-server

git switch development

git merge --squash poulpreben-oauth-authorization-server

git switch development

git merge --ff-only poulpreben-oauth-authorization-server

git switch development

git merge poulpreben-oauth-authorization-server

git push origin development

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

Focus: A11y

Accessibility

  

Focus: Admin/Meta

  

Focus: Authentication

  

Focus: Back-End

  

Focus: Database

  

Focus: Design & UX

  

Focus: Editor - Markdown

  

Focus: Editor - WYSIWYG

  

Focus: Export System

  

Focus: Front-End

  

Focus: Translations

  

Focus: View Customization

  

Is: Docs Update

  

Is: Enhancement

  

Is: Priority

  

Is: Security

  

Is: Upstream

  

Status

Blocked

  

Status

Open to discussion

  

Status

Out of scope

  

Status

Pending Validation

  

Type

API Request

  

Type

Bug Report

  

Type

Feature Request

  

Type

Happy feedback

  

Type

Maintenance

  

Type

Question

  

Type

Support

No labels

Focus: A11y

Focus: Admin/Meta

Focus: Authentication

Focus: Back-End

Focus: Database

Focus: Design & UX

Focus: Editor - Markdown

Focus: Editor - WYSIWYG

Focus: Export System

Focus: Front-End

Focus: Translations

Focus: View Customization

Is: Docs Update

Is: Enhancement

Is: Priority

Is: Security

Is: Upstream

Status

Blocked

Status

Open to discussion

Status

Out of scope

Status

Pending Validation

Type

API Request

Type

Bug Report

Type

Feature Request

Type

Happy feedback

Type

Maintenance

Type

Question

Type

Support

Milestone

Clear milestone

No items

No milestone

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

bookstack/bookstack!6172

No description provided.