Ports, HTTPS, and Certificates in AAI 26.0.0 — What Changed

Products

• Automation Analytics & Intelligence

Issue/Introduction

Three things change in AAI 26.0.0 that affect how the product is reached over the network and how its certificates work.
Read this before or after upgrading from AAI 24.4.x or earlier, whether you use HTTPS today or are considering enabling it for the first time.

New to certificate terminology? This article uses terms like certificate authority, keystore/truststore, and mTLS without redefining them.
See: AAI Glossary — Terms Used in the 26.0.0 Upgrade Documentation

Environment

• AAI 26.0.0 and later, upgrading from 24.4.x or earlier.
• VM / traditional installer — AAI runs directly on a host (Linux or Windows), managed by the installer/upgrader tooling. §3-§6 (the certificate-authority requirement and the HTTPS setup/upgrade procedures) are written for this environment and apply to it directly.
• Kubernetes / OpenShift (Helm) — AAI runs as a set of pods deployed via Helm, and the Frontend Gateway is one of them
  — it's part of this architecture the same as on a VM, not something Kubernetes deployments skip. Internal certificate handling is fully automatic either way (§2).
  Separately, the certificate-authority requirement in §3 does not apply to Helm/container deployments at all — the upgrade path that requirement blocks is specific to the VM/installer upgrade tooling, confirmed directly rather than inferred.

  Where the customer-facing TLS handshake terminates — confirmed, not a default you need to guess at: 
  out of the box, the gateway's own TLS is disabled and the Route (OpenShift) or Ingress (Kubernetes) in front of it uses edge termination, or has no TLS configured at all.
  This means client certificates never reach the gateway by default — only plain HTTP does.
  If your cluster is running this default configuration, client-certificate-authenticated connectors (§5) simply aren't part of your setup, and neither is anything else in this article that depends on the gateway seeing a client certificate directly.
  For that to work at all, someone has to have deliberately switched the Route/Ingress to passthrough mode and enabled the gateway's own TLS — check for both before assuming either the VM-style steps or "it's someone else's problem" apply to you.

Cause

Not applicable. This article explains architectural changes to ports, HTTPS, and certificates in AAI 26.0.0, not a resolution to a specific reported problem.

Resolution

Prerequisites

• keytool on your PATH (§3). This ships with any JDK. Check with keytool -version (identical command on Linux and Windows). If it's not recognized, either add your JDK's bin directory to your PATH,
  or check whether your AAI installation bundles its own JDK and point to that JDK's keytool by its full path instead.
• openssl (§7). Most Linux distributions include it by default — confirm with openssl version. Windows does not include it by default, though you may already have one:
  if Git for Windows/Git Bash is installed, an openssl.exe typically comes with it (check with Get-Command openssl in PowerShell before installing anything new).
• curl (§8). Included by default on Windows 10/11 and macOS, and on most Linux distributions; if missing on Linux, install it through your distribution's package manager (apt install curl, yum install curl, etc.).
• (Kubernetes/OpenShift only) helm and kubectl/oc already configured against the correct cluster and namespace — confirm with helm version and kubectl config current-context (or oc whoami).
• Your AAI installation directory (referred to as <install> or <your-configuration-directory> throughout) and, on Kubernetes/OpenShift, your Helm release name and namespace.

Summary

1. A new component — the Frontend Gateway — now sits in front of AAI and is what your browser and integrations actually talk to. The port you already use keeps working; you don't need to reconfigure firewalls, load balancers, or bookmarks.
2. AAI now uses three independent certificate systems: the gateway's own HTTPS certificate (yours to manage), a separate certificate authority that signs your integrations' certificates (generated automatically, but yours to use), and one purely internal to AAI itself (fully automatic, nothing to configure). None of the three ever shares trust material with another.
3. If you already use HTTPS today, your existing certificate is carried forward as-is during the upgrade — there is no longer a special requirement it must meet. What you do need to check beforehand is covered below. Separately, any existing integration that authenticates with a client certificate will still need a new certificate issued after the upgrade.

1. The new port map

Port	What answers there in 26.0.0	What answered there before (24.4.x)	Needs a client certificate?
Your existing HTTP/HTTPS port (8080/8443 by default)	The new Frontend Gateway	AAI application directly	No
A new internal-only port (8081 by default)	AAI application (moved here)	—	No — not externally reachable
A new internal-only mTLS port (4443 by default) — mTLS means both sides of the connection prove their identity with a certificate, not just the server	AAI application, internal service traffic	Present but unused	Yes — internal only, automatic
Config Tool / Webswing port(s)	Same as before	Same	Only if you had this configured
Ports for individual services (AI Insights, Denormalizer, MCP, Automation AI, connectors, etc.)	New — these are new 26.0.0 services	Not present	Varies by service; automatic

The important part: the port your users type into a browser today keeps working after the upgrade. The upgrade process reads your existing configuration and gives the new Frontend Gateway the exact same port your browser already uses
— whether that's the default or a custom port you chose. Nothing on your side needs to change for existing bookmarks, firewall rules, or monitoring to keep working.

A quirk to be aware of: if you request the bare root path or /v2 on your existing port, you may see a plain placeholder response instead of the AAI login page. This isn't a broken install — it's a leftover of the new gateway component.
Use your normal AAI URL (ending in /aai) and everything behaves as expected.

Verify current port defaults against your installed build. 
The port numbers above are the 26.0.0 defaults; always confirm the actual values against your own installed configuration rather than assuming they match this table exactly, since defaults can shift between releases.

2. Three independent certificate systems

26.0.0 uses three separate certificate authorities that never share trust material:

• Your gateway certificate (yours to manage): the certificate your browsers and integrations see when they connect over HTTPS. You supply this yourself
  — either from your own organization's certificate authority or a public certificate authority.
• A connector certificate authority (automatic, but yours to use): generated automatically the moment AAI is installed, this signs the client certificates your integrations use to authenticate to the gateway. It exists independently of your gateway certificate
  — one never signs the other.
• Internal (fully automatic): covers traffic between AAI's own internal services. This is generated automatically at install time and requires no configuration from you — you'll only ever need to know it exists when diagnosing an issue, not to set it up.

If you ever see documentation or diagrams referring to more than one certificate authority, this is what that means — it's expected, not an error.
The rule to remember: your gateway's own certificate never signs your integrations' certificates, and vice versa 
— they come from two completely independent authorities.

3. If you already use HTTPS: what happens to your certificate during the upgrade

This section applies to VM/traditional-installer upgrades only. If you run AAI on Kubernetes/OpenShift via Helm, the gateway's own certificate isn't touched by this upgrade path at all — see the callout at the end of this section for what to check instead.

If your existing VM installation has HTTPS enabled, the upgrade carries your current certificate forward exactly as-is — same file, same private key, same content.
It is not used to sign a new certificate, and it does not need to be a certificate-authority certificate.
There is no longer a certificate-authority requirement to satisfy before upgrading, regardless of which prior version you're upgrading from.

Action before your upgrade window: confirm your current certificate includes the Subject Alternative Names (SANs) it needs — the hostnames and/or IP addresses your users and integrations actually use to reach it.
This matters more after this upgrade than it used to: earlier upgrade behavior minted a brand-new certificate that could paper over a missing SAN on the original.
Now your original certificate is served exactly as it is, so a missing SAN becomes a real, visible browser warning or connection failure after the upgrade, not something the upgrade covers for you.

Linux:

keytool -list -v -keystore <your-keystore-file>.p12 -storetype PKCS12 -storepass <your-keystore-password> \
  | grep -A5 -i "SubjectAlternativeName"

Windows (Command Prompt — findstr can't show the surrounding context lines; use the PowerShell form below if you need the full block):

keytool -list -v -keystore <your-keystore-file>.p12 -storetype PKCS12 -storepass <your-keystore-password> ^
  | findstr /i "SubjectAlternativeName"

Windows (PowerShell — shows the surrounding lines, closer to the Linux output):

keytool -list -v -keystore <your-keystore-file>.p12 -storetype PKCS12 -storepass <your-keystore-password> `
  | Select-String -Pattern "SubjectAlternativeName" -Context 0,5

Example output (what you want to see):

SubjectAlternativeName [
  DNSName: myaai.example.com
  IPAddress: 10.20.30.40
]

How to read it: you should see an entry for every hostname (DNSName) and/or IP address (IPAddress) your users or integrations use to reach this install.
If the block is missing entirely, or is missing an address you rely on, get an updated certificate from whoever manages your organization's certificates before your upgrade window
— this isn't something the upgrade can fix for you afterward without reissuing the certificate.

On Kubernetes/OpenShift instead: none of the above applies — the gateway's own certificate isn't touched by this upgrade path at all. Confirm your external TLS termination independently
— check your Route/Ingress configuration for whether it uses the cluster's router wildcard certificate or a TLS secret you supplied, and confirm that secret/certificate directly rather than looking for anything on the Frontend Gateway itself.

4. What the upgrade does automatically (VM/installer, if HTTPS was already enabled)

This section applies to VM/installer upgrades. When you upgrade a VM installation from 24.4.x or earlier with HTTPS already configured, the upgrader:

• Carries your existing HTTPS port forward to the new Frontend Gateway (falling back to the standard default only if no HTTPS port was configured before).
• Carries your existing certificate forward as-is, unchanged — it becomes the Frontend Gateway's certificate directly, not a signing authority used to mint a new one.
• Generates a new, separate certificate authority for your integrations' certificates — unrelated to your existing certificate, and needed for the manual step in §5.
• Carries forward whether client certificates were required.

You don't need to do anything for this part — it happens during the upgrade itself.

5. What you must still do manually after upgrading

This applies whenever the Frontend Gateway itself is the thing validating a connector's client certificate — which is always true on a VM install. On Kubernetes/OpenShift, this is not the default — the gateway's own TLS ships disabled, and the Route/Ingress in front of it defaults to edge termination (or no TLS at all), so client certificates never reach the gateway out of the box. If your cluster is running that default configuration, this section doesn't apply to you: your connectors aren't authenticating with a client certificate against this gateway at all. It only applies if someone has deliberately reconfigured the Route/Ingress to passthrough mode and enabled the gateway's own TLS — confirm that setup exists before treating the steps below as relevant.

Whichever applies: the certificate migration or setup covered above only ever covers the gateway's own certificate — it does not reissue certificates for anything that connects to the gateway.

If any of your integrations authenticate with a client certificate, every existing one will stop working immediately after the upgrade, because integrations are now validated against a new, separate certificate authority the upgrade generates for this purpose — unrelated to your gateway's own certificate, which does not change. You will need to:

1. Generate a new certificate bundle for each affected integration, signed by the new certificate authority the upgrade generated (see §4) — using the official 26.0.0 procedure for the exact command and required options.
2. Deploy the new certificate to each integration/connector host.
3. Point each integration at the gateway's (possibly new) HTTPS port — copying the certificate alone does not update the URL the integration calls.

Plan for this as a same-maintenance-window task, not a follow-up — integrations will be down between the upgrade completing and this step finishing. See Connector/Integration Impact of Upgrading AAI to 26.0.0 (Additional Information) for the exact regeneration steps.

6. Enabling HTTPS for the first time on 26.0.0

On a VM/traditional installer install: HTTPS is not turned on by the installer — it's a deliberate, manual post-install procedure. In short, it involves:

1. Obtaining a certificate for the Frontend Gateway itself, with its private key — signed by your organization's own certificate authority or a public certificate authority. This does not need to be a certificate-authority certificate itself, just an ordinary certificate that includes every hostname and IP address your clients use to reach it.
2. Deploying the generated files and enabling HTTPS in configuration, then restarting the gateway.
3. If any integrations need to authenticate with a client certificate, signing each one using the certificate authority that was generated automatically for this purpose when AAI was installed (see §2) — this authority already exists and doesn't need to be created.

Follow the official 26.0.0 configuration procedure for the exact commands — the sequence and required fields are documented there in full,
including which output files are safe to distribute to other teams (public certificate only) versus which must stay restricted (anything containing a private key).

On Kubernetes/OpenShift: the gateway runs here too
— this isn't a VM-only component
— but this specific procedure doesn't apply the same way, and the default configuration doesn't need it at all. 

Out of the box, the gateway's own TLS is disabled and browser-facing HTTPS is handled entirely by the Route (OpenShift) or Ingress (Kubernetes) in front of it
— a router wildcard certificate or a TLS secret you supply there, unrelated to anything in this procedure.

If that's your setup, there's nothing to configure on the gateway itself for ordinary HTTPS.
This procedure only becomes relevant if you specifically need connectors to authenticate with client certificates directly against the gateway
— which requires deliberately switching the Route/Ingress to passthrough mode and enabling the gateway's own TLS, neither of which happens by default.
Confirm that's genuinely what you're trying to do before assuming the VM steps above apply.

7. Don't trust a quoted certificate validity period — check your own

Certificate validity periods you may see quoted in different places (training material, older documentation, etc.) are inconsistent with each other and with what any given install actually has.
Rather than relying on a quoted number, check your own certificate directly:

Linux:

for p12 in <your-configuration-directory>/*.p12; do
  echo "== $p12"
  openssl pkcs12 -in "$p12" -nokeys -passin pass:<your-keystore-password> 2>/dev/null \
    | openssl x509 -noout -subject -enddate
done

Windows (PowerShell — requires openssl on your PATH; install Git for Windows or a standalone OpenSSL build if it isn't already):

Get-ChildItem "<your-configuration-directory>\*.p12" | ForEach-Object {
  Write-Host "== $($_.FullName)"
  openssl pkcs12 -in $_.FullName -nokeys -passin pass:<your-keystore-password> 2>$null `
    | openssl x509 -noout -subject -enddate
}

This also works from a live TLS handshake — the certificate's actual expiration is always logged as part of a successful connection.

8. Quick self-checks

• "A URL that used to work stopped working": get the exact URL including http:// or https:// — the port is the first thing to confirm.
  Compare a request to your existing (gateway) port against the internal AAI port for the same path; whichever behaves differently tells you which side changed:

  curl -s -o /dev/null -w '%{http_code} gateway\n' http://<host>:<your-gateway-port>/aai/api/version
  curl -s -o /dev/null -w '%{http_code} server\n'  http://<host>:8081/aai/api/version

  (This works the same on Linux, macOS, and Windows — curl has shipped built into Windows 10/11 by default since 2018.) A 200 from one and something else
  (404, connection refused, timeout) from the other tells you immediately which side of the gateway boundary the problem is on.
• Confirm your current HTTPS/mTLS status: check whether your configuration shows HTTPS enabled and what the effective internal service URL is (http:// means internal certificates aren't active yet; https:// means they are).
• "Login works but nothing loads" / unexpected 401s on internal-looking calls: treat it as a certificate issue first — AAI's internal certificate enforcement is designed to fail as a clean,
  credible-looking 401 rather than a connection error, which can look like an authentication or permissions problem when it isn't.

Additional Information

• Pre-Upgrade Checklist for AAI 26.0.0 — action-item checklist, including the certificate SAN check above.
• Connector/Integration Impact of Upgrading AAI to 26.0.0 — what breaks for each connector type and how to fix it.
• To speak with a customer representative or a Support Engineer see Contact Support. Scroll to the bottom of the page and click on the respective region.