This is the planning and reference work behind migrating an enterprise business intelligence (BI) 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, the web standard for single sign-on, through a cloud identity provider. Unlike the other projects here, the deliverable is not an application. It is a self-contained reference document: the architecture, a matrix of roughly 30 decisions each recorded with its rationale, the migration sequence, acceptance criteria, and an indexed body of vendor knowledge base findings.
Three drivers converged. First, the existing version was approaching end of support. Second, the newer version replaces the classic interface with a modern one, which is a genuine change-management workstream, not a silent upgrade. And most pressingly, the existing single sign-on had been failing in ways that resisted a multi-week troubleshooting effort.
The most consequential call on this project was to stop fixing the old system. After extended effort, the root cause of one authentication failure was identified, a delegation misconfiguration on the service account. I documented the diagnosis and then chose not to apply it: the entire authentication mechanism was being replaced in the target version anyway, every hour spent stabilizing the old approach was an hour not spent on the migration, and users could work with manual sign-on in the interim without any loss of function. Writing down a correct diagnosis and then declining to act on it is uncomfortable, and it was the right call.
As the only administrator for this platform, there was no colleague to ask and no internal precedent to follow. 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, and several non-obvious. Each is a day lost if discovered during a cutover window instead of during planning, and the detail page enumerates them, along with the one that justifies the whole planning investment: the migration has no rollback capability.
A complete written plan exists, license procurement completed early, and the legacy authentication effort is formally closed with the reasoning recorded, so it does not get reopened by someone encountering the same symptoms later. Planning is complete and implementation pending. The most valuable artifact is the reference document itself, since it means the migration does not depend on one person’s memory of eight weeks of vendor research.
The technical detail
This is the plan for migrating an enterprise reporting platform across two major versions, from a legacy two-node cluster to a single-node deployment with SAML authentication, the web standard for single sign-on, produced by its only administrator working from the vendor’s knowledge base. The deliverable is the reference document itself: a decisions matrix, operating principles, phasing, and vendor findings that would each have cost a day if they had surfaced mid-cutover.
The authentication failures behind the deadline
The variety of the single sign-on failures 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 instead of staying isolated to the node where they originated. They arrived on top of a version approaching end of support and an interface replacement that makes the upgrade a change-management workstream affecting every report consumer.
The decision worth explaining
The big decision on this project was to give up on fixing the old system after finally diagnosing it correctly.
The troubleshooting did, in the end, find the root cause of one significant failure: a constrained delegation misconfiguration on the service account’s directory settings. I wrote the diagnosis down in full.
Then I deliberately chose not to apply it, and recorded that decision as formal, not provisional.
The reasoning had three parts. The target version replaces the whole authentication mechanism, so any fix to the old one comes with a scheduled expiry date. Time spent stabilizing it was time taken from the migration that resolves it. And manual sign-on kept users working in the interim, at the cost of some inconvenience and nothing more.
It is uncomfortable to hold a correct diagnosis and choose not to act on it. It feels like leaving something unfinished. The alternative, though, was continuing to invest in a component with a known retirement date, and the discipline of recording the decision as final matters 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 the plan is the matrix itself: roughly 30 decisions, and every one carries the reason behind it, not just the 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, 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, never 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 instead of 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, which is unusual and turned out to be the most useful section. When a new question arose, the answer was usually derivable from these without 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 instead of 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 cannot match. Otherwise test behavior does not predict production behavior, and the test environment becomes a false comfort, not 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 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 15 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 must 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 must happen before cutover, not 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
Nobody else administers this platform, so there was no colleague to consult and no precedent inside the organization. Everything came from the vendor’s knowledge base, and the research settled into an indexed set of findings, each tied back to the article that established it.
Several were non-obvious, and discovering any of them mid-cutover instead of during planning would have cost a day:
- Dynamic prompt features are unsupported against direct SQL views. They require an intermediate semantic layer. This constrains the drop-the-semantic-layer decision above and is why 15 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 arrives incomplete.
- The migration tool has an object count limit per operation, which shapes how content is batched up front instead of 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 and nothing 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, not 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, instead of 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 must be right the first time, so these findings had to surface now, not during a maintenance window.
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.
Scope of platform change. Several legacy features are removed in the target version. Confirming which removals affect existing content, not assuming a published removal list applies, was its own piece of research. The legacy semantic layer tool, the removal I was most worried about, is on neither list and stays 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
The plan is finished; the build has not started. What carries the value is the document: eight weeks of vendor research now lives somewhere other than one person’s memory, and a project with no rollback path needs its reasoning legible before execution, not after.
Closing the legacy authentication effort is written into the record as a decision, not left as a loose end.