Allow promoting shadowed authentication connections

Author: sfmskywalker

specs/012-external-authentication/contracts/rest-api.md

@@ -313,6 +313,8 @@ Requires `external-authentication:connections:read`. Maximum `pageSize` is 100.
       "key": "contoso",
       "source": "database",
       "overridesConfigurationConnection": true,
+      "canCreateOverride": false,
+      "canPromoteToConfigurationOverride": false,
       "adapterType": "openid-connect",
       "callbackUri": "https://elsa.example/elsa/api/external-authentication/callback/contoso",
       "previewCallbackUri": "https://elsa.example/elsa/api/external-authentication/previews/callback/01JZCONNECTION",
@@ -381,6 +383,8 @@ POST /external-authentication/connections
 
 Requires `external-authentication:connections:create`. Studio starts with a complete editable copy of the configuration-owned connection, preserves its immutable logical `key`, and submits the ordinary create document with `"overridesConfigurationConnection": true`. The server creates a distinct database record with `source=database`; subsequent saves send the whole document to the ordinary update endpoint. No inherited field markers or partial patch semantics exist. A disabled database override continues shadowing the configuration-owned connection. Archiving it reveals configuration; restoring it resumes shadowing in disabled state.
 
+Connection responses expose `canCreateOverride` for configuration-owned connections when deployment policy permits creating a database override. They expose `canPromoteToConfigurationOverride` for an unarchived, shadowed database-owned connection when the same policy permits promotion. Clients promote that existing record by updating its ordinary document with `"overridesConfigurationConnection": true`; this preserves its ID, secret bindings, and enabled lifecycle instead of creating another database record. A promotion that would remove the final normal sign-in path returns `409 conflict` with `error="conflict"` and `details.code="final_login_path_guard"`.
+
 ### Detail and Update
 
 ```http

src/clients/Elsa.Api.Client/Resources/ExternalAuthentication/Connections/Models/ExternalAuthenticationConnection.cs

@@ -23,6 +23,7 @@ public sealed class ExternalAuthenticationConnection
     public bool IsPreferred { get; set; }
     public bool OverridesConfigurationConnection { get; set; }
     public bool CanCreateOverride { get; set; }
+    public bool CanPromoteToConfigurationOverride { get; set; }
     public bool EnabledIntent { get; set; }
     public bool EffectivelyEnabled { get; set; }
     public string Validity { get; set; } = "";

src/modules/Elsa.ExternalAuthentication/Endpoints/Connections/ConnectionManagementModels.cs

@@ -108,6 +108,7 @@ internal sealed class ConnectionResponse
     public bool IsPreferred { get; init; }
     public bool OverridesConfigurationConnection { get; init; }
     public bool CanCreateOverride { get; init; }
+    public bool CanPromoteToConfigurationOverride { get; init; }
     public bool EnabledIntent { get; init; }
     public bool EffectivelyEnabled { get; init; }
     public string Validity { get; init; } = null!;
@@ -157,6 +158,7 @@ public static async ValueTask<ConnectionResponse> FromAsync(EffectiveIdentityPro
             IsPreferred = effective.Connection.IsPreferred,
             OverridesConfigurationConnection = effective.Connection.OverridesConfigurationConnection,
             CanCreateOverride = effective.Ownership == ConnectionSourceOwnership.Configuration && management.CanCreateConfigurationOverride(),
+            CanPromoteToConfigurationOverride = management.CanPromoteToConfigurationOverride(effective),
             EnabledIntent = effective.Connection.IsEnabled,
             EffectivelyEnabled = effective.Connection.IsEnabled && !effective.Connection.ArchivedAt.HasValue && !effective.IsShadowed && effective.Validity != ConnectionValidity.Invalid,
             Validity = effective.Validity.ToString().ToLowerInvariant(),

src/modules/Elsa.ExternalAuthentication/README.md

@@ -28,6 +28,7 @@ Use `BindExternalAuthenticationOptions` for `IConfiguration` binding so the arbi
 - `ExternalAuthentication:Connections` defines immutable, configuration-owned connections.
 - Database-owned connections are optional and controlled by `EnableDatabaseConnections`.
 - Configuration takes precedence over a database connection with the same effective key and scope. Studio shows the database row as shadowed instead of silently overwriting it.
+- When `AllowConfigurationConnectionOverrides` is enabled, an administrator can promote an unarchived shadowed database connection into an explicit override, preserving that record, its secret bindings, and its lifecycle. A promotion that would remove the final normal sign-in path is rejected by the final-login-path guard.
 - Authentication Clients, extension allowlists, permission boundaries, egress policy, and final-login recovery policy remain deployment-owned.
 
 An empty `AllowedAdapterTypes` collection permits every installed adapter. The built-in policy allowlist contains `reject` and `create-user`; the built-in grant-source allowlist contains `elsa-roles`, `claim-mapping`, `group-mapping`, and `claim-pass-through`.

src/modules/Elsa.ExternalAuthentication/Services/IdentityProviderConnectionManagementService.cs

@@ -260,10 +260,32 @@ public async ValueTask<ConnectionValidationResult> ValidateAsync(IdentityProvide
 
     public bool CanCreateConfigurationOverride() => options.Value.AllowConfigurationConnectionOverrides;
 
+    public bool CanPromoteToConfigurationOverride(EffectiveIdentityProviderConnection connection) =>
+        connection.Ownership == ConnectionSourceOwnership.Database &&
+        connection.IsShadowed &&
+        !connection.Connection.ArchivedAt.HasValue &&
+        options.Value.AllowConfigurationConnectionOverrides;
+
     private async ValueTask<bool> IsBlockedByFinalLoginPathGuardAsync(IdentityProviderConnection existing, IdentityProviderConnection candidate, string targetTenantId, ClaimsPrincipal actor, bool confirmedOverride, CancellationToken cancellationToken)
     {
         var guard = services.GetService<FinalLoginPathGuard>();
-        return guard is not null && await guard.AuthorizeAsync(existing, candidate, targetTenantId, actor, confirmedOverride, cancellationToken) == FinalLoginPathGuardResult.Denied;
+        if (guard is null)
+            return false;
+
+        var guardExisting = existing;
+        if (!existing.OverridesConfigurationConnection && candidate.OverridesConfigurationConnection)
+        {
+            var normalizedKey = ConnectionRevisionCalculator.NormalizeKey(candidate.Key);
+            var effective = await registry.GetAsync(targetTenantId, cancellationToken);
+            var displacedConfigurationConnection = effective.Connections.FirstOrDefault(x =>
+                x.Ownership == ConnectionSourceOwnership.Configuration &&
+                !x.IsShadowed &&
+                string.Equals(ConnectionRevisionCalculator.NormalizeKey(x.Connection.Key), normalizedKey, StringComparison.Ordinal));
+            if (displacedConfigurationConnection is not null)
+                guardExisting = displacedConfigurationConnection.Connection;
+        }
+
+        return await guard.AuthorizeAsync(guardExisting, candidate, targetTenantId, actor, confirmedOverride, cancellationToken) == FinalLoginPathGuardResult.Denied;
     }
 
     private async ValueTask<ManagementConnectionMutationResult> ProcessMutationAsync(ConnectionMutationResult result, ClaimsPrincipal actor, string operation, ConnectionLifecycle? previousLifecycle, CancellationToken cancellationToken, IdentityProviderConnection? previousConnection = null)
@@ -479,6 +501,7 @@ private void NormalizeForUpdate(IdentityProviderConnection candidate, IdentityPr
     {
         candidate.Key = candidate.Key?.Trim() ?? string.Empty;
         candidate.TenantId = ConnectionScope.HostTenantId;
+        candidate.IsEnabled = existing.IsEnabled;
         candidate.UpdatedAt = clock.UtcNow;
         candidate.SecretBindings ??= new Dictionary<string, SecretBinding>(StringComparer.Ordinal);
         candidate.PermissionGrantSources ??= [];