feat(galaxy): operator-authenticated alarm ack — send Galaxy credential to mxaccessgw (#749)
v2-ci / unit-tests (push) Failing after 1h8m43s

mxaccessgw 488649c+ acknowledges by AuthenticateUser as the operator and
writing <alarm>.AckMsg, so AcknowledgeAlarmRequest now needs a real Galaxy
operator_user + operator_domain + operator_password. The OPC UA data plane is
API-key/anonymous and carries no Galaxy password, so the driver resolves the
account per ack:

1. the session's API key's Galaxy ack identity, set on AdminUI /apikeys and
   held ONLY in the encrypted Secrets store
   (otopcua/apikeys/<keyId>/galaxy-ack-{user,password}); a key with a user but
   no password secret is refused, never silently downgraded;
2. else the driver instance's AlarmAck fallback account (DriverConfig
   FallbackUser/FallbackDomain/FallbackPasswordSecretRef; secret:/${secret:}/
   env:/file:/dev: only — a literal is refused);
3. else DriverOperationRefusedException: nothing is sent, never an empty
   operator_user. Refusals are excluded from the resilience retry/breaker.

- Pins ZB.MOM.WW.MxGateway.Client/Contracts 0.2.1 -> 0.3.0 (vendored into
  nuget-packages/ from the Gitea feed, per the local-mxgw source mapping).
- The session ApiKeyId (not a secret) rides NativeAlarmAck ->
  RouteNativeAlarmAck -> RouteAlarmAck -> AlarmAcknowledgeRequest; the password
  is resolved in the driver and never travels through actor messages.
- The OPC UA principal + key id are appended to the AckMsg comment
  ("[OPC UA: <principal>, key <id>]") and logged, so a shared fallback
  account does not lose who acknowledged.
- Password never logged: GalaxyAckCredential.ToString omits it, the
  acknowledger scrubs it from every gateway message it echoes and withholds
  any exception that echoes it; audit rows carry only the key id.
- AdminUI: /apikeys "Ack identity" editor (set/remove; delete-key clears it),
  Galaxy driver form gains the fallback section.
- Synchronous OPC UA status for a refusal is follow-up #760 (the native ack
  path is fire-and-forget after the Part 9 method returns).

Tests: request mapping (password populated), password absent from logs and
exception text (mutation-checked), key-mapped / fallback / refused paths at
resolver and driver level, breaker non-trip, key-id propagation through node
manager and DriverHostActor, AdminUI service + form round-trip.

Closes #749
This commit is contained in:
Joseph Doherty
2026-11-06 16:23:00 -05:00
parent 7ec5b95d24
commit dc0a24f224
38 changed files with 1814 additions and 83 deletions
@@ -4,7 +4,9 @@
@using ZB.MOM.WW.OtOpcUa.Configuration.Entities
@using ZB.MOM.WW.OtOpcUa.Core.Authorization
@using ZB.MOM.WW.OtOpcUa.AdminUI.Components.Shared.Raw
@using ZB.MOM.WW.OtOpcUa.AdminUI.ApiKeyAck
@inject IApiKeyAdminService Keys
@inject IApiKeyGalaxyAckIdentityService AckIdentities
<PageErrorBoundary>
<div class="d-flex justify-content-between align-items-center mb-3">
@@ -50,6 +52,45 @@
</div>
</section>
@if (_ackEditKeyId is not null)
{
<section class="panel mb-3">
<div class="panel-head">Galaxy alarm-ack identity — key <span class="mono">@_ackEditKeyId</span></div>
<div style="padding:1rem">
<div class="form-text mb-2">
Native Galaxy alarm acknowledges from sessions using this key authenticate as this Galaxy account, and
the Historian records it as the operator. Stored encrypted in the Secrets store
(<span class="mono">otopcua/apikeys/@(_ackEditKeyId)/galaxy-ack-*</span>), never in the database. Keys
without an identity use the Galaxy driver's fallback account; with neither, acknowledges are refused.
On a split admin/driver topology the two secrets must also exist on the driver nodes.
</div>
<div class="row g-2">
<div class="col-md-3">
<label class="form-label" for="ack-user">Galaxy user</label>
<input id="ack-user" class="form-control form-control-sm" @bind="_ackUser" autocomplete="off" />
</div>
<div class="col-md-3">
<label class="form-label" for="ack-domain">Domain (optional)</label>
<input id="ack-domain" class="form-control form-control-sm" @bind="_ackDomain" autocomplete="off" />
</div>
<div class="col-md-3">
<label class="form-label" for="ack-password">Password</label>
<input id="ack-password" type="password" class="form-control form-control-sm" @bind="_ackPassword"
autocomplete="new-password" />
</div>
<div class="col-md-3 d-flex align-items-end gap-2">
<button class="btn btn-sm btn-primary" @onclick="SaveAckIdentityAsync" disabled="@_busy">Save</button>
@if (_ackIdentities.ContainsKey(_ackEditKeyId))
{
<button class="btn btn-sm btn-outline-danger" @onclick="ClearAckIdentityAsync" disabled="@_busy">Remove</button>
}
<button class="btn btn-sm btn-secondary" @onclick="CloseAckEditor" disabled="@_busy">Cancel</button>
</div>
</div>
</div>
</section>
}
<section class="panel">
<div class="panel-head">Keys</div>
@if (_keys is null)
@@ -71,6 +112,7 @@
<th>Principal</th>
<th>Key id</th>
<th>Status</th>
<th>Galaxy ack identity</th>
<th>Created (UTC)</th>
<th>Expires (UTC)</th>
<th></th>
@@ -97,6 +139,16 @@
<span class="badge bg-success">active</span>
}
</td>
<td>
@if (_ackIdentities.TryGetValue(k.ApiKeyId, out var ackId))
{
<span class="mono">@ackId</span>
}
else
{
<span class="text-muted">driver fallback</span>
}
</td>
<td>@k.CreatedUtc.ToString("yyyy-MM-dd HH:mm")</td>
<td>@(k.ExpiresUtc?.ToString("yyyy-MM-dd") ?? "—")</td>
<td class="text-end">
@@ -105,6 +157,8 @@
@onclick="() => SetEnabledAsync(k.ApiKeyId, !k.Enabled)" disabled="@_busy">
@(k.Enabled ? "Revoke" : "Re-enable")
</button>
<button class="btn btn-sm btn-outline-secondary"
@onclick="() => OpenAckEditor(k.ApiKeyId)" disabled="@_busy">Ack identity</button>
<button class="btn btn-sm btn-outline-danger"
@onclick="() => RequestDelete(k)" disabled="@_busy">Delete</button>
</div>
@@ -121,7 +175,17 @@
</PageErrorBoundary>
@code {
[CascadingParameter] private Task<AuthenticationState>? AuthState { get; set; }
private IReadOnlyList<ApiKey>? _keys;
private IReadOnlyDictionary<string, string> _ackIdentities = new Dictionary<string, string>();
// Galaxy ack identity editor (lmxopcua#749). The password lives in component state only while the
// editor is open and is cleared on save/cancel; it is never rendered back.
private string? _ackEditKeyId;
private string _ackUser = "";
private string _ackDomain = "";
private string _ackPassword = "";
private string _newName = "";
private string _newPrincipal = "";
private DateTime? _newExpires;
@@ -142,6 +206,8 @@
try
{
_keys = await Keys.ListAsync(default);
try { _ackIdentities = await AckIdentities.ListAsync(default); }
catch (Exception ex) { _ackIdentities = new Dictionary<string, string>(); _error = $"Galaxy ack identities unavailable: {ex.Message}"; }
// The one-time banner is only meaningful while its key exists; the credential is
// otua_<keyId>_<secret>, so drop it once no listed key matches (deleted here or elsewhere).
if (_created is not null
@@ -222,9 +288,73 @@
try
{
await Keys.DeleteAsync(apiKeyId, default);
// A deleted key's ack identity must not linger in the Secrets store.
await AckIdentities.ClearAsync(apiKeyId, await ActorAsync(), default);
if (_ackEditKeyId == apiKeyId) CloseAckEditor();
await ReloadAsync();
}
catch (Exception ex) { _error = ex.Message; }
finally { _busy = false; }
}
private void OpenAckEditor(string apiKeyId)
{
_ackEditKeyId = apiKeyId;
_ackPassword = "";
if (_ackIdentities.TryGetValue(apiKeyId, out var current))
{
var slash = current.IndexOf('\\');
_ackDomain = slash < 0 ? "" : current[..slash];
_ackUser = slash < 0 ? current : current[(slash + 1)..];
}
else
{
_ackUser = "";
_ackDomain = "";
}
}
private void CloseAckEditor()
{
_ackEditKeyId = null;
_ackUser = "";
_ackDomain = "";
_ackPassword = "";
}
private async Task SaveAckIdentityAsync()
{
if (_ackEditKeyId is not { } id) return;
_busy = true;
_error = null;
try
{
await AckIdentities.SetAsync(id, _ackUser, _ackDomain, _ackPassword, await ActorAsync(), default);
CloseAckEditor();
await ReloadAsync();
}
catch (Exception ex) { _error = ex.Message; }
finally { _busy = false; }
}
private async Task ClearAckIdentityAsync()
{
if (_ackEditKeyId is not { } id) return;
_busy = true;
_error = null;
try
{
await AckIdentities.ClearAsync(id, await ActorAsync(), default);
CloseAckEditor();
await ReloadAsync();
}
catch (Exception ex) { _error = ex.Message; }
finally { _busy = false; }
}
private async Task<string> ActorAsync()
{
var user = AuthState is null ? null : (await AuthState).User;
return user?.Identity?.Name is { Length: > 0 } name ? name : "unknown";
}
}
@@ -84,6 +84,35 @@
</div>
</section>
@* Native alarm acknowledge credential (lmxopcua#749) *@
<section class="panel rise mt-3" style="animation-delay:.09s">
<div class="panel-head">Alarm acknowledge — fallback Galaxy account</div>
<div style="padding:1rem">
<div class="form-text mb-2">
The gateway acknowledges by authenticating as a Galaxy user and writing <code>AckMsg</code>, so the Historian
records that user. An API key with its own Galaxy ack identity (set on <a href="/apikeys">API keys</a>) uses
that; keys without one and anonymous sessions use this account. With neither, acknowledges are refused.
</div>
<div class="row g-3">
<div class="col-md-3">
<label class="form-label">Fallback user</label>
<InputText @bind-Value="_form.Galaxy.AckFallbackUser" @bind-Value:after="EmitAsync" class="form-control form-control-sm"
placeholder="(none — refuse)" />
</div>
<div class="col-md-3">
<label class="form-label">Fallback domain (optional)</label>
<InputText @bind-Value="_form.Galaxy.AckFallbackDomain" @bind-Value:after="EmitAsync" class="form-control form-control-sm" />
</div>
<div class="col-md-6">
<label class="form-label">Fallback password secret ref</label>
<InputText @bind-Value="_form.Galaxy.AckFallbackPasswordSecretRef" @bind-Value:after="EmitAsync" class="form-control form-control-sm mono"
placeholder="secret:otopcua/galaxy/ack-fallback-password" />
<div class="form-text">Forms: <code>secret:NAME</code> (production), <code>env:NAME</code>, <code>file:PATH</code>, <code>dev:VALUE</code>. A bare literal is refused.</div>
</div>
</div>
</div>
</section>
@* Repository *@
<section class="panel rise mt-3" style="animation-delay:.10s">
<div class="panel-head">Galaxy repository</div>
@@ -237,12 +266,18 @@
// GalaxyDriverOptions top-level
public int ProbeTimeoutSeconds { get; set; } = 30;
// GalaxyAlarmAckOptions (lmxopcua#749)
public string? AckFallbackUser { get; set; }
public string? AckFallbackDomain { get; set; }
public string? AckFallbackPasswordSecretRef { get; set; }
public static GalaxyFormModel FromRecord(GalaxyDriverOptions r)
{
var gw = r.Gateway ?? new GalaxyGatewayOptions("https://localhost:5001", "env:MX_API_KEY");
var mx = r.MxAccess ?? new GalaxyMxAccessOptions("OtOpcUa");
var repo = r.Repository ?? new GalaxyRepositoryOptions();
var rc = r.Reconnect ?? new GalaxyReconnectOptions();
var ack = r.AlarmAck ?? new GalaxyAlarmAckOptions();
return new()
{
GatewayEndpoint = gw.Endpoint,
@@ -262,6 +297,9 @@
ReconnectMaxBackoffMs = rc.MaxBackoffMs,
ReconnectReplayOnSessionLost = rc.ReplayOnSessionLost,
ProbeTimeoutSeconds = r.ProbeTimeoutSeconds,
AckFallbackUser = ack.FallbackUser,
AckFallbackDomain = ack.FallbackDomain,
AckFallbackPasswordSecretRef = ack.FallbackPasswordSecretRef,
};
}
@@ -288,6 +326,10 @@
ReplayOnSessionLost: ReconnectReplayOnSessionLost))
{
ProbeTimeoutSeconds = ProbeTimeoutSeconds,
AlarmAck = new GalaxyAlarmAckOptions(
FallbackUser: string.IsNullOrWhiteSpace(AckFallbackUser) ? null : AckFallbackUser.Trim(),
FallbackDomain: string.IsNullOrWhiteSpace(AckFallbackDomain) ? null : AckFallbackDomain.Trim(),
FallbackPasswordSecretRef: string.IsNullOrWhiteSpace(AckFallbackPasswordSecretRef) ? null : AckFallbackPasswordSecretRef.Trim()),
};
}
}