OIDC Group-Sync with iServ #5192

New Issue

OVERLORD · 2026-02-05T09:47:15+03:00

OVERLORD commented

2026-02-05 09:47:15 +03:00

Originally created by @demlak on GitHub (Feb 21, 2025).

Attempted Debugging

I have read the debugging page

Searched GitHub Issues

I have searched GitHub for the issue.

Describe the Scenario

after fixing the same issue like here https://github.com/BookStackApp/BookStack/issues/4451 by providing key + endpoints, i now try to sync groups with our iServ-OIDC login.. but i can't match the groups..

Any hints on OIDC_GROUPS_CLAIM with this JSON from OIDC_DUMP_USER_DETAILS?

{
  "exp": 1740089286,
  "iat": 1740085686,
  "iss": "https://ourserver.de",
  "aud": "xxxxxxxxxxxxxxxxxxxxxxxx",
  "sub": "xxxxxxxxxxxxxxxxxxxxxxxx",
  "nonce": null,
  "email": "foo.bar@ourserver.de",
  "email_verified": true,
  "groups": {
    "10006": {
      "id": 10006,
      "uuid": "xxxxxxxxxxxxxxxxxxxxxxxx",
      "act": "schueler",
      "name": "Schüler"
    },
    "10742": {
      "id": 10742,
      "uuid": "xxxxxxxxxxxxxxxxxxxxxxxx",
      "act": "digitales.schuelerblatt",
      "name": "Digitales Schülerblatt"
    },
    "10740": {
      "id": 10740,
      "uuid": "xxxxxxxxxxxxxxxxxxxxxxxx",
      "act": "infobildschirm",
      "name": "Infobildschirm"
    },
    "10741": {
      "id": 10741,
      "uuid": "xxxxxxxxxxxxxxxxxxxxxxxx",
      "act": "stundenplan",
      "name": "Stundenplan"
    },
    "10000": {
      "id": 10000,
      "uuid": "xxxxxxxxxxxxxxxxxxxxxxxx",
      "act": "admins",
      "name": "Admins"
    },
    "10273": {
      "id": 10273,
      "uuid": "xxxxxxxxxxxxxxxxxxxxxxxx",
      "act": "kollegium",
      "name": "Kollegium"
    },
    "10329": {
      "id": 10329,
      "uuid": "xxxxxxxxxxxxxxxxxxxxxxxx",
      "act": "support",
      "name": "support"
    }
  },
  "preferred_username": "foo.bar",
  "name": "foo bar",
  "nickname": "foo",
  "given_name": "foo",
  "family_name": "bar",
  "locale": "de-DE"
}

i tried Rolename schueler and also External Auth ID "10006", but when an already logged-in user loggs out and login again, this user is not in the group.

thx in advance for helping

Exact BookStack Version

v24.12.1

Log Content

No response

Hosting Environment

Bookstack in an LXC installed via helper-scripts.com on a proxmox.

Originally created by @demlak on GitHub (Feb 21, 2025). ### Attempted Debugging - [x] I have read the debugging page ### Searched GitHub Issues - [x] I have searched GitHub for the issue. ### Describe the Scenario after fixing the same issue like here https://github.com/BookStackApp/BookStack/issues/4451 by providing key + endpoints, i now try to sync groups with our iServ-OIDC login.. but i can't match the groups.. Any hints on `OIDC_GROUPS_CLAIM` with this JSON from `OIDC_DUMP_USER_DETAILS`? ``` { "exp": 1740089286, "iat": 1740085686, "iss": "https://ourserver.de", "aud": "xxxxxxxxxxxxxxxxxxxxxxxx", "sub": "xxxxxxxxxxxxxxxxxxxxxxxx", "nonce": null, "email": "foo.bar@ourserver.de", "email_verified": true, "groups": { "10006": { "id": 10006, "uuid": "xxxxxxxxxxxxxxxxxxxxxxxx", "act": "schueler", "name": "Schüler" }, "10742": { "id": 10742, "uuid": "xxxxxxxxxxxxxxxxxxxxxxxx", "act": "digitales.schuelerblatt", "name": "Digitales Schülerblatt" }, "10740": { "id": 10740, "uuid": "xxxxxxxxxxxxxxxxxxxxxxxx", "act": "infobildschirm", "name": "Infobildschirm" }, "10741": { "id": 10741, "uuid": "xxxxxxxxxxxxxxxxxxxxxxxx", "act": "stundenplan", "name": "Stundenplan" }, "10000": { "id": 10000, "uuid": "xxxxxxxxxxxxxxxxxxxxxxxx", "act": "admins", "name": "Admins" }, "10273": { "id": 10273, "uuid": "xxxxxxxxxxxxxxxxxxxxxxxx", "act": "kollegium", "name": "Kollegium" }, "10329": { "id": 10329, "uuid": "xxxxxxxxxxxxxxxxxxxxxxxx", "act": "support", "name": "support" } }, "preferred_username": "foo.bar", "name": "foo bar", "nickname": "foo", "given_name": "foo", "family_name": "bar", "locale": "de-DE" } ``` i tried Rolename `schueler` and also External Auth ID "10006", but when an already logged-in user loggs out and login again, this user is not in the group. thx in advance for helping ### Exact BookStack Version v24.12.1 ### Log Content _No response_ ### Hosting Environment Bookstack in an LXC installed via helper-scripts.com on a proxmox.

OVERLORD added the 🐕 Support label 2026-02-05 09:47:15 +03:00

OVERLORD closed this issue

2026-02-05 09:47:18 +03:00

OVERLORD commented

2026-02-05 09:47:21 +03:00

@ssddanbrown commented on GitHub (Feb 21, 2025):

Hi @demlak,

That format of groups isn't directly supported. Do you have any control in the "iserv" system over how the groups are provided?

Otherwise, there may be a way to manipulate the existing format on the BookStack side to make things work but it'd need some custom code, hence asking about possibilities on the auth side first.

@ssddanbrown commented on GitHub (Feb 21, 2025): Hi @demlak, That format of groups isn't directly supported. Do you have any control in the "iserv" system over how the groups are provided? Otherwise, there may be a way to manipulate the existing format on the BookStack side to make things work but it'd need some custom code, hence asking about possibilities on the auth side first.

OVERLORD commented

2026-02-05 09:47:22 +03:00

@demlak commented on GitHub (Feb 21, 2025):

Hi @demlak,

Thx for your fast reply!

That format of groups isn't directly supported. Do you have any control in the "iserv" system over how the groups are provided?

with jq i would parse it like this: .groups.[].act

The parts i can configure are the "Grant-types" of "Authorization Code", "Implicit", "Password", "Client Credentials" and "Refresh Token",

I am also able to choose the Scopes: email, groups, openid, profile, roles, uuid (and two system-specific)

I am not able to go deeper, like changing code or so.. but the support behind "iServ" is sometimes open for suggestions.. so, if you have detailed hints, i can provide them to the support.. maybe they will have an open ear.

Otherwise, there may be a way to manipulate the existing format on the BookStack side to make things work but it'd need some custom code, hence asking about possibilities on the auth side first.

iServ is wide spreaded in germany.. it is a school-managing software, used in nearly 6000 schools.. so maybe it's a good thing to support it? =)

@demlak commented on GitHub (Feb 21, 2025): > Hi [@demlak](https://github.com/demlak), Thx for your fast reply! > That format of groups isn't directly supported. Do you have any control in the "iserv" system over how the groups are provided? > with jq i would parse it like this: `.groups.[].act` The parts i can configure are the "Grant-types" of "Authorization Code", "Implicit", "Password", "Client Credentials" and "Refresh Token", I am also able to choose the Scopes: email, groups, openid, profile, roles, uuid (and two system-specific) I am not able to go deeper, like changing code or so.. but the support behind "iServ" is sometimes open for suggestions.. so, if you have detailed hints, i can provide them to the support.. maybe they will have an open ear. > Otherwise, there may be a way to manipulate the existing format on the BookStack side to make things work but it'd need some custom code, hence asking about possibilities on the auth side first. iServ is wide spreaded in germany.. it is a school-managing software, used in nearly 6000 schools.. so maybe it's a good thing to support it? =)

OVERLORD commented

2026-02-05 09:47:23 +03:00

@ssddanbrown commented on GitHub (Feb 21, 2025):

so maybe it's a good thing to support it?

I'm not keen on supporting additional formats based on specific platforms, I'd prefer to keep to the simple array of group names which most auth systems provide.

When I get a moment at my dev machine I'll look to put together a logical theme system hack to convert the format.

@ssddanbrown commented on GitHub (Feb 21, 2025): > so maybe it's a good thing to support it? I'm not keen on supporting additional formats based on specific platforms, I'd prefer to keep to the simple array of group names which most auth systems provide. When I get a moment at my dev machine I'll look to put together a [logical theme system hack](https://github.com/BookStackApp/BookStack/blob/development/dev/docs/logical-theme-system.md#logical-theme-system) to convert the format.

OVERLORD commented

2026-02-05 09:47:25 +03:00

@demlak commented on GitHub (Feb 21, 2025):

I don't know the syntax, that can be used in OIDC_GROUPS_CLAIM.. but in bash i am able to use this call with jq to parse the group-names: cat json.txt | jq -r '.groups.[].act'

Maybe it is possible to do similar at OIDC_GROUPS_CLAIM?

@demlak commented on GitHub (Feb 21, 2025): I don't know the syntax, that can be used in `OIDC_GROUPS_CLAIM`.. but in bash i am able to use this call with jq to parse the group-names: `cat json.txt | jq -r '.groups.[].act'` Maybe it is possible to do similar at `OIDC_GROUPS_CLAIM`?

OVERLORD commented

2026-02-05 09:47:26 +03:00

@ssddanbrown commented on GitHub (Feb 21, 2025):

Here's a logical theme system hack which should reformat the groups to just be the id values:

<?php

use BookStack\Facades\Theme;
use BookStack\Theming\ThemeEvents;

// Listen to OIDC ID Token pre validation event so that we can handle token data
Theme::listen(ThemeEvents::OIDC_ID_TOKEN_PRE_VALIDATE, function (array $idTokenData, array $accessTokenData) {

    // If there are groups in the response, reformat them
    if (isset($idTokenData['groups'])) {
        $reformattedGroups = [];

        // For each of the groups, grab just the ID property
        foreach ($idTokenData['groups'] as $group) {
            $reformattedGroups[] = $group['id'];
        }

        // Alter the groups property to just be the array of ids we've collected
        $idTokenData['groups'] = $reformattedGroups;
    }

    // Return our tweaked token data
    return $idTokenData;
});

You'll need to have this as your functions.php file within an active theme folder following our logical theme system guidance.

Note: I haven't tested this, just built to what should hopefully work for your scenario.

@ssddanbrown commented on GitHub (Feb 21, 2025): Here's a logical theme system hack which should reformat the groups to just be the `id` values: ```php <?php use BookStack\Facades\Theme; use BookStack\Theming\ThemeEvents; // Listen to OIDC ID Token pre validation event so that we can handle token data Theme::listen(ThemeEvents::OIDC_ID_TOKEN_PRE_VALIDATE, function (array $idTokenData, array $accessTokenData) { // If there are groups in the response, reformat them if (isset($idTokenData['groups'])) { $reformattedGroups = []; // For each of the groups, grab just the ID property foreach ($idTokenData['groups'] as $group) { $reformattedGroups[] = $group['id']; } // Alter the groups property to just be the array of ids we've collected $idTokenData['groups'] = $reformattedGroups; } // Return our tweaked token data return $idTokenData; }); ``` You'll need to have this as your `functions.php` file within an active theme folder following our [logical theme system](https://github.com/BookStackApp/BookStack/blob/development/dev/docs/logical-theme-system.md#getting-started) guidance. Note: I haven't tested this, just built to what should hopefully work for your scenario.

OVERLORD commented

2026-02-05 09:47:28 +03:00

@demlak commented on GitHub (Feb 21, 2025):

Thx a lot.. it seem to work!

just a little change on my side: $group['id']; -> $group['act'];

@demlak commented on GitHub (Feb 21, 2025): Thx a lot.. it seem to work! just a little change on my side: `$group['id'];` -> `$group['act'];`

OVERLORD commented

2026-02-05 09:47:29 +03:00

@ssddanbrown commented on GitHub (Feb 21, 2025):

Good to hear that worked! Will therefore close this off.

@ssddanbrown commented on GitHub (Feb 21, 2025): Good to hear that worked! Will therefore close this off.

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/BookStack#5192