[Feature Request]: Authentication & Authorization - IBM Security Verify Enterprise SSO Integration (Depends on #220)

[crivetimihai]

Authentication & Authorization – IBM Security Verify Enterprise SSO Integration

🧭 Epic

Depends on: Add SSO & IdP-Issued Tokens to Gateway (#220)
Title: Turn-key IBM Security Verify SSO for the Gateway
Goal: Ship a ready-made IBM Security Verify OIDC provider plus comprehensive enterprise tutorial so ops teams can enable IBM Security Verify login in ≤ 15 minutes by configuring tenant settings and environment variables.
Why now: Enterprise organizations using IBM Security Verify need seamless integration with existing identity infrastructure, MFA policies, and conditional access controls.

---

🧭 Type of Feature

• Enterprise-grade security integration
• New functionality (pluggable IdP)
• Security hardening
• Documentation and tutorials
• Multi-factor authentication support

---

🙋‍♂️ User Story 1 – Enterprise IBM Security Verify Login

As a: Platform engineer
I want: to set SSO_IBM_VERIFY_CLIENT_ID/SECRET and SSO_IBM_VERIFY_ISSUER in my .env, and have the UI redirect to IBM Security Verify's enterprise login
So that: users authenticate with their corporate IBM Security Verify credentials with full MFA and conditional access policies.

✅ Acceptance Criteria

Scenario: Successful IBM Security Verify OIDC login
Given generic SSO is enabled
And the IBM Security Verify provider has valid client credentials
When an unauthenticated browser hits "/"
Then the gateway MUST redirect to IBM Security Verify tenant login
And after authentication MUST exchange the code for an ID-token
And MUST create an encrypted session cookie containing sub, email, preferred_username & groups
And MUST honor MFA policies configured in IBM Security Verify

---

🙋‍♂️ User Story 2 – Corporate Domain Restriction

As a: Security admin
I want: to restrict login to corporate domains via SSO_TRUSTED_DOMAINS
So that: only users from verified corporate domains can access the gateway.

✅ Acceptance Criteria

Scenario: Enforce corporate domain restriction
Given SSO_TRUSTED_DOMAINS contains "acmecorp.com"  
When a user signs in with alice@acmecorp.com via IBM Security Verify
Then the gateway MUST allow authentication
And when a user with external@example.com tries to login
Then the gateway MUST respond 403 "forbidden_domain"

---

🙋‍♂️ User Story 3 – IBM Security Verify Groups → Teams Mapping

As a: Security admin
I want: IBM Security Verify group memberships mapped automatically to gateway teams
So that: membership in IBM Security Verify groups like "MCP_Gateway_Admins" creates corresponding team access.

✅ Acceptance Criteria

Scenario: Team assignment via IBM Security Verify groups
Given a user belongs to IBM Security Verify group "MCP_Gateway_Admins"
When the OIDC callback completes
Then "mcp-gateway-admins" team MUST be created or assigned
And the user MUST be added as a team member with appropriate role
And RBAC policy evaluation MUST succeed for team-scoped resources

---

🙋‍♂️ User Story 4 – Enterprise MFA and Conditional Access

As a: Security admin
I want: IBM Security Verify MFA policies and conditional access controls to be honored automatically
So that: enterprise security policies apply transparently to gateway access.

✅ Acceptance Criteria

Scenario: MFA enforcement via IBM Security Verify
Given IBM Security Verify has MFA policy for MCP Gateway application
When a user authenticates via IBM Security Verify
Then the user MUST complete MFA challenge in IBM Security Verify
And the gateway MUST only accept tokens from MFA-completed sessions

Scenario: Conditional access enforcement
Given IBM Security Verify has location-based conditional access policy  
When a user tries to login from blocked location
Then IBM Security Verify MUST deny authentication
And the gateway MUST receive no valid token

---

🙋‍♂️ User Story 5 – Complete Enterprise Setup Tutorial

As an: Enterprise operator
I want: step-by-step tutorial with IBM Security Verify admin console screenshots and complete configuration examples
So that: I can enable the feature following enterprise security best practices.

✅ Acceptance Criteria

• docs/docs/manage/sso-ibm-tutorial.md provides comprehensive tutorial including:
  • IBM Security Verify tenant application creation
  • OIDC configuration with proper scopes and redirect URIs
  • Enterprise security settings (MFA, conditional access)
  • Group/user assignment workflows
  • Complete environment variable reference
  • Production deployment checklist
  • Troubleshooting guide with common enterprise scenarios

---

📐 Design Sketch

flowchart TD
    Browser -->|OAuth 2.0 / OIDC| IBMVerify[(IBM Security Verify)]
    IBMVerify -->|MFA + Conditional Access| AuthSvc[Gateway Auth Service]
    subgraph Gateway
        AuthSvc --> TeamMapper[Team Mapper]
        TeamMapper --> Teams[Teams & RBAC]
        Teams --> API["Multi-tenant APIs"]
    end
    subgraph Enterprise Policies
        IBMVerify --> MFA[Multi-factor Auth]
        IBMVerify --> ConditionalAccess[Conditional Access]
        IBMVerify --> Groups[Enterprise Groups]
    end

Loading

Component	Change	Detail
auth_providers/ibm_verify.py	NEW	OIDC discovery, enterprise token validation, group fetch
auth_service.py	UPDATE	Register "ibm_verify" provider under SSO plugin interface
DB	UPDATE	Store ibm_verify_sub, email, preferred_username
Config	ADD	SSO_IBM_VERIFY_* enterprise configuration variables
Team Service	UPDATE	Auto-create teams from IBM Security Verify groups

---

📋 Configuration Variables

Setting	Description	Example
SSO_IBM_VERIFY_ENABLED	Enable IBM Security Verify SSO	true
SSO_IBM_VERIFY_CLIENT_ID	OIDC Client ID from IBM Security Verify	12345678-abcd-1234-efgh-123456789012
SSO_IBM_VERIFY_CLIENT_SECRET	OIDC Client secret	AbCdEfGhIjKlMnOpQrStUvWxYz123456
SSO_IBM_VERIFY_ISSUER	IBM Security Verify tenant issuer URL	https://acmecorp.verify.ibm.com/oidc/endpoint/default
SSO_IBM_VERIFY_SCOPE	OIDC scopes for user attributes	"openid profile email groups"
SSO_TRUSTED_DOMAINS	Allowed corporate email domains	["acmecorp.com","trusted-partner.com"]
SSO_AUTO_CREATE_USERS	Auto-create users on first login	true
IBM_VERIFY_GROUP_MAPPING	Map IBM groups to gateway teams	{"MCP_Admins": "admin-team-uuid"}

---

🔄 Roll-out Plan

1. Phase 0: Feature-flag SSO_IBM_VERIFY_ENABLED with enterprise-ready defaults.
2. Phase 1: Ship comprehensive enterprise tutorial with security best practices.
3. Phase 2: Add automated group-to-team mapping functionality.
4. Phase 3: Promote to Enterprise Supported after production validation.
5. Phase 4: Integrate with audit logging for enterprise compliance.

---

📝 Enterprise Security Requirements

1. IBM Security Verify OIDC Compliance – "Gateways MUST implement OAuth 2.0 Authorization Code with PKCE against IBM Security Verify OIDC endpoints."
2. MFA Enforcement – "All IBM Security Verify authentication MUST honor tenant MFA policies without gateway bypass."
3. Conditional Access – "IBM Security Verify conditional access policies MUST be enforced transparently."
4. Domain Restriction – "If SSO_TRUSTED_DOMAINS is set, non-corporate domains MUST be rejected with 403."
5. Audit Trail – "All IBM Security Verify authentication events SHOULD be logged for enterprise audit requirements."
6. Group Mapping – "IBM Security Verify group memberships SHOULD map to gateway teams with configurable role assignment."

---

🎯 Enterprise Features Included

• ✅ Complete Tutorial: Step-by-step IBM Security Verify tenant configuration
• ✅ MFA Support: Automatic enforcement of IBM Security Verify MFA policies
• ✅ Conditional Access: Location, device, and risk-based access controls
• ✅ Group Mapping: IBM Security Verify groups → Gateway teams
• ✅ Domain Restriction: Corporate domain enforcement
• ✅ Production Checklist: Enterprise deployment verification
• ✅ Troubleshooting Guide: Common enterprise scenarios and solutions
• ✅ Audit Logging: Enterprise compliance logging requirements

---

📣 Next Steps

• ✅ Complete IBM Security Verify OIDC provider implementation
• ✅ Create comprehensive enterprise tutorial documentation
• ✅ Add automated group-to-team mapping functionality
• ✅ Implement domain restriction and user auto-creation
• ✅ Add enterprise security configuration validation
• Add audit logging integration for compliance
• Create enterprise deployment automation scripts
• Record enterprise setup demonstration video

---

🔗 Implementation Status

IMPLEMENTED: This epic represents completed functionality with comprehensive IBM Security Verify integration including:

• Full OIDC integration with IBM Security Verify tenants
• Complete tutorial at docs/docs/manage/sso-ibm-tutorial.md
• Enterprise-grade configuration options
• MFA and conditional access policy enforcement
• Automated user provisioning and team mapping
• Production-ready security defaults
• Comprehensive troubleshooting documentation

Ready for production enterprise deployments.