Microsoft Entra

Overview

This integration uses both a bash script and PowerShell script to execute. The powershell script is designed to manage named locations in Microsoft Azure Conditional Access policies via the Microsoft Graph API. It allows users to add, delete, or flush named locations related to specific IP addresses. The primary use case is to automate the management of named locations in a secure and efficient manner.

This integration with knocknoc enables IP whitelisting within Microsoft 365. An example of a user's experience can be found below:

User attempts to access Microsoft 365 services:
User must authenticate with knocknoc and will see their granted ACL on the right hand side:
User can now access Microsoft 365 services:

Prerequisites

Before running this script, ensure that you have the following prerequisites installed and configured:

Powershell - Install PowerShell on your system. For Linux, follow these steps:

# Update the list of packages
sudo apt-get update

# Install pre-requisite packages
sudo apt-get install -y wget apt-transport-https software-properties-common

# Download the Microsoft repository GPG keys
wget -q https://packages.microsoft.com/config/ubuntu/20.04/packages-microsoft-prod.deb

# Register the Microsoft repository GPG keys
sudo dpkg -i packages-microsoft-prod.deb

# Update the list of packages after we added the Microsoft repository
sudo apt-get update

# Install PowerShell
sudo apt-get install -y powershell

Azure Enterprise Application: An enterprise application must be created to allow knocknoc to authenticate and change conditional access policies and named locations. Create an enterprise application, create a client secret, and copy the application's client id, azure tenant id and secret. You'll need these later.
Microsoft Graph API Permissions: Ensure that the application has the necessary permissions to access the Microsoft Graph API, particularly for managing conditional access policies and named locations.
Conditional Access Policy/Policies: Knocknoc needs to be able to distinguish between policies it can amend and policies it cannot. Therefore, knocknoc looks for a prepending "knocknoc_" ahead of the name of the ACL. For example, a conditional access policy might be named "knocknoc_financedepartment" with specific rules around applications and services that group can access. These must be created PRIOR to configuring anything in the knocknoc admin portal.
Credentials File: Ensure that a credentials file is present at /opt/knocknoc-agent/etc/entra-credentials.sh with the following content:
```
entra_clientid=""
entra_tenantid=""
entra_clientsecret=""
```
You will need to input the necessary ClientID for your Azure Enterprise Application, your Azure Tenant ID and your application's client secret.

Script Parameters

action: Specifies the action to perform. Valid values are add, del, and flush.
acl: The name of the access control list.
ip: The IP address to add or delete (required for add and del actions).
ClientId: The client ID of your Azure AD application (sourced from the credentials file).
TenantId: The tenant ID of your Azure AD (sourced from the credentials file).
ClientSecret: The client secret of your Azure AD application (sourced from the credentials file).

Script Details

The script begins by initializing a location cache to store existing named locations.
Depending on the specified action (add, del, or flush), the script performs the corresponding operation.
For the add action, the script creates a named location and updates the specified conditional access policy to exclude this location.
For the del action, the script removes the specified named location from all policies and then deletes the named location itself.
For the flush action, the script removes all named locations that match the pattern knocknoc_* from all policies.