🔐 Okta MCP Server for Entitlement Management

Talk to Okta IGA like you talk to a coworker. Import access data, discover patterns, and create entitlement bundles—all through natural conversation.

---

⚠️ Disclaimer: Vibe Coded

This project was "vibe coded"—built rapidly through AI-assisted development with Claude/Copilot. While functional and tested against real Okta tenants, it:

• May contain unconventional patterns or edge cases not fully handled
• Has not undergone formal security review
• Is provided as-is for experimentation and learning
• Should be tested thoroughly in a sandbox environment before any production use

Use at your own risk. Always validate operations in a non-production Okta tenant first.

---

🤔 The Opportunity

Okta Identity Governance (IGA) gives you powerful tools to manage entitlements, grants, and access bundles. This MCP server helps you get value from those features faster by automating the setup work:

Instead of...	You can say...
Manually creating entitlements from a CSV export	"Import the HR system access from that CSV"
Analyzing access patterns to define bundles	"Find patterns and suggest bundles"
Granting access to users one by one	"Grant these permissions to all 500 users"

The goal: Spend less time on data entry, more time on governance strategy.

💡 How It Works

This MCP server lets you describe what you want in plain English, and the AI handles the Okta API calls:

You: "Import the HR system access from that CSV into Okta"
AI:  ✅ Analyzed CSV: 3 entitlement types, 847 users
     ✅ Created entitlements in app 0oa123abc
     ✅ Granted access to 847 users (23 already had access)

You: "Find patterns in who has what access and suggest bundles"
AI:  Found 12 patterns:
     🟢 Engineering dept → always gets Developer role (94% match)
     🟢 Managers → always get Approval permission (89% match)
     Want me to create these as bundles?

---

🎯 What This Does

Capability	Description
CSV → Okta Import	Parse access reports, create entitlement structures, grant to users in bulk
Governance Scorecard	Score applications 0-100 on governance posture with compliance mapping
SoD Enforcement	Detect toxic combinations and create separation of duties risk rules
Pattern Mining	Analyze existing grants to discover who-gets-what patterns
SoD-Safe Bundles	Turn patterns into IGA bundles with automatic conflict checking
Bulk Operations	Parallel API calls with automatic rate limiting
Natural Language	No API knowledge needed—just describe what you want

---

📊 Four Guided Workflows

Workflow 1: Migrate Legacy Access (CSV → Okta)

Use case: You have a CSV export from a legacy system and need to get it into Okta IGA

list_csv_files  →  analyze_csv_for_entitlements  →  prepare_entitlement_structure  →  execute_user_grants
      │                      │                               │                              │
      ▼                      ▼                               ▼                              ▼
 See available         Parse & validate              Create entitlements            Assign users &
  CSV files               the data                    in Okta app                   grant access

Workflow 2: Governance Scorecard

Use case: Assess an application's governance posture with a compliance report

generate_governance_summary(appId)
            │
            ▼
   Score 0-100 + letter grade
   Compliance checks (NIST AC-5, SOX 404, SOC2)
   Prioritized recommendations

Workflow 3: Enforce Compliance (SoD Rules)

Use case: Find toxic access combinations and create separation of duties rules

analyze_sod_context  →  create_sod_risk_rule  →  test_sod_risk_rule
         │                       │                        │
         ▼                       ▼                        ▼
  Map entitlements to      Create enforcement      Validate rules
  ISACA duty categories    rules in Okta           against users

Workflow 4: Discover & Create Roles (Pattern Mining → Bundles)

Use case: You have existing access in Okta and want to create SoD-safe bundles

analyze_entitlement_patterns  →  preview_bundle_creation  →  create_bundle_from_pattern
            │                             │                            │
            ▼                             ▼                            ▼
    Discover correlations          See what would be           SoD conflict check
    between profiles &             created (dry run)            + create bundle
      entitlements

---

📁 Project Structure

okta-mcp-em-python/
├── server.py               # MCP server entry point
├── client.py               # Okta API client with rate limiting
├── batch.py                # Parallel execution engine
├── s3_client.py            # AWS S3 integration (optional)
├── tools/
│   ├── __init__.py
│   ├── api.py              # Okta API tools
│   ├── basic.py            # CSV & connection tools
│   ├── batch.py            # Batch operation tools
│   ├── workflow.py         # CSV import workflow tools
│   ├── bundle.py           # Pattern mining & bundle creation (SoD-safe)
│   ├── sod.py              # Separation of duties analysis & risk rules
│   ├── governance.py       # Governance scorecard & posture reporting
│   ├── app_knowledge.py    # Application-specific SoD knowledge base
│   └── menu.py             # Guided workflow navigation
├── csv/                    # CSV files for processing
│   ├── test_data/          # Sample CSV files
│   ├── processed/          # Completed files
│   ├── processed_and_assigned/
│   └── analysis_cache/     # Cached pattern analysis results
├── .env                    # Environment variables (create this)
├── requirements.txt
└── pyproject.toml

---

📋 Prerequisites

Requirement	Details
Python	3.10 or higher
Okta Tenant	Workforce Identity Cloud with IGA enabled
API Token	Okta API token with appropriate permissions
MCP Client	Claude Desktop, VS Code with Copilot, or any MCP-compatible client

---

🚀 Quick Start

Step 1: Clone & Setup

# Clone the repository
git clone https://github.com/ashwinramn/okta-mcp-em-python.git
cd okta-mcp-em-python

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Step 2: Configure Environment

Create a .env file in the project root:

# Required: Okta Configuration
OKTA_DOMAIN=your-domain.okta.com
OKTA_API_TOKEN=your-api-token

# Optional: S3 for remote CSV storage
S3_ENABLED=false
S3_BUCKET_NAME=your-bucket-name
S3_PREFIX=csv-files/
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key

Step 3: Configure Your MCP Client

<details> <summary><strong>Claude Desktop</strong></summary>

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "okta-entitlements": {
      "command": "python3",
      "args": ["/full/path/to/okta-mcp-em-python/server.py"]
    }
  }
}

</details>

<details> <summary><strong>VS Code with GitHub Copilot</strong></summary>

Add to your VS Code MCP settings or settings.json:

{
  "mcp.servers": {
    "okta-entitlements": {
      "command": "python3",
      "args": ["/full/path/to/okta-mcp-em-python/server.py"]
    }
  }
}

</details>

Step 4: Test the Connection

Restart your MCP client, then ask:

"Check my Okta connection"

You should see a success message with your Okta org details.

---

🛠️ Available Tools

🧭 Navigation

Tool	Description
okta_test	Verify Okta API connectivity
show_workflow_menu	Display guided workflow menu

📥 CSV Import Workflow

Tool	Description
list_csv_files	List available CSV files (local + S3)
analyze_csv_for_entitlements	Analyze CSV structure and identify entitlements
prepare_entitlement_structure	Create/update entitlements in Okta app
execute_user_grants	Grant entitlements to users in bulk

📊 Governance & Compliance

Tool	Description
generate_governance_summary	Full governance posture report with score and compliance checks
analyze_sod_context	Gather SoD analysis context for an application
create_sod_risk_rule	Create separation of duties risk rules
list_sod_risk_rules	List existing SoD risk rules
test_sod_risk_rule	Run risk assessment for a user

📦 Bundle Mining Workflow

Tool	Description
analyze_entitlement_patterns	Discover patterns between user profiles and entitlements
preview_bundle_creation	Preview bundle before creation (dry run)
create_bundle_from_pattern	Create entitlement bundle from a pattern (SoD-safe)
create_entitlement_bundle	Create bundle directly from entitlement value names

⚙️ Utility Tools

Tool	Description
okta_user_search	Search users by various criteria
okta_batch_user_search	Search multiple users in parallel
okta_batch_create_grants	Create multiple grants in parallel
okta_get_rate_status	Check Okta API rate limits
get_entitlement_ids_for_values	Resolve entitlement value names to IDs

---

💬 Example Conversations

Example 1: CSV Import Workflow

You: "Check my Okta connection"
AI:  ✅ Connected to your-domain.okta.com
     Call show_workflow_menu to see available workflows.

You: "Show me the workflow menu"
AI:  ┌─────────────────────────────────────────┐
     │  1. Import CSV → Okta                   │
     │  2. Mine Patterns → Bundles             │
     └─────────────────────────────────────────┘

You: "1"
AI:  📁 Available CSV files:
     1. hr_platform_access_report.csv
     2. finance_core_access_report.csv
     3. dev_platform_access_report.csv

You: "Analyze hr_platform_access_report.csv"
AI:  📊 Analysis Complete
     ├── Rows: 847
     ├── User column: Email
     └── Entitlements detected:
         • Role (15 unique values)
         • Permission (8 unique values)
         • Support_Group (4 unique values)
     
     Ready to import? Provide the Okta App ID.

You: "Yes, app ID is 0oa123abc"
AI:  ✅ Created entitlement structure in app 0oa123abc
     ├── Role: 15 values created
     ├── Permission: 8 values created
     └── Support_Group: 4 values created

You: "Now grant the permissions to users"
AI:  🚀 Processing 847 users...
     ✅ Complete!
     ├── Users processed: 847
     ├── New assignments: 824
     ├── Already assigned: 23
     └── Grants created: 2,541

Example 2: Bundle Mining Workflow

You: "2"
AI:  Enter the Okta App ID to analyze for patterns.

You: "0oa123abc"
AI:  🔍 Analyzing entitlement patterns...
     
     Found 24 patterns across 3 entitlement types:
     
     🟢 STRONG (>85% correlation)
     1. department=Engineering → Role: Developer (94%)
     2. department=Finance → Role: Analyst (91%)
     3. title contains "Manager" → Permission: Approve (89%)
     
     🟡 MODERATE (70-85% correlation)
     4. department=Support → Support_Group: Tier1 (78%)
     5. location=HQ → Permission: Building_Access (72%)

You: "Preview pattern 1"
AI:  📦 Bundle Preview (Dry Run)
     ├── Name: Engineering Access Bundle
     ├── Description: Standard access for Engineering department
     │   members including developer tools and deployment
     │   permissions.
     └── Entitlements:
         • Role = Developer
         • Permission = Deploy
         • Permission = Code_Review

You: "Create it"
AI:  ✅ Bundle created successfully!
     └── Bundle ID: enb789xyz

---

✨ Key Features

Feature	Description
Guided Workflows	Step-by-step navigation—just follow the prompts
Governance Scorecard	Score 0-100 with compliance checks (NIST AC-5, SOX 404, SOC2)
SoD Enforcement	Detect toxic access combinations and create risk rules (ISACA-based)
SoD-Safe Bundles	Bundle creation with automatic separation of duties conflict checks
Pattern Mining	ML-free pattern discovery using correlation analysis
Natural Language Bundles	Auto-generated descriptions for business users
Smart Rate Limiting	Automatic throttling to respect Okta API limits
Concurrent Processing	Parallel batch operations (up to 10x faster)
Flexible CSV Parsing	Handles messy data, various formats, encoding issues
S3 Integration	Optionally pull CSV files from AWS S3 (using boto3)
Analysis Caching	Pattern results cached for quick bundle creation

---

📝 CSV Format

The server handles various CSV formats flexibly. Minimum requirements:

Required	Description
User identifier column	Email, username, login, employee ID, etc.
Entitlement columns	Role, Permission, Group, Access Level, etc.

Example CSV

Email,Department,Title,Role,Permission,Support_Group
john.doe@company.com,Engineering,Developer,Admin,Deploy,Tier2
jane.smith@company.com,Finance,Analyst,Viewer,Read,Tier1
bob.wilson@company.com,Engineering,Manager,Admin,Approve,Tier2

The AI will automatically:

• Detect which column contains user identifiers
• Identify which columns represent entitlements vs. profile attributes
• Handle missing values, duplicates, and encoding issues

---

🐛 Troubleshooting

Test the server manually

python3 server.py

Common Issues

Issue	Solution
Connection failed	Verify OKTA_DOMAIN and OKTA_API_TOKEN in .env
Rate limited	Wait a few minutes, or check okta_get_rate_status
Users not found	Ensure CSV user identifiers match Okta login format
No patterns found	App needs existing grants with entitlements to analyze
Module not found	Run pip install -r requirements.txt in virtual env

Debug Mode

For verbose logging, set in your environment:

export LOG_LEVEL=DEBUG

---

🔗 Related Resources

• Okta IGA Documentation
• Model Context Protocol
• MCP Python SDK

---

📄 License

MIT License - See LICENSE for details.

---

🤝 Contributing

Contributions welcome! This is a vibe-coded project, so:

1. Issues - Report bugs or suggest features
2. PRs - Improvements to error handling, edge cases, and documentation are especially welcome
3. Testing - More real-world testing against different Okta configurations

---

<p align="center"> <em>Built with 🤖 + ☕ by <a href="https://github.com/ashwinramn">@ashwinramn</a></em> </p>