Trigger email alert using API when the Guest user bandwidth limit is exceeded

By esupport posted Apr 16, 2020 01:24 AM


This article is about creating enforcement policy and profile to limit the Guest users based on their bandwidth usage and also send alert email to notify the user and the administrator about the bandwidth usage exceeded.

  • The Insight should be enabled on at least one node in the cluster.
  • SMTP Gateway should be configured and CPPM will require outbound access to the SMTP gateway through None/SSL/StartTLS port.
  • Accounting should be enabled with an interim update in the network devices (NAS/Controller).
  • Interim accounting should be logged with the ClearPass nodes as shown below. Navigation: Administration >> Server Manager >> Server Configuration >> click on the server name >> Service Parameters >> Radius Server.



Note: Email will be triggered every time when the guest user authenticates against the ClearPass, after exceeding their bandwidth Limit.


We can use the Endpoint Context Server action to create an API call to trigger an email. Note: The context server action should be triggered through an enforcement profile. The Insight database will be used to get Guest User accounting (bandwidth usage) details.


Note: This article is mainly focused on restricting access and trigger email using API when the Bandwidth limit is exceeded. Please visit the link below for ClearPass Guest integration or search our community for guest implementation queries.


Enabling Insight:
1. Login to the Publisher (Policy Manager) and navigate to Administration >> Server Manager >> Server Configuration 

2. Select the Publisher or Subscriber node where Insight and Insight Master needs to be enabled.

3. Select "Enable Insight" and "Enable as Insight Master".



Configuring SMTP Server:

1. Configure email gateway in Policy Manager under Administration >> External Servers >> Messaging Setup.

2. Configure SMTP settings and validate using the "Send Test Email" option.


Create a new Filter for Bandwidth Usage:

Add the below SQL query in the authentication source "[Insight Repository]" under Configuration » Authentication » Sources » [Insight Repository] » Attributes » Select "Add more filters"  as below

SQL query used to find the bandwidth usage:

(suminput_bytes+output_bytes/1048576):Integer as bw_today_mb, (suminput_bytes+output_bytes/1073741824):Integer as bw_today_gb from radius_acct where calling_station_id = '%ConnectionClient-Mac-Address}' and start_time between date_trunc'day'now)) and date_trunc'day'now+interval '1 day');


Create API Client ID:

1. Navigate to Guest >> Administration >> API Services >> API Clients >> Create API client, as shown below.

2. Copy "Client ID" and "Client secret" to use it in the endpoint context server configuration.



Configuring Endpoint Context Server:

1. Navigate to ClearPass Policy Manager >> Administration >> External Servers >> Endpoint Context Servers and select "localhost".

Note: If the Endpoint Context Server "localhost" is already in use, then it is recommended to create a new context server and follow the below sample configuration.

2. Select Authentication Method as "OAuth2", enter client id and secret.

3. Checked "Validate" option to check if the connection is working.



Creating Context Server Actions:

1. Navigate to ClearPass Policy Manager >> Administration >> Dictionaries >> Context Server Actions >> Add

2. Under Action, select Server Type: Generic HTTP, Server Name: localhost, Action Name, HTTP Method: POST, Authentication Method: None and URL: /api/email/send

3. Enter the below Header Names.

4. Enter the below JSON attributes in the Content field:

Content-Type: JSON


  "to": ["%{GuestUser:Email}",""],
  "subject": "Bandwidth Usage Exceeded",
  "message": "You have exceeded the daily Bandwidth usage",
  "headers": {"Content-Type":"text/plain; charset=UTF-8"}

Note: Modify the To, Subject and messages based on the requirement.

Model Schema for Content:


to (object, optional): List of Recipients Email Address (e.g., ["", ""]),

subject (string, optional): Email Subject,

message (string, optional): Email Body,

cc_recipients (object, optional): List of CC recipients Email Address (e.g., ["", ""]),

bcc_recipients (object, optional): List of BCC recipients Email Address (e.g., ["", ""]),

headers (object, optional): Email headers (e.g., {"Content-Type":"text/plain; charset=UTF-8","Content-Transfer-Encoding": "8bit"})


Service Configuration:

1. To create enforcement profile, navigate to Configuration >> Enforcement >> Profile >> Add >> HTTP Based Enforcement

2. Select Endpoint Context server and Context server action as shown below.

3. Modify "MAC Caching Bandwidth Limit" to set the bandwidth restriction:

Note: Example shows 1 GB per day. We can modify Limit-Units and Allowed-Limit based on the requirement.

4. Navigate to Configuration >> Services and select the service created for Guest Bandwidth Restriction. 

5. Add "[Insight Repository]" as a  Authorization source in the Guest Authentication service.

6. Create new enforcement policy to check if the bandwidth usage is more than the limit:

7. In the below example, usage restriction set to 1 GB per day.

(Tips:Role  EQUALS  [Guest]) 
 AND  (Authorization:[Insight Repository]:bw_today_gb  GREATER_THAN_OR_EQUALS  1)



Users should not be able to access internet/restricted access after exceeding the bandwidth usage. If ClearPass sends different role for limited access then it can be confirmed from Access Tracker and on the NAS (Controller/Switch).


The email alert sent will be logged in the Application logs, under ClearPass Guest >> Administration >> Support >> Application Log.


Sample Email alert:



Enforcement profile attached. We can restore this in Configuration >> Enforcement >> Profiles >> Import.

It will restore the below configuration:

  • Enforcement Profile: API SMTP Profile
  • Endpoint Context Servers: localhost
  • Context Server Actions: API SMTP

Note: Update Endpoint context server with correct oauth2 credentials.