[Feature Request] Dynamically grant Superuser/Staff status to OIDC/SSO users based on group claims

[BeSovereign]

Description

Use Case / Problem Description

Currently, when setting up OpenID Connect (OIDC) or SSO authentication in Paperless-ngx via django-allauth, automatically provisioned users are created as standard, unprivileged accounts.

In declarative, containerized, or GitOps environments (such as Kubernetes, automated Docker Compose deployments or sophisticated private users), this creates a bootstrapping challenge:

1. Administrators must either maintain a static local superuser using plaintext environment variables PAPERLESS_ADMIN_USER and PAPERLESS_ADMIN_PASSWORD), which exposes credentials in docker inspect or process lists.
2. Or they must manually run createsuperuser inside the container shell, which prevents fully automated deployments.
3. Once the OIDC user logs in for the first time, a local administrator must manually elevate their account to superuser or staff status in the UI or database.

While Paperless-ngx supports syncing user groups from OIDC claims via SOCIAL_ACCOUNT_SYNC_GROUPS, it does not support mapping these groups to the Django-internal database flags is_superuser and is_staff.

Proposed Solution

I propose introducing new configuration settings (exposed as environment variables) to dynamically assign administrative privileges based on synced group claims:

• PAPERLESS_SOCIAL_ACCOUNT_SUPERUSER_GROUPS: A comma-separated list of OIDC groups (e.g., admins,devops) that will automatically grant the user is_superuser = True (and implicitly is_staff = True) upon login.
• PAPERLESS_SOCIAL_ACCOUNT_STAFF_GROUPS: A comma-separated list of OIDC groups (e.g., staff,moderators) that will grant is_staff = True (access to django-admin, but no full superuser rights).

Other

Proposed Technical Implementation

1. Configuration (src/paperless/config.py & settings.py):
   Parse the comma-separated environment variables into Python lists/sets and expose them in the Django settings (e.g., settings.SOCIAL_ACCOUNT_SUPERUSER_GROUPS and settings. SOCIAL_ACCOUNT_STAFF_GROUPS).

2. Adapter Logic (src/paperless/adapter.py):
   Extend the existing CustomSocialAccountAdapter's save_user method to read OIDC claims (sociallogin.account.extra_data), resolve the group claim name (using SOCIAL_ACCOUNT_SYNC_GROUPS_CLAIM),
   and toggle the user database flags accordingly:

python
def save_user(self, request, sociallogin, form=None):
    user = super().save_user(request, sociallogin, form)
    
    # Extract OIDC claims
    extra_data = sociallogin.account.extra_data
    groups_claim = getattr(settings, "SOCIAL_ACCOUNT_SYNC_GROUPS_CLAIM", "groups")
    user_groups = extra_data.get(groups_claim, [])

    # Map superuser status
    superuser_groups = getattr(settings, "SOCIAL_ACCOUNT_SUPERUSER_GROUPS", [])
    if any(g in user_groups for g in superuser_groups):
        user.is_superuser = True
        user.is_staff = True
    else:
        # Map staff status
        staff_groups = getattr(settings, "SOCIAL_ACCOUNT_STAFF_GROUPS", [])
        if any(g in user_groups for g in staff_groups):
            user.is_staff = True

    user.save()
    return user

This implementation remains fully backward-compatible. If the variables are not set, the behavior remains unchanged.

I am happy to implement this!

I have analyzed the codebase and am prepared to implement this change and open a Pull Request.

Please let me know if the maintainers are open to this contribution and if the proposed configuration design aligns with the project guidelines.

[krotname]

I think the general feature makes sense, but I would implement it in the existing social group sync path rather than only in CustomSocialAccountAdapter.save_user().

Right now Paperless already centralizes OIDC group syncing in handle_social_account_updated() in src/paperless/signals.py. That code already handles the current extra_data shape plus the allauth 65.11+ userinfo / id_token nesting, and it clears Django groups when the IdP group list changes. That is the right place to also derive is_staff / is_superuser, otherwise existing users may not be updated correctly on later logins.

The important detail is deprovisioning. The implementation should not only grant flags when a claim is present; it should also remove flags when the IdP group is removed, unless the user is protected by some explicit local override. Otherwise a temporary IdP admin group assignment becomes permanent local superuser access.

The settings shape seems reasonable, but I would suggest tests for at least these cases:

• groups found at top-level extra_data, under userinfo, and under id_token;
• superuser group grants both is_superuser and is_staff;
• staff group grants only is_staff;
• removing the group removes the derived flag on next login;
• no configured mapping preserves current behavior;
• interaction with the first-user bootstrap superuser behavior.

Security-wise, it may also be worth documenting that these flags fully trust the IdP group claim. For deployments where the IdP is the source of truth, that is fine; for mixed local/SSO deployments, a local override/protection mechanism would prevent accidentally stripping the only local admin.

[BeSovereign]

Thanks for the detailed feedback, @krotname.

Those points make total sense. Implementing this within the signal path (handle_social_account_updated() in src/paperless/signals.py) and addressing the deprovisioning behavior is definitely the cleaner and more secure approach.

If the maintainers are open to accepting this feature, I would be happy to draft a PR structured along these lines:

1. Signal-based sync: Hooks into handle_social_account_updated() to dynamically sync mappings on subsequent logins rather than just during initial creation.
2. Deprovisioning & lockout protection: Revokes permissions if claims are removed, but explicitly exempts local, database-only superusers to prevent accidental administrative lockouts.
3. Comprehensive tests: Cover the various claim structures (extra_data, userinfo, id_token), grant/revoke flows, and fallback behavior when no mapping is configured.

Would the team be open to reviewing a PR with this scope?

[BeSovereign]

Since there were no objections, I've started drafting a Pull Request implementing the signal-based approach we discussed above. I'll link it here as soon as it's ready for review.

[BeSovereign]

I have opened a draft Pull Request containing the signal-based implementation we discussed. You can find it here: #13060