Metadata-Version: 2.4
Name: oneport-debug-iam
Version: 0.1.0
Summary: Enterprise IAM-aware debugger: trace 403/401 failures through Okta, Active Directory, Ping Identity, and Azure AD — find the exact missing permission or policy block
Project-URL: Homepage, https://github.com/oneport-debug/oneport-debug
Project-URL: Repository, https://github.com/oneport-debug/oneport-debug
Project-URL: Bug Tracker, https://github.com/oneport-debug/oneport-debug/issues
Project-URL: Changelog, https://github.com/oneport-debug/oneport-debug/blob/main/CHANGELOG.md
Author: OnePort Debug Contributors
License: Apache-2.0
Keywords: active-directory,auth,azure-ad,debugging,enterprise,iam,okta,rbac,rca
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: System :: Systems Administration :: Authentication/Directory
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: click>=8.1.7
Requires-Dist: httpx>=0.27.0
Requires-Dist: oneport-debug-core>=0.1.0
Requires-Dist: pydantic>=2.9.0
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: rich>=13.8.0
Provides-Extra: ad
Requires-Dist: ldap3>=2.9.1; extra == 'ad'
Provides-Extra: azure
Requires-Dist: azure-identity>=1.19.0; extra == 'azure'
Requires-Dist: msal>=1.31.0; extra == 'azure'
Description-Content-Type: text/markdown

# oneport-debug-iam

**Enterprise IAM-aware authorization debugger.** When a user or service gets a
`403`/`401`, this traces the failure through your identity provider (Okta,
Active Directory, Azure AD) *and* re-evaluates the application's RBAC policy
locally — then tells you the exact missing group, scope, or blocking rule, and
how to fix it.

Claude Code and Copilot run with your local privileges and have zero concept of
corporate RBAC. This tool understands the permission matrix.

## Try it in 60 seconds (no Okta, no API key)

```bash
pip install oneport-debug-iam
oneport-iam demo
```

The demo runs the **real** RBAC engine on a bundled 403: an engineer is denied
`POST /api/v1/payments/charge`. You'll see their Okta groups/scopes, the
authorization decision, the **exact missing group and scope**, the policy rule
that governs the endpoint, and a root-cause analysis.

```
✖ DENY
Missing group(s):  payments-admin
Missing scope(s):  payments:write
```

Add `--format json` for machine-readable output (Jira/SIEM/access-review pipelines).

## Use it on your own identities

```bash
export OKTA_ORG_URL=https://corp.okta.com
export OKTA_API_TOKEN=…

oneport-iam trace \
  --user jsmith@corp.com \
  --app payment-service \
  --action POST \
  --resource /api/v1/payments/charge \
  --policy rbac.yaml
```

Other commands:

```bash
# Who can do this? (blast-radius / access review)
oneport-iam who-can --resource /api/v1/admin/users --action DELETE --policy rbac.yaml

# Decode a token and evaluate what it's actually authorized to do
oneport-iam inspect-token --token eyJhbGci... --policy rbac.yaml --resource /api/v1/payments/charge --action POST
```

### RBAC policy format

```yaml
rules:
  - id: allow-charge
    effect: allow                       # allow | deny (deny wins)
    groups: [payments-admin]            # OR within the list
    scopes: [payments:write]            # OAuth scopes (OR); also accepts scope: entries in groups
    resources: ["/api/v1/payments/*"]   # glob
    actions: [POST]
```

### Environment variables

| Provider | Variables |
|---|---|
| Okta | `OKTA_ORG_URL`, `OKTA_API_TOKEN` |
| Active Directory | `AD_SERVER`, `AD_BASE_DN`, `AD_BIND_USER`, `AD_BIND_PASSWORD` (needs the `ad` extra) |

A provider that isn't configured is skipped; one that fails is logged but doesn't
abort the trace (Okta up + AD down still yields a partial analysis).

## Optional dependencies

```bash
pip install 'oneport-debug-iam[ad]'      # Active Directory (LDAP) support
pip install 'oneport-debug-iam[azure]'   # Azure AD / Entra ID
```

The default install is httpx-based (Okta + RBAC) and pulls no LDAP/Azure stack.

## Air-gapped / on-prem AI

Set `ONEPORT_MODE=local` to run the AI analysis against a local model (Ollama /
vLLM) — no data leaves your network. See `oneport-debug-local`.

## Notes

- On **Git Bash (Windows)**, a `--resource /api/...` argument may get path-mangled
  by MSYS. Prefix with `//` or run `MSYS_NO_PATHCONV=1 oneport-iam ...`. PowerShell,
  cmd, and Linux/macOS shells are unaffected.

## License

Apache-2.0
