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

[Enhancement]: OpenID Connect add setting for requested scopes #2010

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

Originally created by @exu-g on GitHub (May 24, 2024).

Type of Enhancement

Server Backend

Describe the Feature/Enhancement

Please add a setting to request specific scopes in addition to the 3 basic ones.

Something similar to this, as offered by the OpenID Connect addon for Nextcloud.

image

Why would this be helpful?

In practice, it's possible to have different names for the scope and its contained claim.
I usually use the application name for the scope and have a different name for the actual claim for consistency on the application side.

Scope:
image

Claim:
image

With the current settings this does not work, either I set the correct claim and the scope won't be sent at all, or I use the working scope, but can't find any groups within.

Future Implementation (Screenshot)

A simple field titled "additional scopes" would be fine.

Audiobookshelf Server Version

v2.9.0

Current Implementation (Screenshot)

Settings > Authentication > OpenID Connect Authentication
image

Originally created by @exu-g on GitHub (May 24, 2024). ### Type of Enhancement Server Backend ### Describe the Feature/Enhancement Please add a setting to request specific scopes in addition to the 3 basic ones. Something similar to this, as offered by the OpenID Connect addon for Nextcloud. ![image](https://github.com/advplyr/audiobookshelf/assets/61015582/0c86ded1-be18-4a8f-8161-2dcecf869ca5) ### Why would this be helpful? In practice, it's possible to have different names for the scope and its contained claim. I usually use the application name for the scope and have a different name for the actual claim for consistency on the application side. Scope: ![image](https://github.com/advplyr/audiobookshelf/assets/61015582/8b080734-df05-46cd-8dd8-cb83590cc812) Claim: ![image](https://github.com/advplyr/audiobookshelf/assets/61015582/3bda4312-460f-4fd7-8b8d-66576f1b1244) With the current settings this does not work, either I set the correct claim and the scope won't be sent at all, or I use the working scope, but can't find any groups within. ### Future Implementation (Screenshot) A simple field titled "additional scopes" would be fine. ### Audiobookshelf Server Version v2.9.0 ### Current Implementation (Screenshot) Settings > Authentication > OpenID Connect Authentication ![image](https://github.com/advplyr/audiobookshelf/assets/61015582/922465a1-b848-4ab2-9d5c-d3ebe690eef0)
adam added the enhancementauthentication labels 2026-04-25 00:02:22 +02:00
adam commented 2026-04-25 00:02:23 +02:00
Author
Owner
Copy Link
Copy Source

@advplyr commented on GitHub (May 24, 2024):

Is this a duplicate of https://github.com/advplyr/audiobookshelf/issues/2878?

With Authentik and KeyCloak you can name the groups however you want and setup a mapping. Maybe you are using Authelia?

@advplyr commented on GitHub (May 24, 2024): Is this a duplicate of https://github.com/advplyr/audiobookshelf/issues/2878? With Authentik and KeyCloak you can name the groups however you want and setup a mapping. Maybe you are using Authelia?
adam commented 2026-04-25 00:02:23 +02:00
Author
Owner
Copy Link
Copy Source

@exu-g commented on GitHub (May 24, 2024):

No, this is about having different scope and claim names. I am using Authentik with a custom mapping to change my group names into the ones specified by Audiobookshelf.

From my understanding, scopes are some kind of container for one or mutliple claims.
Something like this
image

Simplified, I have this mapping.
image

I can change the mapping to this and it works. Here both the scope and claim are called "audiobookshelf" and I set the same value in the Audiobookshelf OIDC settings "Group Claim" field.
image

But scopes can also contain multiple claims. As an example, the openid scope contains these claims:

{
  "iss": "http://my-domain.auth0.com",
  "sub": "auth0|123456",
  "aud": "my_client_id",
  "exp": 1311281970,
  "iat": 1311280970,
  "name": "Jane Doe",
  "given_name": "Jane",
  "family_name": "Doe",
  "gender": "female",
  "birthdate": "0000-10-31",
  "email": "janedoe@example.com",
  "picture": "http://example.com/janedoe/me.jpg"
}

from https://auth0.com/docs/secure/tokens/id-tokens/id-token-structure

This can also be done for custom mappings like this. Here I'm setting the Group Claim and Advanced Permission Claim within the same scope.
image

Visually represented something like this
image

With the current implementation I have to name one claim the same as the scope.
If we could specify the scope separately, the previous graphic would work.

After typing all this out, this is a very tiny issue most users won't ever encounter.
But it does feel more correct to separate scopes and claims.

I guess adding a note that claim == scope name in the documentation would suffice, so others don't have to spend time wondering why the heck stuff doesn't work.

@exu-g commented on GitHub (May 24, 2024): No, this is about having different scope and claim names. I am using Authentik with a custom mapping to change my group names into the ones specified by Audiobookshelf. From my understanding, scopes are some kind of container for one or mutliple claims. Something like this ![image](https://github.com/advplyr/audiobookshelf/assets/61015582/4b22e15f-b96b-445c-8cdf-e9fd4994b3d9) Simplified, I have this mapping. ![image](https://github.com/advplyr/audiobookshelf/assets/61015582/e1597f9b-e2d5-47ae-b463-bafd93b5bb95) I can change the mapping to this and it works. Here both the scope and claim are called "audiobookshelf" and I set the same value in the Audiobookshelf OIDC settings "Group Claim" field. ![image](https://github.com/advplyr/audiobookshelf/assets/61015582/f193c467-1353-4503-aa98-862c818583c7) But scopes can also contain multiple claims. As an example, the `openid` scope contains these claims: ``` { "iss": "http://my-domain.auth0.com", "sub": "auth0|123456", "aud": "my_client_id", "exp": 1311281970, "iat": 1311280970, "name": "Jane Doe", "given_name": "Jane", "family_name": "Doe", "gender": "female", "birthdate": "0000-10-31", "email": "janedoe@example.com", "picture": "http://example.com/janedoe/me.jpg" } ``` *from https://auth0.com/docs/secure/tokens/id-tokens/id-token-structure* This can also be done for custom mappings like this. Here I'm setting the Group Claim and Advanced Permission Claim within the same scope. ![image](https://github.com/advplyr/audiobookshelf/assets/61015582/df6c8b7f-3e22-4da5-8bd0-9e391a6a3317) Visually represented something like this ![image](https://github.com/advplyr/audiobookshelf/assets/61015582/61a9956d-136b-4576-9e2a-e5f72e0286d0) With the current implementation I have to name one claim the same as the scope. If we could specify the scope separately, the previous graphic would work. --- After typing all this out, this is a very tiny issue most users won't ever encounter. But it does feel more correct to separate scopes and claims. I guess adding a note that claim == scope name in the documentation would suffice, so others don't have to spend time wondering why the heck stuff doesn't work.
adam commented 2026-04-25 00:02:23 +02:00
Author
Owner
Copy Link
Copy Source

@Sapd commented on GitHub (May 28, 2024):

I guess adding a note that claim == scope name in the documentation would suffice, so others don't have to spend time wondering why the heck stuff doesn't work.

Yeah I thought (when I developed that feature) to show the claims as greyed-out box which would update with the name of the group claims etc., which would make claim == scope then clear.

But you also got a point that it makes sense to add a box and to allow to add claims to allow configurations as you showed. There then just must be a warning to the user that he also has to put in the name of the scope which contains the claim explicitly in the additional claims field.

PS: I know you just made example pictures, but to prevent you a debugging session, keep in mind that in "abspermissions" in Authentik you have to write the booleans als true python booleans like this. Otherwise they won't be provided as JSON boolean types:

abspermissions = {
  "abspermissions": {
    "canDownload": False, # Upper case without "
     "canUpload": True
     ....
   }
}
@Sapd commented on GitHub (May 28, 2024): > I guess adding a note that claim == scope name in the documentation would suffice, so others don't have to spend time wondering why the heck stuff doesn't work. Yeah I thought (when I developed that feature) to show the claims as greyed-out box which would update with the name of the group claims etc., which would make claim == scope then clear. But you also got a point that it makes sense to add a box and to allow to add claims to allow configurations as you showed. There then just must be a warning to the user that he also has to put in the name of the scope which contains the claim explicitly in the additional claims field. PS: I know you just made example pictures, but to prevent you a debugging session, keep in mind that in "abspermissions" in Authentik you have to write the booleans als true python booleans like this. Otherwise they won't be provided as JSON boolean types: ```python abspermissions = { "abspermissions": { "canDownload": False, # Upper case without " "canUpload": True .... } } ```
adam commented 2026-04-25 00:02:23 +02:00
Author
Owner
Copy Link
Copy Source

@igbjnI05bF commented on GitHub (Nov 16, 2024):

I'm very confused here, most of this is above my head. I'm unable to get the group claim to work at all with keycloak. I've done this successfully with other apps such as Nextcloud, Jellyfin, and Grafana, but cannot get it to work with Audiobookshelf.

In my Audiobookshelf client in Keycloak I went to client scopes, audiobookshelf-dedicated, and added a client roles scope. I named the token claim name "absroles". I then went to the roles tab of audiobookshelf and created "admin", "guest", and "user" roles. I added my user to the audiobookshelf/admin role.

I cannot sign into Audiobookshelf, it says "Error in callback". The webtools show "Invalid scopes: openid profile email absroles". I don't really get it, openid, profile, and email are global realm scopes. absroles isn't (and shouldn't) be a realm scope, it's a client scope.

Am I missing something here? How do I get Audiobookshelf to see this client scope I made and respect the client roles my users are in?

@igbjnI05bF commented on GitHub (Nov 16, 2024): I'm very confused here, most of this is above my head. I'm unable to get the group claim to work at all with keycloak. I've done this successfully with other apps such as Nextcloud, Jellyfin, and Grafana, but cannot get it to work with Audiobookshelf. In my Audiobookshelf client in Keycloak I went to client scopes, audiobookshelf-dedicated, and added a client roles scope. I named the token claim name "absroles". I then went to the roles tab of audiobookshelf and created "admin", "guest", and "user" roles. I added my user to the audiobookshelf/admin role. I cannot sign into Audiobookshelf, it says "Error in callback". The webtools show "Invalid scopes: openid profile email absroles". I don't really get it, openid, profile, and email are global realm scopes. absroles isn't (and shouldn't) be a realm scope, it's a client scope. Am I missing something here? How do I get Audiobookshelf to see this client scope I made and respect the client roles my users are in?
adam commented 2026-04-25 00:02:23 +02:00
Author
Owner
Copy Link
Copy Source

@megheaiulian commented on GitHub (Mar 18, 2025):

I think the issue is at https://github.com/advplyr/audiobookshelf/blob/master/server/Auth.js#L514.
It adds the authOpenIDGroupClaim as a scope value but I think it shouldn't as that is just the property to make groups from.

@megheaiulian commented on GitHub (Mar 18, 2025): I think the issue is at https://github.com/advplyr/audiobookshelf/blob/master/server/Auth.js#L514. It adds the `authOpenIDGroupClaim` as a scope value but I think it shouldn't as that is just the property to make groups from.
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 authentication enhancement
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#2010
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?