# Okta MCP Server (OAuth 2.1 Compliant)

An MCP (Model Context Protocol) server for Okta user management with full OAuth 2.1 compliance. This server provides tools for CRUD operations on Okta users and can be deployed to Railway or run locally with Docker.

## Features

- **create_user** - Create a new Okta user
- **list_users** - List users with optional search filtering
- **get_user** - Get user details by ID or login
- **update_user** - Update user profile information
- **delete_user** - Deactivate and delete a user
- **OAuth 2.1 Authentication** - Industry-standard security with PKCE, Bearer tokens, and token introspection

## Prerequisites

- Docker and Docker Compose
- Okta developer account with API access
- Okta OAuth 2.0 credentials (recommended) OR API token (legacy)

### Getting Okta OAuth 2.0 Credentials (Recommended)

1. Log in to your Okta Admin Console
2. Navigate to **Applications > Applications**
3. Click **Create App Integration**
4. Select **API Services** (for machine-to-machine communication)
5. Give it a name (e.g., "MCP Server")
6. Grant scopes: `okta.users.manage`, `okta.users.read`
7. Save the **Client ID** and **Client Secret**

### Alternative: Using API Token (Legacy)

1. Log in to your Okta Admin Console
2. Navigate to **Security > API > Tokens**
3. Click **Create Token**
4. Give it a name and copy the token value (you won't be able to see it again)

Note: OAuth 2.0 Client Credentials is recommended for better security and OAuth 2.1 compliance.

## Local Development

### 1. Configure Environment

```bash
# Copy the example environment file
cp .env.example .env

# Edit .env with your credentials
# Option 1: OAuth 2.0 Client Credentials (Recommended)
# OKTA_DOMAIN=dev-xxxxx.okta.com
# OKTA_CLIENT_ID=0oaxxxxxxxxx
# OKTA_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxx
# DEVELOPMENT_MODE=true  # For VSCode testing

# Option 2: Legacy API Token
# OKTA_DOMAIN=dev-xxxxx.okta.com
# OKTA_API_TOKEN=00xxxxxxxxxxxxxxxxxx
# DEVELOPMENT_MODE=true  # For VSCode testing
```

### 2. Build and Run with Docker

```bash
# Build and start the server
docker-compose up --build

# The server will be available at http://localhost:8000
```

### 3. Test the Server

```bash
# Check server health (no auth required)
curl http://localhost:8000/health

# Check OAuth 2.1 discovery endpoint
curl http://localhost:8000/.well-known/oauth-authorization-server

# Test MCP endpoint (requires OAuth 2.1 Bearer token)
# First, obtain an access token from Okta using OAuth 2.1 flow with PKCE
# Then use it to call the MCP endpoint:
curl -X POST http://localhost:8000/mcp \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0.0"}}}'
```

### 4. Test with MCP Inspector

```bash
npx @anthropic/mcp-inspector http://localhost:8000/mcp
```

## Railway Deployment

### 1. Push to GitHub

Push this repository to your GitHub account.

### 2. Deploy to Railway

1. Go to [Railway](https://railway.app)
2. Click **New Project** > **Deploy from GitHub repo**
3. Select your repository
4. Railway will auto-detect the Dockerfile

### 3. Configure Environment Variables

In Railway dashboard, add these environment variables:

#### Recommended: OAuth 2.0 Client Credentials
| Variable              | Description                                           |
| --------------------- | ----------------------------------------------------- |
| `OKTA_DOMAIN`         | Your Okta domain (e.g., `dev-12345.okta.com`)        |
| `OKTA_CLIENT_ID`      | OAuth 2.0 Client ID from Okta                         |
| `OKTA_CLIENT_SECRET`  | OAuth 2.0 Client Secret from Okta                     |
| `OKTA_AUDIENCE`       | OAuth 2.1 audience (optional, default: `api://default`) |

#### Alternative: Legacy API Token
| Variable         | Description                                           |
| ---------------- | ----------------------------------------------------- |
| `OKTA_DOMAIN`    | Your Okta domain (e.g., `dev-12345.okta.com`)        |
| `OKTA_API_TOKEN` | Your Okta API token                                   |
| `OKTA_AUDIENCE`  | OAuth 2.1 audience (optional, default: `api://default`) |

#### For VSCode Testing (Optional)
| Variable              | Description                                  |
| --------------------- | -------------------------------------------- |
| `DEVELOPMENT_MODE`    | Set to `true` to disable OAuth authentication |

Railway automatically provides the `PORT` variable.

### 4. Get Your Server URL

After deployment, Railway provides a public URL:

```
https://okta-mcp-server-003-production.up.railway.app
```

## Using with Claude Desktop

Add to your Claude Desktop MCP configuration (`claude_desktop_config.json`) with OAuth 2.1:

```json
{
  "mcpServers": {
    "okta": {
      "url": "https://okta-mcp-server-003-production.up.railway.app/mcp",
      "oauth": {
        "authorizationUrl": "https://YOUR-OKTA-DOMAIN/oauth2/default/v1/authorize",
        "tokenUrl": "https://YOUR-OKTA-DOMAIN/oauth2/default/v1/token",
        "clientId": "YOUR_OKTA_CLIENT_ID",
        "clientSecret": "YOUR_OKTA_CLIENT_SECRET",
        "scopes": ["openid", "profile", "mcp:read", "mcp:write"]
      }
    }
  }
}
```

For local development:

```json
{
  "mcpServers": {
    "okta": {
      "url": "http://localhost:8000/mcp",
      "oauth": {
        "authorizationUrl": "https://YOUR-OKTA-DOMAIN/oauth2/default/v1/authorize",
        "tokenUrl": "https://YOUR-OKTA-DOMAIN/oauth2/default/v1/token",
        "clientId": "YOUR_OKTA_CLIENT_ID",
        "clientSecret": "YOUR_OKTA_CLIENT_SECRET",
        "scopes": ["openid", "profile", "mcp:read", "mcp:write"]
      }
    }
  }
}
```

**Note**: OAuth 2.1 requires PKCE (Proof Key for Code Exchange) with S256 code challenge method. The client must support this requirement.

## Using with VSCode

VSCode's MCP client doesn't natively support OAuth 2.1 flows. For VSCode integration, enable **Development Mode**:

### Configuration

**1. Set environment variable:**
```bash
DEVELOPMENT_MODE=true
```

**2. Configure VSCode MCP (`.vscode/mcp.json`):**
```json
{
  "servers": {
    "okta-mcp": {
      "url": "http://localhost:8000/mcp",
      "type": "http"
    }
  }
}
```

⚠️ **Warning**: Only use development mode for local testing. Never enable in production!

For detailed VSCode setup instructions, see [VSCODE_INTEGRATION.md](./VSCODE_INTEGRATION.md).

## OAuth 2.1 Compliance

This server implements OAuth 2.1 security best practices:

### ✅ Security Features
- **PKCE Required**: S256 code challenge method mandatory for all authorization flows
- **Bearer Token Authentication**: Cryptographic JWT validation with RSA signatures
- **Token Validation**: Full verification of signature, expiration, issuer, and audience
- **No Deprecated Flows**: Implicit and password grants are not supported
- **Token Introspection**: RFC 7662 compliant endpoint at `/token/introspect`
- **Discovery Endpoints**: RFC 8414 compliant metadata at `/.well-known/oauth-authorization-server`

### 🔐 Authentication Flow
1. Client initiates authorization with PKCE (S256 code challenge)
2. User authenticates with Okta
3. Authorization code returned to client
4. Client exchanges code for access token (with code verifier)
5. Client uses Bearer token to access MCP endpoints
6. Server validates JWT signature, expiration, and claims

### 📋 Discovery Endpoints
- `/.well-known/oauth-authorization-server` - OAuth 2.1 server metadata
- `/.well-known/openid-configuration` - OpenID Connect discovery
- `/.well-known/oauth-protected-resource` - Protected resource metadata
- `/health` - Health check with OAuth 2.1 compliance info
- `/token/introspect` - Token introspection (RFC 7662)

For detailed information about OAuth 2.1 changes, see [OAUTH_2.1_CHANGES.md](./OAUTH_2.1_CHANGES.md).

## API Reference

### create_user

Create a new Okta user.

**Parameters:**

- `email` (required): User's email address
- `first_name` (required): User's first name
- `last_name` (required): User's last name
- `login` (optional): User's login (defaults to email)

### list_users

List users with optional filtering.

**Parameters:**

- `limit` (optional): Maximum users to return (default: 20)
- `search` (optional): Search query for filtering

### get_user

Get user by ID or login.

**Parameters:**

- `user_id` (required): User ID or login email

### update_user

Update user profile.

**Parameters:**

- `user_id` (required): User ID or login email
- `first_name` (optional): New first name
- `last_name` (optional): New last name
- `email` (optional): New email address

### delete_user

Deactivate and permanently delete a user.

**Parameters:**

- `user_id` (required): User ID or login email

## Project Structure

```
okta-mcp-server/
├── src/
│   └── okta_mcp_server/
│       ├── __init__.py
│       ├── server.py          # MCP server with tools
│       └── okta_client.py     # Okta API wrapper
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
├── requirements.txt
├── .env.example
└── README.md
```

## License

MIT