Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.prowler.com/llms.txt

Use this file to discover all available pages before exploring further.

Prowler for Okta scans an Okta organization for identity and session-management misconfigurations. The provider authenticates as a service application using OAuth 2.0 with a private-key JWT (Client Credentials grant) — no end-user login, read-only by scope.

​
Prerequisites

Set up authentication for Okta with the Okta Authentication guide before starting:
  • An Okta organization. The UI examples below use Identity Engine terminology such as Global Session Policy; Classic Engine exposes the equivalent sign-on policy concepts under older names.
  • A Super Administrator account on that organization for the one-time service-app setup.
  • An API Services app integration in the Okta Admin Console with the okta.policies.read scope granted and the Read-Only Administrator role assigned.
  • Python 3.10+ and Prowler 5.27.0 or later installed locally.

Prowler Cloud

Onboard Okta using Prowler Cloud

Prowler CLI

Onboard Okta using Prowler CLI

​
Prowler Cloud

Prowler Cloud onboarding for Okta is coming soon. Track the Prowler GitHub repository for release updates. Use the Prowler CLI workflow below in the meantime.

​
Prowler CLI

​
Step 1: Set Up Authentication

Follow the Okta Authentication guide to create the service application, generate a keypair, grant scopes, and assign the Read-Only Administrator role. Then export the credentials: 
export OKTA_ORG_DOMAIN="acme.okta.com"
export OKTA_CLIENT_ID="0oa1234567890abcdef"
export OKTA_PRIVATE_KEY_FILE="/secure/path/to/prowler-okta.pem"
# Optional — defaults to "okta.policies.read"
export OKTA_SCOPES="okta.policies.read"
The private key file may contain either a PEM-encoded RSA key or a JWK JSON document.

​
Supplying the Private Key as Content

For automated environments where writing the key to disk is not desirable (CI runners, container secrets, etc.), the private key may be passed directly as a string: 
export OKTA_ORG_DOMAIN="acme.okta.com"
export OKTA_CLIENT_ID="0oa1234567890abcdef"
export OKTA_PRIVATE_KEY="$(cat /secure/path/to/prowler-okta.pem)"
OKTA_PRIVATE_KEY takes precedence over OKTA_PRIVATE_KEY_FILE when both are set. The private key is intentionally not exposed as a CLI flag — secrets must be supplied via environment variables only.

​
Step 2: Run the First Scan

Run a baseline scan after credentials are configured: 
prowler okta
Or run a specific check directly: 
prowler okta --check signon_global_session_idle_timeout_15min
Prowler prints a summary table; full findings are written to the configured output formats.

​
Step 3: Use a Custom Configuration (Optional)

Prowler uses a configuration file to customize check thresholds. The Okta configuration currently includes: 
okta:
  # okta.signon_global_session_idle_timeout_15min
  # Defaults to 15 minutes per DISA STIG V-273186.
  okta_max_session_idle_minutes: 15
To use a custom configuration: 
prowler okta --config-file /path/to/config.yaml

​
Supported Services

Prowler for Okta includes security checks across the following services:
ServiceDescription
Sign-OnGlobal session policy controls (idle timeout, lifetime, rule priority and ordering)

​
Troubleshooting

​
STIG Rule Ordering

The initial check is mapped to DISA STIG V-273186 / OKTA-APP-000020. Prowler implements the STIG procedure as written: the Default Policy must have a Priority 1 rule that is not Default Rule, and that rule must set Maximum Okta global session idle time to 15 minutes or less. This is stricter than simply finding the same timeout value somewhere else in the policy set. A compliant custom rule in another policy, or a compliant timeout on the built-in Default Rule, does not satisfy this STIG procedure.

​
Default Scopes

Prowler requests a fixed set of OAuth scopes on every token exchange. The default is a single scope that covers the bundled initial check:
  • okta.policies.read
The service app must have that scope granted in the Okta API Scopes tab. When the granted set is narrower than the requested set, the token request fails with an invalid_scope error and the scan stops at provider initialization. When additional checks are enabled — or when running against a service app that exposes a different scope set — override the default with OKTA_SCOPES (comma-separated string for the env var) or --okta-scopes (space-separated list for the CLI): 
# Environment variable — comma-separated
export OKTA_SCOPES="okta.policies.read,okta.apps.read,okta.users.read"

# CLI flag — space-separated
prowler okta --okta-scopes okta.policies.read okta.apps.read okta.users.read
For the full catalog of OAuth scopes exposed by the Okta Management API, refer to the Okta OAuth 2.0 scopes documentation.
As new services and checks land in the Okta provider, the default scope list grows alongside them. Re-check the granted scopes on the service app after each Prowler upgrade and grant any newly required okta.*.read scopes in the Admin Console.

​
Common Errors

  • OktaInvalidOrgDomainError — the org domain must be <org>.okta.com (or .oktapreview.com / .okta-emea.com / .okta-gov.com / .okta.mil / .okta-miltest.com / .trex-govcloud.com). Pass the bare hostname only — no https:// scheme, no path, no trailing slash.
  • OktaPrivateKeyFileError — confirm the file is readable and contains a non-empty PEM or JWK body.
  • OktaInsufficientPermissionsError — the credential probe reached Okta but the service app cannot perform the request. The error string carries invalid_scope, Forbidden, not authorized, or permission. Fix by granting the missing okta.*.read scope from Okta API Scopes and confirming the Read-Only Administrator role is assigned to the service app.
  • OktaInvalidCredentialsError — the credential probe reached Okta but Okta rejected the JWT. Typically the private key on disk does not match the public JWK uploaded to the service app, or the JWT signing parameters are wrong. Regenerate the keypair and re-upload the public JWK.
  • Token requests failing for an unknown scope — the app was granted a narrower scope set than OKTA_SCOPES requests. Either narrow OKTA_SCOPES or grant the missing scopes in the Admin Console.