Authorization servers: Migration remediation

The migration remediation area shows the tenant's sanitized authorization-server migration ledger. It is for coded migrations that convert hosted configuration and legacy external identity-provider records into stable authorization-server resources.

The ledger is the source of truth for remediation. The console does not infer migration state from a missing resource, create replacement records, or edit a runtime projection to make a failed entry appear successful.

PostgreSQL and MySQL upgrades run the same coded conversion contract against their dialect-specific schemas. The orchestrator acquires the database migration lock before it enumerates active and legacy tenant owners. It reconciles tenant and slug, derives deterministic target UUIDs, and records every attempt in the durable ledger. A retry either converges on the same target or fails without creating a second resource.

Open the area

Navigation	Protocols, Authorization Servers, Migration remediation
Scope	Customer tenant
Required role	Tenant administrator

The platform tenant is rejected. Entries from another customer tenant are never returned.

Review an entry

Filter the ledger by status or source type. Open an entry to inspect its source type, stable source key, recorded source digest, target authorization-server UUID, revision, attempt count, timestamps, and sanitized failure category.

The conversion has a durable tenant-and-version completion record. Until that record exists, a changed source is retained as a failed ledger entry with both the recorded digest and the newly observed digest. After every source is applied and the retired identity-provider rows are removed, the platform records completion. Later authorization-server configuration changes are then ordinary resource updates and are never reinterpreted as legacy migration input during startup.

The response never includes source configuration values, client credentials, secret locators, exception messages, or stack traces. Use the failure category and the documented corrective action to repair the authoritative source.

Resume an unchanged source

Choose Resume migration only when the current source digest is identical to the digest recorded by the failed entry. The console sends both the ledger revision and expected source digest. The service compares them atomically before running the coded migration.

If another administrator changed the entry, the source changed, or the migration has already been applied, the request returns a conflict. Refresh the entry before deciding what to do next.

POST /api/platform/config/v1/tenants/{tenantId}/authorization-server-migrations/{authorizationServerMigrationId}/resume
Content-Type: application/json

{
  "expectedRevision": 4,
  "expectedSourceDigest": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}

Accept a reviewed source change

When the source changed after the failed attempt, choose Accept source change. This is a separate audited operation, not a resume option. The console displays the recorded and newly observed current digests from the durable ledger. Review both values, enter a meaningful reason, and confirm the action. The current digest is read-only; an administrator never invents or manually supplies it.

The service re-reads the source and requires the ledger revision, recorded digest, and current digest to match the request. It records the digest transition and administrator reason before retrying the coded migration. A conflict does not mutate the ledger.

POST /api/platform/config/v1/tenants/{tenantId}/authorization-server-migrations/{authorizationServerMigrationId}/accept-source-change
Content-Type: application/json

{
  "expectedRevision": 4,
  "expectedRecordedSourceDigest": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "expectedCurrentSourceDigest": "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789",
  "reason": "Corrected the external issuer URL after certificate rotation."
}

Verify success

After either operation succeeds, confirm that the entry is APPLIED and that its target UUID opens the expected authorization-server resource. For an external source, validate discovery before activation. For a hosted source, verify configuration and signing-key bindings before activating the resource.

The migration deletes or retires an old source only after every conversion step commits successfully. Do not manually remove an old source while its ledger entry is failed.

Hosted sources preserve issuer, routes, configuration, clients, identities, default and system roles, and typed secret or KMS references. Retired identity-provider rows become disabled, unbound external OpenID Connect resources. They are not confused with hosted oauth2.servers.<slug>.* sources. The retired table is removed only after the complete conversion succeeds and the durable schema ledger records the current version.

Diagnose a failed entry

Use the public failure category and remediation details. Do not request raw source values, exception messages, stack traces, client secrets, or secret locators.

Failure category	Meaning	Administrator action
INVALID_SOURCE	The recorded legacy source cannot be parsed or violates the new resource invariants.	Correct the authoritative legacy source, refresh the entry, then use Accept source change after reviewing both digests.
SOURCE_DIGEST_CHANGED	The source changed after the failed attempt.	Review the recorded and current digests and use Accept source change with a reason. Do not use Resume migration.
TARGET_CONFLICT	An existing target does not reconcile with the deterministic tenant, slug, or UUID.	Inspect the target resource and source ownership. Resolve the conflicting authoritative data before retrying.
DISCOVERY_VALIDATION_FAILED	A migrated external issuer does not pass secured discovery.	Correct upstream issuer, DNS, TLS, or metadata. Then accept the reviewed source change when its digest changed.
SECRET_REFERENCE_INVALID	A typed secret or KMS reference is missing, cross-tenant, or has the wrong purpose.	Restore a valid tenant-owned typed reference. Never replace it with plaintext in configuration.
MIGRATION_PLANNING_FAILED	The source could not be converted into a complete deterministic plan.	Correct the source fields identified by the sanitized remediation details.
MIGRATION_APPLY_FAILED	The plan was valid but a transactional persistence step failed.	Repair the database or service dependency. Use Resume migration only if the source digest is unchanged.

A crash after a target write or source retirement does not authorize manual cleanup. Restart the orchestrator or use the appropriate remediation operation. The durable ledger, deterministic identifiers, and idempotent writes allow the migration to resume without duplicating the target.

On a clean installation there are no legacy sources to remediate. The schema ledger is still brought to the current version before runtime transports open.

API reference

The console uses these tenant-scoped operations:

GET  /api/platform/config/v1/tenants/{tenantId}/authorization-server-migrations
GET  /api/platform/config/v1/tenants/{tenantId}/authorization-server-migrations/{authorizationServerMigrationId}
POST /api/platform/config/v1/tenants/{tenantId}/authorization-server-migrations/{authorizationServerMigrationId}/resume
POST /api/platform/config/v1/tenants/{tenantId}/authorization-server-migrations/{authorizationServerMigrationId}/accept-source-change

All mutating operations use revision and digest compare-and-set checks. Retrying a stale browser response is intentionally rejected.