Skip to main content

Cisco Meraki

Knocknoc integrates with Cisco Meraki to dynamically control which source IPs are allowed through Meraki MX firewall policy. The integration uses the Meraki Dashboard API to maintain a single Policy Object Group per Knoc. The orchestration is performed by a Knocknoc orchestration Agent which is subscribed to the central Knocknoc Server.

As users authenticate to Knocknoc and grants expire, the agent creates and deletes CIDR Policy Objects and adds or removes them from the group. A Meraki firewall rule that references the group (as GRP(id)) then gates traffic on whether the user's current IP is a member. Because Meraki is cloud-managed, membership changes propagate to your MX appliances automatically: there's no feed to host and nothing to refresh.

Active only. Meraki MX cannot consume an external dynamic IP feed (there is no EDL equivalent), so Knocknoc manages Meraki actively via the Dashboard API. There is no passive Meraki mode.

Authentication

The Knocknoc agent authenticates with a Dashboard API key. The key is bound to a Dashboard administrator and carries that administrator's organisation access. Knocknoc sends it as the Authorization: Bearer <key> header documented by Meraki.

Generate an API key

  1. Log into the Meraki Dashboard
  2. Open your account profile (top-right menu) and find the API access section
  3. Enable API access and generate a new key. The Dashboard shows it once, so copy it
  4. Prefer a dedicated administrator account for this key so access can be scoped and audited

You'll paste this value into the Dashboard API key field in the Knocknoc wizard.

Permissions

Use a dedicated Dashboard administrator for the API key with access to the target organisation and permission to manage policy objects and firewall rules. Read-only administrators can't manage policy objects.

Setup

Knocknoc maintains a single Policy Object Group and rewrites its membership as users come and go. A firewall rule references the group by ID.

Step 1: Note the Organisation ID

The Organisation ID appears in the Dashboard URL after you sign in, and under Organisation > Settings. Note this value for the wizard.

Step 2: Create the API key

Follow Generate an API key. Keep the key value handy.

Step 3: Create the Policy Object Group

  1. In the Dashboard, go to Organisation > Policy Objects
  2. Create a group (e.g. Knocknoc Authenticated Users). It can start empty, as Knocknoc manages its membership
  3. Open the group and copy its ID (the numeric or opaque identifier used by the API)

Dedicate one group per Knoc. Knocknoc owns the group's entire membership: it adds and removes CIDR policy objects as users come and go, and clears the group's membership when the Knoc is flushed. Don't point two Knocs at the same group, and don't add objects to the group manually, as manual entries are detached on the next flush. If you need static allow-list entries, put them in a separate group and reference both groups from your firewall rule.

Step 4: Reference the Group in a Firewall Rule

Knocknoc doesn't create firewall rules. Reference the group in a rule so its membership controls access.

  1. Edit the relevant MX Layer 3 firewall (or other supported) ruleset
  2. In a rule's source, reference the group as GRP(<id>)
  3. Pair it with the action that fits your policy (e.g. allow to a protected destination)
  4. Save the rule

Step 5: Deploy the Knocknoc Agent

Deploy the Knocknoc orchestration agent with outbound HTTPS (TCP 443) access to api.meraki.com (or your regional host, e.g. api.meraki.cn).

Step 6: Create Knoc in Knocknoc

  1. Select the Cloud / SaaS Knoc type
  2. Choose Cisco Meraki as the Vendor

Step 7: Configure Backend

Field Description
Dashboard API key The API key generated in Step 2. Knocknoc encrypts this at rest.
Organisation ID The organisation that contains your policy object group (from Step 1).
Dashboard base URL Optional. Override only for non-default regions (e.g. https://api.meraki.cn). Blank uses the default.

Step 8: Configure ACL

Field Description
Policy object group ID The group ID copied in Step 3. Knocknoc owns the group's entire membership, so dedicate one group per Knoc (see the note in Step 3).

Step 9: Validate, Assign Users, and Test

  1. Use the wizard's Validate connection step. It checks Dashboard reachability, organisation access, and that the group exists
  2. Assign users and/or groups to the Knoc
  3. Log in as a test user via the Knocknoc portal
  4. In the Dashboard, open the group under Organisation > Policy Objects and confirm a knoc--prefixed object for the user's IP appears
  5. Confirm access through the Meraki-protected path works, and that the object is removed on logout or grant expiry

Scale Note

Knocknoc creates one Policy Object per active grant. Meraki caps the number of policy objects per organisation. For high-volume Knocs, monitor the policy object count. Knocknoc removes objects on revoke, expiry, and flush to keep the working set bounded.

Troubleshooting

Agent Logs

Start with the orchestration agent logs. Common problems:

  • Authentication failed: the API key is invalid or was regenerated. Update the Knocknoc backend configuration. See MERA001.
  • Authorisation failed: the key's administrator can't access the configured organisation, or the Organisation ID is wrong. See MERA002.
  • Policy object group not found: the Policy object group ID points at a deleted group or one in a different organisation. See MERA102.
  • Rate limited: the Dashboard is throttling the organisation's API. The agent backs off automatically and retries. See MERA005.

Membership Not Visible

  1. Confirm the Policy object group ID in the Knocknoc ACL exactly matches the group ID in the Dashboard
  2. Confirm the firewall rule references the group as GRP(id)
  3. Confirm the API key administrator can manage policy objects
  4. Check the agent logs for HTTP 4xx responses

Error Codes

The Knocknoc agent reports structured error codes when Meraki operations fail. They appear in logs as (agent error #MERANNN) description. The full reference is in the Meraki agent error codes chapter.

Code Description Common Causes
MERA000 Failed to connect to the Meraki Dashboard Host unreachable, DNS failure, or proxy blocking outbound HTTPS.
MERA001 Meraki authentication failed Invalid or regenerated API key (HTTP 401).
MERA002 Meraki authorisation failed Key lacks access to the organisation, or wrong Organisation ID (HTTP 403).
MERA003 Meraki Dashboard TLS/SSL certificate error TLS-intercepting proxy or stale CA bundle on the agent host.
MERA004 Meraki Dashboard connection timed out Network timeout between the agent and the Dashboard.
MERA005 Meraki Dashboard API rate limit exceeded Org API budget exhausted (HTTP 429). The agent backs off automatically.
MERA050 Failed to read the Meraki organisation Wrong Organisation ID, or the key lacks access.
MERA100 Failed to read the policy object group Transient error, rate limit, or wrong group ID.
MERA101 Failed to update the policy object group Transient error, rate limit, or insufficient write access.
MERA102 Policy object group not found The group ID points at a deleted or wrong group (HTTP 404).
MERA150 Failed to create a policy object Organisation policy-object limit reached, or insufficient access.
MERA151 Failed to delete a policy object Transient error or insufficient access. Leaves an orphan object.
MERA152 Failed to read a policy object Transient error, or the object was deleted out-of-band.
MERA400 Invalid response from the Meraki Dashboard A proxy or captive portal is altering the response body.

Meraki Documentation References

Back to top