Add support for admin assignment via group/role claims (#965)

[smartcoder0777]

Fixes: #965

Summary

Implements automatic admin role assignment based on OIDC identity provider group or role claims, allowing organizations to manage Kutt admin privileges through their existing IdP.

• Adds OIDC_ROLE_CLAIM and OIDC_ADMIN_GROUP environment variables
• Checks user group/role claims during OIDC authentication
• Updates admin status on every login to stay in sync with IdP
• Supports both array and string claim value formats
• Handles role changes (grant/revoke admin) automatically

Changes

New Environment Variables

• OIDC_ROLE_CLAIM - Claim name containing user roles/groups (default: roles)
• OIDC_ADMIN_GROUP - Group or role value that grants admin privileges (optional)

Technical Implementation

• Enhanced OIDC strategy callback in server/passport.js with role checking logic
• Fixed OIDC initialization race condition by awaiting setup before server start
• Replaced env.isDev with direct NODE_ENV checks to avoid envalid mutation errors
• Updated .example.env with documentation for new OIDC admin configuration

Supported Identity Providers

• ✅ Azure Entra ID (roles/groups claim)
• ✅ Auth0 (roles claim)
• ✅ Keycloak (roles/groups claim)
• ✅ Okta (groups claim)
• ✅ Any OIDC-compliant provider

Configuration Example

OIDC_ENABLED=true
OIDC_ISSUER=https://your-idp.com
OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret
OIDC_SCOPE=openid profile email
OIDC_EMAIL_CLAIM=email
OIDC_ROLE_CLAIM=roles
OIDC_ADMIN_GROUP=admin

Contribution by Gittensor, see my contribution statistics at https://gittensor.io/miners/details?githubId=191128130

[smartcoder0777]

Here is a video of implemented feature.
https://drive.google.com/file/d/10-q2MeulLnEY2BddtegY29ywCsDfiLCl/view?usp=sharing

[smartcoder0777]

Hi everybody,
If the PR looks good, please merge it so I can start another one.
Thanks.

[jgoedeke]

I will test the changes later and report back

[smartcoder0777]

After merging this PR, I'd like to start another issue. If there is any issue that needs contribution in your mind, please let me know. Thanks.

[jgoedeke]

I tried to run this changes but it seems not to work properly. Did you test it?

I checked my JWT in another application and I have see groups in the claims:

"groups": [
    "abcdefgh-57b7-41be-8a96-82f1fad7070e"
  ],

The following env vars are present:

OIDC_ROLE_CLAIM=groups
OIDC_ADMIN_GROUP=abcdefgh-57b7-41be-8a96-82f1fad7070e

When starting the application I see

> OIDC initialized successfully
> Ready on http://localhost:3000

I remove my user via the admin user. When I log in again with normal user it is still no admin.

I see no logs further logs.

[smartcoder0777]

@jgoedeke nice catch!
I just pushed a fix. Please let me know if you find any more issues or improvements.
Thanks

[jgoedeke]

Now it works. Looks good from my side. Thanks for the effort!

@poeti8 can you check the changes?

[smartcoder0777]

Hi @poeti8 can you review the PR?
If it looks good, please merge it and assign another one to me.
Thanks

[smartcoder0777]

@poeti8 @jgoedeke If the PR looks good, would you merge it and close the issue?
Thanks

[smartcoder0777]

Can anybody check and merge my PR, please?

[smartcoder0777]

@poeti8 @jgoedeke please merge my PR and close the issue.

[jgoedeke]

Hey @smartcoder0777, just a small reminder: this is a small open‑source project, and the maintainers aren’t expected to be active every day. Please try not to be too pushy with follow‑ups. Things get reviewed when people have time, and a bit of patience really helps keep the project healthy and enjoyable for everyone. Thanks for understanding!

[smartcoder0777]

Hey @smartcoder0777, just a small reminder: this is a small open‑source project, and the maintainers aren’t expected to be active every day. Please try not to be too pushy with follow‑ups. Things get reviewed when people have time, and a bit of patience really helps keep the project healthy and enjoyable for everyone. Thanks for understanding!

I got it. Thanks. I will look forward.

[jschurawlow]

Just wanted to ask if this had been merged since it's been a couple of weeks. I'm currently dealing with difficulty getting my self-hosted kutt based on the docker kutt/kutt:main branch to recognize admin_emails - also looking at the example env files it doesn't look like admin_emails exists anywhere?

[smartcoder0777]

@jschurawlow Its not merged yet though, it was approved. I look forward the maintainer's merge now.

[smartcoder0777]

@poeti8 , @jgoedeke
It looks like you guys forgot to merge my PR. Will it be merged?

[lvicainne]

Hello,
I would be pleased to use this new IDP feature once merged, as I'm using Kutt in my non profit organization for scouting :-)
Thanks for the contribution of each of you