Security & Certificates

Overview

All ISE API clients implement server certificate validation to prevent Man-in-the-Middle (MITM) attacks. The internal PKI uses DOMUS PKI (Vault-based) for server certificate verification.

Security Architecture: All API connections validate the ISE server certificate against the trusted CA chain. This ensures you’re communicating with the legitimate ISE server, not an attacker intercepting traffic.

PKI Architecture

ISE server certificates are issued by the DOMUS PKI chain:

DOMUS-ROOT-CA (Vault - offline root)
└── DOMUS-ISSUING-CA (Vault pki_int - issues server certs)
    └── ise-02.inside.domusdigitalis.dev (ISE server cert)

Full Chain Required: The CA certificate file must contain the full chain (root + intermediate CA), not just the root CA. ISE server certs are issued by DOMUS-ISSUING-CA, so Python’s SSL verification needs the intermediate in the trust chain.

Certificate Store Structure

Certificates are managed via the .secrets directory:

~/.secrets/certs/
├── d000/                        # Domain-specific certs
│   └── ise/
│       ├── ROOT-CA.crt          # CA chain (root + intermediate)
│       ├── pxgrid-client.crt    # pxGrid mTLS client cert
│       ├── pxgrid-client.key    # pxGrid client key
│       └── dataconnect.crt      # DataConnect cert
└── ca/
    └── DOMUS-CA-CHAIN.pem       # Full CA chain (backup)

CA Verification Implementation

class SecureISEClient:
    """
    Base client with MITM protection via CA verification.

    Security Features:
    - Server certificate validation against DOMUS PKI chain
    - Support for Age-encrypted CA certificates
    - Automatic temp file cleanup for decrypted certs
    """

    def _get_verify_param(self) -> Union[bool, str]:
        """Get the verify parameter for requests."""
        if self._ca_cert:
            if self._ca_cert.endswith('.age'):
                return self._decrypt_ca_cert()
            return self._ca_cert

        return True  # Fall back to system CA bundle

Client Status

Client Port CA Verification Status

ERS API

9060

✓ DOMUS PKI Chain

Validated

Certs API

443

✓ DOMUS PKI Chain

Validated

MnT API

443

✓ DOMUS PKI Chain

Validated

SAML API

443

✓ DOMUS PKI Chain

Validated

DataConnect

2484

Self-signed Oracle

Special handling

DataConnect uses ISE’s internal Oracle database which presents a self-signed certificate. For this API, we explicitly allow the self-signed cert while still validating hostname.

Environment Configuration

# Load credentials with dsec
dsource d000 dev/network

# Environment variables used by netapi:
# ISE_PAN_FQDN       - ISE Primary Admin Node hostname
# ISE_API_TOKEN      - Base64(username:password)
# ISE_CA_CERT        - Path to CA chain (via CA_CERT_PATH in dsec env)

# The dsec env file sets:
# CA_CERT_PATH=~/.secrets/certs/d000
# ISE_CA_CERT=${CA_CERT_PATH}/ise/ROOT-CA.crt

Always use CA certificate validation in production. Disabling SSL verification (verify_ssl=False) should only be used for initial debugging against test environments with self-signed certificates.

Troubleshooting SSL Errors

Certificate Verify Failed

If you see this error:

SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED]
certificate verify failed: unable to get local issuer certificate'))

Cause: The CA cert file contains only the root CA, but ISE’s server cert is issued by the intermediate CA.

Solution: Replace with the full CA chain:

# Check current CA cert
openssl x509 -in ~/.secrets/certs/d000/ise/ROOT-CA.crt -noout -subject -issuer

# If it shows only DOMUS-ROOT-CA, replace with full chain
cp /etc/ssl/certs/DOMUS-CA-CHAIN.pem ~/.secrets/certs/d000/ise/ROOT-CA.crt

# Verify chain contents (should show 2 certs)
openssl crl2pkcs7 -nocrl -certfile ~/.secrets/certs/d000/ise/ROOT-CA.crt | \
  openssl pkcs7 -print_certs -noout

Verifying the CA Chain

# Check ISE server cert issuer
openssl s_client -connect ise-02.inside.domusdigitalis.dev:9060 \
  -showcerts </dev/null 2>/dev/null | openssl x509 -noout -issuer -subject

# Expected output:
# issuer=CN=DOMUS-ISSUING-CA
# subject=CN=ise-02.inside.domusdigitalis.dev

# Verify full chain is in ROOT-CA.crt
grep -c "BEGIN CERTIFICATE" ~/.secrets/certs/d000/ise/ROOT-CA.crt
# Should return: 2 (root + intermediate)