🧭 Type of Feature

Please select the most appropriate category:

• Enhancement to existing functionality
• New feature or capability
• New MCP-compliant server
• New component or integration
• Developer tooling or test improvement
• Packaging, automation and deployment (ex: pypi, docker, quay.io, kubernetes, terraform)
• Other (please describe below)

🧭 Epic

Title: Microsoft EntraID Role and Group Claim Mapping for SSO
Goal: Implement proper role and group claim extraction for Microsoft EntraID SSO authentication to enable granular access control and user authorization
Why now: Currently all EntraID users default to admin role, creating security risks and preventing proper role-based access control. This functionality already exists for Keycloak but is missing for EntraID, creating an inconsistent authentication experience.

🙋♂️ User Story 1

As a: System administrator configuring SSO
I want: Microsoft EntraID users to be assigned appropriate roles based on their group memberships
So that: I can implement proper access control and security boundaries in my organization

✅ Acceptance Criteria

Scenario: EntraID user with specific group membership logs in
  Given a user exists in Microsoft EntraID with group "developers"
  And the group "developers" is mapped to role "user" in Context Forge
  When the user authenticates via EntraID SSO
  Then the user should be assigned "user" role in Context Forge
  And the user should not have admin privileges

Scenario: EntraID user with admin group membership logs in
  Given a user exists in Microsoft EntraID with group "admins"  
  And the group "admins" is mapped to role "admin" in Context Forge
  When the user authenticates via EntraID SSO
  Then the user should be assigned "admin" role in Context Forge
  And the user should have full administrative privileges

🙋♂️ User Story 2

As a: Enterprise user authenticating via EntraID
I want: My role assignments to be consistent with my organizational permissions
So that: I can access the appropriate resources without manual intervention from administrators

✅ Acceptance Criteria

Scenario: User role is automatically assigned based on EntraID groups
  Given I am a member of "data-analysts" group in EntraID
  And "data-analysts" group is mapped to "analyst" role
  When I log in through SSO
  Then I should automatically receive "analyst" permissions
  And I should be able to access analyst-specific features

📐 Design Sketch (optional)

Include a diagram, sketch, or flow (use Mermaid if desired):

sequenceDiagram
    participant U as User
    participant E as EntraID
    participant MCP as MCP Gateway
    participant CF as Context Forge

    U->>E: Authenticate
    E->>MCP: Return ID token with groups claim
    MCP->>CF: Extract groups from token
    CF->>CF: Map groups to roles
    CF->>MCP: Return user with assigned role
    MCP->>U: Grant access with proper permissions

🔗 MCP Standards Check

• Change adheres to current MCP specifications
• No breaking changes to existing MCP-compliant integrations
• If deviations exist, please describe them below:

🔄 Alternatives Considered

• Manual role assignment: Requires admin intervention for each user, doesn't scale
• Default admin for all users: Current behavior, creates security risks
• Custom middleware: Would require additional complexity outside of Context Forge
• Match Keycloak implementation: Preferred approach - reuse existing patterns from lines 560-596 in sso_service.py

📓 Additional Context

Current Implementation Gap:

• Keycloak SSO properly handles role extraction (sso_service.py lines 560-596) ✅
• EntraID SSO missing equivalent functionality (sso_service.py lines 599-618) ❌

Reference Documentation:

• Followed tutorial: https://ibm.github.io/mcp-context-forge/manage/sso-microsoft-entra-id-tutorial/#91-custom-branding
• Documentation shows how to configure EntraID but implementation lacks role mapping

Expected Claims Structure:
EntraID typically provides group information in claims like:

• groups - array of group object IDs
• roles - array of application role assignments
• Custom claims can be configured for group names

Suggested Implementation:
Extend the existing EntraID authentication handler to:

1. Extract group/role claims from the ID token
2. Map these claims to Context Forge roles using similar logic to Keycloak implementation
3. Apply appropriate role assignments during user session creation