Skip to main content

Okta

Knocknoc integrates with Okta to dynamically control which IPs are allowed to access apps protected by Okta. The integration uses the Okta API to maintain a single Network Zone of type IP Zone.

As users authenticate to Knocknoc and grants expire, the network zone's gateway list is updated. Okta sign-on policies and app sign-on rules that reference the zone (typically via a Network is or User is in zone condition) gate access on whether the user's current IP is present.

Authentication

The Knocknoc agent authenticates to Okta with an API token. Tokens are bound to an admin user and carry that user's privileges.

Generate an API token

  1. Log into the Okta admin console as a super-administrator (or any administrator authorised to create tokens)
  2. Navigate to Security > API > Tokens
  3. Click Create token
  4. Give it a name (e.g., knocknoc-agent) and copy the token value. Okta only displays it once
  5. Note the token's expiry. Tokens not used for 30 days are auto-revoked

You will paste this value into the API Token field in the Knocknoc wizard.

User Permissions

The API token must be created on a user with the Org Administrator or Super Administrator role. Both can manage network zones.

  1. Org Administrator. The least-privilege option that works. It manages network zones without the broader super-admin settings.
  2. Super Administrator. Broadest privilege. Use only if Org Administrator doesn't suit your environment.

After assigning the role, follow Generate an API token on that user.

If you recently changed the user's role assignment, rotate the API token afterwards so the new role takes effect. Okta caches role information on the token.

Setup

Knocknoc maintains a single IP Zone in Okta and rewrites its gateways list as users come and go. Sign-on policies and app rules reference the zone by ID.

Step 1: Confirm the Okta Domain

The agent connects to your Okta org's API endpoint. The Okta Domain is the hostname you log into the admin console with, without scheme or path. Examples:

  • acme.okta.com (production, US cell)
  • acme.okta-emea.com (production, EMEA cell)
  • acme.oktapreview.com (preview org)

Note this value. You will enter it in the Knocknoc wizard.

Step 2: Create the Service Account and API Token

Follow the steps in User Permissions, then Generate an API token. Keep the token value handy.

Step 3: Create the IP Zone

The agent will write to a single IP zone. You can pre-create it, or use an existing one if you already have a Knocknoc-managed zone.

  1. In the Okta admin console, go to Security > Networks
  2. Click Add Zone > IP Zone
  3. Configure the zone:
    • Name: e.g., Knocknoc Authenticated Users
    • Gateway IPs: add at least one sentinel CIDR (e.g., 192.0.2.0/32) so the zone is not empty on creation. Knocknoc replaces this list on the next grant
    • Proxy IPs: leave blank unless you have a specific reason to add them
  4. Click Save
  5. Copy the Network Zone ID by following these instructions.

Step 4: Reference the Zone in a Sign-On Policy

Knocknoc does not create or modify Okta sign-on policies. The zone needs to be referenced by a policy you already have (or one you create) so its membership controls access.

  1. Go to Security > Authentication Policies > Show authentication steps > App sign-in
  2. Click on the Policy that you would like Knocknoc to protect
  3. Edit (or create) a rule on the policy such that the IF condition contains User's IP is in any of the following zones and select the Knocknoc-managed zone
  4. Pair this with whatever THEN action fits your policy (e.g., Allowed when in zone, Denied otherwise)
  5. Save the policy

Step 5: Deploy the Knocknoc Agent

Deploy the Knocknoc orchestration agent with outbound HTTPS (TCP 443) access to your Okta domain.

Step 6: Create Knoc in Knocknoc

  1. Select the CloudFirewall /-> SaaSActive Knoc type
  2. Choose Okta as the Vendor

Step 7: Configure Backend

Field Description
Okta Domain Your Okta org's hostname (e.g., acme.okta.com). No scheme, no trailing slash, no /api/... path.
API Token The API token generated in Step 2. Knocknoc encrypts this at rest.

Step 8: Configure ACL

Field Description
Network Zone ID The nzo... ID copied from Step 3. Knocknoc replaces the zone's gateway list on each grant.

Step 9: Assign Users and Test

  1. Assign users and/or groups to the Knoc
  2. Log in as a test user via the Knocknoc portal
  3. In the Okta admin console, go to Security > Networks, open the zone
  4. Verify the user's IP appears in the Gateway IPs list
  5. Verify access through the Okta-protected app works
  6. On logout or grant expiry, the IP should be removed from the zone

Troubleshooting

Error Codes

The Knocknoc agent reports structured error codes when Okta operations fail. You can find more details on resolving these issues here.

Zone Updates Not Visible

If the IP zone's gateway list never changes:

  1. Confirm the Network Zone ID in the Knocknoc ACL exactly matches the zone ID on Okta
  2. Verify the API user has the Org Administrator or Super Administrator role, which Okta requires to manage network zones
  3. If you recently changed the admin's role, rotate the API token. Okta caches role information on the token
  4. Check the agent logs for HTTP 4xx responses on the PUT to /api/v1/zones/<id>

Okta Documentation References

    Okta API reference: API documentation Network Zones API: zone schema and endpoints Okta rate limits: per-endpoint thresholds Standard Administrator roles: role permissions table
    Back to top