What it is
This is the planning and reference work behind migrating an enterprise reporting platform from a legacy two-node cluster to a current single-node deployment on modern infrastructure, replacing a longstanding Kerberos-based single sign-on setup with SAML authentication through a cloud identity provider.
Unlike the other projects described here, the deliverable is not an application. It is a self-contained reference document covering architecture, decisions and their rationale, component scope, database and service account design, authentication approach, migration sequencing, acceptance criteria, and an indexed body of vendor knowledge base research.
Why it mattered
Three drivers converged at once.
The existing version was approaching end of support, which sets a real deadline rather than an aspirational one. The newer version replaces the classic launchpad interface with a modern one, which makes this a change management workstream affecting every report consumer rather than a silent backend upgrade. And most pressingly, single sign-on on the existing platform had been failing in ways that resisted weeks of troubleshooting.
The authentication failures are worth enumerating, because their variety is what eventually justified the decision to stop fixing them: encryption salt mismatches between the directory and the platform, service principal name drift, service account identity alignment problems between two different naming conventions, and credential cache failures that cascaded across the entire cluster rather than staying isolated to the node where they originated.
The decision worth explaining
The most consequential call on this project was to stop fixing the old system, and to do so after finally diagnosing it correctly.
After extended effort, the root cause of one significant authentication failure was actually identified: a constrained delegation misconfiguration on the service account’s directory settings. I documented the diagnosis fully.
Then I deliberately chose not to apply it, and recorded that decision as formal rather than provisional.
The reasoning had three parts. The entire authentication mechanism is being replaced in the target version anyway, so stabilizing the old one produces a result with a scheduled expiry date. Every hour spent on it was an hour not spent on the migration that actually resolves it. And users could work with manual sign-on in the interim, which is an inconvenience rather than a loss of function.
Writing down a correct diagnosis and then explicitly declining to act on it is uncomfortable. It feels like leaving something unfinished. But the alternative was continuing to invest in a component with a known retirement date, and the discipline of recording the decision as final matters specifically so that someone encountering the same symptoms later, possibly me, does not reopen it out of a sense of tidiness.
A related decision covered a separately scheduled fix to the service account’s identity format, prepared with a rollback plan, stop conditions, and an execution sequence, and then also set aside under the same reasoning.
The decisions matrix, which is the actual document
The core of this plan is a matrix of roughly thirty decisions, each recorded with its rationale rather than just its outcome. That format matters: a decision without a reason cannot be re-evaluated later when circumstances change, and it invites someone to quietly reverse it.
The choices worth explaining are the ones where I deliberately chose less than was available.
| Decision | Choice | Why |
|---|---|---|
| Production topology | Single node, not a cluster | The existing cluster did not deliver availability; it delivered cascading failures. Hypervisor-level failover covers hardware. A solo administrator maintaining a cluster is a liability, not resilience. |
| Web tier | All-in-one, not split | No load justifies separating the application server. Fewer moving parts means faster diagnosis. |
| Component scope | Report lifecycle only | Every additional module is a lifetime maintenance commitment for one person. |
| Semantic layer | Dropped entirely, replaced with SQL views | The SQL infrastructure already exists, is version-independent, and requires no new tooling to learn. |
| Custom integrations | None at all | If a capability is not natively supported, the feature gets dropped rather than glued together. |
| Cloud storage output | Not used | One option removed by the vendor; the other uses a per-user folder model that is the wrong shape for shared reports. |
| Source platform patching | None during the project | The current patch level is confirmed sufficient for migration. Patching introduces risk with no benefit. |
| Content migration scope | Selective — active folders only | Decommissioned reports stay behind and retire with the old platform rather than being carried forward. |
| Test environment | Built first, and kept architecturally identical to production | A solo administrator needs somewhere to be wrong safely, and test behavior only predicts production behavior if the architecture matches. |
| Authentication | SAML through the cloud identity provider | Kerberos pain here is protocol-inherent, not misconfiguration. |
| Service accounts | Three separate ones | One per environment, for lifecycle separation and blast radius containment. |
| Database authentication | Dedicated login per environment, not a shared or integrated one | Privilege separation. |
The pattern running through the right-hand column is a deliberate bias toward subtraction. That bias has a name in the plan itself.
The operating principles, written down before the decisions
The plan states its own decision-making rules explicitly, which is unusual and turned out to be the most useful section. When a new question arose, the answer was usually derivable from these rather than requiring fresh deliberation.
Solo administrator bandwidth is a first-class constraint. One person owns installation, configuration, troubleshooting, training, support, database administration, directory work, and monitoring. Every additional virtual machine, product, or integration multiplies that load. This is not a complaint; it is a design input, and it is why the matrix above keeps choosing the smaller option.
Do not touch what is working. The default for any proposed change is that it must address a real, named problem. Newer is not a reason. Concretely: the source platform stays at its current patch level through the entire migration, the new platform gets installed at a mature patch level and then left alone, and patches happen for active security issues or vendor end-of-life, not on a schedule.
Native only. If a capability is not natively supported, the feature gets dropped rather than assembled from scripts and third-party glue. This is what eliminated cloud storage outputs and the semantic layer tooling, and it is a harder discipline than it sounds, because glue is always locally cheaper than saying no.
Test and production must be architecturally identical except for values that genuinely cannot match. Otherwise test behavior does not predict production behavior, and the test environment becomes a false comfort rather than a rehearsal.
Prefer modern federated authentication over Kerberos when a modern identity provider is already present. This is the lesson from the authentication saga stated as a forward-looking rule.
Platform work of this kind is measured in weeks per version, not days, and a solo administrator doubles the estimate. Stating that up front is how a plan survives contact with someone asking whether it can be done faster.
Phasing, and what explicitly cannot be compressed
The plan lays out eight phases across roughly five months, and the most useful thing about it is that it separates work that can start immediately from work that cannot be rushed.
| Phase | Activities |
|---|---|
| Planning and setup | Pull vendor knowledge base articles, request license keys given their lead time, coordinate with the identity, database, and network teams, obtain installer media |
| Test build | Provision the test machine, install, configure federated authentication against a test application registration, set up HTTPS, install the report designer, create the database and login |
| Test refinement and user acceptance | Promote a real subset of content, run pilot user testing, refine the installation procedure, build training material, identify slow value lists and add caching |
| Production build | Provision production, install using lessons from test, configure authentication and certificates for production |
| Production migration | Promote selected active content, validate per report, re-point dynamic parameters from the old semantic layer to SQL views, validate schedules and destinations |
| Pilot on production | Pilot users access the new platform, refine, then freeze content |
| Cutover | Users move, the old platform closes to writes, communications and post-cutover support |
| Decommission | After stability is proven: shut down both old nodes, retire the old service account, release the license |
What can start early to de-risk the critical path: the license request, because the vendor lead time is the longest single dependency; pulling the vendor research; coordinating with the other teams; and building the fifteen SQL value-list views, which work against the old platform too, so one could even be piloted there before migration begins.
What cannot be compressed, stated plainly: per-report validation, because each report has to be run, its prompts checked, its data verified, and its schedule confirmed, and there is no shortcut through that. Pilot user testing, because humans need time to discover the problems they will discover. And change-management lead time, because training has to happen before cutover rather than after.
That last section is the part I would defend hardest in a conversation about the timeline. A plan that does not say what cannot be compressed will be compressed there.
Working alone against vendor documentation
As the only administrator for this platform, there was no colleague to consult and no internal precedent. The primary source was the vendor’s knowledge base, and the practical output became an indexed set of specific findings, each tied to the article that established it.
Several were genuinely non-obvious, and each represents a day lost if discovered during a cutover window rather than during planning:
- Dynamic prompt features are unsupported against direct SQL views. They require an intermediate semantic layer. This directly constrains the drop-the-semantic-layer decision above, and is why fifteen SQL value-list views became their own workstream.
- The migration tool’s version must match the target platform, not the source, which determines which machine it runs from. Easy to get backwards, since the instinct is to run tools from the system you are leaving.
- Direct migration across both major versions is supported, with no intermediate hop required, and no minimum support-pack floor on the source. Both had to be confirmed rather than assumed, because either being false would have added a whole migration stage.
- Value lists are emptied after migration and connection rights are lost. Neither surfaces as an error. Content simply arrives incomplete.
- The migration tool has an object count limit per operation, which shapes how content is batched rather than being discovered partway through.
- A required four-pass promotion sequence exists — users, then dependencies, then folders, then security — along with temporary storage of roughly two and a half times the content size, a recommendation to disable the new authentication during user promotion, and no rollback capability.
- A specific runtime configuration block is mandatory on the new platform. Its absence produces a generic server error rather than anything pointing at a missing configuration.
- Special characters in a service account password silently break authentication, with no error indicating the password is the cause. Hostile, and directly relevant, since the existing password contained exactly those characters, making it a live contributing factor rather than a theoretical one.
- The mail component uses its own certificate trust file, not the operating system store. A valid wildcard server certificate does not substitute; the correct root certificate must be placed at the configured path on every node.
- The identity provider is supported as a federated authentication provider only, not as a directory source. This distinction shapes the entire authentication design and is easy to miss when both roles are nominally on offer.
- The tooling whose retirement was the primary concern turned out to be on neither the removed nor the deprecated list, and remains supported. Confirming that, rather than assuming a published removal list applied, saved a migration path from being abandoned unnecessarily.
The no-rollback item is what justifies the entire planning investment. A migration that cannot be reversed has to be right the first time, which makes the difference between researching these findings now versus during a maintenance window rather stark.
Timeline and effort
The planning and research work spanned roughly 5 weeks across 8 distinct working sessions, from the first reference document through to the export capturing the full body of vendor research. License procurement, historically the longest-lead item on a project of this kind, completed early in that window.
Technical reference
Target architecture. Single-node deployment on a current server operating system, replacing a two-node cluster, with SAML authentication through the cloud identity provider. The identity provider is supported as a SAML provider only, not as a directory source, which is a distinction that shapes the entire authentication design and is easy to miss when both roles are nominally offered.
Scope of platform change. Several legacy features are removed in the target version. Confirming which removals actually affect existing content, rather than assuming a published removal list applies, was its own piece of research. The legacy semantic layer tool, whose retirement was the primary concern, turned out to be on neither the removed nor deprecated list and remains supported.
Content migration approach. Direct promotion between the two versions is supported. Legacy business views migrate to SQL views, with the dynamic prompt limitation above constraining which content can make that transition without an intermediate layer.
Where it stands now
Planning is complete; implementation is pending. The most valuable artifact is the reference document itself, because it means the migration does not depend on one person’s memory of eight weeks of vendor research, and because a project with no rollback path needs its reasoning legible before execution rather than after.
The legacy authentication effort is formally closed with the reasoning recorded, which is a deliberate act rather than an omission.