okta-mcp-server/README.md

Model Context Protocol (MCP) server for Okta API operations with support for bulk operations and caching

# Okta MCP Server

Model Context Protocol (MCP) server for Okta API operations. Provides identity and access management capabilities to LLMs through a standardized interface.

[![npm version](https://img.shields.io/npm/v/okta-mcp-server.svg)](https://www.npmjs.com/package/okta-mcp-server)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)

## ⚠️ CRITICAL PRODUCTION SAFETY WARNING

**🚨 USE WITH EXTREME CAUTION IN PRODUCTION ENVIRONMENTS 🚨**

This MCP server provides **FULL ADMINISTRATIVE ACCESS** to your Okta organization, including the ability to:
- **CREATE, MODIFY, AND DELETE USERS** (including administrators)
- **MODIFY GROUP MEMBERSHIPS** (including security groups)
- **CREATE AND MODIFY APPLICATIONS** (including SSO configurations)
- **CHANGE SECURITY POLICIES** (including MFA and password policies)
- **PERFORM BULK OPERATIONS** (affecting thousands of users at once)

### 🔒 STRONGLY RECOMMENDED: Use Read-Only Mode in Production

For production environments, **always enable read-only mode**:

```bash
# Claude Code (RECOMMENDED for production)
claude mcp add okta npx okta-mcp-server \
  -e OKTA_DOMAIN=your-domain.okta.com \
  -e OKTA_API_TOKEN=your-api-token \
  -e READ_ONLY_MODE=true
```

```json
// Claude Desktop (RECOMMENDED for production)
{
  "mcpServers": {
    "okta": {
      "command": "npx",
      "args": ["okta-mcp-server"],
      "env": {
        "OKTA_DOMAIN": "your-domain.okta.com",
        "OKTA_API_TOKEN": "your-api-token",
        "READ_ONLY_MODE": "true"
      }
    }
  }
}
```

Read-only mode blocks all write operations while allowing:
- ✅ User and group queries
- ✅ Application and policy inspection  
- ✅ Audit log analysis
- ✅ Data exports and reporting
- ✅ Compliance reporting

### 🛡️ Production Safety Guidelines

1. **Use read-only mode by default** - Only disable for specific, controlled operations
2. **Limit API token permissions** - Use principle of least privilege
3. **Monitor all operations** - Review audit logs regularly
4. **Test in development first** - Never run untested operations in production
5. **Have rollback procedures** - Know how to quickly reverse changes
6. **Use version control** - Track all configuration changes

### 🚫 NOT RECOMMENDED for Production (Without Read-Only Mode)

Direct write access in production can lead to:
- Accidental user lockouts (including your own)
- Unintended security policy changes
- Mass user modifications or deletions
- Application configuration corruption
- Compliance violations

## Features

### Core Capabilities
- **User Management**: Create, read, update, delete, and search users with advanced filtering
- **Group Management**: Full group lifecycle management including member operations
- **Application Management**: Manage SAML, OIDC, and other application integrations
- **Policy Management**: Configure and manage authentication, authorization, and MFA policies
- **Bulk Operations**: Process thousands of users efficiently with CSV/JSON import/export
- **Audit Logging**: Comprehensive audit trail with compliance reporting (SOC2, HIPAA, GDPR)

### Technical Features
- **Simple Configuration**: Just provide your Okta domain and API token
- **High Performance**: Memory/SQLite caching and optimized pagination
- **Rate Limiting**: Automatic rate limiting to comply with Okta API limits
- **Error Handling**: Comprehensive error handling with detailed error messages
- **Type Safety**: Full TypeScript implementation with strict typing
- **Streaming Support**: Async generators for handling large datasets

## Installation

```bash
npm install -g okta-mcp-server
```

## Quick Start

### Option 1: Claude Code (Recommended)

#### Production Setup (Read-Only Mode - RECOMMENDED)
1. Get an Okta API token from your Okta admin console
2. Add the MCP server with read-only mode for safety:

```bash
claude mcp add okta npx okta-mcp-server \
  -e OKTA_DOMAIN=your-domain.okta.com \
  -e OKTA_API_TOKEN=your-api-token \
  -e READ_ONLY_MODE=true
```

#### Development Setup (Full Access)
For development/testing environments only:

```bash
claude mcp add okta npx okta-mcp-server \
  -e OKTA_DOMAIN=your-domain.okta.com \
  -e OKTA_API_TOKEN=your-api-token
```

3. You're done! The server is now available in Claude Code.

### Option 2: Claude Desktop

#### Production Setup (Read-Only Mode - RECOMMENDED)
1. Get an Okta API token from your Okta admin console
2. Configure Claude Desktop with read-only mode:

```json
{
  "mcpServers": {
    "okta": {
      "command": "npx",
      "args": ["okta-mcp-server"],
      "env": {
        "OKTA_DOMAIN": "your-domain.okta.com",
        "OKTA_API_TOKEN": "your-api-token",
        "READ_ONLY_MODE": "true"
      }
    }
  }
}
```

#### Development Setup (Full Access)
For development/testing environments only:

```json
{
  "mcpServers": {
    "okta": {
      "command": "npx",
      "args": ["okta-mcp-server"],
      "env": {
        "OKTA_DOMAIN": "your-domain.okta.com",
        "OKTA_API_TOKEN": "your-api-token"
      }
    }
  }
}
```

3. Restart Claude Desktop - you're done!

### Quick Start Examples

Try these commands immediately after setup:

```
"Show me my Okta domain statistics"
"List the first 10 users in my organization"
"What groups exist in my Okta instance?"
"Show me users who logged in today"
"Find inactive users from the last 30 days"
```

#### Verify Read-Only Mode (Production Safety Check)

```
"What is the current read-only mode status?"
"Show me which operations are allowed and blocked"
```

If read-only mode is enabled, you'll see a clear message about which operations are available.

### Option 3: OAuth Protection (Advanced)

#### Claude Code with OAuth
```bash
# Add server with OAuth protection
claude mcp add okta npx okta-mcp-server \
  -e OKTA_DOMAIN=your-domain.okta.com \
  -e OKTA_API_TOKEN=your-api-token \
  -e MCP_AUTH_REQUIRED=true \
  -e MCP_AUTH_AUDIENCE=https://okta-mcp-server \
  -e MCP_AUTH_ISSUER=https://auth.example.com
```

#### Claude Desktop with OAuth
Protect your MCP server with OAuth so Claude must authenticate before using it:

```json
{
  "mcpServers": {
    "okta": {
      "command": "npx",
      "args": ["okta-mcp-server"],
      "env": {
        "OKTA_DOMAIN": "your-domain.okta.com",
        "OKTA_API_TOKEN": "your-api-token",
        "MCP_AUTH_REQUIRED": "true",
        "MCP_AUTH_AUDIENCE": "https://okta-mcp-server",
        "MCP_AUTH_ISSUER": "https://auth.example.com"
      },
      "oauth": {
        "authorization_url": "https://auth.example.com/authorize",
        "token_url": "https://auth.example.com/oauth/token",
        "client_id": "your-oauth-client-id",
        "scopes": ["read:okta", "write:okta"]
      }
    }
  }
}
```

## Environment Variables

### Required
| Variable | Description |
|----------|-------------|
| `OKTA_DOMAIN` | Your Okta domain (e.g., `your-domain.okta.com`) |
| `OKTA_API_TOKEN` | Your Okta API token |

### Production Safety (STRONGLY RECOMMENDED)
| Variable | Description | Default |
|----------|-------------|---------|
| `READ_ONLY_MODE` | **Enable read-only mode to prevent write operations** | `false` |

### Optional - MCP OAuth Protection
| Variable | Description | Default |
|----------|-------------|---------|
| `MCP_AUTH_REQUIRED` | Enable OAuth protection for MCP server | `false` |
| `MCP_AUTH_AUDIENCE` | Expected audience in JWT tokens | - |
| `MCP_AUTH_ISSUER` | Expected issuer of JWT tokens | - |

### Optional - Performance
| Variable | Description | Default |
|----------|-------------|---------|
| `CACHE_ENABLED` | Enable caching | `true` |
| `CACHE_TYPE` | Cache type (`memory` or `sqlite`) | `memory` |
| `CACHE_TTL` | Cache TTL in seconds | `300` |
| `CACHE_MAX_SIZE` | Maximum cache entries | `1000` |

### Optional - Other
| Variable | Description | Default |
|----------|-------------|---------|
| `LOG_LEVEL` | Logging level (`debug`, `info`, `warn`, `error`) | `info` |
| `USE_MOCK_OKTA` | Use mock Okta client for testing | `false` |

## Claude Code Specific Features

### MCP Resource References
Use `@` mentions to reference MCP resources directly:

```
@okta://users?status=ACTIVE  # Reference active users
@okta://groups               # Reference all groups  
@okta://audit-logs?since=2024-01-01  # Reference recent audit logs
```

### Slash Commands
If your server provides MCP prompts, use them as slash commands:

```
/okta-security-audit        # Run security audit prompt
/okta-user-cleanup         # Run user cleanup prompt
```

### Server Management
```bash
# Check server status
/mcp

# Add server with different scopes
claude mcp add okta npx okta-mcp-server --scope project  # Share with team
claude mcp add okta npx okta-mcp-server --scope user     # Available across projects

# Remove server
claude mcp remove okta
```

## Example Usage in Claude Code

Once you've added the Okta MCP server, here are some powerful things you can ask Claude to do:

### 🔍 User Discovery & Analysis
```
"Show me all users who haven't logged in for 90 days"
"Find users without MFA enabled and create a report"
"List all admin users and their last activity"
"Which users have access to our production apps?"
"Find duplicate user accounts by email domain"
```

### 👥 User Management Automation
```
"Create 50 test users for our QA environment with usernames like qa-user-001"
"Disable all users who haven't logged in since January"
"Add all users from the Engineering department to the GitHub-Users group"
"Reset passwords for all users in the compromised-users.csv file"
"Update all user profiles to include their department from this CSV"
```

### 🛡️ Security & Compliance
```
"Generate a SOC2 compliance report for user access changes this month"
"Show me all privileged access grants in the last 7 days"
"Find all users with admin roles and verify they have MFA"
"Create an audit report of all user deletions this quarter"
"Which service accounts have excessive permissions?"
```

### 📊 Bulk Operations
```
"Export all users to a CSV with their group memberships"
"Import these 500 new employees from this CSV file and assign to onboarding group"
"Migrate all users from @oldcompany.com to @newcompany.com email addresses"
"Bulk update user departments based on this mapping file"
"Remove all users in the contractors group who haven't logged in for 30 days"
```

### 🔧 Application & Policy Management
```
"Show me all SAML applications and their user counts"
"Which applications have the most inactive users?"
"Create a new password policy requiring 12 characters and MFA"
"List all policies that don't enforce MFA"
"Find applications without any assigned users"
```

### 📈 Analytics & Reporting
```
"Create a dashboard of user growth over the last 6 months"
"Show me login patterns by hour of day and day of week"
"Which departments have the highest MFA adoption?"
"Generate a report of all API tokens and their last usage"
"Analyze group membership overlap between Engineering and DevOps"
```

### 🚨 Incident Response
```
"Immediately disable all users who logged in from these suspicious IPs"
"Find and suspend all accounts created in the last hour"
"List all users who had password resets today"
"Show me all admin actions performed by user@company.com"
"Revoke all sessions for users in the security-incident group"
```

### 🤖 Automation Workflows
```
"Every Friday, send me a report of users added this week"
"Create a cleanup list of users to be deactivated next month"
"Set up monitoring for any new admin role assignments"
"Generate onboarding tasks for all users created today"
"Check for users with conflicting group memberships"
```

## Available Tools

### User Management
- `listUsers` - List users with pagination and filtering
- `getUser` - Get a single user by ID or login
- `createUser` - Create a new user
- `updateUser` - Update user profile
- `deleteUser` - Deactivate or delete a user
- `getUserGroups` - Get groups for a user

### Group Management
- `listGroups` - List groups with pagination
- `getGroup` - Get a single group
- `createGroup` - Create a new group
- `updateGroup` - Update group profile
- `deleteGroup` - Delete a group
- `listGroupMembers` - List members of a group
- `addGroupMember` - Add user to group
- `removeGroupMember` - Remove user from group

### Application Management
- `listApps` - List applications
- `getApp` - Get application details
- `createApp` - Create new application
- `updateApp` - Update application
- `deleteApp` - Delete application
- `assignUserToApp` - Assign user to app
- `assignGroupToApp` - Assign group to app

### Policy Management
- `listPolicies` - List policies by type
- `getPolicy` - Get policy details
- `createPasswordPolicy` - Create password policy
- `createSignOnPolicy` - Create sign-on policy
- `createMfaPolicy` - Create MFA policy
- `updatePolicy` - Update policy
- `deletePolicy` - Delete policy

### Bulk Operations
- `bulkCreateUsers` - Create multiple users from CSV/JSON
- `bulkUpdateUsers` - Update multiple users
- `bulkDeleteUsers` - Delete multiple users
- `exportUsers` - Export users to CSV/JSON

### Audit & Compliance
- `queryAuditLogs` - Query audit logs with filters
- `getAuditStatistics` - Get audit statistics
- `exportAuditLogs` - Export audit logs
- `generateComplianceReport` - Generate compliance reports

### System Management
- `getReadOnlyStatus` - Check read-only mode status and show allowed/blocked operations

## Example Usage in Claude

```
Human: List all active users in Okta

Assistant: I'll help you list all active users in your Okta organization. Let me query the Okta API for you.

[Uses listUsers tool with filter "status eq \"ACTIVE\""]

I found 247 active users in your Okta organization. Here's a summary of the first few users:

1. **John Smith** (john.smith@company.com)
   - Department: Engineering
   - Created: 2024-01-15
   - Last login: 2024-03-20

2. **Jane Doe** (jane.doe@company.com)
   - Department: Sales
   - Created: 2024-02-01
   - Last login: 2024-03-19

[... more users ...]

Would you like me to:
- Export the full list to CSV?
- Filter by a specific department?
- Show users who haven't logged in recently?
```

## Security

- API tokens are never exposed in logs or error messages
- All sensitive data is automatically masked in audit logs
- Supports encryption for cached data
- Rate limiting prevents API abuse
- Circuit breaker pattern for reliability

## Troubleshooting

### Common Issues

1. **"OKTA_API_TOKEN must be provided"**
   - Ensure you've set the `OKTA_API_TOKEN` environment variable
   - Check that your API token has the necessary permissions

2. **"Invalid domain"**
   - Use just the domain part: `your-domain.okta.com` (not `https://your-domain.okta.com`)

3. **Rate limiting errors**
   - The server automatically handles rate limits with exponential backoff
   - For bulk operations, consider using the batch endpoints

## Development

```bash
# Clone the repository
git clone https://github.com/yourusername/okta-mcp-server.git
cd okta-mcp-server

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run in development mode
npm run dev
```

## Migration from v1.x

Version 2.0 is a major simplification:

1. **Removed OAuth client implementation** - The server no longer tries to authenticate TO Okta using OAuth
2. **Simplified to API token only** - Just provide your Okta API token
3. **Optional MCP OAuth protection** - Let Claude handle the OAuth flow if you want to protect your MCP server
4. **Removed unnecessary dependencies** - Smaller, faster, more reliable

### Migration Steps

#### For Claude Code Users
1. Remove the old server: `claude mcp remove okta`
2. Update to v2.0: `npm update -g okta-mcp-server`
3. Re-add with simplified config:
   ```bash
   claude mcp add okta npx okta-mcp-server \
     -e OKTA_DOMAIN=your-domain.okta.com \
     -e OKTA_API_TOKEN=your-api-token
   ```

#### For Claude Desktop Users
1. Update to v2.0: `npm update okta-mcp-server`
2. Simplify your configuration to just `OKTA_DOMAIN` and `OKTA_API_TOKEN`
3. Remove any OAuth client configuration (CLIENT_ID, CLIENT_SECRET, etc.)
4. Restart Claude Desktop

## Contributing

Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.

## License

Apache-2.0 - see [LICENSE](LICENSE) for details.