[Bug]: username regex blocks OIDC integration #888

New Issue

OVERLORD · 2026-02-04T21:33:14+03:00

OVERLORD commented

2026-02-04 21:33:14 +03:00

Originally created by @exhuma on GitHub (Jan 1, 2026).

Where is the problem occurring?

I encountered the problem while interacting with the server (Backend)

What browsers are you seeing the problem on?

Other

Current behavior

While integrating with OIDC I ran into the following server-side problem:

planka_1    | 2026-01-01 18:10:36 [E] Sending 500 ("Server Error") response:
planka_1    |  Invalid new record.
planka_1    | Details:
planka_1    |   Could not use specified `username`.  Violated one or more validation rules:
planka_1    |   • Value ('test-user-2') did not match the configured regular expression (/^[a-zA-Z0-9]+((_|\.)?[a-zA-Z0-9])*$/)

I tracked down the issue to this regex: af8865327a/server/utils/validators.js (L14)

This effectively makes it impossible for us to integrate Planka with OIDC as our (existing) user-names violate that regular expression.

Desired behavior

Usernames should preferably not be restricted at all. At least it should allow user-names like foo-bar-baz-13 (including hyphens).

Steps to reproduce

Create the user-name foo-bar-baz on you OIDC IDP then try to log in with that user.

Other information

No response

Originally created by @exhuma on GitHub (Jan 1, 2026). ### Where is the problem occurring? I encountered the problem while interacting with the server (Backend) ### What browsers are you seeing the problem on? Other ### Current behavior While integrating with OIDC I ran into the following server-side problem: ``` planka_1 | 2026-01-01 18:10:36 [E] Sending 500 ("Server Error") response: planka_1 | Invalid new record. planka_1 | Details: planka_1 | Could not use specified `username`. Violated one or more validation rules: planka_1 | • Value ('test-user-2') did not match the configured regular expression (/^[a-zA-Z0-9]+((_|\.)?[a-zA-Z0-9])*$/) ``` I tracked down the issue to this regex: https://github.com/plankanban/planka/blob/af8865327a534a62efd8f9bfbe8b48e27792edd5/server/utils/validators.js#L14 This effectively makes it impossible for us to integrate Planka with OIDC as our (existing) user-names violate that regular expression. ### Desired behavior Usernames should preferably not be restricted at all. At least it should allow user-names like `foo-bar-baz-13` (including hyphens). ### Steps to reproduce Create the user-name `foo-bar-baz` on you OIDC IDP then try to log in with that user. ### Other information _No response_

OVERLORD commented

2026-02-04 21:33:19 +03:00

@meltyshev commented on GitHub (Jan 1, 2026):

Hey! Thanks for reporting this.

We've updated the username regex a few times to make it less strict (^[a-z0-9._-]*$), also increased the maximum length to 64 characters.

We're currently working on the final v2 release, which will include all of these changes. It should be ready within the next 1-2 weeks.

In the meantime, you can use the nightly build - it already includes the relaxed username rules and shouldn't have this issue. Once the final version is released, just remember to switch the image tag back to latest, since the current nightly build are fairly stable, but it's better not to rely on it long term.

@meltyshev commented on GitHub (Jan 1, 2026): Hey! Thanks for reporting this. We've updated the username regex a few times to make it less strict (`^[a-z0-9._-]*$`), also increased the maximum length to 64 characters. We're currently working on the final v2 release, which will include all of these changes. It should be ready within the next 1-2 weeks. In the meantime, you can use the `nightly` build - it already includes the relaxed username rules and shouldn't have this issue. Once the final version is released, just remember to switch the image tag back to `latest`, since the current `nightly` build are fairly stable, but it's better not to rely on it long term.

OVERLORD commented

2026-02-04 21:33:21 +03:00

@exhuma commented on GitHub (Jan 1, 2026):

Thanks for the quick response. I might give it a try in the coming weeks although I'm still investigating other board alternatives and am not sure if I will stick with Planka.

@exhuma commented on GitHub (Jan 1, 2026): Thanks for the quick response. I might give it a try in the coming weeks although I'm still investigating other board alternatives and am not sure if I will stick with Planka.

OVERLORD commented

2026-02-04 21:33:23 +03:00

@exhuma commented on GitHub (Jan 16, 2026):

After investigating alternatives, planka is still the one that wins because it brings oidc integration.

It seems also that the nightly build does indeed solve the username issue but I still cannot login. The IDP (keycloak) correctly authenticates and redirects. Planka then says that it first needs an admin login to initialise the system.

I am logging in with a keycloak user that has is member of the planka_admin group in keycloak and I have configured the group mapping as documented in the planka docs.

What did I miss?

@exhuma commented on GitHub (Jan 16, 2026): After investigating alternatives, planka is still the one that wins because it brings oidc integration. It seems also that the nightly build does indeed solve the username issue but I still cannot login. The IDP (keycloak) correctly authenticates and redirects. Planka then says that it first needs an admin login to initialise the system. I am logging in with a keycloak user that has is member of the planka_admin group in keycloak and I have configured the group mapping as documented in the planka docs. What did I miss?

OVERLORD commented

2026-02-04 21:33:28 +03:00

@meltyshev commented on GitHub (Jan 16, 2026):

After investigating alternatives, planka is still the one that wins because it brings oidc integration.

It seems also that the nightly build does indeed solve the username issue but I still cannot login. The IDP (keycloak) correctly authenticates and redirects. Planka then says that it first needs an admin login to initialise the system.

I am logging in with a keycloak user that has is member of the planka_admin group in keycloak and I have configured the group mapping as documented in the planka docs.

What did I miss?

Hm, let me test the initial login via OIDC - maybe we just missed something in the implementation. As a temporary workaround, you can try creating an admin user as described here: https://docs.planka.cloud/docs/configuration/admin-user/ and log in with it (you'll need to set OIDC_ENFORCED=false to see the login form).

@meltyshev commented on GitHub (Jan 16, 2026): > After investigating alternatives, planka is still the one that wins because it brings oidc integration. > > It seems also that the nightly build does indeed solve the username issue but I still cannot login. The IDP (keycloak) correctly authenticates and redirects. Planka then says that it first needs an admin login to initialise the system. > > I am logging in with a keycloak user that has is member of the planka_admin group in keycloak and I have configured the group mapping as documented in the planka docs. > > What did I miss? Hm, let me test the initial login via OIDC - maybe we just missed something in the implementation. As a temporary workaround, you can try creating an admin user as described here: https://docs.planka.cloud/docs/configuration/admin-user/ and log in with it (you'll need to set `OIDC_ENFORCED=false` to see the login form).

OVERLORD commented

2026-02-04 21:33:34 +03:00

@exhuma commented on GitHub (Jan 16, 2026):

I don't remember whether I already started the system up once before configuring oidc. I have an admin user and password defined in my env vars and it's not clear if that could create a conflict.

Over the weekend I might try a fresh/clean setup from scratch.

While I'm here, I also noticed that upgrading to the nightly (from the last official release) I no longer see logs in the docker container. But that's off topic here 😅

@exhuma commented on GitHub (Jan 16, 2026): I don't remember whether I already started the system up once before configuring oidc. I have an admin user and password defined in my env vars and it's not clear if that could create a conflict. Over the weekend I might try a fresh/clean setup from scratch. While I'm here, I also noticed that upgrading to the nightly (from the last official release) I no longer see logs in the docker container. But that's off topic here 😅

OVERLORD commented

2026-02-04 21:33:37 +03:00

@exhuma commented on GitHub (Jan 16, 2026):

I don't remember whether I already started the system up once before configuring oidc. I have an admin user and password defined in my env vars and it's not clear if that could create a conflict.

Over the weekend I might try a fresh/clean setup from scratch.

While I'm here, I also noticed that upgrading to the nightly (from the last official release) I no longer see logs in the docker container. But that's off topic here 😅

@exhuma commented on GitHub (Jan 16, 2026): I don't remember whether I already started the system up once before configuring oidc. I have an admin user and password defined in my env vars and it's not clear if that could create a conflict. Over the weekend I might try a fresh/clean setup from scratch. While I'm here, I also noticed that upgrading to the nightly (from the last official release) I no longer see logs in the docker container. But that's off topic here 😅

OVERLORD commented

2026-02-04 21:33:39 +03:00

@meltyshev commented on GitHub (Jan 16, 2026):

I don't remember whether I already started the system up once before configuring oidc. I have an admin user and password defined in my env vars and it's not clear if that could create a conflict.

I don't think that should be a problem - it should work with any admin user logging in. It might be that Keycloak didn't add the groups to the userinfo endpoint. Another possibility is that in the docs it says OIDC_ADMIN_ROLES=planka-admin (with a dash), but based on your message it looks like you have an underscore - maybe you copied the config and left the dash there by mistake. You could also try using OIDC_CLAIMS_SOURCE=id_token to skip fetching everything from the endpoint and extract the info directly from the token.

While I'm here, I also noticed that upgrading to the nightly (from the last official release) I no longer see logs in the docker container. But that's off topic here 😅

Ah, good catch! I'll need to check that too - thanks for reporting it.

@meltyshev commented on GitHub (Jan 16, 2026): > I don't remember whether I already started the system up once before configuring oidc. I have an admin user and password defined in my env vars and it's not clear if that could create a conflict. I don't think that should be a problem - it should work with any admin user logging in. It might be that Keycloak didn't add the groups to the `userinfo` endpoint. Another possibility is that in the docs it says `OIDC_ADMIN_ROLES=planka-admin` (with a dash), but based on your message it looks like you have an underscore - maybe you copied the config and left the dash there by mistake. You could also try using `OIDC_CLAIMS_SOURCE=id_token` to skip fetching everything from the endpoint and extract the info directly from the token. > While I'm here, I also noticed that upgrading to the nightly (from the last official release) I no longer see logs in the docker container. But that's off topic here 😅 Ah, good catch! I'll need to check that too - thanks for reporting it.

OVERLORD commented

2026-02-04 21:33:41 +03:00

@exhuma commented on GitHub (Jan 16, 2026):

I'll try your suggestions as soon as I get the opportunity. Thanks for the quick replies.

@exhuma commented on GitHub (Jan 16, 2026): I'll try your suggestions as soon as I get the opportunity. Thanks for the quick replies.

OVERLORD commented

2026-02-04 21:33:45 +03:00

@exhuma commented on GitHub (Jan 16, 2026):

nb: I'd say that the original ticket here can be closed as it is fixed in the nightly build.

However, I'd like to pick your brain a bit while you're here ;)

I succeeded logging in by disabling the enforcment of OIDC. This allowed me to log in with my default admin user as defined in the env-vars. I then tried an OIDC login which also worked but that OIDC user has no permissions. The user has the same e-mail as my default admin-user in Planka which should link it to the admin user according to the docs https://docs.planka.cloud/docs/configuration/oidc/

I wanted to exclude the possibility of a typo in my config so I logged back in with the default login method and correctly was granted the admin role. Looking into the "users" section of the admin page I could also only see one single entry which is correctly marked as admin.

The next step was looking into the database. I can see that I have one entry in the user_accounts table and one entry in the identity_provider_user table. I don't see any foreign keys though linking those two tables together but that's not that important. I do see that both entries match (identity_provider_user.user_id == user_account.id):

planka=# SELECT
  u.id,
  u.role,
  idp.id,
  idp.sub,
  u.created_at AS created_in_users,
  idp.created_at AS created_in_idp
FROM user_account u
INNER JOIN identity_provider_user idp ON (u.id=idp.user_id);
-[ RECORD 1 ]----+-------------------------------------
id               | 1688738417497605121
role             | admin
id               | 1689193089102513156
sub              | 5cde2099-247b-43d0-8c88-2aa92ee040d5
created_in_users | 2026-01-15 19:21:46.972
created_in_idp   | 2026-01-16 10:25:08.009

So there clearly is an entry and it links to the user-account table which has the "admin" flag. So why don't I have admin permissions in Planka?

Even switching to the ID-Token for the claims did not solve that issue.

One thing I do notice is that the login procedure requests the following URL: https://my-planka-url.example/api/access-tokens/exchange-with-oidc?withHttpOnlyToken=true which returns a suspiciously small token (see below). This may be an implementation detail of Planka in that it exchanges the real token behind the scenes and this small token is a custom token between the Planka UI and the Planka API but it might give some insight.

The token (signature removed to defuse it) ;)

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImJjMjdjYTUwLTBhNDgtNGFlNS1iNjI4LTVhNGU0OTJmNzI0ZSJ9.eyJpYXQiOjE3Njg1NzkxNzUsImV4cCI6MTgwMDExNTE3NSwic3ViIjoiMTY4ODczODQxNzQ5NzYwNTEyMSJ9.xxx

@exhuma commented on GitHub (Jan 16, 2026): nb: I'd say that the original ticket here can be closed as it is fixed in the nightly build. However, I'd like to pick your brain a bit while you're here ;) I succeeded logging in by disabling the enforcment of OIDC. This allowed me to log in with my default admin user as defined in the env-vars. I then tried an OIDC login which also worked but that OIDC user has no permissions. The user _has_ the same e-mail as my default admin-user in Planka which should link it to the admin user according to the docs https://docs.planka.cloud/docs/configuration/oidc/ <img width="905" height="195" alt="Image" src="https://github.com/user-attachments/assets/120072c1-1b20-4017-b77d-1821edbb1726" /> I wanted to exclude the possibility of a typo in my config so I logged back in with the default login method and correctly was granted the admin role. Looking into the "users" section of the admin page I could also only see one single entry which is correctly marked as admin. The next step was looking into the database. I can see that I have one entry in the `user_accounts` table and one entry in the `identity_provider_user` table. I don't see any foreign keys though linking those two tables together but that's not that important. I _do_ see that both entries match (`identity_provider_user.user_id == user_account.id`): ``` planka=# SELECT u.id, u.role, idp.id, idp.sub, u.created_at AS created_in_users, idp.created_at AS created_in_idp FROM user_account u INNER JOIN identity_provider_user idp ON (u.id=idp.user_id); -[ RECORD 1 ]----+------------------------------------- id | 1688738417497605121 role | admin id | 1689193089102513156 sub | 5cde2099-247b-43d0-8c88-2aa92ee040d5 created_in_users | 2026-01-15 19:21:46.972 created_in_idp | 2026-01-16 10:25:08.009 ``` So there clearly is an entry and it links to the user-account table which has the "admin" flag. So why don't I have admin permissions in Planka? Even switching to the ID-Token for the claims did not solve that issue. One thing I do notice is that the login procedure requests the following URL: `https://my-planka-url.example/api/access-tokens/exchange-with-oidc?withHttpOnlyToken=true` which returns a suspiciously small token (see below). This may be an implementation detail of Planka in that it exchanges the real token behind the scenes and this small token is a custom token between the Planka UI and the Planka API but it might give some insight. The token (signature removed to defuse it) ;) ``` eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImJjMjdjYTUwLTBhNDgtNGFlNS1iNjI4LTVhNGU0OTJmNzI0ZSJ9.eyJpYXQiOjE3Njg1NzkxNzUsImV4cCI6MTgwMDExNTE3NSwic3ViIjoiMTY4ODczODQxNzQ5NzYwNTEyMSJ9.xxx ```

OVERLORD commented

2026-02-04 21:33:48 +03:00

@exhuma commented on GitHub (Jan 16, 2026):

I fixed the issue by setting the "ignore roles" option.

This was a bit of trial & error because I currently don't see any logs. But all in all, it seems to be working now.

@exhuma commented on GitHub (Jan 16, 2026): I fixed the issue by setting the "ignore roles" option. This was a bit of trial & error because I currently don't see any logs. But all in all, it seems to be working now.

OVERLORD commented

2026-02-04 21:33:51 +03:00

@meltyshev commented on GitHub (Jan 16, 2026):

I'm testing with Keycloak right now, just need a few minutes to connect everything. My guess is that the groups attribute isn't being returned by the provider, or it's being ignored by the app (I will know soon), so it silently falls back to the default "Board user" role. When ignore roles is enabled - it stops updating the role and keeps the admin one instead.

@meltyshev commented on GitHub (Jan 16, 2026): I'm testing with Keycloak right now, just need a few minutes to connect everything. My guess is that the groups attribute isn't being returned by the provider, or it's being ignored by the app (I will know soon), so it silently falls back to the default "Board user" role. When ignore roles is enabled - it stops updating the role and keeps the admin one instead.

OVERLORD commented

2026-02-04 21:33:55 +03:00

@meltyshev commented on GitHub (Jan 16, 2026):

This worked for me with Keycloak:

Created a group called planka_admin.
Assigned this group to a user.
Went to "Clients" and selected the configured client (for me, it's planka).
Opened "Client scopes" -> planka-dedicated -> "Configure a new mapper".
Selected "Group Membership" - set "Name" and "Token Claim Name" to groups, and disabled "Full group path".

After that, the groups attribute is returned from the userinfo endpoint with the correctly assigned group name.

@meltyshev commented on GitHub (Jan 16, 2026): This worked for me with Keycloak: 1. Created a group called `planka_admin`. 2. Assigned this group to a user. 3. Went to "Clients" and selected the configured client (for me, it's `planka`). 4. Opened "Client scopes" -> `planka-dedicated` -> "Configure a new mapper". 5. Selected "Group Membership" - set "Name" and "Token Claim Name" to `groups`, and disabled "Full group path". After that, the `groups` attribute is returned from the `userinfo` endpoint with the correctly assigned group name.

OVERLORD commented

2026-02-04 21:33:59 +03:00

@exhuma commented on GitHub (Jan 16, 2026):

Awesome. Thanks for the effort. For now, this works for me (even with the "ignore groups" option). Might be wort adding these steps to the docs though for anyone else wanting to set this up.

My needs are pretty humble (which is why Planka turned out to be a good fit). I am a solo dev doing some development for clients as a side-gig to my usual day-job. So I don't have a ton of users but I still don't want them to have to create accounts in my different support platforms. And having OIDC via keycloak is perfect.

Other solutions (mattermost, focal-board, open-project) all only support OIDC in their paid tiers. And they aren't cheap for a solo-dev. Planka really fits that niche pretty well.

@exhuma commented on GitHub (Jan 16, 2026): Awesome. Thanks for the effort. For now, this works for me (even with the "ignore groups" option). Might be wort adding these steps to the docs though for anyone else wanting to set this up. My needs are pretty humble (which is why Planka turned out to be a good fit). I am a solo dev doing some development for clients as a side-gig to my usual day-job. So I don't have a ton of users but I still don't want them to have to create accounts in my different support platforms. And having OIDC via keycloak is perfect. Other solutions (mattermost, focal-board, open-project) all only support OIDC in their paid tiers. And they aren't cheap for a solo-dev. Planka really fits that niche pretty well.

OVERLORD referenced this issue

2026-02-04 21:52:39 +03:00

[PR #888] [MERGED] Fix to retrieve oidcEmailAttribute from tokenSet.claims() if not found in standard userInfo #1136

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/planka#888