ISE 3.4 Certificate-Based API Authentication Roadmap

1. Overview

ISE 3.4 introduces the ability to use separate identity sources for API authentication, decoupling API credentials from admin portal credentials. This enables certificate-based authentication for API calls using certificates issued by HashiCorp Vault PKI.

1.1. ISE 3.4 New Feature

Prior to ISE 3.4, API authentication was tied to admin portal credentials (username/password or SAML). ISE 3.4 adds:

  • ERS API: Certificate-based authentication option

  • OpenAPI: Separate identity source configuration

  • Decoupled credentials: API clients can authenticate independently of admin users

1.2. Goals

  • Eliminate password-based API authentication

  • Use Vault PKI-issued certificates for netapi CLI

  • Enable automated certificate rotation

  • Improve audit trail (certificate CN identifies caller)

  • Support for service account certificates (non-human principals)

2. Current State

2.1. API Authentication Methods (Pre-3.4)

API Surface Auth Method Credential Source

ERS

Basic Auth (username/password)

ISE Internal User or AD

OpenAPI

Bearer Token or Basic Auth

ISE Admin credentials

MnT

Basic Auth

ISE Internal User

DataConnect

Oracle JDBC (username/password)

ISE DataConnect credentials

pxGrid

Client Certificate (already cert-based)

Vault PKI

2.2. Target State (ISE 3.4)

API Surface Auth Method Credential Source

ERS

Client Certificate

Vault PKI (pki_int/issue/domus-automation)

OpenAPI

Client Certificate

Vault PKI (pki_int/issue/domus-automation)

MnT

Basic Auth (no cert option)

ISE Internal User

DataConnect

Oracle JDBC (no cert option)

ISE DataConnect credentials

pxGrid

Client Certificate

Vault PKI (already implemented)

3. Phase 1: Vault PKI Role for API Clients

3.1. Create Automation Role

Create a dedicated Vault PKI role for API client certificates:

vault write pki_int/roles/domus-automation \
  allowed_domains="inside.domusdigitalis.dev" \
  allow_subdomains=true \
  allow_bare_domains=false \
  max_ttl="8760h" \
  key_type="rsa" \
  key_bits=2048 \
  key_usage="DigitalSignature,KeyEncipherment" \
  ext_key_usage="ClientAuth" \
  require_cn=true \
  organization="Domus Digitalis" \
  ou="Automation"

3.2. Issue netapi Client Certificate

vault write pki_int/issue/domus-automation \
  common_name="netapi-client.inside.domusdigitalis.dev" \
  ttl="8760h" \
  -format=json > /tmp/netapi-client.json

Extract components:

jq -r '.data.certificate' /tmp/netapi-client.json > ~/.config/netapi/client.crt
jq -r '.data.private_key' /tmp/netapi-client.json > ~/.config/netapi/client.key
chmod 600 ~/.config/netapi/client.key

4. Phase 2: ISE Certificate Authentication Profile

4.1. Create Certificate Authentication Profile

In ISE Admin UI:

  1. Navigate to: Administration > Identity Management > External Identity Sources > Certificate Authentication Profile

  2. Click Add

  3. Configure:

Setting Value

Name

DOMUS_API_Cert_Profile

Certificate Attribute

Subject - Common Name (CN)

Match Certificate Template

No (Vault doesn’t use MS templates)

Allow SHA-1 Certificates

No

4.2. Create Identity Source Sequence

  1. Navigate to: Administration > Identity Management > Identity Source Sequences

  2. Create: API_Certificate_Sequence

  3. Add: DOMUS_API_Cert_Profile

5. Phase 3: ERS API Certificate Configuration

5.1. Enable Certificate Authentication for ERS

  1. Navigate to: Administration > System > Settings > API Settings > API Service Settings

  2. Under ERS (External RESTful Services):

    • Enable: Allow client certificate authentication

    • Certificate Identity Source: DOMUS_API_Cert_Profile

  3. Click Save

5.2. Test ERS with Certificate

curl -X GET "https://ise-01.inside.domusdigitalis.dev:9060/ers/config/endpoint" \
  --cert ~/.config/netapi/client.crt \
  --key ~/.config/netapi/client.key \
  --cacert /etc/ssl/certs/DOMUS-CA-CHAIN.pem \
  -H "Accept: application/json"

6. Phase 4: netapi CLI Integration

6.1. Update netapi Configuration

Add certificate configuration to netapi:

# ~/.config/netapi/config.yaml
ise:
  host: ise-01.inside.domusdigitalis.dev
  auth_method: certificate  # New option
  client_cert: ~/.config/netapi/client.crt
  client_key: ~/.config/netapi/client.key
  ca_cert: /etc/ssl/certs/DOMUS-CA-CHAIN.pem

6.2. Update dsec Environment Template

# Certificate-based auth (ISE 3.4+)
ISE_AUTH_METHOD=certificate
ISE_CLIENT_CERT=$HOME/.config/netapi/client.crt
ISE_CLIENT_KEY=$HOME/.config/netapi/client.key
ISE_CA_CERT=/etc/ssl/certs/DOMUS-CA-CHAIN.pem

7. Phase 5: Certificate Rotation Automation

7.1. Vault Agent Template

Create Vault Agent configuration for auto-renewal:

template {
  source = "/etc/vault.d/templates/netapi-cert.tpl"
  destination = "/home/evanusmodestus/.config/netapi/client.crt"
  perms = "0644"
}

template {
  source = "/etc/vault.d/templates/netapi-key.tpl"
  destination = "/home/evanusmodestus/.config/netapi/client.key"
  perms = "0600"
}

7.2. Certificate Template

{{- with secret "pki_int/issue/domus-automation" "common_name=netapi-client.inside.domusdigitalis.dev" "ttl=720h" -}}
{{ .Data.certificate }}
{{ end }}

8. Implementation Checklist

8.1. Vault PKI

  • Create domus-automation role with ClientAuth EKU

  • Issue netapi client certificate

  • Test certificate validity

8.2. ISE Configuration

  • Create Certificate Authentication Profile

  • Create Identity Source Sequence

  • Enable ERS certificate authentication

  • Enable OpenAPI certificate authentication

  • Test certificate-based API calls

8.3. netapi Integration

  • Add certificate auth support to ERS client

  • Update CLI configuration schema

  • Update dsec environment templates

  • Test all API surfaces with cert auth

8.4. Automation

  • Configure Vault Agent for cert renewal

  • Create renewal notification script

  • Document rotation procedure

9. Security Benefits

Benefit Description

No password exposure

Certificates can’t be easily copied like passwords

Mutual TLS

Both client and server authenticate

Audit trail

Certificate CN logged in ISE - identifies caller

Automated rotation

Vault Agent handles renewal before expiry

Service identity

Non-human principals (netapi) have unique identity

Revocation

Compromised certs can be revoked via CRL/OCSP

10. Limitations

  • MnT API: No certificate auth support (still requires password)

  • DataConnect: Oracle JDBC uses password auth

  • SAML Admin SSO: Unaffected (browser-based flow)

11. Related Documentation