okta-auth-cli 0.1.1__tar.gz

okta_auth_cli-0.1.1/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @bunizao

okta_auth_cli-0.1.1/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,23 @@
+---
+name: Bug report
+about: Report an issue in okta-auth-mcp
+labels: bug
+---
+
+## Description
+
+## Steps to Reproduce
+
+1. 
+2. 
+3. 
+
+## Expected Behavior
+
+## Actual Behavior
+
+## Environment
+
+- OS:
+- Python version:
+- Package version:

okta_auth_cli-0.1.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security report
+    url: https://github.com/bunizao/okta-auth-mcp/security/advisories/new
+    about: Please report security issues privately.

okta_auth_cli-0.1.1/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,13 @@
+---
+name: Feature request
+about: Propose an enhancement
+labels: enhancement
+---
+
+## Problem
+
+## Proposed Solution
+
+## Alternatives Considered
+
+## Additional Context

okta_auth_cli-0.1.1/.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5

okta_auth_cli-0.1.1/.github/pull_request_template.md

@@ -0,0 +1,14 @@
+## Summary
+
+- 
+
+## Validation
+
+- [ ] `ruff format --check .`
+- [ ] `ruff check .`
+- [ ] `pytest`
+
+## Security
+
+- [ ] No secrets/session artifacts were added to the repo
+- [ ] Changes to auth/session paths considered threat model

okta_auth_cli-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main, master]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install -U pip
+          pip install -e .[dev]
+
+      - name: Ruff format check
+        run: ruff format --check .
+
+      - name: Ruff lint
+        run: ruff check .
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install -U pip
+          pip install -e .[dev]
+
+      - name: Run tests
+        run: pytest

okta_auth_cli-0.1.1/.github/workflows/dependency-review.yml

@@ -0,0 +1,15 @@
+name: Dependency Review
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  dependency-review:
+    if: ${{ !github.event.repository.private }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Dependency review
+        uses: actions/dependency-review-action@v4

okta_auth_cli-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,50 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Build artifacts
+        run: |
+          python -m pip install -U pip build twine
+          python -m build
+          twine check dist/*
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

okta_auth_cli-0.1.1/.gitignore

@@ -0,0 +1,22 @@
+# macOS
+.DS_Store
+
+# Python caches
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual environments
+.venv/
+venv/
+
+# Tool caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+

okta_auth_cli-0.1.1/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.13.2
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

okta_auth_cli-0.1.1/AGENTS.md

@@ -0,0 +1,61 @@
+# AGENTS.md
+
+This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
+
+## Project Overview
+
+okta-auth is an Okta login toolkit with an interactive CLI and an MCP server for session reuse. It uses Playwright to automate Okta SSO and persists per-domain session state for reuse by AI agents.
+
+## Commands
+
+```bash
+# Setup
+uv venv && source .venv/bin/activate
+uv pip install -e '.[dev]'
+playwright install chromium
+
+# Quality gates (run all three before submitting)
+ruff format --check .
+ruff check .
+pytest
+
+# Run single test
+pytest tests/test_session_store.py -v
+
+# Run interactive CLI
+okta
+
+# Run MCP server (stdio transport, stdout is JSON-RPC)
+okta-auth
+```
+
+## Architecture
+
+```
+src/okta_auth/
+├── server.py          # FastMCP entry point, defines all 5 MCP tools
+├── log.py             # Stderr-only logging (stdout reserved for JSON-RPC)
+├── auth/
+│   ├── login.py       # auto_login() engine: selector-based form filling, portal detection, MFA/TOTP
+│   ├── session_store.py  # Per-domain session CRUD at ~/.okta-auth/sessions/
+│   └── totp.py        # pyotp wrapper for TOTP code generation
+└── browser/
+    ├── controller.py  # BrowserController async context manager, BrowserConfig dataclass
+    ├── detection.py   # Cross-platform browser executable discovery with env var overrides
+    └── helpers.py     # fill_first_match(), click_first_match(), maybe_switch_to_code_factor()
+```
+
+### Key Patterns
+
+- **Selector redundancy**: `login.py` defines 16+ CSS selectors per form field (USERNAME_SELECTORS, PASSWORD_SELECTORS, etc.) tried in priority order for broad Okta form compatibility.
+- **Portal detection**: `_is_on_portal()` confirms auth completion by checking domain change + login field absence.
+- **Session keying**: Sessions are stored as `{domain_hash}.json` + `{domain_hash}.meta.json` using the URL's netloc as the domain key.
+- **Async-first**: All I/O uses `async/await`; the server runs on asyncio via FastMCP.
+- **Browser fallback**: `BrowserController` tries the requested channel first, falls back to default Chromium on launch failure.
+
+## Code Style
+
+- **Formatter/Linter**: Ruff (line-length 100, target py311, double quotes, LF endings)
+- **Lint rules**: E, F, I (isort), B (flake8-bugbear); E501 ignored
+- **Type checking**: mypy with `check_untyped_defs = true`, `ignore_missing_imports = true`
+- **All logs go to stderr** — never print to stdout (breaks MCP stdio transport)

okta_auth_cli-0.1.1/CLAUDE.md

@@ -0,0 +1,61 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+okta-auth is an Okta login toolkit with an interactive CLI and an MCP server for session reuse. It uses Playwright to automate Okta SSO and persists per-domain session state for reuse by AI agents.
+
+## Commands
+
+```bash
+# Setup
+uv venv && source .venv/bin/activate
+uv pip install -e '.[dev]'
+playwright install chromium
+
+# Quality gates (run all three before submitting)
+ruff format --check .
+ruff check .
+pytest
+
+# Run single test
+pytest tests/test_session_store.py -v
+
+# Run interactive CLI
+okta
+
+# Run MCP server (stdio transport, stdout is JSON-RPC)
+okta-auth
+```
+
+## Architecture
+
+```
+src/okta_auth/
+├── server.py          # FastMCP entry point, defines all 5 MCP tools
+├── log.py             # Stderr-only logging (stdout reserved for JSON-RPC)
+├── auth/
+│   ├── login.py       # auto_login() engine: selector-based form filling, portal detection, MFA/TOTP
+│   ├── session_store.py  # Per-domain session CRUD at ~/.okta-auth/sessions/
+│   └── totp.py        # pyotp wrapper for TOTP code generation
+└── browser/
+    ├── controller.py  # BrowserController async context manager, BrowserConfig dataclass
+    ├── detection.py   # Cross-platform browser executable discovery with env var overrides
+    └── helpers.py     # fill_first_match(), click_first_match(), maybe_switch_to_code_factor()
+```
+
+### Key Patterns
+
+- **Selector redundancy**: `login.py` defines 16+ CSS selectors per form field (USERNAME_SELECTORS, PASSWORD_SELECTORS, etc.) tried in priority order for broad Okta form compatibility.
+- **Portal detection**: `_is_on_portal()` confirms auth completion by checking domain change + login field absence.
+- **Session keying**: Sessions are stored as `{domain_hash}.json` + `{domain_hash}.meta.json` using the URL's netloc as the domain key.
+- **Async-first**: All I/O uses `async/await`; the server runs on asyncio via FastMCP.
+- **Browser fallback**: `BrowserController` tries the requested channel first, falls back to default Chromium on launch failure.
+
+## Code Style
+
+- **Formatter/Linter**: Ruff (line-length 100, target py311, double quotes, LF endings)
+- **Lint rules**: E, F, I (isort), B (flake8-bugbear); E501 ignored
+- **Type checking**: mypy with `check_untyped_defs = true`, `ignore_missing_imports = true`
+- **All logs go to stderr** — never print to stdout (breaks MCP stdio transport)

okta_auth_cli-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# Contributing
+
+## Setup
+
+```bash
+uv venv && source .venv/bin/activate
+uv pip install -e '.[dev]'
+playwright install chromium
+```
+
+## Local Quality Gates
+
+```bash
+ruff format --check .
+ruff check .
+pytest
+```
+
+## Pull Requests
+
+- Keep PRs focused and small.
+- Add/update tests for behavior changes.
+- Do not commit secrets, cookies, or local session files.

okta_auth_cli-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bunizao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

okta_auth_cli-0.1.1/PKG-INFO

@@ -0,0 +1,264 @@
+Metadata-Version: 2.4
+Name: okta-auth-cli
+Version: 0.1.1
+Summary: Okta login toolkit with an interactive CLI and MCP session reuse
+Project-URL: Homepage, https://github.com/bunizao/okta-auth
+Project-URL: Issues, https://github.com/bunizao/okta-auth/issues
+Author: bunizao
+License: MIT
+License-File: LICENSE
+Keywords: authentication,mcp,okta,playwright,sso
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: mcp[cli]>=1.9.0
+Requires-Dist: playwright>=1.54.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyotp>=2.9.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.2.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 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:
+
+```bash
+okta
+```
+
+You can also pass values directly:
+
+```bash
+okta https://portal.company.com --username you@company.com
+```
+
+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.
+
+```bash
+# Add to ~/.zshrc or ~/.zprofile (zsh) / ~/.bashrc (bash)
+export OKTA_USERNAME="you@company.com"
+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`](https://developer.1password.com/docs/cli/secrets-scripts/) 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):
+
+```bash
+op item create --category login --title "Okta MCP" \
+  username="you@company.com" \
+  password="your-okta-password" \
+  totp_secret="JBSWY3DPEHPK3PXP"
+```
+
+**2. Create a secrets reference file** at `~/.okta-auth/.env` (contains paths, not values):
+
+```bash
+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:_
+```bash
+claude mcp add okta-auth -- op run --env-file=$HOME/.okta-auth/.env -- uvx --from okta-auth-cli okta-auth
+```
+
+_Claude Desktop / Cursor / Windsurf:_
+```json
+{
+  "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):
+
+```bash
+security add-generic-password -a okta-mcp -s OKTA_USERNAME    -w "you@company.com"
+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`:
+
+```bash
+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
+
+```bash
+uv tool install okta-auth-cli
+okta
+```
+
+### With pipx
+
+```bash
+pipx install okta-auth-cli
+okta
+```
+
+### With pip
+
+```bash
+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:
+
+```bash
+playwright install chromium
+```
+
+## MCP Client Configuration
+
+### Claude Code
+
+```bash
+claude mcp add okta-auth -- uvx --from okta-auth-cli okta-auth
+```
+
+### Claude Desktop / Cursor / Windsurf
+
+```json
+{
+  "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
+
+```bash
+uv venv && source .venv/bin/activate
+uv pip install -e '.[dev]'
+playwright install chromium
+```
+
+Run checks locally:
+
+```bash
+ruff format --check .
+ruff check .
+pytest
+```