okta-auth-cli 0.1.1

Okta login toolkit with an interactive CLI and MCP session reuse

okta-auth

Alpha — this project is under active development and iterating quickly. APIs, tool signatures, and session formats may change between releases.

Okta login toolkit with two entry points:

• okta: interactive CLI for humans to log in and save a session locally
• okta-auth: MCP server for AI agents that reuse those sessions

CLI Usage

Run okta with no arguments to start an interactive login flow:

okta

You can also pass values directly:

okta https://portal.company.com --username [e-mail]

The login flow is headless by default. Pass --headed if you want to see the browser window.

Available commands:

• okta [url]: log in and save a session
• okta check <url>: verify a saved session
• okta list: list saved sessions
• okta delete <url>: delete a saved session
• okta cookies <url>: inspect stored cookies

MCP Tools

Tool	Description
okta_login	Authenticate to a target URL and store session state
okta_check_session	Verify whether a stored session is still valid
okta_list_sessions	List saved sessions and metadata
okta_delete_session	Remove a stored session
okta_get_cookies	Retrieve cookies from stored session (sensitive)

Sessions are stored under ~/.okta-auth/sessions/. Existing sessions under ~/.okta-auth-mcp/sessions/ are migrated automatically.

Security Model

• This project is intended for local trusted execution.
• Session files and cookies are sensitive credentials; protect the host account.
• Prefer private/internal usage unless security controls are reviewed.
• Never pass credentials as tool arguments — use environment variables so that AI agents never see your username, password, or TOTP secret in their context.

Credentials Setup

Environment Variables

Set credentials in your shell profile so they are inherited by the CLI or MCP server process.

# Add to ~/.zshrc or ~/.zprofile (zsh) / ~/.bashrc (bash)
export OKTA_USERNAME="[e-mail]"
export OKTA_PASSWORD="your-okta-password"
export OKTA_TOTP_SECRET="JBSWY3DPEHPK3PXP"  # only if MFA is enabled

After editing, reload your shell or open a new terminal, then restart the AI Agent.

The AI agent can then log in with just the URL:

okta_login(url="https://portal.company.com")

Explicit arguments still override environment variables if needed.

1Password CLI

op run injects secrets at process launch time. No plaintext credentials appear in shell profiles, config files, or environment variables — they live only in 1Password.

1. Store credentials in 1Password (one-time setup):

op item create --category login --title "Okta MCP" \
  username="[e-mail]" \
  password="your-okta-password" \
  totp_secret="JBSWY3DPEHPK3PXP"

2. Create a secrets reference file at ~/.okta-auth/.env (contains paths, not values):

OKTA_USERNAME=op://Personal/Okta MCP/username
OKTA_PASSWORD=op://Personal/Okta MCP/password
OKTA_TOTP_SECRET=op://Personal/Okta MCP/totp_secret

3. Update your MCP client config to wrap the server with op run:

Claude Code:

claude mcp add okta-auth -- op run --env-file=$HOME/.okta-auth/.env -- uvx --from okta-auth-cli okta-auth

Claude Desktop / Cursor / Windsurf:

{
  "mcpServers": {
    "okta-auth": {
      "command": "op",
      "args": ["run", "--env-file=/Users/yourname/.okta-auth/.env", "--", "uvx", "--from", "okta-auth-cli", "okta-auth"]
    }
  }
}

op run prompts for biometric/Touch ID once per session. Install 1Password CLI via brew install 1password-cli.

macOS Keychain

A built-in alternative that requires no extra tools. Credentials are stored in the system Keychain and fetched on each shell startup.

Store (one-time, run in terminal):

security add-generic-password -a okta-mcp -s OKTA_USERNAME    -w "[e-mail]"
security add-generic-password -a okta-mcp -s OKTA_PASSWORD    -w "your-okta-password"
security add-generic-password -a okta-mcp -s OKTA_TOTP_SECRET -w "JBSWY3DPEHPK3PXP"

Load in ~/.zshrc or ~/.zprofile:

export OKTA_USERNAME=$(security find-generic-password    -a okta-mcp -s OKTA_USERNAME    -w 2>/dev/null)
export OKTA_PASSWORD=$(security find-generic-password    -a okta-mcp -s OKTA_PASSWORD    -w 2>/dev/null)
export OKTA_TOTP_SECRET=$(security find-generic-password -a okta-mcp -s OKTA_TOTP_SECRET -w 2>/dev/null)

macOS may prompt for Keychain access on the first load after a reboot.

How to Get Your TOTP Secret Key

The TOTP secret is the Base32 key (16–32 uppercase letters and digits) that backs your authenticator app. You need to obtain it during the initial MFA enrollment — it cannot be retrieved from an already-configured authenticator app.

During Okta MFA setup

1. In Okta, go to Settings → Security Methods (or follow your admin's enrollment link).
2. Choose Google Authenticator as the factor type.
3. The QR code screen also shows a "Can't scan?" link — click it.
4. Copy the displayed text key (e.g. JBSWY3DPEHPK3PXP). This is your OKTA_TOTP_SECRET.
5. Finish enrollment by entering the 6-digit code from your authenticator app to confirm.

This project does not currently support portals that use only the Okta Verify app for MFA.

Already enrolled and lost the secret?

You must re-enroll the authenticator factor to obtain a new secret:

1. Go to Okta → Settings → Security Methods.
2. Remove the existing authenticator entry.
3. Re-add it and follow the steps above to capture the secret before scanning the QR code.

Installation

With uv tool

uv tool install okta-auth-cli
okta

With pipx

pipx install okta-auth-cli
okta

With pip

pip install okta-auth-cli
okta

Browser setup

The server uses Playwright for browser automation. It automatically detects and prefers your system Chrome/Edge — no extra download required if you already have one installed.

If no system browser is found, install the Playwright-bundled Chromium as fallback:

playwright install chromium

MCP Client Configuration

Claude Code

claude mcp add okta-auth -- uvx --from okta-auth-cli okta-auth

Claude Desktop / Cursor / Windsurf

{
  "mcpServers": {
    "okta-auth": {
      "command": "uvx",
      "args": ["--from", "okta-auth-cli", "okta-auth"]
    }
  }
}

Use okta for the interactive CLI. Use okta-auth only when wiring the package into an MCP client.

Development

uv venv && source .venv/bin/activate
uv pip install -e '.[dev]'
playwright install chromium

Run checks locally:

ruff format --check .
ruff check .
pytest