Harden external authentication contracts and flows

Author: sfmskywalker

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

@@ -293,7 +293,7 @@ Adapter descriptor:
 ```http
 GET /external-authentication/connections
     ?search=
-    &source=configuration|studio|studioOverride
+    &source=configuration|database
     &adapterType=
     &enabled=
     &valid=
@@ -311,9 +311,11 @@ Requires `external-authentication:connections:read`. Maximum `pageSize` is 100.
     {
       "id": "01JZCONNECTION",
       "key": "contoso",
-      "source": "studioOverride",
-      "overridesConfiguration": true,
+      "source": "database",
+      "overridesConfigurationConnection": true,
       "adapterType": "openid-connect",
+      "callbackUri": "https://elsa.example/elsa/api/external-authentication/callback/contoso",
+      "previewCallbackUri": "https://elsa.example/elsa/api/external-authentication/previews/callback/01JZCONNECTION",
       "displayName": "Contoso",
       "iconId": "building",
       "order": 10,
@@ -350,17 +352,17 @@ Requires `external-authentication:connections:create`.
 ```json
 {
   "key": "contoso",
+  "scope": {"kind":"host"},
   "adapterType": "openid-connect",
   "displayName": "Contoso",
   "iconId": "building",
   "order": 10,
   "isPreferred": false,
   "adapterSettingsVersion": 1,
   "adapterSettings": {},
-  "secretBindings": {},
+  "overridesConfigurationConnection": false,
   "unlinkedPolicy": {"type":"reject","settingsVersion":1,"settings":{}},
-  "defaultRoleIds": [],
-  "matcherPolicy": null,
+  "permissionGrantSources": [],
   "claimProjection": {
     "allowedClaimTypes": ["name", "email", "groups"],
     "redactedClaimTypes": ["email"]
@@ -371,13 +373,13 @@ Requires `external-authentication:connections:create`.
 
 Creates a disabled draft. Success: `201`, `Location` header, `ETag: "1"`, and detail body.
 
-### Create Studio Override
+### Create Database Override
 
 ```http
-POST /external-authentication/connections/{connectionId}/override
+POST /external-authentication/connections
 ```
 
-Requires create/update authorization and an explicit confirmation payload. The server returns a complete editable copy with `source=studioOverride`; subsequent saves send the whole document. No inherited field markers or partial patch semantics exist. A disabled override continues shadowing. Archiving it reveals configuration; restoring it resumes shadowing in disabled state.
+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.
 
 ### Detail and Update
 
@@ -388,15 +390,15 @@ PUT /external-authentication/connections/{connectionId}
 
 Read requires `external-authentication:connections:read`; update requires `external-authentication:connections:update` and `If-Match`.
 
-Detail includes the create fields plus lifecycle, validation, shadow/conflict diagnostics, effective policy, resolved extension availability, and secret binding state:
+Detail includes the create fields plus lifecycle, validation, shadow/conflict diagnostics, effective policy, resolved extension availability, and secret binding state. `callbackUri` and `previewCallbackUri` are deployment-derived, read-only values that must be registered exactly with strict providers when their respective normal and administrator-preview flows are used:
 
 ```json
 {
   "secretBindings": {
     "clientSecret": {
-      "resolverType": "elsa-secrets",
       "ownership": "managed",
-      "reference": "contoso-oidc-secret",
+      "resolverType": null,
+      "reference": null,
       "isConfigured": true,
       "isResolvable": true
     }
@@ -423,42 +425,43 @@ For an OpenID Connect connection, `adapterSettings` MAY include explicit overrid
 }
 ```
 
-The safe default is to omit `advancedTrustOverrides` and use the exact `discoveryUrl`. Creating or updating a connection with any advanced trust override requires both the normal create/update permission and `external-authentication:provider-trust:unsafe`; deployment policy must also allow the operation. The command MUST include the non-persisted field `"confirmUnsafeProviderTrust": true`; omission or `false` is rejected. Acceptance emits a security notification containing the connection identity, changed field names, actor, and revision, but not signing-key bodies or secret material. Authorized detail responses return the configured override values and identify that Advanced trust is active so Studio can keep its warning visible; `confirmUnsafeProviderTrust` is never returned or persisted.
+The safe default is to omit `advancedTrustOverrides` and use the exact `discoveryUrl`. Creating or updating a connection with any advanced trust override requires both the normal create/update permission and `external-authentication:provider-trust:unsafe`; deployment policy must also allow the operation. The command MUST include the non-persisted field `"confirmUnsafeSettings": true`; omission or `false` is rejected. Acceptance emits a security notification containing the connection identity, changed field names, actor, and revision, but not signing-key bodies or secret material. Authorized detail responses return the configured override values and identify that Advanced trust is active so Studio can keep its warning visible; `confirmUnsafeSettings` is never returned or persisted.
 
 These fields replace only the corresponding discovery-derived inputs. They cannot change Elsa-owned callback routing, confidential-client requirements, mandatory S256 PKCE, or state, correlation, nonce, signature, issuer, audience/authorized-party, expiry, and callback-error validation.
 
 ### Secret Binding Replacement/Removal
 
 ```http
-PUT /external-authentication/connections/{connectionId}/secret-bindings/{fieldName}
+PUT /external-authentication/connections/{connectionId}/secret-bindings/{fieldName}/managed
 DELETE /external-authentication/connections/{connectionId}/secret-bindings/{fieldName}
 ```
 
 Requires `external-authentication:connections:update` and `If-Match`.
 
 ```json
 {
-  "ownership": "managed",
   "resolverType": "elsa-secrets",
-  "reference": "contoso-oidc-secret",
-  "expectedType": "text",
-  "expectedScope": "external-authentication"
+  "value": "write-only-secret-value"
 }
 ```
 
-If the Elsa Secrets bridge supports inline creation/replacement, its secret value is submitted to the Secrets API, not returned or embedded in the connection response. External bindings use `ownership=external` and a deployment resolver such as `configuration`; their value cannot be replaced or removed through these endpoints.
+The managed writer stages a new secret reference, publishes it only if the connection revision compare-and-swap succeeds, and removes staged material after any definitive failure. If a store failure has an ambiguous commit outcome and the persisted binding cannot be verified, Elsa retains the staged material rather than risk deleting a live secret and records an operational warning. Neither the value nor the managed reference is returned. General create/update connection documents cannot supply secret bindings.
+
+External bindings use `ownership=external` and a deployment resolver such as `configuration`. They are deployment-owned, may be declared only by configuration connections, and cannot be created, replaced, or removed through management endpoints.
 
 ### Lifecycle Actions
 
 ```http
 POST /external-authentication/connections/{connectionId}/enable
-POST /external-authentication/connections/{connectionId}/disable?confirmFinalLoginPathOverride=false
+POST /external-authentication/connections/{connectionId}/disable?confirmFinalLoginPathOverride=false&revokeActiveSessions=false
 DELETE /external-authentication/connections/{connectionId}?confirmFinalLoginPathOverride=false
 POST /external-authentication/connections/{connectionId}/restore
 ```
 
 All require `If-Match`.
 
+`revokeActiveSessions=true` additionally requires `external-authentication:sessions:revoke` and emits an aggregate, redacted session-revocation security notification.
+
 Disabling or archiving the final normal login method is rejected with `409 conflict` and `details.code` set to `final_login_path_guard` unless another normal/local method or deployment-owned break-glass method remains. A caller holding the deployment-configured privileged override permission may repeat the operation with `confirmFinalLoginPathOverride=true`; Studio requires a separate explicit recovery confirmation before sending it.
 
 | Action | Permission |
@@ -514,6 +517,8 @@ Requires `external-authentication:connections:preview`. POST requires `If-Match`
 
 The authorize route consumes the administrator-bound start state and redirects to the provider. The provider callback stores only a redacted result and returns safe completion status. Result GET is one-time, bound to the initiating administrator session, and returns the allowlisted Preview Result. It returns `410` after expiry/consumption and never produces a normal completion code.
 
+The provider registration must include the exact read-only `previewCallbackUri` returned on the connection resource. This is distinct from the normal `callbackUri` because preview completion is isolated from user sign-in and cannot create a user, link, credential, or session.
+
 ## External Identity Links
 
 ### Bounded User Lookup

specs/012-external-authentication/data-model.md

@@ -184,6 +184,8 @@ Shared, protected, short-lived provider/local/preview correlation state.
 | `ExpiresAt` | DateTimeOffset | Default 10 minutes |
 | `ConsumedAt` | DateTimeOffset? | Atomic single-use marker |
 
+EF persistence also stores the normalized `ExpiresAtUtcTicks` companion used in the same compare-and-swap predicate as `ConsumedAt`, because not every supported provider can order `DateTimeOffset` values directly.
+
 The public handle contains no protected payload. Atomic take transitions pending to consumed; expired or mismatched state is never revived.
 
 ## AuthorizationGrant
@@ -202,6 +204,8 @@ Single-use Elsa completion code record.
 | `ExpiresAt` | DateTimeOffset | Default 60 seconds |
 | `ConsumedAt` | DateTimeOffset? | Atomic single use |
 
+EF persistence uses the same normalized `ExpiresAtUtcTicks` companion for the atomic consume predicate.
+
 ## ExternalAuthenticationSession
 
 | Field | Type | Rules |
@@ -262,6 +266,8 @@ An observation is stale when its tested revision differs from the current effect
 | `ExpiresAt` | DateTimeOffset | Default 10 minutes |
 | `ConsumedAt` | DateTimeOffset? | One-time read |
 
+EF persistence uses the same normalized `ExpiresAtUtcTicks` companion for the atomic consume predicate.
+
 ## OpenIdConnectAdapterSettings v2
 
 | Field | Type | Rules |

specs/012-external-authentication/quickstart.md

@@ -106,10 +106,13 @@ Authentication__ExternalAuthentication__ClientSecret={strong-random-value}
 ```json
 {
   "ExternalAuthentication": {
+    "Redirects": {
+      "ExternalCallbackBaseUri": "https://elsa.example/elsa/api/"
+    },
     "Connections": [
       {
         "id": "01JZCONTOSOOIDC000000000001",
-        "connectionKey": "contoso-workforce",
+        "key": "contoso-workforce",
         "adapterType": "openid-connect",
         "displayName": "Contoso",
         "iconId": "building",
@@ -135,9 +138,10 @@ Authentication__ExternalAuthentication__ClientSecret={strong-random-value}
         "unlinkedPolicy": {
           "type": "create-user",
           "settingsVersion": 1,
-          "settings": {}
+          "settings": {
+            "defaultRoleIds": ["workflow-user"]
+          }
         },
-        "defaultRoleIds": ["workflow-user"],
         "claimProjection": {
           "allowedClaimTypes": ["name", "email", "groups"],
           "redactedClaimTypes": ["email"],
@@ -173,9 +177,10 @@ Elsa derives the provider callback from its deployment-owned external base addre
 
 ```text
 https://elsa.example/elsa/api/external-authentication/callback/contoso-workforce
+https://elsa.example/elsa/api/external-authentication/previews/callback/01JZCONTOSOOIDC000000000001
 ```
 
-Register that exact callback with the provider. The callback, confidential-client requirement, S256 PKCE, and validation steps are immutable. Discovery-derived issuer, authorization/token endpoints, and signing keys appear only under **Advanced** when deployment policy enables unsafe provider trust and the caller has the dedicated permission; saving them requires explicit confirmation and leaves a persistent warning. The configuration-first example intentionally uses discovery without overrides.
+Register both exact callbacks with the provider when administrators will use Preview. The first handles normal user sign-in and is keyed by the immutable logical Connection Key; the second handles administrator previews and is keyed by the stable connection record ID. Both are shown read-only in management responses and Studio. The callbacks, confidential-client requirement, S256 PKCE, and validation steps are immutable. Discovery-derived issuer, authorization/token endpoints, and signing keys appear only under **Advanced** when deployment policy enables unsafe provider trust and the caller has the dedicated permission; saving them requires explicit confirmation and leaves a persistent warning. The configuration-first example intentionally uses discovery without overrides.
 
 The role IDs in `defaultRoleIds` must exist, and the actor applying persisted equivalents must be authorized to assign them. They apply only when `create-user` creates a new user. The optional matcher-based policy selects one deployed `IExternalUserMatcher`; v1 ships no Elsa verified-email matcher, and matchers never select roles or permissions.
 

src/clients/Elsa.Api.Client/Resources/ExternalAuthentication/Connections/Contracts/IExternalAuthenticationConnectionsApi.cs

@@ -26,19 +26,37 @@ public interface IExternalAuthenticationConnectionsApi
     Task<ExternalAuthenticationConnection> EnableAsync(string connectionId, [Header("If-Match")] string ifMatch, CancellationToken cancellationToken = default);
 
     [Post("/external-authentication/connections/{connectionId}/disable")]
-    Task<ExternalAuthenticationConnection> DisableAsync(string connectionId, [Header("If-Match")] string ifMatch, CancellationToken cancellationToken = default);
+    Task<ExternalAuthenticationConnection> DisableAsync(
+        string connectionId,
+        [Header("If-Match")] string ifMatch,
+        [Query] bool confirmFinalLoginPathOverride = false,
+        [Query] bool revokeActiveSessions = false,
+        CancellationToken cancellationToken = default);
 
     [Delete("/external-authentication/connections/{connectionId}")]
-    Task<ExternalAuthenticationConnection> ArchiveAsync(string connectionId, [Header("If-Match")] string ifMatch, CancellationToken cancellationToken = default);
+    Task<ExternalAuthenticationConnection> ArchiveAsync(
+        string connectionId,
+        [Header("If-Match")] string ifMatch,
+        [Query] bool confirmFinalLoginPathOverride = false,
+        CancellationToken cancellationToken = default);
 
     [Post("/external-authentication/connections/{connectionId}/restore")]
     Task<ExternalAuthenticationConnection> RestoreAsync(string connectionId, [Header("If-Match")] string ifMatch, CancellationToken cancellationToken = default);
 
     [Post("/external-authentication/connections/{connectionId}/validate")]
     Task<ValidateExternalAuthenticationConnectionResponse> ValidateAsync(string connectionId, CancellationToken cancellationToken = default);
 
-    [Put("/external-authentication/connections/{connectionId}/secret-bindings/{fieldName}")]
-    Task<ExternalAuthenticationConnection> ReplaceSecretBindingAsync(string connectionId, string fieldName, [Body] SaveExternalAuthenticationSecretBindingRequest request, [Header("If-Match")] string ifMatch, CancellationToken cancellationToken = default);
+    [Post("/external-authentication/connections/{connectionId}/test")]
+    Task<TestExternalAuthenticationConnectionResponse> TestAsync(string connectionId, [Header("If-Match")] string ifMatch, CancellationToken cancellationToken = default);
+
+    [Post("/external-authentication/connections/{connectionId}/preview")]
+    Task<InitiateExternalAuthenticationPreviewResponse> InitiatePreviewAsync(string connectionId, [Header("If-Match")] string ifMatch, CancellationToken cancellationToken = default);
+
+    [Get("/external-authentication/previews/{previewHandle}")]
+    Task<ExternalAuthenticationPreviewResult> GetPreviewResultAsync(string previewHandle, CancellationToken cancellationToken = default);
+
+    [Put("/external-authentication/connections/{connectionId}/secret-bindings/{fieldName}/managed")]
+    Task<ExternalAuthenticationConnection> ReplaceManagedSecretAsync(string connectionId, string fieldName, [Body] SaveManagedExternalAuthenticationSecretRequest request, [Header("If-Match")] string ifMatch, CancellationToken cancellationToken = default);
 
     [Delete("/external-authentication/connections/{connectionId}/secret-bindings/{fieldName}")]
     Task<ExternalAuthenticationConnection> RemoveSecretBindingAsync(string connectionId, string fieldName, [Header("If-Match")] string ifMatch, CancellationToken cancellationToken = default);

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

@@ -13,6 +13,7 @@ public sealed class ExternalAuthenticationConnection
     public ExternalAuthenticationConnectionScope Scope { get; set; } = new();
     public string AdapterType { get; set; } = "";
     public Uri? CallbackUri { get; set; }
+    public Uri? PreviewCallbackUri { get; set; }
     public int AdapterSettingsVersion { get; set; }
     public JsonElement AdapterSettings { get; set; }
     public Dictionary<string, ExternalAuthenticationSecretBindingState> SecretBindings { get; set; } = new(StringComparer.Ordinal);
@@ -21,6 +22,7 @@ public sealed class ExternalAuthenticationConnection
     public int Order { get; set; }
     public bool IsPreferred { get; set; }
     public bool OverridesConfigurationConnection { get; set; }
+    public bool CanCreateOverride { get; set; }
     public bool EnabledIntent { get; set; }
     public bool EffectivelyEnabled { get; set; }
     public string Validity { get; set; } = "";
@@ -37,16 +39,15 @@ public sealed class ExternalAuthenticationConnection
 
 public sealed class ExternalAuthenticationConnectionScope
 {
-    public string Kind { get; set; } = "tenant";
+    public string Kind { get; set; } = "host";
     public string? TenantId { get; set; }
 }
 
 public sealed class ExternalAuthenticationSecretBindingState
 {
-    public string ResolverType { get; set; } = "";
-    public string Reference { get; set; } = "";
-    public string? ExpectedType { get; set; }
-    public string? ExpectedScope { get; set; }
+    public string Ownership { get; set; } = "";
+    public string? ResolverType { get; set; }
+    public string? Reference { get; set; }
     public bool IsConfigured { get; set; }
     public bool IsResolvable { get; set; }
 }