Integrating external systems through the ClearPass API

Notes from reading documentation, not results from testing on a live system. Main source: the Infoblox–Aruba ClearPass integration Deployment Guide (01/2020). Each point carries a page citation at the end; anything that could not be verified is marked.

For an external system to push data into ClearPass so that policy can use it, the ClearPass side needs four pieces. In the sample permission set, the line most worth scrutinizing is Identity – Endpoints: Read, Write — the right to write to endpoint records; the other lines are narrower or read-only.

The four pieces¹:

1. Custom endpoint attributes — somewhere to hold the data the other system sends over.
2. Operator Profile — the minimum permission set for the integration.
3. API Client — a machine-to-machine identity, using OAuth 2.0 client_credentials.
4. Enable Insight — a hard requirement.

This note describes that framework; the concrete example comes from the Infoblox integration (DNS security and IPAM), but the first three steps are reusable for any integration of this kind.

Details

1. Custom endpoint attributes

Data from outside has no place to land by itself — you have to create it first. Each attribute is declared with Entity = Endpoint, a data type, and in the Infoblox example all of them are set to Is Mandatory = No and Allow Multiple = No¹.

The set of attributes Infoblox writes over illustrates the kind of data being sent — part network context, part threat assessment results¹:

Attribute	Type	Content
Infoblox DHCP Fingerprint	String	the device’s DHCP fingerprint, if known
Infoblox Last Known IP	String	the IP address registered in IPAM
Infoblox Managed	Boolean	whether IPAM manages this device
Infoblox Threat Category	String	the type of threat seen on the device
Infoblox Threat Detection Device IP	String	IP of the DNS server that detected it
Infoblox Threat Name	String	the domain name requested
Infoblox Threat Severity	List	severity
Infoblox Threat Status	List	handled or not
Infoblox RuleId · Infoblox RuleCategory	Integer · Text	which rule matched and which group it belongs to

These attributes can then be used like any other endpoint attribute in role mapping and enforcement — the same way as attributes produced by profiling.

2. Operator Profile — least privilege

Created under Administration → Operator Logins → Profiles in ClearPass Guest: choose the Custom level, then enable exactly the permissions needed¹. The permission set for Infoblox:

Group	Permission	Level
Administrator	Plugin Manager	Full
API services	Allow API Access	Allow Access
Guest Manager	Active Sessions	Full
Guest Manager	Active Sessions History	Read Only
Guest Manager	Create Multiple Guest Accounts	Full
Guest Manager	Create New Guest Account	Read Only
Guest Manager	Full User Control	Read Only
Insight	Administration	Read
Policy Manager	Identity – Endpoints	Read, Write

The line that matters is Identity – Endpoints: Read, Write — that is the permission that lets the external system write to endpoint records. The other lines are narrower or read-only.

3. API Client

Created under Administration → API Services → API Clients¹:

• Set a Client ID.
• Assign the Operator Profile built in step 2 — this is where permissions get attached to the machine identity.
• Grant Type: Client credentials (grant_type=client_credentials) — a machine-to-machine flow, with no user logging in.
• Write down the Client Secret; it is shown only once and the other side will need it.

Unverified. The document does not say whether the Client Secret can be rotated, how it expires, or how to revoke it. I have no source yet for the lifecycle of this key.

4. Enable Insight

Administration → Server Manager → Server Configuration → select the server → System tab → check Enable Insight Current → Save¹.

The external system’s side (Infoblox example)

The general shape: event → filter → template → REST API endpoint → ClearPass¹.

• Requires a Security Ecosystem License, of type Grid Wide (activates the service on every appliance in the same Grid).
• The admin group must have the API interface enabled.
• The template is uploaded under Grid → Ecosystem → Templates; the Client ID and Client Secret go into Aruba_Session.json (variable names Client_ID and KEY, case-sensitive).
• REST API Endpoint: the URI must be ClearPass’s FQDN, Vendor Type set to Aruba ClearPass, plus API access accounts on both sides. A client certificate and server certificate validation are optional, used when you want the connection encrypted.
• A Notification ties events to the template.

Supported events: DNS RPZ (malicious or unwanted DNS queries) · DNS Tunneling (data exfiltration) · DHCP Leases · Object Change for IPv4/IPv6 Fixed Address and Host Address · Security ADP · Network Discovery¹.

On its side, Infoblox also uses extensible attributes to control behavior: Aruba_Sync (whether to push this asset to ClearPass), Aruba_Secure (whether to update security attributes), Aruba_Location, plus two timestamps Aruba_LastSecurityEvent and Aruba_SyncedAt¹.

Good practice and how to test

The document states¹:

• In production, keep log level at Info or above (Warning, Error); use Debug only while testing.
• Keep notification filters as narrow as possible — this is performance advice, and it also avoids flooding ClearPass with events.
• For RPZ, enable “Enable RPZ event deduplication”.

A way to test without staging a real attack: go to Dashboards → Status → Security, enter a domain that is blocked by an RPZ list included in the notification, click Perform Dig; then check the result under Grid → Ecosystem → Outbound Endpoint → View Debug Log¹.

A note on the source. This document has real editing errors: page 11 still has a stray “Lorem ipsum” passage between the steps, and the table of contents has an entry named “Heading Level 2”. Although it says it was developed together with HPE Aruba, it should be rated below carefully edited vendor documents, and each step should be double-checked before following it.

The document also points to three other Infoblox integrations via external URLs (Endpoint Context Server in CPPM 6.7; MAC Address Filter updates; and sample code in the aruba/clearpass-exchange-snippets repo for IPAM-based authorization)¹ — I have not opened those sources, so they are unchecked.

Related

• ClearPass Policy Manager · ClearPass Access Tracker
• Operating ClearPass from the CLI (appadmin) — system create-api-client creates an API client straight from the CLI, no UI needed

Sources

Footnotes

1. Infoblox Integration with Aruba ClearPass — Deployment Guide (01/2020), PDF pp. 3–23 ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹ ↩¹⁰ ↩¹¹ ↩¹²