# Okta Workspace MCP

A Model Context Protocol (MCP) server for Okta identity management. Provides
AI assistants with secure, authenticated access to your Okta organization
through Browser Session or OIDC/OAuth authentication.

## Features

- **Browser Session mode** -- authenticate through your browser with full SSO
  and MFA support, then interact with Okta through the MCP
- **OIDC/OAuth mode** -- standard Authorization Code + PKCE flow for
  programmatic access
- **Identity context** -- `whoami`, `userinfo`, group membership, and app
  assignments
- **Organization tools** -- read-only access to users, groups, and applications
  (requires appropriate scopes)
- **Guided setup** -- interactive first-run configuration via MCP form
  elicitation

## Quick Start

### Install

```bash
git clone https://github.com/oreneHack/okta_mcp.git
cd okta_mcp
npm install
```

### Register in your MCP client

**Claude Code / VS Code:**

Add to your MCP settings:

```json
{
  "okta-workspace": {
    "type": "stdio",
    "command": "node",
    "args": ["path/to/okta_mcp/scripts/okta-mcp.mjs"]
  }
}
```

**Or install globally:**

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

Then register `okta-workspace-mcp` as a stdio MCP server in your client.

### Authenticate

Ask your AI assistant:

> "Connect to Okta" or "Start Okta MCP"

The guided setup collects your Okta org URL and authentication preference
(Browser Session or OIDC/OAuth). Subsequent launches reuse saved settings.

## Authentication Modes

### Browser Session

Opens an isolated browser window for authentication. Supports all Okta sign-on
policies including MFA, FastPass, and device trust. Session metadata is stored
locally with redacted cookie values.

Available tools after authentication:

| Tool | Description |
|------|-------------|
| `okta-browser-status` | Session state and activity |
| `okta-browser-snapshot` | Current page content (sanitized) |
| `okta-browser-navigate` | Navigate within your Okta org |
| `okta-browser-read` | Read Okta API endpoints (GET only) |

### OIDC/OAuth

Standard Authorization Code + PKCE flow. Requires a Native OIDC application
registered in your Okta org with a loopback redirect URI.

Recommended scopes:

| Scope | Purpose |
|-------|---------|
| `openid profile email` | Identity (minimum) |
| `offline_access` | Token refresh |
| `okta.users.read` | User directory access |
| `okta.groups.read` | Group directory access |
| `okta.apps.read` | Application inventory |

## Configuration

Configuration is stored under `~/.okta-workspace-mcp/`:

| File | Purpose |
|------|---------|
| `startup.json` | Selected mode and Okta org |
| `config.json` | Public OIDC client settings |
| `tokens.json` | Local OAuth token cache |

### Environment Variables

All settings can be provided via `okta-start` form elicitation. Environment
variables are optional overrides for managed or headless deployments.

| Variable | Description | Default |
|----------|-------------|---------|
| `OKTA_ORG_URL` | Okta org URL (`https://example.okta.com`) | Set via `okta-start` |
| `OKTA_CLIENT_ID` | OIDC application client ID | Set via `okta-start` |
| `OKTA_AUTH_SERVER` | Authorization server ID | `org` |
| `OKTA_SCOPES` | Space-delimited OAuth scopes | `openid profile email offline_access` |

See [.env.example](.env.example) for the full list.

## Available Tools

| Tool | Description |
|------|-------------|
| `okta-start` | Configure and authenticate |
| `okta-status` | Connection and authentication status |
| `okta-reset` | Clear saved configuration |
| `whoami` | Current user identity |
| `userinfo` | Detailed user profile |
| `token-details` | OAuth token metadata |
| `my-groups` | Group memberships |
| `my-apps` | Assigned applications |
| `list-users` | Organization user directory |
| `get-user` | Single user lookup |
| `search-users` | User search |
| `list-groups` | Organization groups |
| `list-apps` | Organization applications |

## Security

See [SECURITY.md](SECURITY.md) for data handling policies and recommended
hardening steps.

- Cookie values are redacted in all MCP tool responses
- OAuth tokens are cached locally and never exposed in tool output
- Browser Session uses an isolated temporary profile
- Metadata service binds to `127.0.0.1` only

## Requirements

- Node.js 20+
- Chrome or Microsoft Edge (Browser Session mode)
- Okta organization (any edition, including free developer orgs)

## License

[MIT](LICENSE)