starred/audiobookshelf

Fork 0

mirror of https://github.com/advplyr/audiobookshelf.git synced 2026-03-02 22:46:56 -05:00

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

New issue

Open

opened 2026-02-20 02:13:09 -05:00 by deekerman · 5 comments

deekerman commented

2026-02-20 02:13:09 -05:00

Owner

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.

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:

Claim:

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

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)

deekerman added the

enhancement

authentication

labels

2026-02-20 02:13:09 -05:00

deekerman commented

2026-02-20 02:13:10 -05:00

Author

Owner

@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?

deekerman commented

2026-02-20 02:13:10 -05:00

Author

Owner

@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

Simplified, I have this mapping.

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.

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.

Visually represented something like this

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.

deekerman commented

2026-02-20 02:13:11 -05:00

Author

Owner

@Sapd commented on GitHub (May 27, 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 27, 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 .... } } ```

deekerman commented

2026-02-20 02:13:11 -05:00

Author

Owner

@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?

deekerman commented

2026-02-20 02:13:11 -05:00

Author

Owner

@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.