Okta connector (Service App / private-key JWT)

When to use Service App / JWT

• You want a no-user-in-the-loop integration that can mint its own access tokens without anyone signing in.
• Your security model prefers public-key cryptography over shared secrets — only the public key (JWK) is ever uploaded to Okta; the private key stays in ITDR encrypted at rest.
• You expect this connector to run unattended for years. JWT signing keys do not expire the way OAuth refresh tokens can be revoked or invalidated.

Required Okta scopes

• okta.users.read — Pull identity inventory.
• okta.users.manage — Containment bundles (deactivate user, clear sessions).
• okta.logs.read — System log (sign-ins, MFA, lifecycle).
• okta.policies.read — Posture findings: sign-on/password/lockout policies.
• okta.factors.read — Posture findings: MFA enrollment coverage.
• okta.userTypes.read — Resolving admin role assignments cleanly.

Generate the RSA key pair

• openssl genrsa -out itdr-okta.pem 2048
• openssl rsa -in itdr-okta.pem -pubout -out itdr-okta.pub.pem
• # Convert public PEM to JWK (Okta wants the JWK form). Many online and CLI tools do this; the result looks like {"kty":"RSA","kid":"<id>","n":"...","e":"AQAB"}.
• # Pick a kid value (any opaque string — typically a uuid or yyyy-mm-dd-<n>) and use the same kid in the JWK and in the ITDR form.

Register the Service App in Okta

1. Sign in to your Okta admin console as a Super Admin.
2. Navigate to Applications > Applications and click "Create App Integration".
3. Choose "API Services". Name it "ITDR Platform (Service App)" and save.
4. In the new app, open the "General" tab. Under "Client Credentials", change Client authentication to "Public key / Private key" and click "Add key". Paste your JWK (public key) into the field. Save.
5. Switch to the "Okta API Scopes" tab and grant all six scopes listed above.
6. Copy the Client ID from the General tab. Note the kid you used when generating the key.

Add the connector in ITDR

1. Open /connectors in ITDR.
2. Click "Add connector", then in the Okta pill row pick "Service App (Private key)".
3. Fill in: Connector name, Okta org URL, Service App client_id, kid, and paste the PEM-encoded RSA private key (the contents of itdr-okta.pem).
4. Click "Create Okta service-app connector". ITDR signs a short-lived JWT with the private key and posts it to /oauth2/v1/token to mint an access token. On success the connector is saved ACTIVE; on failure you see a specific reason (401 = JWT rejected, check kid match; 403 = scopes insufficient).

Security and rotation

• The private key is Fernet-encrypted at rest using CONNECTOR_CREDENTIALS_KEY before persisting to connector.configuration. It is decrypted only briefly in memory to sign each JWT.
• JWT lifetime: ITDR signs assertions with a 5-minute expiry. Each access token is short-lived (typically 1 hour). The OktaClient transparently mints a new one when needed.
• Key rotation: register a second public key (different kid) in the Okta Service App, then update the connector configuration with the new kid + matching private key. Test before removing the old key.
• Revocation: delete the public key from the Okta Service App. Next token mint attempt fails with 401, the connector flips to sync_status="credentials_rejected".