mirror of
https://github.com/advplyr/audiobookshelf.git
synced 2026-03-02 22:46:56 -05:00
[Enhancement]: OIDC: Add possibility to spcecify names of group claims #2083
Labels
No labels
authentication
awaiting release
backlog
bug
chapter editor
config-issue
ebooks
encoding/embedding
enhancement
help wanted
listening sessions & progress
planned
possible plugin
progress sync
sorting/filtering/searching
unable to reproduce
upload
users & permissions
waiting
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
starred/audiobookshelf#2083
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
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?
Originally created by @v3DJG6GL on GitHub (Apr 24, 2024).
Describe the feature/enhancement
With #2769 we do now have the possiblity to specify Group Claims for the groups
admin,userandguest.While I really appreciate that feature, It would be nice to also specify the names of these groups, rather than relying on these hardcoded names
admin,userandguest.I do have a setup with Authelia and LLDAP and I do have a lot of different user groups specified which are allowed to use specific services. As an example, I do have a
nextcloud_usersgroup for all users that are allowed to use Nextcloud and ajellyfin_usersgroup for all users that are allowed to use Jellyfin. The same goes for admin groups, although that's less relevant in my case.I'd love to see a similar option for ABS :)
@advplyr commented on GitHub (Apr 24, 2024):
You should be able to use whatever group names you want and just add a custom property mapping. I haven't used Authelia but I used Authentik to successfully map some groups I setup with different names.
I followed @Sapd's guide in this PR https://github.com/advplyr/audiobookshelf/pull/2769
@Sapd commented on GitHub (Apr 24, 2024):
It was in the original concept (see https://github.com/advplyr/audiobookshelf/issues/2523 ) but left out because identity providers usually provide the ability of attribute mappings. Not sure about Authelia, but KeyCloak and Authentik can do that.
@v3DJG6GL commented on GitHub (Apr 24, 2024):
hmh, would it be something like this?
https://github.com/authelia/authelia/issues/2868
That's not (yet) implemented in Authelia.
All other OIDC-claim capable apps I use have the possibility to specify the names for group claims so I wasn't even aware that there's an option to map custom properties.
But yeah, it doesn't seem to be supported by Authelia...
@Sapd commented on GitHub (Apr 24, 2024):
Yeah in fact that would be it.
I also just remembered another (severe) limitation of Authelia, it does not support restricting access for OpenID Connect: https://www.authelia.com/integration/openid-connect/frequently-asked-questions/#why-doesnt-the-access-control-configuration-work-with-openid-connect-10 which makes the combination with this issue a bit worse
@advplyr commented on GitHub (Apr 24, 2024):
@v3DJG6GL What are some other self-hosted apps that support OIDC have that feature? I'd like to see how they implemented it.
I'm not sure if it is worth adding more complexity to our OIDC implementation if 2 out of 3 major providers support this already.
@advplyr commented on GitHub (Apr 24, 2024):
From your OP I can guess nextcloud and the jellyfin SSO plugin.
@v3DJG6GL commented on GitHub (Apr 24, 2024):
@CEbbinghaus commented on GitHub (Nov 2, 2024):
Just wanted to add my support for this. kanidm/kanidm does not allow custom group names and instead provides the group names either as their unique guid or as their unique specifier
group_name@host.tldwhich makes it completely incompatible with audiobookshelf.Ideally there would be a UI to map group names provided as strings to the groups within audiobookshelf so the user could specify the groups.
I had a little stab at implementing it myself but I'm not overly fond nor adept at vuejs frontend dev. Will see if I can get it looking halfway decent though and submit a patch.
@igbjnI05bF commented on GitHub (Nov 19, 2024):
I have no idea if my issue is related to this or not, if it isn't just let me know and maybe I'll make a new issue for it.
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?
@Sapd commented on GitHub (Nov 23, 2024):
@igbjnI05bF It would be better if you create a new discussion for that.
Edit I missed that you want to use the dedicated scope. Indeed that currently does not work. Because one cannot specify which scopes to request. It will always request a scope with the same name as the claim currently.
I quickly tested it however and it works and there seems to be multiple ways
First make sure you set ABS logs to "Debug" this way you can see in the logs the userinfo field which is returned.
Your goal is that userinfo should look like this:
Basically there must be a scope with a mapper which is for example named absgroups. It must be multi-value (so it will be an array)
In this case I did an attribute mapper. It is important to check that it will be included in user-info, the name must the for example absgroups, "token claim name" must also be the same. Also ofc the client needs to add that scope.
Then I added to my testuser the attribute "absgroups" and the value "admin".
I also tested to match roles, which also work. Note that you will need one of the latest major versions of keycloak for that to work. As there was a bug where he would not rename roles in userinfo.
For that also simply create a Client Scope and assign it in the Client. Add a "absadmin" role IN the client. Assign your user to it.



Then create those two mappings in client scopes:
@igbjnI05bF commented on GitHub (Nov 25, 2024):
@Sapd
I appreciate your response. I hope that we can use the dedicated scope in the future as it just seems the cleanest way to implement per-client roles and not make your keycloak realm messy. I will play with your solution later today and try to implement it that way for now. Thanks!
@cyclingwithelephants commented on GitHub (Apr 21, 2025):
Given it looks like this isn't going to be implemented client side, is it possible to provide an example for how to implement this with Authelia? Happy to update documentation accordingly
@yourfate commented on GitHub (Apr 29, 2025):
I want this as well, with my setup (lldap + pocket ID) its kind of annoying to scope the gropus to audiobookshelf.
@cyclingwithelephants commented on GitHub (Apr 29, 2025):
I ended up taking the hit and lost much of a day to this, but I got it working with Authelia. I even hit a bug in the Authelia helm chart because this feature was brand new. I hope this is helpful to people.
It would be much nicer from an end user perspective to allow this mapping from Audiobookshelf's side, I do appreciate it's work though. Something as simple as being able to say "groups X,Y,Z map to admin, groups A,B,C map to user, groups D,E,F map to guest" would have made a big difference.
If somebody lets me know where to put the documentation, I'm happy to write this up for audiobookshelf, or would you rather this existed in Authelia's docs?
@zodac-personal commented on GitHub (Aug 10, 2025):
I gave this a try with the latest Authelia (4.39.5), but wasn't able to get it to work. I might come back to it again, but it would be much more straightforward if we could customise the groups that ABS is looking for.
@Lasithih commented on GitHub (Sep 2, 2025):
I am using Keycloak and OIDC in general works when I don't use the groups claim. But when I turn it on, "Error in callback" error message is shown.
This is what my groups mapper looks like.

I know this works because I use the same config for syncing groups to Proxmox.
This is the error I see in the browser.
Any idea what I am doing wrong here?
Thanks!
@Sapd commented on GitHub (Sep 2, 2025):
@Lasithih See my explanation above, it handles that exact case: https://github.com/advplyr/audiobookshelf/issues/2878#issuecomment-2495505329
I will overwrite some things towards end of this year which should also fix that issue entirely.
@Lasithih commented on GitHub (Sep 5, 2025):
@Sapd I tried both User Attribute and Role Name Mapper. But for some reason I'm stuck with the same error.
@languagegame commented on GitHub (Oct 15, 2025):
I also would like to see this mapping in audiobookshelf for pocket ID. Not all OIDC providers (yet) providing mapping capabilities, so helpful to have this in audiobookshelf itself. In other words, the user sets the group claim and then is allowed to determine which group name maps to admin, user and guest in audiobookshelf
@MadManChLP commented on GitHub (Oct 30, 2025):
anything new to this becaws i want to use authentik but cant get it to work because i cant ise the group naming admin, user and guest for some security reasons
@Sapd commented on GitHub (Oct 30, 2025):
On Authentik its a none issue because you can user mappers.
@MadManChLP commented on GitHub (Oct 31, 2025):
im quite new to authentik so how do i ned to configure it could you please tell me more
@Sapd commented on GitHub (Oct 31, 2025):
See here: https://github.com/advplyr/audiobookshelf/pull/2769
@MadManChLP commented on GitHub (Oct 31, 2025):
thanks
@staticdev commented on GitHub (Feb 3, 2026):
@Sapd I am available to collaborate with that also. Using Keycloak here, and I am also contributing to Jellyfin SSO and Nextcloud OIDC plugin. Abs native OIDC is the best self-hosting experience I had so far, only the groups handling is missing this last step to be 100% smooth. ;)
@Sapd commented on GitHub (Feb 5, 2026):
Yeah I will probably try to make some time for a sweep. Also there are other points open like removing the passport layer.
@Sapd commented on GitHub (Feb 5, 2026):
@staticdev If you have time you can test that please: https://github.com/advplyr/audiobookshelf/pull/5031
@staticdev commented on GitHub (Feb 5, 2026):
Looks awesome @Sapd , i can try in the weekend.