IBM Security Verify Setup Tutorial¶
This tutorial walks you through setting up IBM Security Verify (formerly IBM Cloud Identity) SSO authentication for MCP Gateway, enabling enterprise-grade identity management.
Prerequisites¶
- MCP Gateway installed and running
- IBM Security Verify tenant with admin access
- Access to your gateway's environment configuration
Step 1: Configure IBM Security Verify Application¶
1.1 Access IBM Security Verify Admin Console¶
- Navigate to your IBM Security Verify admin console
- URL format:
https://[tenant-name].verify.ibm.com
- Log in with your administrator credentials
- Go to Applications in the left sidebar
1.2 Create New Application¶
- Click Add application
- Choose Custom Application
- Select OpenID Connect as the sign-on method
1.3 Configure Application Settings¶
General Settings: - Application name: MCP Gateway
- Description: Model Context Protocol Gateway SSO Authentication
- Application URL: Your gateway's public URL - Example: https://gateway.yourcompany.com
Sign-on Settings: - Application type: Web
- Grant types: Select Authorization Code
- Redirect URIs: Critical - must be exact - Production: https://gateway.yourcompany.com/auth/sso/callback/ibm_verify
- Development: http://localhost:8000/auth/sso/callback/ibm_verify
1.4 Configure Advanced Settings¶
Token Settings: - Access token lifetime: 3600 seconds (1 hour) - Refresh token lifetime: 86400 seconds (24 hours) - ID token lifetime: 3600 seconds (1 hour)
Scopes: - Select openid
(required) - Select profile
(recommended) - Select email
(required)
1.5 Obtain Client Credentials¶
After saving the application:
- Go to the Sign-on tab
- Note the Client ID
- Click Generate secret to create a client secret
- Important: Copy the client secret immediately - you won't see it again
- Note the Discovery endpoint URL (usually
https://[tenant].verify.ibm.com/oidc/endpoint/default/.well-known/openid_configuration
)
Step 2: Configure MCP Gateway Environment¶
2.1 Find Your IBM Security Verify Endpoints¶
Before configuring, you need your tenant's OIDC endpoints:
# Replace [tenant-name] with your actual tenant name
curl https://[tenant-name].verify.ibm.com/oidc/endpoint/default/.well-known/openid-configuration
# This returns endpoint URLs you'll need
2.2 Update Environment Variables¶
Add these variables to your .env
file:
# Enable SSO System
SSO_ENABLED=true
# IBM Security Verify OIDC Configuration
SSO_IBM_VERIFY_ENABLED=true
SSO_IBM_VERIFY_CLIENT_ID=your-client-id-from-ibm-verify
SSO_IBM_VERIFY_CLIENT_SECRET=your-client-secret-from-ibm-verify
SSO_IBM_VERIFY_ISSUER=https://[tenant-name].verify.ibm.com/oidc/endpoint/default
# Optional: Auto-create users on first login
SSO_AUTO_CREATE_USERS=true
# Optional: Restrict to corporate email domains
SSO_TRUSTED_DOMAINS=["yourcompany.com"]
# Optional: Preserve local admin authentication
SSO_PRESERVE_ADMIN_AUTH=true
2.3 Example Production Configuration¶
# Production IBM Security Verify SSO Setup
SSO_ENABLED=true
SSO_IBM_VERIFY_ENABLED=true
SSO_IBM_VERIFY_CLIENT_ID=12345678-abcd-1234-efgh-123456789012
SSO_IBM_VERIFY_CLIENT_SECRET=AbCdEfGhIjKlMnOpQrStUvWxYz123456
SSO_IBM_VERIFY_ISSUER=https://acmecorp.verify.ibm.com/oidc/endpoint/default
# Enterprise security settings
SSO_AUTO_CREATE_USERS=true
SSO_TRUSTED_DOMAINS=["acmecorp.com"]
SSO_PRESERVE_ADMIN_AUTH=true
# Optional: Custom scopes for additional user attributes
SSO_IBM_VERIFY_SCOPE="openid profile email"
2.4 Development Configuration¶
# Development IBM Security Verify SSO Setup
SSO_ENABLED=true
SSO_IBM_VERIFY_ENABLED=true
SSO_IBM_VERIFY_CLIENT_ID=dev-client-id
SSO_IBM_VERIFY_CLIENT_SECRET=dev-client-secret
SSO_IBM_VERIFY_ISSUER=https://dev-tenant.verify.ibm.com/oidc/endpoint/default
# More permissive for testing
SSO_AUTO_CREATE_USERS=true
SSO_PRESERVE_ADMIN_AUTH=true
2.5 Advanced Configuration Options¶
# Custom OAuth scopes for enterprise features
SSO_IBM_VERIFY_SCOPE="openid profile email groups"
# Custom user attribute mappings (if needed)
IBM_VERIFY_USER_MAPPING={"preferred_username": "username", "family_name": "last_name"}
# Group/role mapping for automatic team assignment
IBM_VERIFY_GROUP_MAPPING={"CN=Developers,OU=Groups": "dev-team-uuid", "CN=Administrators,OU=Groups": "admin-team-uuid"}
Step 3: Configure User Access in IBM Security Verify¶
3.1 Assign Users to Application¶
- In IBM Security Verify admin console, go to Applications
- Find your MCP Gateway application
- Go to Access tab
- Click Assign access
- Choose assignment method:
- Users: Assign specific users
- Groups: Assign entire groups (recommended)
- Everyone: Allow all users (not recommended for production)
3.2 Configure Group-Based Access (Recommended)¶
- Create or use existing groups in IBM Security Verify
- Assign the application to appropriate groups:
MCP_Gateway_Users
- Regular usersMCP_Gateway_Admins
- Administrative users- Add users to these groups as needed
Step 4: Restart and Verify Gateway¶
4.1 Restart the Gateway¶
# Development
make dev
# Or directly with uvicorn
uvicorn mcpgateway.main:app --reload --host 0.0.0.0 --port 8000
# Production
make serve
4.2 Verify IBM Security Verify SSO is Enabled¶
Test that IBM Security Verify appears in SSO providers:
# Check if IBM Security Verify is listed
curl -X GET http://localhost:8000/auth/sso/providers
# Should return IBM Security Verify in the list:
[
{
"id": "ibm_verify",
"name": "ibm_verify",
"display_name": "IBM Security Verify"
}
]
Step 5: Test IBM Security Verify SSO Login¶
5.1 Access Login Page¶
- Navigate to your gateway's login page:
- Development:
http://localhost:8000/admin/login
-
Production:
https://gateway.yourcompany.com/admin/login
-
You should see a "Continue with IBM Security Verify" button
5.2 Test Authentication Flow¶
- Click Continue with IBM Security Verify
- You'll be redirected to IBM Security Verify's login page
- Enter your corporate credentials
- Complete any multi-factor authentication if required
- Grant consent if prompted
- You'll be redirected back to the gateway admin panel
- You should be logged in successfully
5.3 Verify User Creation¶
Check that a user was created:
# Using the admin API (requires admin token)
curl -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
http://localhost:8000/auth/users
# Look for your IBM Security Verify email in the user list
Step 6: Enterprise Features (Advanced)¶
6.1 Multi-Factor Authentication (MFA)¶
IBM Security Verify MFA is handled automatically:
- Configure MFA policies in IBM Security Verify admin console
- Go to Security β Multi-factor authentication
- Set up policies for your MCP Gateway application
- Users will be prompted for MFA during login
6.2 Conditional Access¶
Configure access policies based on conditions:
- In IBM Security Verify, go to Security β Access policies
- Create policies for your MCP Gateway application
- Configure conditions:
- Device compliance
- Location-based access
- Risk-based authentication
- Time-based restrictions
6.3 User Lifecycle Management¶
Configure automatic user provisioning:
- Set up SCIM provisioning (if supported)
- Configure user attribute synchronization
- Set up automatic de-provisioning for terminated users
6.4 Audit and Compliance¶
Enable comprehensive audit logging:
- In IBM Security Verify, configure audit settings
- Enable logging for:
- Authentication events
- Authorization decisions
- User provisioning actions
- Administrative changes
Step 7: Production Deployment Checklist¶
7.1 Security Requirements¶
- HTTPS enforced for all redirect URIs
- Client secrets stored in secure vault
- MFA policies configured
- Conditional access policies set
- Audit logging enabled
- Regular security reviews scheduled
7.2 IBM Security Verify Configuration¶
- Application created with correct settings
- Redirect URIs match exactly
- Appropriate users/groups assigned access
- MFA policies configured
- Audit logging enabled
7.3 Network and Infrastructure¶
- Gateway accessible from corporate network
- IBM Security Verify endpoints reachable
- HTTPS certificates valid
- Load balancer configured (if needed)
Troubleshooting¶
Error: "SSO authentication is disabled"¶
Problem: SSO endpoints return 404 Solution: Set SSO_ENABLED=true
and restart gateway
Error: "invalid_redirect_uri"¶
Problem: IBM Security Verify redirect URI doesn't match Solution: Verify exact URL match in IBM Security Verify application settings
# IBM Security Verify redirect URI must exactly match:
https://your-domain.com/auth/sso/callback/ibm_verify
# Common mistakes:
https://your-domain.com/auth/sso/callback/ibm_verify/ # Extra slash
http://your-domain.com/auth/sso/callback/ibm_verify # HTTP instead of HTTPS
https://your-domain.com/auth/sso/callback/ibm-verify # Wrong provider ID
Error: "invalid_client"¶
Problem: Wrong client ID or client secret Solution: Verify credentials from IBM Security Verify application
# Double-check these values match IBM Security Verify
SSO_IBM_VERIFY_CLIENT_ID=your-actual-client-id
SSO_IBM_VERIFY_CLIENT_SECRET=your-actual-client-secret
Error: "User not authorized"¶
Problem: User not assigned access to the application Solution: Assign user or their group to the MCP Gateway application
- In IBM Security Verify admin console, go to Applications
- Find MCP Gateway application β Access tab
- Assign access to the user or their group
Error: "Issuer mismatch"¶
Problem: Wrong issuer URL configured Solution: Verify issuer URL matches your IBM Security Verify tenant
# Get the correct issuer from the well-known configuration
curl https://[tenant-name].verify.ibm.com/oidc/endpoint/default/.well-known/openid-configuration
# Look for "issuer" field in response
MFA Not Working¶
Problem: Multi-factor authentication not triggered Solution: Check MFA policies in IBM Security Verify
- Go to Security β Multi-factor authentication
- Ensure policies are enabled for your application
- Check user enrollment status
- Verify policy conditions are met
Testing Checklist¶
- IBM Security Verify application created
- Client ID and secret generated
- Redirect URI configured correctly
- Users/groups assigned access to application
- Environment variables set correctly
- Gateway restarted with new config
-
/auth/sso/providers
returns IBM Security Verify provider - Login page shows "Continue with IBM Security Verify" button
- Authentication flow completes successfully
- User appears in gateway user list
- MFA working (if configured)
Enterprise Integration¶
Active Directory Integration¶
If IBM Security Verify is connected to Active Directory:
- User attributes sync automatically
- Group memberships are available
- Configure group-based access in IBM Security Verify
- Map AD groups to gateway teams
SAML Federation (Alternative)¶
For environments preferring SAML over OIDC:
- Configure SAML application in IBM Security Verify
- Use custom SAML integration (requires additional development)
- Configure SAML assertions and attribute mapping
Next Steps¶
After IBM Security Verify SSO is working:
- Configure MFA policies for enhanced security
- Set up conditional access based on risk factors
- Integrate with existing AD/LDAP if needed
- Configure audit logging for compliance
- Train users on the new login process
- Set up monitoring for authentication failures
Related Documentation¶
- Complete SSO Guide - Full SSO documentation
- GitHub SSO Tutorial - GitHub setup guide
- Google SSO Tutorial - Google setup guide
- Team Management - Managing teams and roles
- RBAC Configuration - Role-based access control
Support¶
If you encounter issues:
- Check IBM Security Verify admin console for error messages
- Enable debug logging:
LOG_LEVEL=DEBUG
- Review gateway logs for IBM Security Verify errors
- Verify all IBM Security Verify settings match tutorial
- Contact IBM Security Verify support for tenant-specific issues