OIDC: Ability to specify external_id claim #3399

New Issue

OVERLORD · 2026-02-05T06:36:00+03:00

OVERLORD commented

2026-02-05 06:36:00 +03:00

Originally created by @danpoltawski on GitHub (Dec 13, 2022).

Describe the feature you'd like

The ability to specify the OIDC claim which is used to map users via external auth would be useful for migrations from other auth systems.

I'm trying to convert from AUTH_AZUREAD to OIDC and the mapping of external_id statically to sub is problematic. 24f82749ff/app/Auth/Access/Oidc/OidcService.php (L206)

As this value appears to be opaque in Azure AD and difficult to retrieve in bulk. The process of moving users from AUTH_AZUREAD would be difficult. I'd like to set the external_id value to something like UPN which would allow me to bulk-update users and have aseamless migraiton.

Describe the benefits this would bring to existing BookStack users

Easier migration of users from other auth systems to OIDC. Consistency with SAML2_EXTERNAL_ID_ATTRIBUTE

Can the goal of this request already be achieved via other means?

Not as far as I know.

Have you searched for an existing open/closed issue?

I have searched for existing issues and none cover my fundemental request

How long have you been using BookStack?

1 to 5 years

Additional context

Hacky POC patch which wuld allow me to link on UPN

diff --git a/app/Auth/Access/Oidc/OidcService.php b/app/Auth/Access/Oidc/OidcService.php
index b8e017b4..14577c1e 100644
--- a/app/Auth/Access/Oidc/OidcService.php
+++ b/app/Auth/Access/Oidc/OidcService.php
@@ -151,7 +151,7 @@ class OidcService
         $id = $token->getClaim('sub');

         return [
-            'external_id' => $id,
+            'external_id' => $token->getClaim('upn'),
             'email'       => $token->getClaim('email'),
             'name'        => $this->getUserDisplayName($token, $id),
         ];

Originally created by @danpoltawski on GitHub (Dec 13, 2022). ### Describe the feature you'd like The ability to specify the OIDC claim which is used to map users via external auth would be useful for migrations from other auth systems. I'm trying to convert from `AUTH_AZUREAD` to `OIDC` and the mapping of `external_id` statically to `sub` is problematic. https://github.com/BookStackApp/BookStack/blob/24f82749ffd03f9a4800dd32545ace46e5fe7dcc/app/Auth/Access/Oidc/OidcService.php#L206 As this value appears to be opaque in Azure AD and difficult to retrieve in bulk. The process of moving users from AUTH_AZUREAD would be difficult. I'd like to set the `external_id` value to something like UPN which would allow me to bulk-update users and have aseamless migraiton. ### Describe the benefits this would bring to existing BookStack users Easier migration of users from other auth systems to OIDC. Consistency with `SAML2_EXTERNAL_ID_ATTRIBUTE` ### Can the goal of this request already be achieved via other means? Not as far as I know. ### Have you searched for an existing open/closed issue? - [X] I have searched for existing issues and none cover my fundemental request ### How long have you been using BookStack? 1 to 5 years ### Additional context Hacky POC patch which wuld allow me to link on UPN ``` diff --git a/app/Auth/Access/Oidc/OidcService.php b/app/Auth/Access/Oidc/OidcService.php index b8e017b4..14577c1e 100644 --- a/app/Auth/Access/Oidc/OidcService.php +++ b/app/Auth/Access/Oidc/OidcService.php @@ -151,7 +151,7 @@ class OidcService $id = $token->getClaim('sub'); return [ - 'external_id' => $id, + 'external_id' => $token->getClaim('upn'), 'email' => $token->getClaim('email'), 'name' => $this->getUserDisplayName($token, $id), ]; ```

OVERLORD added the 🔨 Feature Request 📖 Docs Update 🚪 Authentication labels 2026-02-05 06:36:00 +03:00

OVERLORD closed this issue

2026-02-05 06:36:04 +03:00

OVERLORD commented

2026-02-05 06:36:08 +03:00

@ssddanbrown commented on GitHub (Jan 26, 2023):

@danpoltawski I thought that with OIDC we can be nicely fixed to the standard spec but nooooo, of course that was too good to be true, and active directory has to ruin the party 😢

Can totally understand why you'd want this though based upon what AzureAD is providing. Should be a relatively simple addition too.

@ssddanbrown commented on GitHub (Jan 26, 2023): @danpoltawski I thought that with OIDC we can be nicely fixed to the standard spec but nooooo, of course that was too good to be true, and active directory has to ruin the party :cry: Can totally understand why you'd want this though based upon what AzureAD is providing. Should be a relatively simple addition too.

OVERLORD commented

2026-02-05 06:36:11 +03:00

@danpoltawski commented on GitHub (Jan 26, 2023):

You've made me wonder if there might be some AzureAD voodoo to get the UPN into the sub field 🤔

@danpoltawski commented on GitHub (Jan 26, 2023): You've made me wonder if there might be some AzureAD voodoo to get the UPN into the sub field 🤔

OVERLORD commented

2026-02-05 06:36:14 +03:00

@ssddanbrown commented on GitHub (Jan 26, 2023):

Maybe there is but, knowing these platforms, you have to upgrade all authenticating users to a Premium P15 Enterprise license or something like that.

@ssddanbrown commented on GitHub (Jan 26, 2023): Maybe there is but, knowing these platforms, you have to upgrade all authenticating users to a `Premium P15 Enterprise` license or something like that.

OVERLORD commented

2026-02-05 06:36:19 +03:00

@ssddanbrown commented on GitHub (Jan 26, 2023):

I've now added this via commit 811be3a36a. This will be part of the next feature release.
The env option will be as follows:

OIDC_EXTERNAL_ID_CLAIM=upn

Docs Updates

Add new option to ODIC docs.
- Ensure there's a note to indicate this rarely should need to be defined or changed.

@ssddanbrown commented on GitHub (Jan 26, 2023): I've now added this via commit 811be3a36ac67d0d098b442d97316e0e4ad8d0db. This will be part of the next feature release. The env option will be as follows: ```bash OIDC_EXTERNAL_ID_CLAIM=upn ``` ### Docs Updates - Add new option to ODIC docs. - Ensure there's a note to indicate this rarely should need to be defined or changed.

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/BookStack#3399

OIDC: Ability to specify external_id claim #3399

Describe the feature you'd like

Describe the benefits this would bring to existing BookStack users

Can the goal of this request already be achieved via other means?

Have you searched for an existing open/closed issue?

How long have you been using BookStack?

Additional context

Docs Updates

OIDC: Ability to specify `external_id` claim #3399