
okta-inspector
GRC connector for Okta: password/MFA/session policies, inactive users, admin factor enrollment → v1 finding contract
- version
- 0.1.0
- GitHub stars
- 436
Install
/plugin install okta-inspector@grc-engineering-suiteRun it inside Claude Code after adding the marketplace with /plugin marketplace add GRCEngClub/claude-grc-engineering.
Contents
Discovered from sourceSkills 1
okta-inspector expert
You are the interpretation layer between Okta configuration and compliance frameworks.
Checks this connector runs (v0.1.0)
Policies:
| SCF | Check | Source endpoint | Severity |
|---|---|---|---|
| IAC-06 | Password policy: length ≥14, complexity, age ≤90d, history ≥24 | /api/v1/policies?type=PASSWORD | high |
| IAC-01.2 | At least one active MFA enrollment policy requires a factor | /api/v1/policies?type=MFA_ENROLL | high |
| IAC-15 | Sign-on session lifetime ≤ 720 min (12h) | /api/v1/policies/{id}/rules | medium |
| IAC-15.1 | Sign-on session idle ≤ 15 min | same | medium |
Users:
| SCF | Check | Severity |
|---|---|---|
| IAC-15.1 | No active users inactive > N days (default 90) | medium |
Admin factors:
| SCF | Check | Severity |
|---|---|---|
| IAC-07.1 | ≤5 super admins | medium |
| IAC-01.2 | Every super admin has ≥1 active MFA factor | critical |
| IAC-01.3 | Every super admin has ≥2 active MFA factors (backup) | high |
Framework mappings (auto-expanded by gap-assessment)
- IAC-01.2 (MFA) → SOC 2 CC6.1, CC6.2 · NIST 800-53 IA-02(01), IA-02(02) · FedRAMP IA-02(01) · PCI 8.4, 8.5 · CIS 6.3, 6.5
- IAC-06 (password policy) → SOC 2 CC6.1 · NIST 800-53 IA-05 · PCI 8.3 · CIS 5.2
- IAC-15 (session mgmt) → SOC 2 CC6.1 · NIST 800-53 AC-11, AC-12 · PCI 8.1.8
- IAC-15.1 (lifecycle) → SOC 2 CC6.2, CC6.3 · NIST 800-53 AC-02(03) · PCI 8.1.4
Interpreting output
Password policy fails (IAC-06)
Okta's default policy is lenient (minLength=8, no age, no history). Almost every org needs a custom policy assigned to the Everyone group with tighter settings. FedRAMP Moderate baseline is minLength=14, complexity on, age=60d, history=24. The fix is usually straightforward but requires admin access to Okta.
MFA enforcement fails (IAC-01.2)
Two distinct failures under this control:
- No enrollment policy requires a factor: users can enroll MFA if they want but don't have to. This fails SOC 2 immediately.
- Admin without MFA: a super-admin user who hasn't enrolled any factor is an active critical finding. These tokens should be revoked until the admin enrolls.
Session timeouts (IAC-15, IAC-15.1)
FedRAMP requires session termination after inactivity. Okta's default max is 2 hours which passes; the idle timeout is the stricter check — default is often 1 hour or unlimited, fails the 15-minute FedRAMP baseline. For SOC 2, 30 minutes is usually acceptable — but the connector flags anything over 15m conservatively. Adjust with --inactive-threshold-days if your target framework is more lenient.
Inactive users (IAC-15.1)
FedRAMP is notoriously strict here — 35 days is the cutoff for Moderate. SOC 2 doesn't have a hard number but most auditors expect ≤90. The default threshold is 90; pass --inactive-threshold-days=35 for FedRAMP.
"Never logged in" users: separate signal. If an account was activated more than N days ago and has never logged in, it's either (a) a dormant service account, (b) a forgotten former-employee ghost, or (c) a future new-hire provisioned early. Any of those warrant review.
Super admin count (IAC-07.1)
Okta has built-in admin roles: Super Admin, Org Admin, App Admin, Group Admin, Help Desk Admin, Read-Only Admin, etc. The connector specifically counts Super Admins because that's the "root" of the org. 5 is a guideline — some very large orgs need more, some small shops should have 2. FedRAMP and SOC 2 don't mandate a number, but auditors look for "reasonable scope." Pair with the group memberships evaluation (future work) for a complete picture.
Limits (v0.1.0)
Not covered yet:
- Factor types evaluated (is the admin using SMS instead of WebAuthn? SMS-only MFA is a FedRAMP red flag)
- Okta Identity Engine (OIE) policy features: authenticators, phishing-resistant constraints
- Password hashing algorithm (bcrypt vs older)
- API token inventory and age (how many tokens exist, how old, what scope)
- ThreatInsight / suspicious login analytics
- App assignments (which apps are assigned to which groups / users — orphan apps)
- Log retention (System Log is 90 days by default; Log Streaming adds BYO-SIEM)
- Lifecycle integration with HRIS — whether offboarding is triggered from an authoritative HR system
When a user asks about these, say "v0.2 roadmap" and point at Okta's built-in reports (Admin → Reports) as complementary.
Common pitfalls
- Okta Classic vs Identity Engine (OIE): some API responses differ. The connector targets OIE (the current default). If the user is on Classic,
--inactive-threshold-daysstill works but some policy settings are named differently; expect moreinconclusiveresults. - Rate limits: Okta's per-API-token rate limits are tight (roughly 600 req/minute for the read endpoints). Large orgs with many admins + factors can hit these; the connector wraps to one retry on 429.
- Admin roles are hierarchical: a user with Super Admin and Org Admin counts once. Don't over-count based on role assignments.
- Factor-less admins via service accounts: some orgs have "service" super-admin accounts used only for API calls. These fail the MFA check. The right fix is usually to replace them with an API-service-principal or scoped API tokens rather than a super-admin user.
Commands 3
/okta-inspector:collect
Scans an Okta org and emits Findings evaluating identity-related SCF controls.
How to run
node plugins/connectors/okta-inspector/scripts/collect.js [options]
Arguments
--services=<csv>— subset ofpolicies,users,factors,logs(default: all)--output=<fmt>—silent|summary(default) |json--include-deactivated— include deactivated users in the scan (default: no)--inactive-threshold-days=<n>— flag users inactive beyond this many days (default: 90)--quiet— no stderr progress
What it evaluates
Authentication policies:
| SCF | Check | Severity |
|---|---|---|
| IAC-01.2 | MFA required for all users | high |
| IAC-06 | Password policy meets baseline (length ≥14, complexity, age ≤90d, history ≥24) | high |
| IAC-15 | Session maximum duration ≤ 12 hours | medium |
| IAC-15 | Session idle timeout ≤ 15 minutes | medium |
MFA enrollment (per user, sampled):
| SCF | Check | Severity |
|---|---|---|
| IAC-01.2 | All admin users have MFA enrolled | critical |
| IAC-01.2 | At least 2 factors enrolled per admin (no single-factor fallback) | high |
Users:
| SCF | Check | Severity |
|---|---|---|
| IAC-15.1 | No users inactive > N days (default 90) still active | medium |
| IAC-07.1 | Super-admin count is reasonable (<5 super admins) | medium |
Audit logs:
| SCF | Check | Severity |
|---|---|---|
| MON-02 | System log retention reachable (logs fetched successfully) | info |
Output
-
~/.cache/claude-grc/findings/okta-inspector/<run_id>.json -
Summary to stdout unless
--quiet:okta-inspector: 12 resources, 38 evaluations, 4 failing (0 critical, 2 high, 2 medium).
Exit codes
0success2auth invalid3rate-limited (Okta has tight per-token limits — the connector waits then retries once)4partial5config missing — run setup
Token permissions
A Read-only API token created in Okta admin is sufficient. The connector never calls write endpoints. Required scopes (all covered by Read-only):
- Users: read, admins read
- Policies: read
- Groups: read (optional, enhances admin scope analysis)
- System log: read
Example output narrative
When policies miss the baseline, findings include specific remediation:
IAC-06 — Password policy
fail (high): Okta default password policy 'Default Policy' has minLength=8 (<14),
no history (<24), maxAgeDays=0 (unset).
remediation: Tighten the policy for /api/v1/policies/{id} with {settings.password: {...}}.
Examples
# All checks
export OKTA_API_TOKEN=00abc...
/okta-inspector:collect
# Just authentication policies (fast)
/okta-inspector:collect --services=policies
# Strict inactivity threshold (e.g., FedRAMP 30-day requirement)
/okta-inspector:collect --inactive-threshold-days=30
/okta-inspector:setup
Configures the okta-inspector connector. Verifies an Okta API token works against the given org, writes ~/.config/claude-grc/connectors/okta-inspector.yaml.
How to run
bash plugins/connectors/okta-inspector/scripts/setup.sh --domain=<your-org>.okta.com [--token-env=OKTA_API_TOKEN]
Credential sources (in precedence order)
--token=<value>flag (not recommended — ends up in shell history)--token-env=<ENV_VAR>— tells the connector which env var holds the tokenOKTA_API_TOKEN— default env var name
The token must be a Read-only API token at minimum, created at https://<your-org>.okta.com/admin/access/api/tokens. The connector never writes the token to disk — only the env-var name.
What it does
-
Verify
curlis available. -
Read the token from the specified env var.
-
Call
GET /api/v1/users/meto verify the token resolves to an active admin/user. -
Fetch org details (
GET /api/v1/org) to record the org ID and status. -
Write config:
version: 1 source: okta-inspector source_version: "0.1.0" domain: "acme.okta.com" org_id: "00oab12c3d4E5f6G7h8" caller: "security-scanner@acme.com" token_env: "OKTA_API_TOKEN" defaults: include_deactivated_users: false
Typical output
okta-inspector:setup ✓
domain: acme.okta.com
org id: 00oab12c3d4E5f6G7h8
caller: security-scanner@acme.com
token source: $OKTA_API_TOKEN
config: ~/.config/claude-grc/connectors/okta-inspector.yaml
Next: /okta-inspector:collect
Failure modes
- curl missing: exit 5. (Should never happen on a real machine.)
- Token env var unset: exit 2. Set
OKTA_API_TOKENthen re-run. - 401 Unauthorized: exit 2. Token invalid or revoked. Create a new one in Okta admin.
- 403 Forbidden: exit 2. Token lacks read scope on the endpoint. Use at least a Read-only token.
- Org not found / 404: exit 2. Domain typo. Should look like
acme.okta.com, nothttps://acme.okta.com.
Safe to re-run
Yes. Overwrites the config; the token itself is never stored.
/okta-inspector:status
Non-destructive health check. Shows whether the connector is configured, whether the token still works, and when it last produced findings.
How to run
bash plugins/connectors/okta-inspector/scripts/status.sh
Output
okta-inspector
status: ready
domain: acme.okta.com
org id: 00oab12c3d4E5f6G7h8
token source: $OKTA_API_TOKEN (valid)
caller: security-scanner@acme.com
config: ~/.config/claude-grc/connectors/okta-inspector.yaml
last run: 5h ago (run_id 20260413-a1b2c3d4)
cached: 12 resources, 38 evaluations
Status values
ready— all systems gonot-configured— setup not runtoken-missing— token env var unsettoken-invalid— Okta returned 401 on/users/mestale— last run > 7 days
Sponsors
Details
- Marketplace
- GRCEngClub/claude-grc-engineering
- Source
- plugins/connectors/okta-inspector
- Category
- Community
More from GRCEngClub/claude-grc-engineering
All 70- onepassword-connectorv0.1.0
- oscalv0.1.0
- pbmmv0.1.0
- pci-dssv0.1.0
- poam-automationv0.1.0
- sg-mas-trmv0.1.0
- singapore-pdpav0.1.0
- slack-inspectorv0.1.0
- snowflake-inspectorv0.1.0
- soc2v0.1.0
- splunk-inspectorv0.1.0
- staterampv0.1.0
- teach-mev0.1.0
- tenable-inspectorv0.1.0
- testssl-inspectorv0.1.0
- trust-centerv0.1.0
- us-ccpav0.1.0
- us-exportv0.1.0
- us-finrav0.1.0
- us-hipaa-securityv0.1.0
- us-nerc-cipv0.1.0
- us-soxv0.1.0
- vault-kvv0.1.0
- wiz-inspectorv0.1.0