mirror of
https://github.com/prowler-cloud/prowler.git
synced 2026-10-30 15:24:22 +00:00
145 lines
6.9 KiB
Plaintext
145 lines
6.9 KiB
Plaintext
---
|
|
title: 'Getting Started With Okta on Prowler'
|
|
---
|
|
|
|
import { VersionBadge } from "/snippets/version-badge.mdx"
|
|
|
|
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](/user-guide/providers/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.
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Prowler Cloud" icon="cloud" href="#prowler-cloud">
|
|
Onboard Okta using Prowler Cloud
|
|
</Card>
|
|
<Card title="Prowler CLI" icon="terminal" href="#prowler-cli">
|
|
Onboard Okta using Prowler CLI
|
|
</Card>
|
|
</CardGroup>
|
|
|
|
## Prowler Cloud
|
|
|
|
<Note>
|
|
Prowler Cloud onboarding for Okta is coming soon. Track the [Prowler GitHub repository](https://github.com/prowler-cloud/prowler) for release updates. Use the [Prowler CLI](#prowler-cli) workflow below in the meantime.
|
|
</Note>
|
|
|
|
---
|
|
|
|
## Prowler CLI
|
|
|
|
<VersionBadge version="5.27.0" />
|
|
|
|
### Step 1: Set Up Authentication
|
|
|
|
Follow the [Okta Authentication](/user-guide/providers/okta/authentication) guide to create the service application, generate a keypair, grant scopes, and assign the Read-Only Administrator role. Then export the credentials:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
prowler okta
|
|
```
|
|
|
|
Or run a specific check directly:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```bash
|
|
prowler okta --config-file /path/to/config.yaml
|
|
```
|
|
|
|
## Supported Services
|
|
|
|
Prowler for Okta includes security checks across the following services:
|
|
|
|
| Service | Description |
|
|
| ----------- | ----------------------------------------------------------------------------------- |
|
|
| **Sign-On** | Global 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):
|
|
|
|
```bash
|
|
# 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](https://developer.okta.com/docs/api/oauth2/).
|
|
|
|
<Note>
|
|
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.
|
|
</Note>
|
|
|
|
### 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.
|