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-suite

Run it inside Claude Code after adding the marketplace with /plugin marketplace add GRCEngClub/claude-grc-engineering.

Contents

Discovered from source

Skills 1

okta-inspector expert

You are the interpretation layer between Okta configuration and compliance frameworks.

Checks this connector runs (v0.1.0)

Policies:

SCFCheckSource endpointSeverity
IAC-06Password policy: length ≥14, complexity, age ≤90d, history ≥24/api/v1/policies?type=PASSWORDhigh
IAC-01.2At least one active MFA enrollment policy requires a factor/api/v1/policies?type=MFA_ENROLLhigh
IAC-15Sign-on session lifetime ≤ 720 min (12h)/api/v1/policies/{id}/rulesmedium
IAC-15.1Sign-on session idle ≤ 15 minsamemedium

Users:

SCFCheckSeverity
IAC-15.1No active users inactive > N days (default 90)medium

Admin factors:

SCFCheckSeverity
IAC-07.1≤5 super adminsmedium
IAC-01.2Every super admin has ≥1 active MFA factorcritical
IAC-01.3Every 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:

  1. No enrollment policy requires a factor: users can enroll MFA if they want but don't have to. This fails SOC 2 immediately.
  2. 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-days still works but some policy settings are named differently; expect more inconclusive results.
  • 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 of policies,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:

SCFCheckSeverity
IAC-01.2MFA required for all usershigh
IAC-06Password policy meets baseline (length ≥14, complexity, age ≤90d, history ≥24)high
IAC-15Session maximum duration ≤ 12 hoursmedium
IAC-15Session idle timeout ≤ 15 minutesmedium

MFA enrollment (per user, sampled):

SCFCheckSeverity
IAC-01.2All admin users have MFA enrolledcritical
IAC-01.2At least 2 factors enrolled per admin (no single-factor fallback)high

Users:

SCFCheckSeverity
IAC-15.1No users inactive > N days (default 90) still activemedium
IAC-07.1Super-admin count is reasonable (<5 super admins)medium

Audit logs:

SCFCheckSeverity
MON-02System 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

  • 0 success
  • 2 auth invalid
  • 3 rate-limited (Okta has tight per-token limits — the connector waits then retries once)
  • 4 partial
  • 5 config 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)

  1. --token=<value> flag (not recommended — ends up in shell history)
  2. --token-env=<ENV_VAR> — tells the connector which env var holds the token
  3. OKTA_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

  1. Verify curl is available.

  2. Read the token from the specified env var.

  3. Call GET /api/v1/users/me to verify the token resolves to an active admin/user.

  4. Fetch org details (GET /api/v1/org) to record the org ID and status.

  5. 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_TOKEN then 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, not https://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 go
  • not-configured — setup not run
  • token-missing — token env var unset
  • token-invalid — Okta returned 401 on /users/me
  • stale — 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