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.

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.

2. Create the Cisco ISE integration within Identity Intelligence

1. Using an Admin role in Cisco Identity Intelligence, navigate to Integrations and select Cisco ISE

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

4. Save the deployment material immediately. Use Download ISE Agent Package or Copy Command. Note: 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.

3. Install the agent on premises

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

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.

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

Option B — downloaded ZIP

1. Copy the ZIP to the agent host using your organization-approved secure transfer method

2. Extract it into a dedicated directory. Change into the directory that contains .env, start.sh, docker-compose.yml, and certs

3. Restore executable permissions if necessary and start the agent

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

What the credential setup validates

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

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 section above for more info.

Register a new pxGrid client

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

3. Start the agent and note the client name shown in the logs

4. In ISE, go to Administration > pxGrid Services > Client Management > Clients

5. Find and approve the displayed client

6. Follow the logs and confirm account activation, WebSocket connection, session synchronization, and session-topic subscription

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

Reconfigure pxGrid later

./start.sh --enable-pxgrid 

This replaces the stored pxGrid configuration and restarts the deployment.

5. Verify the first connection

1. Find the generated container name. Read the container_name line from docker-compose.yml . Do NOT assume a fixed suffix

2. Confirm the container is running. Use the Compose or Podman status command for your runtime

3. Follow agent logs. Look for the healthy markers below and investigate any errors before continuing

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

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>

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

6. Supported host commands

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

Safely reconfigure ISE credentials

Stop the running deployment before replacing ISE credentials or proxy settings.

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

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.

7. Troubleshooting workflow

Step 1 — establish the local state

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 

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.

Step 2 — inspect container status and logs

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

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

Step 3 — interpret the first relevant log error

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

To replace credentials safely, refer to the steps in the Safely reconfigure ISE credentials section above

Step 4 — diagnose outbound IoT / proxy failures

• 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

• 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

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

After correcting pxGrid configuration, run:

./start.sh --enable-pxgrid 

Step 6 — agent is connected but the dashboard is stale

1. Confirm IoT Core connectivity. Look for Connected to IoT Core and command / bulk-upload subscriptions

2. Confirm heartbeat health. Look for Started heartbeat loop (interval=60) and ISE health warnings

3. Check ISE reachability. Failed to collect ISE health means the heartbeat can reach the cloud while ISE itself is unavailable

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

5. Update an old agent. Run ./start.sh --update, then verify the reported agent version and fresh heartbeat

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