Expose "External Authentication IDs" in the environment (.env) file #5194

New Issue

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

OVERLORD commented

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

Originally created by @Mojo-OG on GitHub (Feb 24, 2025).

Describe the feature you'd like

I am testing/scoping the product, and it is disappointing to see that the ability to map specific values to the External Authentication IDs for the built-in roles does not exist. A similar Feature Request was raised here, but was specifically for OIDC Auth, and was subsequently closed: https://github.com/BookStackApp/BookStack/issues/5081

Whilst I am interested specifically in LDAP, I would think that the External Authentication IDs are not unique in the backend to each authentication mechanism, rather, the content field is mapped to the same input regardless and enabled if the authentication mechanism is something other than standard.

Describe the benefits this would bring to existing BookStack users

In an environment where infrastructure is setup/deployed via Infrastructure as Code (IaC), not exposing these variables to the environment file means that the initial setup of the environment, and subsequent redeployments, requires manual intervention to make the instance useable.

If you deploy the environment as LDAP from the get-go, you cannot login with the default admin user in order to assign admin permissions. Likewise, if you deploy as standard, you can login with the admin account -- but no directory users exist to assign admin privileges to, nor is the external_auth_id class exposed in the HTML in order for something to be defined prior to swapping the auth mechanisms around.

As it stands, in order to get LDAP authentication (and assumably other auth mechanisms) to an acceptable state after deployment, you need to:

Use your desired auth mechanism (in this case, LDAP).
Login with a user from the auth mechanism in order to have the user imported and appear in the user list.
Log out, because your directory user doesn't have any permissions.
Modify the environment file to change auth back to standard, and reload the instance.
Login with the admin@admin.com built-in Admin account.
Assign the user you logged in with earlier admin rights -- because external_auth_id isn't exposed/available with the standard auth.
Logout as admin.
Modify the environment file back to the desired auth type.
Login with the directory user from earlier, which now has admin rights.
NOW you can assign a value to external_auth_id for the desired role(s) and allow other users to login without jumping through multiple hoops.

Overall this leads to a rather clunky deployment experience.

As such, it would be great to see a mechanism to configure the External Authentication IDs of the built-in roles via the .env file as a bare minimum. What would be even better would be the implementation of some logic where any role can have its External Authentication ID set based on the variable names. Such as:

AUTH_EXTID_ADMIN=
AUTH_EXTID_EDITOR=
AUTH_EXTID_PUBLIC=
AUTH_EXTID_VIEWER=
AUTH_EXTID_YOURCUSTOMROLENAME=

Where the role names would be case insensitive and trim whitespace, where AUTH_EXTID_YOURCUSTOMROLENAME would map to Your Custom Role Name if it was named that way in in the application. Because nobody is going to have Your Custom Role Name, YourCustom Role Name, YOURcustomROLEname, or any other various combinations of what is effectively the same thing.

This would cut out the entire set of extra steps I have outlined above, and allow an instance to be deployed with authentication configured as desired immediately.

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

No, manual intervention is required to complete setup in these situations which is not ideal for automated deployments or IaC environments.

Have you searched for an existing open/closed issue?

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

How long have you been using BookStack?

Not using yet, just scoping

Additional context

No response

Originally created by @Mojo-OG on GitHub (Feb 24, 2025). ### Describe the feature you'd like I am testing/scoping the product, and it is disappointing to see that the ability to map specific values to the External Authentication IDs for the built-in roles does not exist. A similar Feature Request was raised here, but was specifically for OIDC Auth, and was subsequently closed: https://github.com/BookStackApp/BookStack/issues/5081 Whilst I am interested specifically in LDAP, I would think that the External Authentication IDs are not unique in the backend to each authentication mechanism, rather, the content field is mapped to the same input regardless and enabled if the authentication mechanism is something other than `standard`. ### Describe the benefits this would bring to existing BookStack users In an environment where infrastructure is setup/deployed via Infrastructure as Code (IaC), not exposing these variables to the environment file means that the initial setup of the environment, and subsequent redeployments, requires manual intervention to make the instance useable. If you deploy the environment as LDAP from the get-go, you cannot login with the default admin user in order to assign admin permissions. Likewise, if you deploy as standard, you can login with the admin account -- but no directory users exist to assign admin privileges to, nor is the `external_auth_id` class exposed in the HTML in order for something to be defined prior to swapping the auth mechanisms around. As it stands, in order to get LDAP authentication (and assumably other auth mechanisms) to an acceptable state after deployment, you need to: 1. Use your desired auth mechanism (in this case, LDAP). 2. Login with a user from the auth mechanism in order to have the user imported and appear in the user list. 3. Log out, because your directory user doesn't have any permissions. 4. Modify the environment file to change auth back to `standard`, and reload the instance. 5. Login with the `admin@admin.com` built-in Admin account. 6. Assign the user you logged in with earlier admin rights -- because `external_auth_id` isn't exposed/available with the `standard` auth. 7. Logout as admin. 8. Modify the environment file back to the desired auth type. 9. Login with the directory user from earlier, which now has admin rights. 10. NOW you can assign a value to `external_auth_id` for the desired role(s) and allow other users to login without jumping through multiple hoops. Overall this leads to a rather clunky deployment experience. As such, it would be great to see a mechanism to configure the External Authentication IDs of the built-in roles via the .env file as a bare minimum. What would be even better would be the implementation of some logic where any role can have its External Authentication ID set based on the variable names. Such as: ``` AUTH_EXTID_ADMIN= AUTH_EXTID_EDITOR= AUTH_EXTID_PUBLIC= AUTH_EXTID_VIEWER= AUTH_EXTID_YOURCUSTOMROLENAME= ``` Where the role names would be case insensitive and trim whitespace, where `AUTH_EXTID_YOURCUSTOMROLENAME` would map to `Your Custom Role Name` if it was named that way in in the application. Because nobody is going to have `Your Custom Role Name`, `YourCustom Role Name`, `YOURcustomROLEname`, or any other various combinations of what is effectively the same thing. This would cut out the entire set of extra steps I have outlined above, and allow an instance to be deployed with authentication configured as desired immediately. ### Can the goal of this request already be achieved via other means? No, manual intervention is required to complete setup in these situations which is not ideal for automated deployments or IaC environments. ### Have you searched for an existing open/closed issue? - [x] I have searched for existing issues and none cover my fundamental request ### How long have you been using BookStack? Not using yet, just scoping ### Additional context _No response_

OVERLORD added the 🔨 Feature Request label 2026-02-05 09:47:30 +03:00

OVERLORD closed this issue

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

OVERLORD commented

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

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

Thanks for the request @Mojo-OG, but as said in #5081, I don't really assure, or want to increase our scope, to allow all UI actions/options to be handled via config options where there's a minor edge-case or desire to suit.

You could technically (unofficially) set/update the external auth values by command or via the database.
The API could also be used, but right now there's no (official) means to gain API details without UI access.

If the main issue is the auth dance, I'd be happy for a specific issue to be raised to show that by default.
I updated the user external auth field to always show (via a collapsible block), I'd be happy to align the same for roles too, to avoid the auth switching dance.

@ssddanbrown commented on GitHub (Feb 24, 2025): Thanks for the request @Mojo-OG, but as said in #5081, I don't really assure, or want to increase our scope, to allow all UI actions/options to be handled via config options where there's a minor edge-case or desire to suit. You could technically (unofficially) set/update the external auth values by command or via the database. The API could also be used, but right now there's no (official) means to gain API details without UI access. If the main issue is the auth dance, I'd be happy for a specific issue to be raised to show that by default. I updated the user external auth field to always show (via a collapsible block), I'd be happy to align the same for roles too, to avoid the auth switching dance.

OVERLORD commented

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

@Mojo-OG commented on GitHub (Feb 25, 2025):

If the main issue is the auth dance, I'd be happy for a specific issue to be raised to show that by default.
I updated the user external auth field to always show (via a collapsible block), I'd be happy to align the same for roles too, to avoid the auth switching dance.

If nothing else, this would at least reduce the teething pains of getting a new instance into a usable state.

What would also be nice is the ability to enable multiple auth methods simultaneously. Previously having used Mediawiki, this is handled by the authentication extensions PluggableAuth (https://www.mediawiki.org/wiki/Extension:PluggableAuth) and LDAPAuthentication2 (https://www.mediawiki.org/wiki/Extension:LDAPAuthentication2), wherein a pseudo-domain for "Local" is added on a drop down on the logon page where the desired auth source can be selected.

I get that the way BookStack and Mediawiki handle things like modifications or extensions will be fundamentally different, but the ability to have both standard and another auth method enabled would further reduce the teething pains with getting an instance setup, since the instance can be deployed with the desired auth method + standard, and the admin user logged in to so that External Authentication IDs can be set on the roles immediately instead of needing to switch auth methods back and forth.

If that doesn't sound feasible though, I'd concede to at least having the External Authentication IDs field exposed.

I assume you'd like me to close and raise the external auth field for roles as a separate issue (and maybe the multiple authentication methods/selection as another feature request if you're feeling benevolent)?

@Mojo-OG commented on GitHub (Feb 25, 2025): > If the main issue is the auth dance, I'd be happy for a specific issue to be raised to show that by default. > I updated the user external auth field to always show (via a collapsible block), I'd be happy to align the same for roles too, to avoid the auth switching dance. If nothing else, this would at least reduce the teething pains of getting a new instance into a usable state. What would also be nice is the ability to enable multiple auth methods simultaneously. Previously having used Mediawiki, this is handled by the authentication extensions PluggableAuth (https://www.mediawiki.org/wiki/Extension:PluggableAuth) and LDAPAuthentication2 (https://www.mediawiki.org/wiki/Extension:LDAPAuthentication2), wherein a pseudo-domain for "Local" is added on a drop down on the logon page where the desired auth source can be selected. I get that the way BookStack and Mediawiki handle things like modifications or extensions will be fundamentally different, but the ability to have both standard and another auth method enabled would further reduce the teething pains with getting an instance setup, since the instance can be deployed with the desired auth method + standard, and the admin user logged in to so that External Authentication IDs can be set on the roles immediately instead of needing to switch auth methods back and forth. If that doesn't sound feasible though, I'd concede to at least having the External Authentication IDs field exposed. I assume you'd like me to close and raise the external auth field for roles as a separate issue (and maybe the multiple authentication methods/selection as another feature request if you're feeling benevolent)?

OVERLORD commented

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

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

I assume you'd like me to close and raise the external auth field for roles as a separate issue

Yes please. I'll go ahead and close this one.

and maybe the multiple authentication methods/selection as another feature request if you're feeling benevolent)

Already requested/open under #2715

@ssddanbrown commented on GitHub (Feb 25, 2025): > I assume you'd like me to close and raise the external auth field for roles as a separate issue Yes please. I'll go ahead and close this one. > and maybe the multiple authentication methods/selection as another feature request if you're feeling benevolent) Already requested/open under #2715

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/BookStack#5194