starred/audiobookshelf
1
0
Fork 0
mirror of https://github.com/advplyr/audiobookshelf.git synced 2026-05-30 23:40:40 +02:00
Code Issues 1.0k Packages Projects Releases 10 Wiki Activity

[PR #5031] Revamp OIDC auth and add Back-Channel Logout #4399

New Issue
Open
opened 2026-04-25 00:19:36 +02:00 by adam · 0 comments
adam commented 2026-04-25 00:19:36 +02:00
Owner
Copy Link
Copy Source

📋 Pull Request Information

Original PR: https://github.com/advplyr/audiobookshelf/pull/5031
Author: @Sapd
Created: 2/5/2026
Status: 🔄 Open

Base: master ← Head: oidc-revamp

📝 Commits (10+)

  • 33bee70 Revamp OIDC auth: remove Passport wrapper, add schema-driven settings UI
  • 073eff7 Add OIDC Back-Channel Logout support
  • ed0db53 Add unit tests for 5 OidcAuthStrategy methods
  • d504797 Add unit tests for OIDC callback flow and authorization
  • b3d63f4 Fix backchannel logout always returning 501
  • 49aeb2d Require email_verified to be explicitly true when enforcement is enabled
  • c2a7615 OIDC: Improve error messages
  • e428ba5 OIDC: Fix CodeQL warnings
  • c99543b Update en-us.json
  • 84b3d4d Fix migration crash on upgrade from v2.31.0

📊 Changes

22 files changed (+3370 additions, -580 deletions)

View changed files

➕ client/components/app/KeyValueEditor.vue (+97 -0)
➕ client/components/app/OidcSettings.vue (+126 -0)
📝 client/layouts/default.vue (+11 -0)
📝 client/pages/config/authentication.vue (+91 -254)
📝 client/strings/en-us.json (+1 -0)
📝 package.json (+2 -1)
📝 server/Auth.js (+127 -159)
➕ server/auth/AuthError.js (+9 -0)
➕ server/auth/BackchannelLogoutHandler.js (+148 -0)
📝 server/auth/OidcAuthStrategy.js (+202 -96)
➕ server/auth/OidcSettingsSchema.js (+348 -0)
📝 server/auth/TokenManager.js (+15 -2)
📝 server/controllers/MiscController.js (+125 -55)
➕ server/migrations/v2.33.0-oidc-scopes-and-group-map.js (+143 -0)
➕ server/migrations/v2.34.0-backchannel-logout.js (+127 -0)
📝 server/models/Session.js (+9 -3)
📝 server/objects/settings/ServerSettings.js (+38 -10)
📝 server/routers/ApiRouter.js (+1 -0)
➕ test/server/auth/AuthError.test.js (+24 -0)
➕ test/server/auth/BackchannelLogoutHandler.test.js (+319 -0)

...and 2 more files

📄 Description

This PR revamps the OIDC system. Passport is removed. Support for groups mapping provided, and scopes can now be configured.

In-depth Description

Passport was removed for OIDC

It clashed how we OIDC used. We are not only an OIDC relying party but also an OAuth2 proxy for mobile clients. Thats a use case the passport provider does not handle well, we did some hacks before to support that. The new code is much simpler

Add Server-Driven (or also called Schema-Driven) UI for the OIDC settings

Instead of defining the settings (again) in the frontend, the server provides a schema and the frontend automatically renders all settings. Minimizes code (less duplication) and bugs. I would also recommend that for all other settings, however I handled here only OIDC.

OIDC Mappings

Added group mappings. A group from the identity provider can be now directly mapped to a ABS group. Also scopes can now be configured. Fixes #2878 and Fixes #3006
Fixed also some edge cases of validation (Fixes #4744 )

Add verified email enforcement option

Every idP provider handles the email_verified field differently (some provide hardcoded true or false or do not provide it). The Admin can now configure how ABS should handle the field. Fixes #4832
If the setting is turned on, it is expected that the IdP sends the value with and that its true.

Store OIDCToken in session table instead of cookie

The token is better placed server side. Also it can be quite long exceeding maximum allowed cookies length.

Add Back-Channel Logout support

Authentik now supports Back-Channel logout. So I implemented it here, too.
There is a POST endpoint on ABS side. When the configuration is turned on, it accepts a signed JWT from Authentik and can cancel sessions.
When a user logs out on Authentik, Authentik will use it to log out a user on ABS too. (The user's existing access token remains valid until it expires).

Other

Jose was added as explicit dependency for Backchannel Logout (there for checking the JWT). It was a dependency anyway from node-openid-client.

How have you tested this?

Simply add a mapper for one on the groups and use as value an Authentik Group.

For Backchannel logout. Make sure to configure the URL in Authentik. Then check the sessions in ABS sqliteDB. Then log out in authentik. You should see in the ABS Console a message that there was a Back Channel logout. The session will be gone in the ABS sqliteDB.

Also added extensive unit tests.

Screenshots

image

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/advplyr/audiobookshelf/pull/5031 **Author:** [@Sapd](https://github.com/Sapd) **Created:** 2/5/2026 **Status:** 🔄 Open **Base:** `master` ← **Head:** `oidc-revamp` --- ### 📝 Commits (10+) - [`33bee70`](https://github.com/advplyr/audiobookshelf/commit/33bee70a126d8aa77628fbe4684cd8af2b2f8e09) Revamp OIDC auth: remove Passport wrapper, add schema-driven settings UI - [`073eff7`](https://github.com/advplyr/audiobookshelf/commit/073eff74efc6379614d19a5fb6a4f6585beab8b9) Add OIDC Back-Channel Logout support - [`ed0db53`](https://github.com/advplyr/audiobookshelf/commit/ed0db539c96021d39fa9d39824310e4fd3ab508d) Add unit tests for 5 OidcAuthStrategy methods - [`d504797`](https://github.com/advplyr/audiobookshelf/commit/d5047978a853ef02b29abd97e2017f69fb36db8b) Add unit tests for OIDC callback flow and authorization - [`b3d63f4`](https://github.com/advplyr/audiobookshelf/commit/b3d63f4158691d0dc65791a8a1a4c16e965adf21) Fix backchannel logout always returning 501 - [`49aeb2d`](https://github.com/advplyr/audiobookshelf/commit/49aeb2da195b8eb2f74a315c4d7bea3222656558) Require email_verified to be explicitly true when enforcement is enabled - [`c2a7615`](https://github.com/advplyr/audiobookshelf/commit/c2a7615319f2121989417fe1b9f9ff994860adb1) OIDC: Improve error messages - [`e428ba5`](https://github.com/advplyr/audiobookshelf/commit/e428ba5657d4d5e237c3b8ad71bf482cb8edf6fc) OIDC: Fix CodeQL warnings - [`c99543b`](https://github.com/advplyr/audiobookshelf/commit/c99543be87dea5af3a580ca92433dffac23fe58c) Update en-us.json - [`84b3d4d`](https://github.com/advplyr/audiobookshelf/commit/84b3d4d2151a0dc3f9c97a6e6a936adb83605390) Fix migration crash on upgrade from v2.31.0 ### 📊 Changes **22 files changed** (+3370 additions, -580 deletions) <details> <summary>View changed files</summary> ➕ `client/components/app/KeyValueEditor.vue` (+97 -0) ➕ `client/components/app/OidcSettings.vue` (+126 -0) 📝 `client/layouts/default.vue` (+11 -0) 📝 `client/pages/config/authentication.vue` (+91 -254) 📝 `client/strings/en-us.json` (+1 -0) 📝 `package.json` (+2 -1) 📝 `server/Auth.js` (+127 -159) ➕ `server/auth/AuthError.js` (+9 -0) ➕ `server/auth/BackchannelLogoutHandler.js` (+148 -0) 📝 `server/auth/OidcAuthStrategy.js` (+202 -96) ➕ `server/auth/OidcSettingsSchema.js` (+348 -0) 📝 `server/auth/TokenManager.js` (+15 -2) 📝 `server/controllers/MiscController.js` (+125 -55) ➕ `server/migrations/v2.33.0-oidc-scopes-and-group-map.js` (+143 -0) ➕ `server/migrations/v2.34.0-backchannel-logout.js` (+127 -0) 📝 `server/models/Session.js` (+9 -3) 📝 `server/objects/settings/ServerSettings.js` (+38 -10) 📝 `server/routers/ApiRouter.js` (+1 -0) ➕ `test/server/auth/AuthError.test.js` (+24 -0) ➕ `test/server/auth/BackchannelLogoutHandler.test.js` (+319 -0) _...and 2 more files_ </details> ### 📄 Description This PR revamps the OIDC system. Passport is removed. Support for groups mapping provided, and scopes can now be configured. ## In-depth Description #### Passport was removed for OIDC It clashed how we OIDC used. We are not only an OIDC relying party but also an OAuth2 proxy for mobile clients. Thats a use case the passport provider does not handle well, we did some hacks before to support that. The new code is much simpler #### Add Server-Driven (or also called Schema-Driven) UI for the OIDC settings Instead of defining the settings (again) in the frontend, the server provides a schema and the frontend automatically renders all settings. Minimizes code (less duplication) and bugs. I would also recommend that for all other settings, however I handled here only OIDC. #### OIDC Mappings Added group mappings. A group from the identity provider can be now directly mapped to a ABS group. Also scopes can now be configured. Fixes #2878 and Fixes #3006 Fixed also some edge cases of validation (Fixes #4744 ) #### Add verified email enforcement option Every idP provider handles the email_verified field differently (some provide hardcoded true or false or do not provide it). The Admin can now configure how ABS should handle the field. Fixes #4832 If the setting is turned on, it is expected that the IdP sends the value with and that its true. #### Store OIDCToken in session table instead of cookie The token is better placed server side. Also it can be quite long exceeding maximum allowed cookies length. #### Add Back-Channel Logout support Authentik now supports Back-Channel logout. So I implemented it here, too. There is a POST endpoint on ABS side. When the configuration is turned on, it accepts a signed JWT from Authentik and can cancel sessions. When a user logs out on Authentik, Authentik will use it to log out a user on ABS too. (The user's existing access token remains valid until it expires). #### Other Jose was added as explicit dependency for Backchannel Logout (there for checking the JWT). It was a dependency anyway from node-openid-client. ## How have you tested this? Simply add a mapper for one on the groups and use as value an Authentik Group. For Backchannel logout. Make sure to configure the URL in Authentik. Then check the sessions in ABS sqliteDB. Then log out in authentik. You should see in the ABS Console a message that there was a Back Channel logout. The session will be gone in the ABS sqliteDB. Also added extensive unit tests. ## Screenshots <img width="1030" height="1523" alt="image" src="https://github.com/user-attachments/assets/a5a32bae-8136-4885-ba71-c09a6da2f648" /> --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
adam added the pull-request label 2026-04-25 00:19:36 +02:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
authentication
backlog
bug
chapter editor
config-issue
ebooks
encoding/embedding
enhancement
help wanted
listening sessions & progress
planned
possible plugin
progress sync
pull-request
Mirrored from GitHub Pull Request
 sorting/filtering/searching
unable to reproduce
upload
users & permissions
waiting
No Label pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adam (Adam Melkus)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/audiobookshelf#4399
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?