Connector and Integration Impact of Upgrading to AAI 26.0.0
search cancel

Connector and Integration Impact of Upgrading to AAI 26.0.0

book

Article ID: 453435

calendar_today

Updated On:

Products

Automation Analytics & Intelligence

Issue/Introduction

If you use any connector or integration that authenticates to AAI with a client certificate
— including IWS, Airflow, Automic, Control-M, or a similar third-party scheduler integration
— upgrading to AAI 26.0.0 stops every one of them working immediately.

This article explains why, and how to get each connector working again.

New to certificate terminology? This article uses terms like certificate authority and SAN 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, with one or more connectors/integrations in use.
  • This article is written primarily for VM/traditional-installer deployments, where connectors authenticate with a client certificate directly against the Frontend Gateway.
  • On Kubernetes/OpenShift, this does not happen out of the box. By default, the gateway's own application-level TLS is disabled, and the Route (OpenShift) or Ingress (Kubernetes) in front of it either uses edge termination or has no TLS configured at all
    — meaning client certificates never reach the gateway by default; it only ever sees plain HTTP forwarded from the Route/Ingress. 
    If your cluster is running the default configuration, client-certificate-authenticated connectors are not — and cannot be — validated at the gateway, and this entire article doesn't apply to you.
  • For a client-certificate-authenticated connector to work on Kubernetes/OpenShift at all, someone must have deliberately reconfigured the deployment away from these defaults: enabled the gateway's own TLS (a real keystore/truststore, not the default disabled state) and switched the Route/Ingress to passthrough so encrypted traffic — and the certificate inside it — actually reaches the gateway. 
    Confirm this deliberate setup exists before applying anything below — check whether your Route's TLS termination is passthrough (not the edge default) and whether the gateway's own SSL configuration is enabled.
    If neither is true, your connectors are authenticating some other way (or not authenticating with a certificate at all), and the steps in this article won't be the fix for whatever issue you're actually seeing.
  • If passthrough is configured, the underlying certificate-validation logic is the same code as the VM path, so treat the steps below the same way once you've confirmed that setup exists.

Cause

Your existing connector certificates were signed by your own certificate authority, but after the upgrade the gateway validates connectors against a brand-new, dedicated connector certificate authority it generates automatically
— one that has no relationship to your own certificates at all.
Your gateway's own certificate is not reissued by this upgrade
— it's carried forward unchanged, and isn't the cause of this (see Ports, HTTPS, and Certificates in AAI 26.0.0).
This is expected behavior, not a defect.

Resolution

Prerequisites

  • The connector certificate authority's file and password — on a VM install, this is generated automatically for you during installation and is separate from your own organization's certificate (see Ports, HTTPS, and Certificates in AAI 26.0.0 for where to find it, in Additional Information).
  • Your gateway's own existing certificate file and password. Re-issuing a connector after this upgrade requires telling the tool to also trust your gateway's own certificate, in addition to the connector certificate authority above — see §2.
  • keytool on your PATH, if you want to inspect a connector certificate directly. Ships with any JDK — check with keytool -version (same command on Linux and Windows). If not recognized, add your JDK's bin directory to PATH, or use the JDK bundled with your AAI installation if it has one.
  • Administrative access to each connector host, to deploy the new certificate bundle and restart the connector service.
  • Access to your gateway's log, to check for the connector-allowlist messages in §3.
  • (If a connector allowlist is in use) write access to the allowlist file's location — on a VM, that's a local path; on Kubernetes/OpenShift, that's the underlying shared storage from outside the cluster, not the pod itself (see §3).
  • Your AAI installation directory (referred to as <install> throughout).

Summary

Two separate things need to happen before a connector works again:

  1. A new certificate, signed by the new connector certificate authority, needs to be generated and deployed to the connector.
  2. Possibly: if your environment enforces a connector allowlist, the new certificate's identity needs to be added to it — a correctly reissued certificate can still be rejected if this step is missed (see §3).

1. Why every connector certificate breaks

Connectors don't authenticate against your organization's general HTTPS certificate — they present their own client certificate directly to the gateway,
and the gateway validates it against a dedicated connector certificate authority that AAI generates automatically.
Before the upgrade, your connectors were signed by your own certificate authority; after the upgrade, the gateway only trusts certificates signed by this new, separate connector certificate authority.
Your existing connector certificates, though never expired or revoked, don't chain up to it at all — because it didn't exist until the upgrade created it.
Your gateway's own certificate is not the cause of this and does not change as part of this upgrade (see Ports, HTTPS, and Certificates in AAI 26.0.0).

This means the failure looks like a certificate problem (because it is one) rather than a version-mismatch problem — expect handshake failures, not a friendly "please upgrade your connector" message.

2. Regenerate and deploy a new connector certificate

Do this for each connector separately. You do not need to regenerate the gateway's own certificate again — only the connector-side certificates.

Linux:

cd <install>/connectors
./generateFegConnector.sh \
  --customer-ca "<path-to-your-connector-CA-file>.p12" \
  --additional-trust-cert "<path-to-your-gateway's-own-certificate-file>" \
  --additional-trust-cert-password "<your-gateway-certificate's-plaintext-password>" \
  --connector-name "<your-connector-name>" \
  --connector-sans "<connector-ip>,<connector-hostname>" \
  --ca-password "<your-connector-CA-password>" \
  --connector-password "<new-connector-keystore-password>" \
  --output-dir "<install>/connectors/upgrade-output"

Windows:

cd "<install>\connectors"
generateFegConnector.bat ^
  --customer-ca "<path-to-your-connector-CA-file>.p12" ^
  --additional-trust-cert "<path-to-your-gateway's-own-certificate-file>" ^
  --additional-trust-cert-password "<your-gateway-certificate's-plaintext-password>" ^
  --connector-name "<your-connector-name>" ^
  --connector-sans "<connector-ip>,<connector-hostname>" ^
  --ca-password "<your-connector-CA-password>" ^
  --connector-password "<new-connector-keystore-password>" ^
  --output-dir "<install>\connectors\upgrade-output"

--customer-ca here is your connector certificate authority 
— not your own organization's certificate.
A connector needs to trust two independent things at once: the connector certificate authority that signs it, and your gateway's own certificate, which it also has to trust in order to connect at all.
That's what the two --additional-trust-cert flags are for — they point at your gateway's own existing certificate file and its plaintext password (the same certificate covered in Ports, HTTPS, and Certificates in AAI 26.0.0). 
Leaving either of these two flags out lets the command complete successfully, but the connector will still fail to connect afterward with a certificate-chain error 
— the connector certificate authority alone has no relationship to your gateway's certificate and cannot vouch for it. Nothing on the gateway host itself needs to change or restart for this step.

Then, for each connector:

  1. Copy the generated <your-connector-name>.jar (and only that file — not the accompanying .p12, which contains a private key and should stay with whoever administers the certificates) to the connector host's secure configuration location.
  2. Restart the connector service so it picks up the new certificate.
  3. Point the connector's own configuration at the gateway's current HTTPS port. Copying the certificate alone does not update the URL the connector calls — if the gateway's port changed as part of the upgrade (see Ports, HTTPS, and Certificates in AAI 26.0.0, Additional Information), the connector needs to be told the new port explicitly.

Plan this as part of the same maintenance window as the upgrade itself, not a follow-up task — every affected connector is down from the moment the upgrade completes until this finishes for that connector.

3. Check the connector SAN allowlist

SAN (Subject Alternative Name) is the list of hostnames/IPs a certificate is valid for — every connector certificate has one, identifying the connector. Separately from certificate regeneration,
AAI 26.0.0 has an optional feature that restricts which connector identities are permitted to connect at all
— independent of whether their certificate is otherwise valid.
When it's active, a freshly regenerated, perfectly valid connector certificate can still be rejected if its identity hasn't been explicitly added to the allowlist.
This is easy to misdiagnose as "the certificate regeneration didn't work," when the certificate is actually fine.

Whether this applies to you depends on your environment:

  • VM/traditional installer: off by default. Every connector certificate signed by the trusted certificate authority is accepted regardless of its identity, unless someone explicitly turned on enforcement (CONNECTOR_SAN_ALLOWLIST_ENABLED=true in your properties file). If nobody enabled this on your install, this section doesn't apply to you — skip to §4.
  • Kubernetes/OpenShift (Helm): on by default. Every Helm deployment enforces this unless explicitly disabled, and the allowlist starts out completely empty on a fresh deployment. This means every connector
    — even one with a perfectly valid, freshly-regenerated certificate — is rejected by default until its identity is explicitly added. Note this only matters once passthrough TLS is actually configured (see Environment above)
    — with the default edge-terminated Route/Ingress, no client certificate ever reaches the gateway for this check to act on in the first place.

Check whether it's active, and what's currently allowed, from the gateway's own startup log:

grep -i "Connector SAN allowlist loaded from" <your-gateway-log>
  • No match → the feature is disabled; this section doesn't apply.
  • A match looks like this, and tells you the file path and everything currently allowed:
Connector SAN allowlist loaded from '/etc/aai/connector-allowlist.json': 2 allowed SAN value(s): [10.0.1.5, 10.0.1.9]

Confirm a specific rejection is actually the allowlist, not the certificate itself:

grep -i "not found in connector allowlist" <your-gateway-log>

A match names the exact SAN(s) presented and rejected:

Rejecting request: client certificate SAN(s) [10.0.1.12] not found in connector allowlist (subject=CN=my-connector)

Add the new connector's identity to the allowlist. The file is JSON, one entry per connector:

{
  "connectors": [
    { "name": "store-connector-01", "sans": ["10.0.1.5"] }
  ]
}
  • VM: edit the file at the path your CONNECTOR_ALLOWLIST_PATH property points to, add an entry for the new connector's SAN(s), then restart the gateway.
    If you're using generateFegConnector to generate the connector, pass --allowlist-path pointing at this same file so the new entry merges in automatically instead of hand-editing JSON.
  • Kubernetes/OpenShift: this file lives on shared persistent storage mounted read-only into the gateway pod — you cannot edit it via kubectl exec.
    It's designed to be maintained by running your connector-generation tooling from outside the cluster, pointed at that same shared storage, using --allowlist-path.
    Confirm with whoever manages your cluster's storage how that path is reached from outside the cluster.

4. Verify

Confirm the new certificate is actually what's being presented, and that the gateway is accepting it:

openssl s_client -connect <connector-host>:<connector-port> -showcerts </dev/null

Confirm the certificate's issuer matches your certificate authority, and that its Subject Alternative Names include the hostname/IP the connector actually connects from
— a mismatch here (rather than an expired or wrong-CA certificate) is one of the more common causes of a handshake still failing after regeneration.

If the handshake succeeds but the connector still reports errors, check the connector's own log for the exact rejection
— a wrong CN/SAN, an unallowlisted identity (§3), and an expired certificate all fail differently and are easy to tell apart once you're looking at the actual log line rather than guessing from symptoms alone.

Additional Information

Powered by Wolken Software