Merge pull request #2843 from bcgov/DEP-262-add-super-admin-role-db

DEP-262: add SUPER_ADMIN role and associated functionality to db; remove staff_user tenant_id column

Author: NatSquared

CHANGELOG.MD

@@ -1,3 +1,11 @@
+## May 4, 2026
+
+- **Feature** Sync SUPER_ADMIN tenant membership and protect super admins in user management [🎟️ DEP-262](https://citz-gdx.atlassian.net/browse/DEP-262)
+  - Added a migration to create the `SUPER_ADMIN` group, the `super_admin` role, and their mapping so super admins can be represented in tenant memberships.
+  - Updated the API to add or remove `SUPER_ADMIN` group membership based on the user's Keycloak roles during login/request processing, including unit tests for assignment and removal.
+  - Updated the user management UI to recognize Super Admin as a composite role and prevent administrators and super admins from being deactivated, while showing the correct permission messaging.
+  - Removed the tenant_id column from staff_user table, as tenant membership is determined by group memberships rather than a direct column on the user model, making the column redundant.
+
 ## April 30, 2026
 
 - **Feature** Updated all S3 uploaded objects to dynamically generate document URLs from the bucket and object key, rather than storing the full URL in the database. [🎟️ DEP-261](https://citz-gdx.atlassian.net/browse/DEP-261)

api/migrations/versions/9d2d16f5f3aa_add_super_admin_role_group_mapping.py

@@ -0,0 +1,80 @@
+"""Add super admin role/group mapping.
+
+Revision ID: 9d2d16f5f3aa
+Revises: 8e50e47b7d32
+Create Date: 2026-04-30 12:00:00.000000
+"""
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = '9d2d16f5f3aa'
+down_revision = '8e50e47b7d32'
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    op.execute(
+        """
+        INSERT INTO user_group (created_date, updated_date, id, name, created_by, updated_by)
+        SELECT NOW(), NOW(), COALESCE((SELECT MAX(id) + 1 FROM user_group), 1), 'SUPER_ADMIN', NULL, NULL
+        WHERE NOT EXISTS (
+            SELECT 1 FROM user_group WHERE name = 'SUPER_ADMIN'
+        )
+        """
+    )
+
+    op.execute(
+        """
+        INSERT INTO user_role (created_date, updated_date, id, name, description, created_by, updated_by)
+        SELECT NOW(), NOW(), COALESCE((SELECT MAX(id) + 1 FROM user_role), 1),
+               'super_admin', 'Role for system-wide super administrator access', NULL, NULL
+        WHERE NOT EXISTS (
+            SELECT 1 FROM user_role WHERE name = 'super_admin'
+        )
+        """
+    )
+
+    op.execute(
+        """
+        INSERT INTO group_role_mapping (created_date, updated_date, id, role_id, group_id, created_by, updated_by)
+        SELECT NOW(), NOW(), COALESCE((SELECT MAX(id) + 1 FROM group_role_mapping), 1),
+               r.id, g.id, NULL, NULL
+        FROM user_group g
+        JOIN user_role r ON r.name = 'super_admin'
+        WHERE g.name = 'SUPER_ADMIN'
+          AND NOT EXISTS (
+              SELECT 1
+              FROM group_role_mapping m
+              WHERE m.group_id = g.id
+                AND m.role_id = r.id
+          )
+        """
+    )
+
+
+def downgrade():
+    op.execute(
+        """
+        DELETE FROM user_group_membership
+        WHERE group_id IN (
+            SELECT id FROM user_group WHERE name = 'SUPER_ADMIN'
+        )
+        """
+    )
+
+    op.execute(
+        """
+        DELETE FROM group_role_mapping
+        WHERE group_id IN (
+            SELECT id FROM user_group WHERE name = 'SUPER_ADMIN'
+        )
+        OR role_id IN (
+            SELECT id FROM user_role WHERE name = 'super_admin'
+        )
+        """
+    )
+
+    op.execute("DELETE FROM user_role WHERE name = 'super_admin'")
+    op.execute("DELETE FROM user_group WHERE name = 'SUPER_ADMIN'")

api/migrations/versions/a6f15ee2c7b4_remove_staff_user_tenant_id.py

@@ -0,0 +1,48 @@
+"""Remove redundant tenant_id from staff_users.
+
+Revision ID: a6f15ee2c7b4
+Revises: 9d2d16f5f3aa
+Create Date: 2026-05-04 16:40:00.000000
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision = 'a6f15ee2c7b4'
+down_revision = '9d2d16f5f3aa'
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    _drop_matching_foreign_keys('staff_users', 'tenant_id', 'tenant')
+    with op.batch_alter_table('staff_users', schema=None) as batch_op:
+        batch_op.drop_column('tenant_id')
+
+
+def downgrade():
+    with op.batch_alter_table('staff_users', schema=None) as batch_op:
+        batch_op.add_column(sa.Column('tenant_id', sa.Integer(), nullable=True))
+
+    op.create_foreign_key(None, 'staff_users', 'tenant', ['tenant_id'], ['id'])
+
+
+def _drop_matching_foreign_keys(table_name, local_column, referred_table):
+    """Drop FK constraints for a specific local column and referenced table."""
+    bind = op.get_bind()
+    inspector = sa.inspect(bind)
+    foreign_keys = inspector.get_foreign_keys(table_name)
+
+    for foreign_key in foreign_keys:
+        name = foreign_key.get('name')
+        constrained_columns = foreign_key.get('constrained_columns') or []
+        current_referred_table = foreign_key.get('referred_table')
+
+        if (
+            name
+            and local_column in constrained_columns
+            and current_referred_table == referred_table
+        ):
+            op.drop_constraint(name, table_name, type_='foreignkey')

api/src/api/__init__.py

@@ -205,6 +205,12 @@ def get_roles(token_info) -> list:
         # ... so any extraneous roles are discarded
         user_roles = list(set(roles_from_token).intersection(keycloak_forwarded_roles))
 
+        StaffUserService.sync_super_admin_membership(
+            token_info=token_info,
+            token_roles=roles_from_token,
+            tenant_id=getattr(g, 'tenant_id', None),
+        )
+
         # Retrieve user by external ID from token info
         user = StaffUserService.get_user_by_external_id(token_info['sub'])
 

api/src/api/models/base_model.py

@@ -19,8 +19,6 @@
 from sqlalchemy.ext.declarative import declared_attr
 
 from .db import db
-from ..utils.token_info import TokenInfo
-
 TENANT_ID = 'tenant_id'
 
 
@@ -48,7 +46,8 @@ def _get_current_user():
 
         Used to populate the created_by and modified_by relationships on all models.
         """
-        return TokenInfo.get_id()
+        token_info = getattr(g, 'jwt_oidc_token_info', None) or {}
+        return token_info.get('sub')
 
     @classmethod
     def find_by_id(cls, identifier: int):

api/src/api/models/staff_user.py

@@ -7,7 +7,7 @@
 from typing import Optional
 
 from flask import g
-from sqlalchemy import Column, ForeignKey, String, asc, desc, func, or_
+from sqlalchemy import Column, ForeignKey, String, asc, desc, func
 from sqlalchemy.orm import column_property
 from sqlalchemy.sql import text
 from sqlalchemy.sql.operators import ilike_op
@@ -36,7 +36,6 @@ class StaffUser(BaseModel):
     contact_number = Column(db.String(50), nullable=True)
     external_id = Column(db.String(50), nullable=False, unique=True)
     status_id = db.Column(db.Integer, ForeignKey('user_status.id'), nullable=False, default=1)
-    tenant_id = db.Column(db.Integer, db.ForeignKey('tenant.id'), nullable=True)
 
     @classmethod
     def get_all_paginated(cls, pagination_options: PaginationOptions, search_text='', include_inactive=False):
@@ -67,18 +66,12 @@ def get_all_paginated(cls, pagination_options: PaginationOptions, search_text=''
     @classmethod
     def _add_tenant_filter(cls, query):
         """Add tenant filtering to the query based on user group membership."""
-        has_tenant_id = hasattr(cls, TENANT_ID)
         has_g_tenant_id = hasattr(g, TENANT_ID) and g.tenant_id
-        if has_tenant_id and has_g_tenant_id:
-            return query.outerjoin(
+        if has_g_tenant_id:
+            return query.join(
                 UserGroupMembership,
                 (UserGroupMembership.staff_user_external_id == cls.external_id) &
                 (UserGroupMembership.tenant_id == g.tenant_id)
-            ).filter(
-                or_(
-                    UserGroupMembership.id != None,  # noqa: E711  # pylint: disable=C0121
-                    cls.tenant_id == g.tenant_id,   # new user, no role yet
-                )
             )
         return query
 

api/src/api/resources/staff_user.py

@@ -111,8 +111,8 @@ def delete(user_id):
         """Permanently delete an inactive user."""
         try:
             user_data = TokenInfo.get_user_data()
-            StaffUserService.delete_deactivated_user(user_id, user_data.get('external_id'))
-            return {'message': 'User deleted successfully.'}, HTTPStatus.OK
+            response = StaffUserService.delete_deactivated_user(user_id, user_data.get('external_id'))
+            return response, HTTPStatus.OK
         except BusinessException as err:
             return {'message': err.error}, err.status_code
 

api/src/api/schemas/staff_user.py

@@ -25,5 +25,4 @@ class Meta:  # pylint: disable=too-few-public-methods
     created_date = fields.Str(data_key='created_date')
     updated_date = fields.Str(data_key='updated_date')
     roles = fields.List(fields.Str(data_key='roles'))
-    tenant_id = fields.Str(data_key='tenant_id')
     status_id = fields.Int(data_key='status_id')