Okta Collector Configuration

Authentication Setup

OAuth 2.0 (Recommended)

OAuth 2.0 with private key JWT is the recommended authentication method. It provides:
- Scoped access (only the permissions you need)
- Short-lived tokens
- Better audit logging

Step 1: Create a Service App

1. Go to Okta Admin Console → Applications → Applications
2. Click "Create App Integration"
3. Select "API Services" and click Next
4. Name your application (e.g., "epack-collector")
5. Click Save

Step 2: Configure Public Key

1. In the app settings, go to "Client Credentials"
2. Edit the "Client authentication" section
3. Select "Public key / Private key"
4. Disable DPoP: Uncheck "Require Demonstrating Proof of Possession (DPoP) header in token requests"
5. In the "Public keys" section below, click "Edit"
6. Keep "Save keys in Okta" selected
7. Click "Generate new key"
8. Important: When prompted, choose PEM format (not JWK/JSON)
9. Download the private key immediately - Okta only shows it once
10. Save the private key securely (e.g., ~/.okta/epack-private-key.pem)
11. Copy the Key ID: After saving, expand the key details to find the Key ID (a string like abc123xyz...). You'll need this for your epack config.

Step 3: Grant API Scopes

1. Go to the Okta API Scopes tab
2. Click Grant next to each of these scopes:
   • okta.users.read
   • okta.apps.read
   • okta.policies.read

Step 4: Assign Admin Role

OAuth scopes alone aren't enough - the service app needs an admin role to access org-wide resources.

1. Go to Security → Administrators
2. Click Add Administrator
3. In the "Admin" field, search for and select your service app (e.g., "epack-collector")
4. Under "Role", select Read Only Administrator
5. Click Save Changes

Step 5: Configure epack

collectors:
  okta:
    source: locktivity/epack-collector-okta@^0.1
    config:
      org_domain: your-org.okta.com
      client_id: 0oa1234567890abcdef   # From app settings
      key_id: abc123xyz                # From public key settings
    secrets:
      - OKTA_PRIVATE_KEY               # PEM-encoded private key

Set the environment variable (use the PEM file you downloaded):

export OKTA_PRIVATE_KEY="$(cat ~/.okta/epack-private-key.pem)"

API Token (Legacy)

API tokens are simpler to set up but less secure:
- Tokens don't expire automatically
- Tokens have full permissions of the user who created them
- Harder to audit

Step 1: Create an API Token

1. Go to Okta Admin Console → Security → API → Tokens
2. Click "Create Token"
3. Name it (e.g., "epack-collector")
4. Copy the token value immediately (it won't be shown again)

Step 2: Configure epack

collectors:
  okta:
    source: locktivity/epack-collector-okta@^0.1
    config:
      org_domain: your-org.okta.com
    secrets:
      - OKTA_API_TOKEN

Set the environment variable:

export OKTA_API_TOKEN="00abcdef..."

Configuration Options

Environment Variables

Troubleshooting

"Authentication required" error

Ensure either:
- client_id, key_id config and OKTA_PRIVATE_KEY env var are all set (for OAuth), OR
- OKTA_API_TOKEN env var is set (for API token auth)

"Token exchange failed" or "invalid_client - JWT kid is invalid" error

For OAuth 2.0:
- Verify the client_id is correct
- Verify the key_id matches the Key ID shown in Okta (General → Client Credentials → Public Keys)
- Ensure the private key matches the public key configured in Okta (they're a matched pair)
- Make sure DPoP is disabled
- Check that all required scopes are granted

"Rate limited" errors

The collector handles rate limits automatically with exponential backoff. If you see persistent rate limit errors:
- Reduce collection frequency
- Contact Okta support to increase rate limits

Missing data

Some metrics require specific permissions:
- Policy details require okta.policies.read scope
- If using API token, ensure the token creator has admin privileges

Examples

Basic Usage

Using OAuth 2.0 (Recommended)

stream: myorg/okta-posture

collectors:
  okta:
    source: locktivity/epack-collector-okta@^0.1
    config:
      org_domain: company.okta.com
      client_id: 0oa1234567890abcdef
      key_id: abc123xyz
    secrets:
      - OKTA_PRIVATE_KEY

Then run:

export OKTA_PRIVATE_KEY="$(cat /path/to/private-key.pem)"
epack collect

See Configuration for OAuth 2.0 setup instructions.

Using API Token (Legacy)

stream: myorg/okta-posture

collectors:
  okta:
    source: locktivity/epack-collector-okta@^0.1
    config:
      org_domain: company.okta.com
    secrets:
      - OKTA_API_TOKEN

Then run:

export OKTA_API_TOKEN=00abcdef...
epack collect

Sample Output

{
  "protocol_version": 1,
  "data": {
    "schema_version": "1.0.0",
    "collected_at": "2026-02-25T14:00:00Z",
    "org_domain": "company.okta.com",
    "posture": {
      "mfa_coverage": 85,
      "mfa_phishing_resistant": 20,
      "sso_coverage": 90
    },
    "users": {
      "password_expired": 2,
      "locked_out": 0,
      "inactive": 15
    },
    "apps": {
      "provisioning_enabled": 40,
      "deprovisioning_enabled": 30
    },
    "policy": {
      "policy_count": 2,
      "mfa_required_all": false,
      "mfa_required_any": true,
      "session_lifetime_min_minutes": 15,
      "session_lifetime_max_minutes": 1440,
      "idle_timeout_min_minutes": 5,
      "idle_timeout_max_minutes": 120
    }
  }
}

All coverage values are percentages (0-100). See Overview for detailed metric descriptions.

CI/CD Integration

GitHub Actions (with OAuth 2.0)

name: Collect Evidence

on:
  schedule:
    - cron: "0 0 * * 1"  # Weekly on Monday
  workflow_dispatch:

jobs:
  collect:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install epack
        run: |
          curl -sSL https://github.com/locktivity/epack/releases/latest/download/epack-linux-amd64 -o epack
          chmod +x epack
          sudo mv epack /usr/local/bin/

      - name: Collect evidence
        run: epack collect --frozen
        env:
          OKTA_PRIVATE_KEY: ${{ secrets.OKTA_PRIVATE_KEY }}

      - name: Upload pack
        uses: actions/upload-artifact@v4
        with:
          name: evidence-pack
          path: "*.pack"

Store the Okta private key as a repository secret named OKTA_PRIVATE_KEY.

Multiple Okta Organizations

To collect from multiple Okta orgs, define separate collectors:

stream: mycompany/identity-posture

collectors:
  okta-prod:
    source: locktivity/epack-collector-okta@^0.1
    config:
      org_domain: company.okta.com
      client_id: 0oa1234567890abcdef
      key_id: prodkey123
    secrets:
      - OKTA_PROD_PRIVATE_KEY

  okta-preview:
    source: locktivity/epack-collector-okta@^0.1
    config:
      org_domain: company.oktapreview.com
      client_id: 0oa0987654321fedcba
      key_id: previewkey456
    secrets:
      - OKTA_PREVIEW_PRIVATE_KEY

Then set both environment variables:

export OKTA_PROD_PRIVATE_KEY="$(cat prod-key.pem)"
export OKTA_PREVIEW_PRIVATE_KEY="$(cat preview-key.pem)"
epack collect