Skip to main content

Okta Network Zones

Okta Network Zones

Status: Draft / unreleased. This integration is in proof-of-concept stage and has not been validated against a live Okta tenant. Do not deploy to customer environments until smoke-tested. Page hidden from non-admins.

Overview

This integration manages Okta IP Network Zones and Authentication Policy rule conditions via the Okta Management API. It mirrors the Microsoft Entra backend: as users authenticate to Knocknoc, their granted IP is added to a Knocknoc-managed Okta Network Zone, and that zone is added to the exclude list of a designated Authentication Policy rule so the policy no longer blocks access.

For customers using both Okta and Entra (e.g. mid-migration from one to the other), the two backends can run side by side against the same Knocknoc ACLs.

Prerequisites

Before configuring the backend, ensure the following are in place:

  • PowerShell — install the latest PowerShell on the host running the Knocknoc agent. See the PowerShell releases page for your architecture. The same install steps used for the Entra integration apply here.

  • Okta API token — generate an Okta API token (SSWS) under Security → API → Tokens in the Okta admin console. The token must be created by an admin user holding at least the following permissions:

    • Manage Network Zones (scope: okta.networkZones.manage)
    • Manage Authentication Policies (scope: okta.policies.manage)

    Use a dedicated service-account admin rather than a personal admin login. Tokens expire after 30 days of inactivity — rotate accordingly.

  • Authentication Policy — one Okta Authentication Policy (type ACCESS_POLICY under Okta Identity Engine) must exist per Knocknoc ACL, named knocknoc_<acl>. The policy must contain exactly one non-default rule whose network conditions Knocknoc will manage. Knocknoc rewrites that rule's conditions.network.exclude array on each grant/revoke; other rule fields (priority, status, action) are preserved.

    Note: Okta Classic Engine sign-on policies (type OKTA_SIGN_ON) are not currently supported by this backend. Tenants must be on Identity Engine.

  • Network Zone cap — Okta limits an org to 100 Network Zones total. The current PoC creates one zone per granted IP, so it suits small deployments only. For larger user counts, a refactor to a single shared zone per ACL (with gateway IPs added/removed inside it) is planned.

  • Credentials file — install a credentials file at /opt/knocknoc-agent/etc/okta-credentials.sh containing:

    okta_domain="your-org.okta.com"
okta_apitoken="00abc..."

    okta_domain is your Okta org hostname without the https:// prefix.

Admin Portal Configuration

  1. Create a new Custom Script backend in the Knocknoc admin portal. The wrapper script is installed at /opt/knocknoc-agent/scripts/update-okta-acl.sh by default.

  2. Create one or more ACLs in Knocknoc that correspond to your knocknoc_<acl> Authentication Policies in Okta. ACL names must match the policy name suffix exactly (case-sensitive).

    Set a clear description so the user sees what they are being granted access to (e.g. "Okta-protected finance apps") and a redirect URL pointing to the relevant Okta-protected service.

  3. Assign the ACL and the relevant users to a group, as with any other Knocknoc backend.

On grant, the agent invokes update-okta-acl.sh add <acl> <ip>, which creates a Network Zone named knocknoc_<ip> and adds it to the configured policy rule's exclude list. On revoke, the corresponding del call removes the zone from the rule and deletes it.

Troubleshooting

  • 401 Unauthorized — API token is expired, revoked, or missing required scopes. Regenerate.
  • Policy 'knocknoc_<acl>' not found — verify the Authentication Policy exists under Identity Engine (not Classic) and that the name matches exactly.
  • No non-default rule found — the managed policy must have at least one rule beyond Okta's built-in catch-all. Add a custom rule.
  • 429 Too Many Requests — Okta org rate limits exceeded. Reduce grant churn or contact Okta to raise limits.
Back to top