pxGrid Setup Guide

Overview

pxGrid requires mutual TLS authentication. This guide covers certificate generation, client registration, and service subscription.

Prerequisites

  • ISE 2.4+ with pxGrid enabled

  • CA certificate trusted by ISE (e.g., Vault PKI)

  • OpenSSL or similar for certificate generation

Step 1: Generate Client Certificate

Using Vault PKI

# Generate pxGrid client certificate
vault write -format=json pki_int/issue/pxgrid-client \
  common_name="pxgrid-netapi" \
  ttl="8760h" > /tmp/pxgrid-cert.json

# Extract certificate and key
jq -r '.data.certificate' /tmp/pxgrid-cert.json > ~/.pxgrid/client.pem
jq -r '.data.private_key' /tmp/pxgrid-cert.json > ~/.pxgrid/client.key
jq -r '.data.ca_chain[]' /tmp/pxgrid-cert.json > ~/.pxgrid/ca-chain.pem

# Set permissions
chmod 600 ~/.pxgrid/client.key

Using OpenSSL

# Generate key
openssl genrsa -out ~/.pxgrid/client.key 2048

# Generate CSR
openssl req -new -key ~/.pxgrid/client.key \
  -out ~/.pxgrid/client.csr \
  -subj "/CN=pxgrid-netapi/O=Domus Digitalis"

# Sign with your CA
openssl x509 -req -in ~/.pxgrid/client.csr \
  -CA ca.pem -CAkey ca.key -CAcreateserial \
  -out ~/.pxgrid/client.pem -days 365

Step 2: Import CA into ISE

ISE must trust your client certificate’s CA.

  1. ISE Admin > Administration > System > Certificates > Trusted Certificates

  2. Import your CA certificate

  3. Enable for "Trust for client authentication and pxGrid"

# Verify via API
curl -sk -u "${ISE_AUTH}" \
  "https://${ISE_PAN_IP}:9060/ers/config/certificate?filter=name.CONTAINS.pxgrid" \
  -H "Accept: application/json"

Step 3: Enable pxGrid in ISE

  1. ISE Admin > Administration > pxGrid Services > Settings

  2. Enable pxGrid

  3. (Optional) Enable automatic approval for new clients

Step 4: Register Client

Activate Account

PXGRID_CERT="$HOME/.pxgrid/client.pem"
PXGRID_KEY="$HOME/.pxgrid/client.key"

curl -sk --cert "${PXGRID_CERT}" --key "${PXGRID_KEY}" \
  "https://${ISE_PAN_IP}:8910/pxgrid/control/AccountActivate" \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{
  "accountState": "ENABLED",
  "version": "2.0.0.13"
}

If accountState is PENDING, approve in ISE Admin UI.

Approve in ISE (if needed)

  1. ISE Admin > Administration > pxGrid Services > Clients

  2. Find pending client (CN from certificate)

  3. Click Approve

Step 5: Lookup Services

# List all available services
curl -sk --cert "${PXGRID_CERT}" --key "${PXGRID_KEY}" \
  "https://${ISE_PAN_IP}:8910/pxgrid/control/ServiceLookup" \
  -H "Content-Type: application/json" \
  -d '{"name": ""}' | jq '.services[].name'

Common services:

Service Description

com.cisco.ise.session

Session directory (sessions, SGT)

com.cisco.ise.config.anc

Adaptive Network Control

com.cisco.ise.trustsec

TrustSec SGT/SXP data

com.cisco.ise.radius

RADIUS failure events

com.cisco.ise.system

System health events

Step 6: Get WebSocket Credentials

Get Pub/Sub Node

SERVICE_RESPONSE=$(curl -sk --cert "${PXGRID_CERT}" --key "${PXGRID_KEY}" \
  "https://${ISE_PAN_IP}:8910/pxgrid/control/ServiceLookup" \
  -H "Content-Type: application/json" \
  -d '{"name": "com.cisco.ise.session"}')

PUBSUB_NODE=$(echo "$SERVICE_RESPONSE" | jq -r '.services[0].properties.wsPubsubService')
NODE_NAME=$(echo "$SERVICE_RESPONSE" | jq -r '.services[0].nodeName')

echo "Pub/Sub Node: $PUBSUB_NODE"
echo "Node Name: $NODE_NAME"

Get Access Secret

SECRET_RESPONSE=$(curl -sk --cert "${PXGRID_CERT}" --key "${PXGRID_KEY}" \
  "https://${ISE_PAN_IP}:8910/pxgrid/control/AccessSecret" \
  -H "Content-Type: application/json" \
  -d "{\"peerNodeName\": \"${NODE_NAME}\"}")

ACCESS_SECRET=$(echo "$SECRET_RESPONSE" | jq -r '.secret')

Step 7: Subscribe to Events

Using Python

import websocket
import ssl
import json
import base64

PUBSUB_URL = "wss://ise-01:8910/pxgrid/ise/pubsub"
CERT_FILE = "/home/user/.pxgrid/client.pem"
KEY_FILE = "/home/user/.pxgrid/client.key"
NODE_NAME = "pxgrid-netapi"
SECRET = "your-access-secret"

# Create auth header
auth = base64.b64encode(f"{NODE_NAME}:{SECRET}".encode()).decode()

ws = websocket.create_connection(
    PUBSUB_URL,
    sslopt={
        "cert_reqs": ssl.CERT_REQUIRED,
        "certfile": CERT_FILE,
        "keyfile": KEY_FILE,
    },
    header=[f"Authorization: Basic {auth}"]
)

# Subscribe to session topic
subscribe_msg = {
    "type": "SUBSCRIBE",
    "subscriptionId": "session-sub-1",
    "serviceName": "com.cisco.ise.session",
    "topic": "/topic/com.cisco.ise.session"
}
ws.send(json.dumps(subscribe_msg))

# Receive events
while True:
    result = ws.recv()
    print(json.loads(result))

Troubleshooting

Certificate Not Trusted

# Verify cert chain
openssl verify -CAfile ~/.pxgrid/ca-chain.pem ~/.pxgrid/client.pem

# Check ISE trusted certs
curl -sk -u "${ISE_AUTH}" \
  "https://${ISE_PAN_IP}/api/v1/certs/trusted-certificate" \
  -H "Accept: application/json" | jq '.response[].friendlyName'

Account Stuck in PENDING

  1. Check ISE Admin > pxGrid Services > Clients

  2. Look for approval notifications

  3. Or enable auto-approve in Settings

Connection Refused

  1. Verify pxGrid is enabled on ISE

  2. Check port 8910 is accessible

  3. Verify ISE firewall allows pxGrid

See Also