Skip to main content

Microsoft Entra

Knocknoc integrates with Microsoft Entra ID (formerly Azure AD) to dynamically control which IPs are allowed to sign in through Conditional Access. The integration uses the Microsoft Graph API to maintain a single IP Named Location.

As users authenticate to Knocknoc and grants expire, the Named Location's ipRanges list is updated. Conditional Access policies that reference the Named Location (typically a Block policy when the user is not in the trusted location, or a Require MFA / allow policy when they are) gate sign-in on whether the user's current IP is present.

Authentication

The Knocknoc agent authenticates to Microsoft Graph as an app registration using the OAuth 2.0 client-credentials flow. It needs three values:

  • Tenant ID: the directory (tenant) ID the app registration lives in
  • Client ID: the application (client) ID of the app registration
  • Client Secret: a secret value generated under the app registration's Certificates & secrets

Knocknoc uses application permissions (not delegated). The agent acts as the app itself, not on behalf of a user.

Create the app registration

  1. In the Azure portal, navigate to Microsoft Entra ID > App registrations > + New registration
  2. Name it (e.g., knocknoc-agent), leave Supported account types at the default (single tenant), and click Register
  3. On the app's Overview page, copy the Application (client) ID and Directory (tenant) ID

Create a client secret

  1. Open the app registration's Certificates & secrets blade
  2. Click + New client secret
  3. Give it a description (e.g., knocknoc-agent-secret) and pick an expiry. Entra caps secrets at two years
  4. Click Add and immediately copy the Value (not the Secret ID). Entra only shows the value once

You will paste these three values into the Knocknoc wizard.

App Permissions

The app registration needs one Microsoft Graph application permission: Policy.ReadWrite.ConditionalAccess. This permission covers reading and updating Named Locations and Conditional Access policies. No other permissions are required.

  1. In the app registration, open API permissions
  2. Click + Add a permission > Microsoft Graph > Application permissions
  3. Search for Policy.ReadWrite.ConditionalAccess and tick the box
  4. Click Add permissions

The permission now appears in the list with a yellow warning that admin consent has not been granted.

A Privileged Role Administrator (or Global Administrator) must consent on behalf of the tenant before the permission takes effect:

  1. In the same API permissions blade, click Grant admin consent for <tenant>
  2. Confirm the consent prompt
  3. The Status column for Policy.ReadWrite.ConditionalAccess should turn into a green tick

Without admin consent the agent will see HTTP 403 on every Named Location call.

Setup

Knocknoc maintains a single IP Named Location in Entra and rewrites its ipRanges list as users come and go. Conditional Access policies reference the Named Location by ID.

Step 1: Create the App Registration

Follow the steps in Authentication and App Permissions. Note the Tenant ID, Client ID, and Client Secret value.

Step 2: Create the IP Named Location

  1. In the Azure portal, navigate to Microsoft Entra ID > Security > Conditional Access > Named locations
  2. Click + IP ranges location (not + Countries location)
  3. Configure the location:
    • Name: e.g., Knocknoc Authenticated Users
    • Mark as trusted location: tick this if your Conditional Access policy depends on the trusted-location flag (recommended)
    • IP ranges: add at least one sentinel CIDR (e.g., 192.0.2.0/32) so the location is not empty on creation. Knocknoc replaces this list on the next grant
  4. Click Create
  5. Open the new Named Location and copy the ID (a GUID) from the browser URL

Step 3: Reference the Named Location in a Conditional Access Policy

Knocknoc does not create or modify Conditional Access policies. The Named Location needs to be referenced by a policy you already have (or one you create) so its membership controls sign-in.

  1. Go to Conditional Access > Policies
  2. Edit or create a policy. Under Conditions > Locations, include or exclude the Knocknoc-managed Named Location
  3. Pair this with whatever Grant / Block outcome fits your policy (e.g., Block when Not in the trusted location)
  4. Save the policy

Step 4: Deploy the Knocknoc Agent

Deploy the Knocknoc orchestration agent with outbound HTTPS (TCP 443) access to:

  • login.microsoftonline.com (token endpoint)
  • graph.microsoft.com (Named Location API)

Step 5: Create Knoc in Knocknoc

  1. Select the Cloud / SaaS Knoc type
  2. Choose Microsoft Entra ID as the Vendor

Step 6: Configure Backend

Field Description
Tenant ID The Directory (tenant) ID from the app registration's Overview page (a GUID).
Client ID The Application (client) ID from the app registration's Overview page (a GUID).
Client Secret The opaque Value (not the Secret ID) of the client secret created in Step 1. Knocknoc encrypts this at rest.

Step 7: Configure ACL

Field Description
Named Location ID The GUID copied from Step 2. Knocknoc replaces the Named Location's ipRanges on each grant.

Step 8: 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 Azure portal, navigate to Conditional Access > Named locations and open the Named Location
  4. Verify the user's IP appears in the IP ranges list
  5. Verify sign-in to an Entra-protected app behaves as your Conditional Access policy dictates
  6. On logout or grant expiry, the IP should be removed from the Named Location

Troubleshooting

Agent Logs

Start by checking the orchestration agent logs. Common problems:

  • Authentication failed: the Tenant ID, Client ID, or Client Secret is wrong, or the secret has expired. Check the secret's expiry in Certificates & secrets. See ENTRA001.
  • Authorization failed: the app registration is missing Policy.ReadWrite.ConditionalAccess or admin consent has not been granted. See ENTRA002.
  • Named Location not found: the Named Location ID points at a deleted location, or at a location in a different tenant. See ENTRA052.
  • Wrong location type: the configured Named Location is a country location, not an IP location. See ENTRA053.
  • Throttled: Microsoft Graph is throttling the tenant. The agent backs off automatically. See ENTRA005.

Named Location Updates Not Visible

If the Named Location's IP ranges never change:

  1. Confirm the Named Location ID in the Knocknoc ACL exactly matches the ID in the Azure portal (compare the GUIDs)
  2. Confirm the app registration has the Policy.ReadWrite.ConditionalAccess application permission (not the delegated variant) and admin consent is granted
  3. Check the agent logs for HTTP 4xx responses on the PATCH to /v1.0/identity/conditionalAccess/namedLocations/<id>

Conditional Access Policy Not Triggering

If IPs land in the Named Location correctly but Conditional Access does not behave as expected:

  1. Confirm the Conditional Access policy is On, not Report-only
  2. Confirm the policy references the Knocknoc-managed Named Location under Conditions > Locations
  3. Use Conditional Access > What If to simulate the sign-in with the user's current IP and see which policy applies

Error Codes

The Knocknoc agent reports structured error codes when Entra operations fail. These appear in agent logs and are forwarded to the Knocknoc server.

Error codes show up as (agent error #ENTRA0NN) description in log output.

Connection and Authentication (ENTRA000-ENTRA049)

Code Description Common Causes
ENTRA000 Failed to connect to Microsoft Graph The agent host cannot reach login.microsoftonline.com or graph.microsoft.com.
ENTRA001 Microsoft Entra authentication failed Wrong Tenant ID, Client ID, or Client Secret; or the secret has expired.
ENTRA002 Microsoft Entra authorization failed App registration missing Policy.ReadWrite.ConditionalAccess or admin consent. See App Permissions.
ENTRA003 Microsoft Graph TLS/SSL certificate error TLS proxy in the path or stale CA bundle on the agent host.
ENTRA004 Microsoft Graph connection timed out Network timeout. Check connectivity from the agent to Microsoft Graph.
ENTRA005 Microsoft Graph API throttled The tenant has hit the Conditional Access API rate limit. The agent backs off automatically.

Named Location Operations (ENTRA050-ENTRA099)

Code Description Common Causes
ENTRA050 Failed to get Entra Named Location A 4xx/5xx other than 404 reading the location. Check the agent logs for the underlying status.
ENTRA051 Failed to update Entra Named Location PATCH to update ipRanges was rejected. May indicate a malformed CIDR or a concurrent modification.
ENTRA052 Entra Named Location not found The Named Location ID points at a deleted location or a location in a different tenant.
ENTRA053 Entra Named Location is not an IP-based location The Named Location exists but is a country location. Recreate it as an IP location.
ENTRA054 Invalid or unexpected response from Microsoft Graph A proxy or captive portal is altering the response body. Check the network path.

Microsoft Documentation References

Back to top