Troubleshoot AIM health check endpoint

AVEVA Identity Manager (AIM) provides a health-check endpoint that reports the real-time status of the identity services the platform depends on https://<aim-host>/identitymanager/v2/healthz.

This endpoint reports whether the configured identity provider is currently reachable and able to authenticate users. To determine this, AIM runs a lightweight background probe against the discovery endpoint of the configured Federated Identity Provider (FIDP). The probe behavior is controlled by two settings and they are as follows:

• AvailabilityCheckTimeout: Specifies the maximum time period AIM waits for a response from the configured identity provider during the availability probe.

• ResultCacheDuration: Specifies the duration AIM retains (caches) the most recent probe result before initiating a new availability check.

Client applications and monitoring tools do not run the availability probe themselves. They retrieve the current status by calling the AIM /healthz endpoint, either directly or through the SDK.

Identity provider topology

A deployment is configured to use a single Federated Identity Provider (FIDP) at any given time. Optionally, a domain connection can be configured to provide fallback authentication if the active FIDP is unavailable.

• A single FIDP is active at any time. The deployment authenticates against either Azure AD or CONNECT. The health check reports the status of the currently configured active FIDP.

• The domain connection provides fallback authentication. If the active FIDP is unreachable, the deployment can authenticate domain users, depending on the configured settings.

• The health check represents the reachability of the active FIDP. This status is the primary indicator used to determine whether the system remains in Connected Mode or begins transitioning to Offline Fallback Mode.

Configuration settings

The background probe is controlled by two settings in the AIM configuration file (appsettings.json), located at the following location:

C:\Program Files (x86)\AVEVA\Platform Common Services\Management Server\appsettings.json

{

  "OpenIdConnectAvailability": {

    "AvailabilityCheckTimeout": "00:00:03",

    "ResultCacheDuration": "00:00:15"

  }

}

AvailabilityCheckTimeout

This setting specifies the maximum time period AIM waits for the active FIDP to respond to the availability probe before the provider is considered as unavailable.

• Default: The default time period is 3 seconds. A healthy FIDP typically responds in well under one second, so three seconds provides a comfortable margin while keeping the worst-case response time of the /healthz endpoint short.

• If set too low: A temporarily slow network or a busy identity provider may be reported as unavailable even though it is reachable (false negative).

• If set too high: When the identity provider is genuinely down, AIM and any client waiting on /healthz, waits longer before reporting the issue.

ResultCacheDuration

After AIM obtains a result (available or unavailable), it stores that result for this duration. While the stored result is valid, further calls to /healthz return the value immediately without contacting the identity provider again.

• Default: The default time period is 15 seconds. This aligns with typical monitoring poll intervals, ensuring at most one live probe per identity provider per 15-second window, regardless of how often /healthz is called.

• If set to 00:00:00: Caching is disabled and every /healthz call triggers a live probe. This increases load on the identity provider and is not recommended in production.

• If set too high: After an outage, AIM continues to report unavailable for the full cache duration after the identity provider has recovered, delaying the return to normal operation.

The relationship between these two settings and the frequency at which clients call /healthz is important.

Behaviour during normal operation

Under healthy conditions, the feature operates with low impact:

• A client or monitor calls /healthz.

• AIM checks its cached result for the active FIDP. If none exists, it sends a probe to the FIDP discovery endpoint.

• The FIDP responds (typically in under one second). AIM stores available for 15 seconds.

• For the next 15 seconds, further /healthz calls return the cached result instantly, with no additional traffic to the FIDP.

• After 15 seconds, the next call triggers one fresh probe, and the cycle repeats.

• Network overhead: Approximately four probes per minute per AIM instance for the active FIDP. This is negligible.

Behaviour during failures

The following table reflects the single-active-FIDP topology with a domain backup.

Recommended configuration

For most deployments, no action is required.

The default values (3-second timeout and 15-second cache) are tuned for typical cloud and data-centre environments that connect to Azure AD or CONNECT, and they work well without adjustment.

Conditions requiring adjustment

The following table explains situation when adjustment are needed:

Configuration changes take effect after a service restart, or after a configuration reload where supported by the hosting platform.