fix(rbac): resolve SSO role assignment FK constraint violation on granted_by='sso_system' (#3502)

* fix(rbac): resolve SSO role assignment FK constraint violation on granted_by='sso_system' (#3484)

Add grant_source column to UserRole to track role assignment provenance
(e.g. 'sso', 'manual', 'bootstrap') separately from the granted_by FK.
SSO role sync now uses granted_by=user_email (satisfying the FK to
email_users) with grant_source='sso' to distinguish SSO-granted roles
for revocation logic.

Closes #3484

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

* fix(sso): rewrite Keycloak issuer URL to public_base_url for id_token verification

Keycloak discovery fetches OIDC metadata via the internal base_url
(e.g. http://keycloak:8080), but tokens issued through the browser flow
contain the public-facing issuer (e.g. http://localhost:8180). The
authorization_url was already rewritten to public_base_url but the
issuer was not, causing id_token verification to fail with
"Invalid issuer".

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

* docs: update CHANGELOG and Keycloak tutorial for SSO fixes

Add grant_source provenance tracking and both SSO fixes to RC2
CHANGELOG. Update Keycloak tutorial with split-URL issuer
troubleshooting and SSO_KEYCLOAK_PUBLIC_BASE_URL description.

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

* fix(rbac): expose grant_source in UserRoleResponse API schema

Add grant_source field to UserRoleResponse so /rbac/my/roles and
other role endpoints return the provenance of each assignment.
Update Entra ID tutorial example to match the full response shape.

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

---------

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>
Signed-off-by: Yosief Eyob <yosiefogbazion@gmail.com>

Author: crivetimihai

CHANGELOG.md

@@ -180,6 +180,11 @@ This release **tightens production defaults** and adds **defense-in-depth contro
 * Admins can now set email verification status on users via API (`PUT /auth/email/admin/users/{email}`) and Admin UI checkbox
 * `@require_permission("teams.join")` added to `accept_team_invitation`, `request_to_join_team`, and `leave_team` endpoints
 
+#### **🏷️ Role Assignment Provenance Tracking** ([#3484](https://github.com/IBM/mcp-context-forge/issues/3484), [#3502](https://github.com/IBM/mcp-context-forge/pull/3502))
+* New `grant_source` column on `user_roles` table tracks the origin of role assignments (`'sso'`, `'manual'`, `'bootstrap'`, `'auto'`)
+* SSO role sync uses `grant_source='sso'` to distinguish SSO-granted roles from manually or auto-assigned roles, enabling correct revocation without affecting non-SSO roles
+* Alembic migration `e1f2a3b4c5d6` adds the column (nullable, backward-compatible with existing rows)
+
 ### Fixed
 
 #### **🔐 Security** (S-01, S-02, S-03, A-02, A-05, A-06, O-01, O-05, O-10, O-17, U-05, C-03, C-04, C-07, C-09, C-10, C-11, C-14, C-15, C-28, C-29, EXTRA-01)
@@ -210,6 +215,8 @@ This release **tightens production defaults** and adds **defense-in-depth contro
 * **GitHub SSO email-claim compatibility** - GitHub logins no longer fail when `/user` omits `email_verified`; explicit false verification claims are still denied (O-03 follow-up)
 * **SSO approval-state hardening** - expired pending approvals no longer fall through to user creation; approval statuses now fail closed (O-04)
 * **SSO scope policy enforcement** - requested scopes are normalized and constrained to provider policy; invalid scopes rejected with HTTP 400 (O-06)
+* **SSO role assignment FK constraint violation** - `_sync_user_roles()` used `granted_by='sso_system'` which violated the `user_roles.granted_by` foreign key to `email_users.email` on PostgreSQL; now uses `granted_by=<user_email>` with a new `grant_source` column to track provenance ([#3484](https://github.com/IBM/mcp-context-forge/issues/3484), [#3502](https://github.com/IBM/mcp-context-forge/pull/3502))
+* **Keycloak SSO issuer mismatch** - Keycloak OIDC discovery rewrote `authorization_url` to `public_base_url` but not `issuer`; tokens issued via browser flow contain the public-facing issuer, causing `id_token` verification to fail with "Invalid issuer" when `SSO_KEYCLOAK_PUBLIC_BASE_URL` differs from `SSO_KEYCLOAK_BASE_URL` ([#3502](https://github.com/IBM/mcp-context-forge/pull/3502))
 * **OAuth grant fallback removal** - `authorization_code` no longer falls back to `client_credentials` in non-interactive token retrieval (O-11)
 * **SSO callback session binding** - state is bound to browser session marker and callback requires matching session binding (O-14)
 * **OAuth authorize/status ownership checks** - gateway visibility/team/owner checks now enforced consistently on authorize/status endpoints (O-16)

docs/docs/architecture/adr/034-sso-admin-sync-config-precedence.md

@@ -30,7 +30,7 @@ if should_be_admin and not user.is_admin:
 - The `is_admin` flag is a **platform-level override** that grants `["*"]` permissions via JWT scopes
 - Manual admin grants via Admin UI/API are intentional decisions by platform administrators
 - SSO should enhance access control, not unexpectedly revoke access
-- The RBAC system (`platform_admin` role) already handles group-based role revocation with proper tracking (`granted_by='sso_system'`)
+- The RBAC system (`platform_admin` role) already handles group-based role revocation with proper tracking (`grant_source='sso'`)
 - To revoke admin access, administrators should use the Admin UI/API explicitly
 
 **Trade-offs**:

docs/docs/manage/sso-entra-role-mapping.md

@@ -80,7 +80,7 @@ ContextForge includes a comprehensive RBAC system with the following default rol
    - Revokes SSO-granted roles no longer in groups
    - Assigns new roles based on current groups
    - Preserves manually assigned roles
-   - Maintains audit trail with `granted_by='sso_system'`
+   - Maintains audit trail with `grant_source='sso'` and `granted_by=<user_email>`
 
 6. **Admin Status Synchronization** (`authenticate_or_create_user()`)
 
@@ -242,7 +242,7 @@ When a new user logs in via EntraID SSO:
 2. Groups are mapped to roles via `_map_groups_to_roles()`
 3. Roles are assigned via `_sync_user_roles()`
 4. User is created with `is_admin` flag if in admin groups
-5. RBAC roles are assigned with `granted_by='sso_system'`
+5. RBAC roles are assigned with `grant_source='sso'` (self-granted by the user)
 
 ### On User Login
 
@@ -259,8 +259,8 @@ When an existing user logs in:
 ### Manual Role Management
 
 - Admins can manually assign additional roles via the Admin UI
-- Manually assigned roles (not granted by `sso_system`) are preserved
-- Only SSO-granted roles are synchronized on login
+- Manually assigned roles (without `grant_source='sso'`) are preserved
+- Only SSO-granted roles (`grant_source='sso'`) are synchronized on login
 
 ## Token Claims
 

docs/docs/manage/sso-keycloak-tutorial.md

@@ -403,7 +403,7 @@ SSO_KEYCLOAK_CLIENT_ID=mcp-gateway-prod
 |----------|----------|---------|-------------|
 | `SSO_KEYCLOAK_ENABLED` | Yes | `false` | Enable Keycloak SSO provider |
 | `SSO_KEYCLOAK_BASE_URL` | Yes | - | Base URL of Keycloak instance |
-| `SSO_KEYCLOAK_PUBLIC_BASE_URL` | No | _unset_ | Browser-facing Keycloak URL used for authorization redirects when gateway uses an internal URL |
+| `SSO_KEYCLOAK_PUBLIC_BASE_URL` | No | _unset_ | Browser-facing Keycloak URL used for authorization redirects and issuer verification when gateway uses an internal URL |
 | `SSO_KEYCLOAK_REALM` | Yes | `master` | Keycloak realm name |
 | `SSO_KEYCLOAK_CLIENT_ID` | Yes | - | OAuth client ID from Keycloak |
 | `SSO_KEYCLOAK_CLIENT_SECRET` | Yes | - | OAuth client secret from Keycloak |
@@ -823,6 +823,17 @@ SSO_KEYCLOAK_BASE_URL=https://keycloak.yourcompany.com/auth
 SSO_KEYCLOAK_BASE_URL=https://keycloak.yourcompany.com
 ```
 
+**Split-URL deployments** (e.g., Docker Compose with reverse proxy): When the gateway
+reaches Keycloak via an internal URL (`SSO_KEYCLOAK_BASE_URL=http://keycloak:8080`) but
+users authenticate via a different public URL, set `SSO_KEYCLOAK_PUBLIC_BASE_URL` to the
+browser-facing URL. The gateway rewrites both the authorization URL and the issuer to
+the public base so that `id_token` issuer verification succeeds:
+
+```bash
+SSO_KEYCLOAK_BASE_URL=http://keycloak:8080          # Internal (token, userinfo, JWKS)
+SSO_KEYCLOAK_PUBLIC_BASE_URL=http://localhost:8180   # Browser-facing (auth URL, issuer)
+```
+
 ### Roles Not Appearing in JWT
 
 **Problem**: User roles not included in JWT token

docs/docs/manage/sso-microsoft-entra-id-tutorial.md

@@ -601,12 +601,20 @@ After configuration, test role assignment:
 curl -H "Authorization: Bearer YOUR_TOKEN" \
   http://localhost:8000/rbac/my/roles
 
-# Should return assigned roles:
+# Should return assigned roles (abbreviated):
 [
   {
+    "id": "...",
+    "user_email": "user@example.com",
+    "role_id": "...",
     "role_name": "developer",
     "scope": "team",
-    "granted_by": "sso_system"
+    "scope_id": null,
+    "granted_by": "user@example.com",
+    "granted_at": "2026-02-20T21:20:20Z",
+    "expires_at": null,
+    "is_active": true,
+    "grant_source": "sso"
   }
 ]
 ```
@@ -643,7 +651,7 @@ Roles are automatically synchronized:
 
 - Admins can manually assign additional roles via Admin UI
 - Manually assigned roles are preserved during sync
-- Only SSO-granted roles (granted_by='sso_system') are synchronized
+- Only SSO-granted roles (`grant_source='sso'`) are synchronized
 
 ### 8.5.7 Troubleshooting Role Mapping
 

mcpgateway/alembic/versions/e1f2a3b4c5d6_add_grant_source_to_user_roles.py

@@ -0,0 +1,53 @@
+# pylint: disable=no-member
+"""add grant_source to user_roles
+
+Revision ID: e1f2a3b4c5d6
+Revises: d9e0f1a2b3c4
+Create Date: 2026-03-05
+
+Adds a grant_source column to user_roles to track the origin of role
+assignments (e.g. 'sso', 'manual', 'bootstrap', 'auto').  This replaces
+the previous pattern of using granted_by='sso_system' which violated the
+FK constraint on granted_by -> email_users.email.
+"""
+
+# Standard
+from typing import Sequence, Union
+
+# Third-Party
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "e1f2a3b4c5d6"
+down_revision: Union[str, Sequence[str], None] = "d9e0f1a2b3c4"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Add grant_source column to user_roles table."""
+    inspector = sa.inspect(op.get_bind())
+
+    if "user_roles" not in inspector.get_table_names():
+        return
+
+    columns = [col["name"] for col in inspector.get_columns("user_roles")]
+    if "grant_source" in columns:
+        return
+
+    op.add_column("user_roles", sa.Column("grant_source", sa.String(50), nullable=True))
+
+
+def downgrade() -> None:
+    """Remove grant_source column from user_roles table."""
+    inspector = sa.inspect(op.get_bind())
+
+    if "user_roles" not in inspector.get_table_names():
+        return
+
+    columns = [col["name"] for col in inspector.get_columns("user_roles")]
+    if "grant_source" not in columns:
+        return
+
+    op.drop_column("user_roles", "grant_source")

mcpgateway/db.py

@@ -978,6 +978,7 @@ class UserRole(Base):
     granted_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utc_now)
     expires_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True), nullable=True)
     is_active: Mapped[bool] = mapped_column(Boolean, nullable=False, default=True)
+    grant_source: Mapped[Optional[str]] = mapped_column(String(50), nullable=True, default=None)
 
     # Relationships
     role: Mapped["Role"] = relationship("Role", back_populates="user_assignments")

mcpgateway/schemas.py

@@ -6701,6 +6701,7 @@ class UserRoleResponse(BaseModel):
     granted_at: datetime = Field(..., description="When role was granted")
     expires_at: Optional[datetime] = Field(None, description="Optional expiration")
     is_active: bool = Field(..., description="Whether assignment is active")
+    grant_source: Optional[str] = Field(None, description="Origin of the grant (e.g., 'sso', 'manual', 'bootstrap', 'auto')")
 
 
 class PermissionCheckRequest(BaseModel):

mcpgateway/services/role_service.py

@@ -526,7 +526,9 @@ async def delete_role(self, role_id: str) -> bool:
         logger.info(f"Deleted role: {role.name} (id: {role.id})")
         return True
 
-    async def assign_role_to_user(self, user_email: str, role_id: str, scope: str, scope_id: Optional[str], granted_by: str, expires_at: Optional[datetime] = None) -> UserRole:
+    async def assign_role_to_user(
+        self, user_email: str, role_id: str, scope: str, scope_id: Optional[str], granted_by: str, expires_at: Optional[datetime] = None, grant_source: Optional[str] = None
+    ) -> UserRole:
         """Assign a role to a user.
 
         Args:
@@ -536,6 +538,7 @@ async def assign_role_to_user(self, user_email: str, role_id: str, scope: str, s
             scope_id: Team ID if team-scoped
             granted_by: Email of user granting the role
             expires_at: Optional expiration datetime
+            grant_source: Origin of the grant (e.g., 'sso', 'manual', 'bootstrap', 'auto')
 
         Returns:
             UserRole: The role assignment
@@ -619,7 +622,7 @@ async def assign_role_to_user(self, user_email: str, role_id: str, scope: str, s
             raise ValueError("User already has this role assignment")
 
         # Create the assignment
-        user_role = UserRole(user_email=user_email, role_id=role_id, scope=scope, scope_id=scope_id, granted_by=granted_by, expires_at=expires_at)
+        user_role = UserRole(user_email=user_email, role_id=role_id, scope=scope, scope_id=scope_id, granted_by=granted_by, expires_at=expires_at, grant_source=grant_source)
 
         self.db.add(user_role)
         self.db.commit()

mcpgateway/services/sso_service.py

@@ -1893,9 +1893,9 @@ async def _sync_user_roles(self, user_email: str, role_assignments: List[Dict[st
 
         role_service = RoleService(self.db)
 
-        # Get current SSO-granted roles (granted_by='sso_system')
+        # Get current SSO-granted roles
         current_roles = await role_service.list_user_roles(user_email, include_expired=False)
-        sso_roles = [r for r in current_roles if r.granted_by == "sso_system"]
+        sso_roles = [r for r in current_roles if getattr(r, "grant_source", None) == "sso"]
 
         # Build set of desired role assignments
         desired_roles = {(r["role_name"], r["scope"], r.get("scope_id")) for r in role_assignments}
@@ -1921,7 +1921,9 @@ async def _sync_user_roles(self, user_email: str, role_assignments: List[Dict[st
 
                 if not existing or not existing.is_active:
                     # Assign role to user
-                    await role_service.assign_role_to_user(user_email=user_email, role_id=role.id, scope=assignment["scope"], scope_id=assignment.get("scope_id"), granted_by="sso_system")
+                    await role_service.assign_role_to_user(
+                        user_email=user_email, role_id=role.id, scope=assignment["scope"], scope_id=assignment.get("scope_id"), granted_by=user_email, grant_source="sso"
+                    )
                     logger.info(f"Assigned SSO role '{role.name}' to {user_email}")
 
             except Exception as e: