> For the complete documentation index, see [llms.txt](https://docs.oort.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.oort.io/integrations/cisco-identity-services-engine-ise.md).

# Cisco Identity Services Engine (ISE)

## Overview 

Cisco Identity Intelligence connects to Cisco Identity Services Engine (ISE) through a secure, on-premises agent to collect identity, device, network session, authentication, and deployment health data from ISE and provide visibility into connected users and devices, ISE infrastructure health, and authentication activity.\
\
The goal of this guide is to help you configure the integration between Identity Intelligence and your organization’s ISE environment, including deploying the agent, configuring pxGrid, verifying the connection, and troubleshooting common issues.

### Quick path 

1. Prepare ISE and the agent host. Enable the required ISE services and verify network connectivity. 
2. Create the ISE integration. In Cisco Identity Intelligence, open Integrations, choose Cisco ISE, and enter a meaningful name and optional description. 
3. Capture the one-time deployment material. Download the agent package or copy the one-line installation command before leaving the setup page. 
4. Run the installer on an on-premises host. Use a dedicated directory on a host that can reach ISE and the required outbound cloud endpoints. 
5. Enter and verify ISE credentials. Setup validates the required ISE APIs before saving credentials in an encrypted store. 
6. Configure required pxGrid access. The agent requires pxGrid for real-time session events. 
7. Approve a new pxGrid client. If the agent registers a new client, approve it in ISE Client Management. 
8. Verify a healthy startup. Confirm pxGrid is active, IoT Core is connected, collection has started, and a fresh heartbeat appears in the ISE dashboard. 

## 1. Prepare ISE and the agent host 

#### Agent host prerequisites 

* Docker with Compose, or Podman with podman compose or podman-compose. 
* Cisco ISE 3.3 or later with ERS, the required endpoint APIs, and pxGrid enabled. 
* Network access from the agent host to the configured ISE API port, which defaults to TCP 443 during setup. 
* Network access from the agent host to ISE pxGrid services on TCP 8910. 
* Outbound TCP 443 to the environment-specific IOT\_ENDPOINT in .env, GitHub release and GHCR endpoints, and signed S3 upload hosts. 
* If outbound access uses a proxy, the proxy must allow HTTP CONNECT on port 443. Enter it using an `http://` URL during credential setup. 
* Create a dedicated internal ISE administrator account for the agent with:
  * ERS Operator for the required ERS and endpoint API access
  * MnT Admin for Monitoring API access used by health and active-session checks
  * Use ERS Admin instead of ERS Operator if you would like to be able to perform write actions

#### ISE-side preparation 

* Enable pxGrid services and arrange for an ISE administrator to approve the agent client
* Ensure the selected ISE host is reachable from the agent host
* Ensure TCP 8910 is available between the agent host and the applicable pxGrid nodes
* Enable password-based pxGrid account creation
  * A Cisco ISE Super Admin or System Admin must navigate to **Administration** > **pxGrid Services** > **Settings**, then select "Allow password based account creation" and **Save**
  * This setting is disabled by default and is required for the agent to create its pxGrid account. It is separate from enabling the pxGrid service on an ISE deployment node

Cisco Identity Intelligence does not connect directly to the customer ISE environment. ISE communication originates from the on-premises agent. 

{% hint style="warning" %}
**Protect the deployment material:** The package and copied command contain a sensitive, one-time bootstrap token. Transfer them only to the intended agent host, do not paste them into tickets or chat, and restrict access to the installation directory. The agent private key is generated locally during setup.
{% endhint %}

### 2. Create the Cisco ISE integration within Identity Intelligence

<img src="/files/1eUBKiZEBfM9IvxWZbHd" alt="" height="285" width="609">

1. Using an Admin role in Cisco Identity Intelligence, navigate to **Integrations** and select **Cisco ISE**&#x20;
2. Enter a name and (optional) description into the form. Be sure to use a name that easily identifies the ISE cluster or location
3. Select **Generate ISE Agent Package.** Identity Intelligence will then provision the agent identity, and display the deployment package and copyable install command&#x20;
4. Save the deployment material *immediately*. Use **Download ISE Agent Package** or C**opy Command**. <mark style="color:$danger;">Note:</mark> You **must** save these credentials as they **cannot** be displayed again after leaving the setup page; if replacement material is generated and deployed, the running agent credentials are rotated.&#x20;

<img src="/files/cunXQaWTUdA0PeeghnFO" alt="" height="264" width="609">

### 3. Install the agent on premises&#x20;

Use a dedicated, access-controlled directory. **Do not** run the installer from a directory containing unrelated environment, certificate, Compose, or launcher files.

#### Option A — one-line install command&#x20;

```
mkdir -p ~/ise-agent 
cd ~/ise-agent 
# Paste the complete command copied from Cisco Identity Intelligence, then press Enter 
```

The installer downloads the released host tools, creates the deployment files, completes the one-time agent setup, and starts credential and pxGrid configuration in the terminal.&#x20;

**Do not edit** tenant IDs, agent IDs, the IoT endpoint, topic prefix, certificate, or private key

#### Option B — downloaded ZIP&#x20;

1. Copy the ZIP to the agent host using your organization-approved secure transfer method&#x20;
2. Extract it into a dedicated directory. Change into the directory that contains `.env`, `start.sh`, `docker-compose.yml`, and certs&#x20;
3. Restore executable permissions if necessary and start the agent

```
cd ~/ise-agent
chmod +x ./start.sh
./start.sh
```

<img src="/files/zQ8xWtcheRd2PdrgrVOe" alt="" height="349" width="609">

#### What the credential setup validates&#x20;

| ISE Host, Username, Password, Port | Saved in an encrypted credential store under certs. The password is not written to `.env`                          |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| HTTPS Proxy (optional)             | Used for AWS IoT Core and signed S3 egress. Leave blank for direct access and use an `http://` URL when configured |
| ERS API verified                   | The agent reached ISE and the account had access to the required ERS API                                           |
| Endpoints API verified             | The account had access to the endpoint information required by the integration                                     |
| HTTP 401                           | The username or password was rejected. Nothing is saved                                                            |
| HTTP 403                           | Authentication reached ISE, but the account lacks access to the identified API. Nothing is saved                   |
| Other HTTP error                   | ISE returned an unexpected response. Nothing is saved                                                              |
| Connection error or timeout        | The agent host cannot reach the configured ISE host and API port. Nothing is saved                                 |
| Proxy connection verified          | Setup established an authenticated connection to AWS IoT Core through the configured proxy                         |

### 4. Configure required pxGrid access&#x20;

pxGrid is required to ingest real-time session events and the complete session information expected by Cisco Identity Intelligence. First-run setup proceeds directly to pxGrid configuration. \
\
Ensure password-based pxGrid account create is enabled. See [ISE side preparations](#ise-side-preparation) section above for more info.

<img src="/files/gDBz8IaJgVIsDgk6PTte" alt="" height="349" width="609">

#### Register a new pxGrid client&#x20;

1. Choose a pxGrid node name. Accept `cii-agent` or enter a deployment-specific name
2. When asked whether you already have an approved pxGrid client, answer `N`&#x20;
3. Start the agent and note the client name shown in the logs
4. In ISE, go to **Administration** > **pxGrid Services** > **Client Management** > **Clients**&#x20;
5. Find and approve the displayed client
6. Follow the logs and confirm account activation, WebSocket connection, session synchronization, and session-topic subscription&#x20;

#### Use existing pxGrid credentials

1. Enter the approved pxGrid node name
2. Answer `Y` when asked whether approved credentials already exist
3. Enter the pxGrid password
4. Start the agent and verify successful activation and subscription&#x20;

#### Reconfigure pxGrid later &#x20;

```
./start.sh --enable-pxgrid 
```

This replaces the stored pxGrid configuration and restarts the deployment.

### 5. Verify the first connection&#x20;

1. Find the generated container name. Read the `container_name` line from `docker-compose.yml` . Do **NOT** assume a fixed suffix&#x20;
2. Confirm the container is running. Use the Compose or Podman status command for your runtime&#x20;
3. Follow agent logs. Look for the healthy markers below and investigate any errors before continuing&#x20;
4. Confirm IoT Core connectivity as well as pxGrid activation and session subscription. A heartbeat starts immediately and then repeats every 60 seconds by default. Verify Connected to Iot Core and Agent connected, pxGrid account activated and WebSocket connected, Last Heartbeat, ISE Reachable, agent version, nodes, and current session information synchronized
5. Complete the setup page by returning to the **Integrations** page within Identity Intelligence. Select the existing ISE integration and select **Agent is running** after the first heartbeat is visible&#x20;

```
grep 'container_name:' docker-compose.yml

# Docker 
docker compose ps 
docker logs --tail 200 -f <container_name>

# Podman 
podman ps 
podman logs --tail 200 -f <container_name>
```

<img src="/files/M9j1JoJQBWGMAY8Ntfhn" alt="" height="349" width="609">

\
You will now see something similar to the screenshot below when you navigate to the ISE menu item in Identity Intelligence:&#x20;

<img src="/files/iWZKzPoWwcqoDTReWE33" alt="" height="285" width="609">

### 6. Supported host commands&#x20;

<table data-header-hidden data-search="false"><thead><tr><th width="274.9296875"></th><th></th></tr></thead><tbody><tr><td><strong>Command</strong> </td><td><strong>Use</strong> </td></tr><tr><td><code>./start.sh</code> </td><td>Pull the released image once, run first-time setup when needed, and start the agent </td></tr><tr><td><code>./start.sh --reconfigure</code></td><td>Re-enter ISE credentials and the optional outbound proxy; restart with the new encrypted values </td></tr><tr><td><code>./start.sh --enable-pxgrid</code> </td><td>Configure or replace pxGrid state, then restart</td></tr><tr><td><code>./start.sh --update</code> </td><td>Pull ghcr.io/duosecurity/ise-agent:latest and restart the deployment</td></tr><tr><td><code>./start.sh --no-pull</code> </td><td>Start using an already-loaded local image. Use only for offline or explicitly preloaded-image environments</td></tr><tr><td><code>./start.sh --update --no-pull</code> </td><td>Skip the pull and restart the already-loaded local image</td></tr><tr><td><code>./start.sh --stop</code> </td><td>Stop and remove the Compose-managed agent container without deleting the installation files or encrypted credentials</td></tr></tbody></table>

#### Safely reconfigure ISE credentials&#x20;

Stop the running deployment before replacing ISE credentials or proxy settings.&#x20;

```
./start.sh --stop 
./start.sh --reconfigure 
```

{% hint style="info" %}
**COMMAND RULE** \
Use only one action flag at a time. `--no-pull` is the exception: it is a modifier that can accompany startup or `--update`.&#x20;
{% endhint %}

### 7. Troubleshooting workflow&#x20;

#### Step 1 — establish the local state&#x20;

```
pwd 
ls -la 
test -f .env && echo '.env present' 
test -f certs/certificate.pem.crt && echo 'certificate present' 
test -f certs/private.pem.key && echo 'private key present' 
grep 'container_name:' docker-compose.yml 
```

{% hint style="warning" %}
**DO NOT ATTACH SECRETS**\
Never include `.env`, `certs/private.pem.key`, certificate bundles, `.credentials.enc`, .`pxgrid.enc`, or the one-line bootstrap command in a support ticket. Be sure to always redact tenant IDs, agent IDs, hostnames, usernames, and IoT endpoint prefixes from logs when required by policy.&#x20;
{% endhint %}

#### Step 2 — inspect container status and logs&#x20;

```
# Docker 
docker compose ps 
docker logs --tail 200 <container_name> 
 
# Podman 
podman ps -a 
podman logs --tail 200 <container_name> 
```

<table data-header-hidden><thead><tr><th width="199.83984375"></th><th></th></tr></thead><tbody><tr><td><strong>Symptom</strong> </td><td><strong>Next action</strong> </td></tr><tr><td>No container runtime found </td><td>Install Docker with Compose or Podman with a Compose provider, then rerun <code>./start.sh</code></td></tr><tr><td>Required file not found </td><td>Re-extract the complete package or reset agent credentials in the UI and deploy the replacement package. Do not reconstruct the missing file</td></tr><tr><td>Container repeatedly restarts </td><td>Read the first fatal error in logs. Common causes are missing env values, missing encrypted ISE credentials, authentication failure, or unreachable endpoints</td></tr><tr><td>Image pull fails </td><td>Verify access to ghcr.io and proxy/firewall policy. Use <code>--no-pull</code> only when the exact image is already present locally</td></tr><tr><td>Deployment material cannot be used </td><td>Generate replacement deployment material in Cisco Identity Intelligence and redeploy the package</td></tr></tbody></table>

#### Step 3 — interpret the first relevant log error&#x20;

<table data-header-hidden><thead><tr><th width="298.484375"></th><th></th></tr></thead><tbody><tr><td><strong>Log / symptom</strong> </td><td><strong>Meaning and next action</strong> </td></tr><tr><td>HTTP 401 / authentication failed </td><td>Rerun <code>./start.sh --reconfigure</code> and enter the current ISE service-account credentials</td></tr><tr><td>HTTP 403 / access denied </td><td>Ask the ISE administrator to confirm the account has the required ERS API access</td></tr><tr><td>Connection error or timeout </td><td>Verify the configured ISE hostname and port, then confirm DNS, routing, and firewall access from the agent host</td></tr><tr><td>JSON or unexpected-response error </td><td>Capture the timestamp and surrounding redacted log lines, then contact support. Do not run diagnostic commands inside the container</td></tr><tr><td>Image pull failed </td><td>Verify registry and proxy access. Use <code>--no-pull</code> only when the released image is already present locally</td></tr></tbody></table>

To replace credentials safely, refer to the steps in the [Safely reconfigure ISE credentials](#safely-reconfigure-ise-credentials) section above

#### Step 4 — diagnose outbound IoT / proxy failures&#x20;

* Look for Connected to IoT Core. Repeated CONNACK timeouts or connect-attempt failures mean the cloud path is not healthy
* If direct access is expected, confirm outbound TCP 443 to the IOT\_ENDPOINT value in `.env`&#x20;
* If a proxy is required, rerun `./start.sh --reconfigure` and enter the proxy as `http://host:port` (with credentials only if required). Setup performs an authenticated MQTT validation through the proxy before saving
* Allowlist the `IOT_ENDPOINT` hostname, not a resolved IP address. Large batches also require HTTPS access to the host in the short-lived signed S3 URL

```
grep '^IOT_ENDPOINT=' .env 
./start.sh --stop 
./start.sh --reconfigure 
```

#### Step 5 — diagnose pxGrid&#x20;

<table data-header-hidden><thead><tr><th width="257.23046875"></th><th></th></tr></thead><tbody><tr><td><strong>Log / symptom</strong> </td><td><strong>Meaning and response</strong> </td></tr><tr><td>Waiting for admin approval </td><td>Approve the displayed client under Administration > pxGrid Services > Client Management > Clients</td></tr><tr><td>Account disabled by ISE admin </td><td>Re-enable or recreate the pxGrid client, then rerun <code>--enable-pxgrid</code> if credentials changed</td></tr><tr><td>Activation timed out </td><td>Verify approval, node name, password, ISE reachability, and pxGrid service availability</td></tr><tr><td>Session service not found / pubsub service not found </td><td>Verify pxGrid services are enabled and advertised by the deployment</td></tr><tr><td>WebSocket connection failed</td><td>Verify TCP 8910 connectivity, routing, and pxGrid node availability</td></tr><tr><td>pxGrid activation failed</td><td>Correct the approval, credentials, TCP 8910 connectivity, or pxGrid service configuration, then restart the agent</td></tr></tbody></table>

After correcting pxGrid configuration, run:&#x20;

```
./start.sh --enable-pxgrid 
```

#### Step 6 — agent is connected but the dashboard is stale&#x20;

1. Confirm IoT Core connectivity. Look for Connected to IoT Core and command / bulk-upload subscriptions&#x20;
2. Confirm heartbeat health. Look for Started heartbeat loop (interval=60) and ISE health warnings&#x20;
3. Check ISE reachability. Failed to collect ISE health means the heartbeat can reach the cloud while ISE itself is unavailable&#x20;
4. Use the dashboard refresh button. Refresh re-queries cloud-side integration, health-history, and node-metric data; it does not replace local log validation&#x20;
5. Update an old agent. Run `./start.sh --update`, then verify the reported agent version and fresh heartbeat&#x20;

```
docker logs --since 10m <container_name> 2>&1 | \ 
grep -E 'Connected to IoT Core|heartbeat|Failed to collect ISE health|pxGrid|Connection failed' 
```

#### Step 7 — collect safe support details

```
docker logs --since 30m <container_name> 
# Copy only the relevant time window and redact it before sharing.
```

* Include the agent version, approximate failure time with timezone, container state, and the first relevant error chain
* State whether the failure affects ISE access, IoT Core, pxGrid, bulk S3 upload, or only the cloud dashboard
* Do not include the installation bundle, private keys, encrypted credential files, passwords, or unreviewed log output&#x20;