Okta OIDC Setup Tutorial¶
This tutorial walks you through setting up Okta Single Sign-On (SSO) authentication for MCP Gateway, enabling enterprise identity management with Okta's comprehensive platform.
Prerequisites¶
- MCP Gateway installed and running
- Okta account with admin access (Developer or Enterprise edition)
- Access to your gateway's environment configuration
Step 1: Create Okta Application Integration¶
1.1 Access Okta Admin Console¶
- Navigate to your Okta admin console
- URL format:
https://[org-name].okta.com
orhttps://[org-name].oktapreview.com
- Log in with your administrator credentials
- Go to Applications β Applications in the left sidebar
1.2 Create New App Integration¶
- Click Create App Integration
- Choose OIDC - OpenID Connect as the sign-in method
- Choose Web Application as the application type
- Click Next
1.3 Configure General Settings¶
App integration name: MCP Gateway
App logo: Upload your organization's logo (optional)
Grant type: Select Authorization Code (should be pre-selected)
1.4 Configure Sign-in Settings¶
Sign-in redirect URIs: Critical - must be exact - Production: https://gateway.yourcompany.com/auth/sso/callback/okta
- Development: http://localhost:8000/auth/sso/callback/okta
- Click Add URI if you need both
Sign-out redirect URIs (optional): - Production: https://gateway.yourcompany.com/admin/login
- Development: http://localhost:8000/admin/login
Controlled access: Choose appropriate option: - Allow everyone in your organization to access (most common) - Limit access to selected groups (recommended for production) - Skip group assignment for now (development only)
1.5 Save and Obtain Credentials¶
- Click Save
- After creation, you'll see the Client Credentials:
- Client ID: Copy this value
- Client secret: Copy this value (click to reveal)
- Note your Okta domain (e.g.,
https://dev-12345.okta.com
)
Step 2: Configure Okta Application Settings¶
2.1 Configure Token Settings (Optional)¶
- In your application, go to the General tab
- Scroll to General Settings β Edit
- Configure token lifetimes:
- Access token lifetime: 1 hour (default)
- Refresh token lifetime: 90 days (default)
- ID token lifetime: 1 hour (default)
2.2 Configure Claims (Advanced)¶
- Go to the Sign On tab
- Scroll to OpenID Connect ID Token
- Configure claims if you need custom user attributes:
groups
- User's group membershipsdepartment
- User's departmenttitle
- User's job title
Example custom claim configuration: - Name: groups
- Include in token type: ID Token, Always - Value type: Groups - Filter: Matches regex .*
(for all groups)
Step 3: Configure User and Group Access¶
3.1 Assign Users to Application¶
- Go to the Assignments tab in your application
- Click Assign β Assign to People
- Select users who should have access
- Click Assign for each user
- Click Save and Go Back
3.2 Assign Groups to Application (Recommended)¶
- Click Assign β Assign to Groups
- Select groups that should have access:
Everyone
- All users (not recommended for production)MCP Gateway Users
- Custom group for gateway accessIT Admins
- Administrative access- For each group, you can set a custom Application username
- Click Assign and Done
3.3 Create Custom Groups (Optional)¶
If you want specific groups for MCP Gateway:
- Go to Directory β Groups
- Click Add Group
- Create groups like:
- Name:
MCP Gateway Users
- Description:
Users with access to MCP Gateway
- Add appropriate users to these groups
Step 4: Configure MCP Gateway Environment¶
4.1 Update Environment Variables¶
Add these variables to your .env
file:
# Enable SSO System
SSO_ENABLED=true
# Okta OIDC Configuration
SSO_OKTA_ENABLED=true
SSO_OKTA_CLIENT_ID=0oa1b2c3d4e5f6g7h8i9
SSO_OKTA_CLIENT_SECRET=AbCdEfGhIjKlMnOpQrStUvWxYz1234567890abcdef
SSO_OKTA_ISSUER=https://dev-12345.okta.com
# 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
4.2 Example Production Configuration¶
# Production Okta SSO Setup
SSO_ENABLED=true
SSO_OKTA_ENABLED=true
SSO_OKTA_CLIENT_ID=0oa1b2c3d4e5f6g7h8i9
SSO_OKTA_CLIENT_SECRET=AbCdEfGhIjKlMnOpQrStUvWxYz1234567890abcdef
SSO_OKTA_ISSUER=https://acmecorp.okta.com
# 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_OKTA_SCOPE="openid profile email groups"
4.3 Development Configuration¶
# Development Okta SSO Setup
SSO_ENABLED=true
SSO_OKTA_ENABLED=true
SSO_OKTA_CLIENT_ID=0oa_dev_client_id
SSO_OKTA_CLIENT_SECRET=dev_client_secret
SSO_OKTA_ISSUER=https://dev-12345.oktapreview.com
# More permissive for testing
SSO_AUTO_CREATE_USERS=true
SSO_PRESERVE_ADMIN_AUTH=true
4.4 Advanced Configuration Options¶
# Custom OAuth scopes for enhanced user data
SSO_OKTA_SCOPE="openid profile email groups address phone"
# Group mapping for automatic team assignment
OKTA_GROUP_MAPPING={"MCP Gateway Admins": "admin-team-uuid", "MCP Gateway Users": "user-team-uuid"}
# Custom authorization server (if using custom Okta authorization server)
SSO_OKTA_ISSUER=https://dev-12345.okta.com/oauth2/custom-auth-server-id
Step 5: Restart and Verify Gateway¶
5.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
5.2 Verify Okta SSO is Enabled¶
Test that Okta appears in SSO providers:
# Check if Okta is listed
curl -X GET http://localhost:8000/auth/sso/providers
# Should return Okta in the list:
[
{
"id": "okta",
"name": "okta",
"display_name": "Okta"
}
]
Step 6: Test Okta SSO Login¶
6.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 Okta" button
6.2 Test Authentication Flow¶
- Click Continue with Okta
- You'll be redirected to Okta's sign-in page
- Enter your Okta credentials
- Complete any multi-factor authentication if required
- Grant consent for the application if prompted
- You'll be redirected back to the gateway admin panel
- You should be logged in successfully
6.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 Okta email in the user list
Step 7: Okta Advanced Features (Enterprise)¶
7.1 Multi-Factor Authentication (MFA)¶
Configure MFA policies in Okta:
- Go to Security β Multifactor
- Set up MFA policies for your MCP Gateway application
- Configure factors (SMS, Email, Okta Verify app, etc.)
- Users will be prompted for MFA during login
7.2 Adaptive Authentication¶
Configure risk-based authentication:
- Go to Security β Authentication β Sign On
- Create policies with conditions:
- Device trust
- Network location
- User risk level
- Time-based restrictions
7.3 Universal Directory Integration¶
Sync user attributes from external directories:
- Go to Directory β Directory Integrations
- Configure integration with:
- Active Directory
- LDAP
- HR systems (Workday, BambooHR, etc.)
- Map attributes for automatic user provisioning
7.4 API Access Management¶
For programmatic API access:
- Create a custom authorization server
- Configure API scopes and claims
- Issue API tokens for service-to-service authentication
Step 8: Production Deployment Checklist¶
8.1 Security Requirements¶
- HTTPS enforced for all redirect URIs
- Client secrets stored securely (vault/secret management)
- MFA policies configured appropriately
- Adaptive authentication policies set
- Password policies enforced
- Session management configured
8.2 Okta Configuration¶
- Application created with correct settings
- Appropriate users/groups assigned access
- Custom claims configured if needed
- Token lifetimes set appropriately
- Sign-out redirect URIs configured
8.3 Monitoring and Compliance¶
- System Log monitoring enabled
- Audit trail configured
- Compliance reporting set up (if required)
- Regular access reviews scheduled
Troubleshooting¶
Error: "SSO authentication is disabled"¶
Problem: SSO endpoints return 404 Solution: Set SSO_ENABLED=true
and restart gateway
Error: "invalid_client"¶
Problem: Wrong client ID or client secret Solution: Verify credentials from Okta application settings
# Double-check these values match your Okta application
SSO_OKTA_CLIENT_ID=your-actual-client-id
SSO_OKTA_CLIENT_SECRET=your-actual-client-secret
Error: "redirect_uri_mismatch"¶
Problem: Okta redirect URI doesn't match Solution: Verify exact URL match in Okta application settings
# Okta redirect URI must exactly match:
https://your-domain.com/auth/sso/callback/okta
# Common mistakes:
https://your-domain.com/auth/sso/callback/okta/ # Extra slash
http://your-domain.com/auth/sso/callback/okta # HTTP instead of HTTPS
https://your-domain.com/auth/sso/callback/oauth # Wrong provider ID
Error: "User is not assigned to the client application"¶
Problem: User doesn't have access to the application Solution: Assign user to the application
- In Okta admin console, go to Applications β [Your App]
- Go to Assignments tab
- Assign the user or their group to the application
Error: "The issuer specified in the request is invalid"¶
Problem: Wrong Okta domain or issuer URL Solution: Verify issuer URL matches your Okta domain
# Get the correct issuer from Okta's well-known configuration
curl https://[your-okta-domain].okta.com/.well-known/openid_configuration
# Use the "issuer" field value
MFA Bypass Issues¶
Problem: Users not prompted for MFA Solution: Check MFA policies and user enrollment
- Verify MFA policies are active for your application
- Check user MFA enrollment status
- Ensure policy conditions are met (device, location, etc.)
Token Validation Errors¶
Problem: JWT tokens failing validation Solution: Check token configuration and clock sync
- Verify token lifetime settings
- Check server clock synchronization
- Validate JWT signature verification
Testing Checklist¶
- Okta application integration created
- Client ID and secret configured
- Redirect URIs set correctly
- Users/groups assigned to application
- Environment variables configured
- Gateway restarted with new config
-
/auth/sso/providers
returns Okta provider - Login page shows "Continue with Okta" button
- Authentication flow completes successfully
- User appears in gateway user list
- MFA working (if configured)
- Group claims included in tokens (if configured)
Okta API Integration (Advanced)¶
Programmatic User Management¶
Use Okta APIs for advanced user management:
# Example: Sync Okta groups with Gateway teams
import requests
def sync_okta_groups():
okta_token = "your-okta-api-token"
okta_domain = "https://dev-12345.okta.com"
# Get user's groups from Okta
response = requests.get(
f"{okta_domain}/api/v1/users/{user_id}/groups",
headers={"Authorization": f"SSWS {okta_token}"}
)
groups = response.json()
return [group['profile']['name'] for group in groups]
Custom Authorization Server¶
For advanced API access patterns:
- Create custom authorization server in Okta
- Define custom scopes for MCP Gateway APIs
- Configure audience restrictions
- Use for service-to-service authentication
Next Steps¶
After Okta SSO is working:
- Configure MFA policies for enhanced security
- Set up adaptive authentication based on risk
- Integrate with existing directories (AD/LDAP)
- Configure custom user attributes and claims
- Set up automated user provisioning/deprovisioning
- Monitor authentication patterns for security insights
Related Documentation¶
- Complete SSO Guide - Full SSO documentation
- GitHub SSO Tutorial - GitHub setup guide
- Google SSO Tutorial - Google setup guide
- IBM Security Verify Tutorial - IBM setup guide
- Team Management - Managing teams and roles
- RBAC Configuration - Role-based access control
Support¶
If you encounter issues:
- Check Okta System Log for authentication errors
- Enable debug logging:
LOG_LEVEL=DEBUG
- Review gateway logs for Okta-specific errors
- Verify all Okta settings match tutorial exactly
- Use Okta's support resources and community forums