A decision memo for replacing an identity provider is a single page with six parts: the situation, the options, the cost shape, the risk, the timeline and the decision you are asking for. A founder or CTO can approve or decline from that page without joining a meeting, which is the reason to write it as a memo instead of a long chat thread. The template below is meant to be copied, filled in and forwarded, and each section has a short note on what belongs in it.
The post is written for the engineer or head of platform who has already concluded that the current identity provider needs to change and now has to get approval. The person who signs is usually a CTO, VP of Engineering or founder at a small or mid-size software company, and they will read the memo in a few minutes between other things.
What is the memo for, and who reads it?
The memo exists to get one decision made: go or no-go on replacing the identity provider, with a date. It is read by the person who holds the budget, and often forwarded to finance, security and sometimes the board, so it has to make sense to someone who has never opened your identity provider’s admin console.
Why does a one-page memo get a faster decision than a long thread?
A long thread asks the reader to reconstruct the argument, and most busy readers will not. A memo does the reconstruction for them, puts the options side by side and ends with a specific question. It also leaves a record: when someone asks in a year why you changed providers, the memo is the answer, and it shows that the alternatives were considered.
If you also need a short description of a vendor to attach, our vendor brief is a one-page summary designed for that, and the guide for leaders covers the decision from the buyer’s side.
The memo, section by section
Copy the headings, keep each section to a few sentences, and put numbers where you have them. The explanations below say what to put under each heading.
Situation: what changed and why does it matter to the business?
State the trigger in plain terms and tie it to something the reader already cares about. Good triggers include a hosted provider that is more expensive each year, a product being wound down by its vendor, or a customer asking for enterprise single sign-on that the current tool handles badly. Avoid describing the technical symptoms alone, because “the login flow is hard to customize” does not move a budget. “Two enterprise deals this quarter are waiting on a login feature we cannot ship on the current provider” does, because it names revenue.
If the trigger is a vendor timeline, quote it exactly and link to the vendor’s statement. For example, Microsoft’s Azure AD B2C FAQ says new customers could no longer buy the service from 1 May 2025 and that existing customers are supported until at least May 2030. That is a planning horizon and not an emergency, and the memo is more credible if it says so.
Options: keep, self-host or move to a managed provider
List three options, always including “keep the current provider,” even if you expect to reject it. For each one write a sentence on what it is and a sentence on what it costs the team to run.
- Keep. Stay on the current provider and accept the cost and limits that triggered the memo.
- Self-host. Run an open-source identity system yourselves (Keycloak is the common choice) on your own infrastructure.
- Move to a managed provider. Use a hosted service that runs the software for you, so your team configures but does not operate it.
Keeping the comparison to three options makes it easy to read. If you have a shortlist of named vendors, put them in an appendix. Our post on what to check before you build or buy is a good source of criteria for this section.
Cost shape: what grows with users, what grows with customers and what is fixed?
Finance readers want the shape of the cost more than the first-year number, so describe it in three groups.
- Grows with users. Anything priced per monthly active user or per seat.
- Grows with customers. Per-connection fees for enterprise single sign-on, or the engineering time to set up each customer.
- Fixed. Platform fees, the people who operate the system, the one-off migration project.
Leave vendor prices out of the memo body and put them in an attachment dated the day you collected them, because they change and because a number in the middle of a page invites an argument about the number. If you need a model for projecting a per-user bill, this post on pricing risk shows how to do it at two and five times your user count, and what it costs to switch identity providers lists the one-off lines.
Risk: what could go wrong, and who owns each risk?
Write three to five risks, each with an owner and a mitigation. Typical ones for this decision are users locked out during cutover, enterprise customer connections breaking, a stalled project that leaves you paying for two systems, and a dependency on the new provider that recreates the problem you are leaving. The last one is worth including honestly: ask whether you could leave the new provider within a quarter, and note the answer. Our exit plan checklist covers what to check, and the vendor risk brief is the same idea written for the person who signs.
Timeline and the people needed
Give phases and dates, and name the roles instead of the individuals if the team is still being decided. A pilot with one application is a useful first phase because it replaces estimates with a measured number. Say which people the project needs, for how many days, and what they stop doing meanwhile. The approach we recommend for the cutover itself is described in dual-run IAM migration.
The decision requested and the deadline
End the memo with a specific request and a date, such as “approve a four-week discovery and pilot phase by 30 October, with a go or no-go on full migration at the end.” A small first request is easier to approve than a full migration, and it gives you the facts for the larger decision. State what happens if there is no decision, because “the renewal auto-renews on 15 December” is often the most persuasive sentence in the memo.
What does a filled-in example look like?
The example below is illustrative. The company, the dates and the numbers are placeholders, not a real customer, and you should replace every one of them.
Memo: replace the identity provider for the Acme platform (example)
Situation. We are a 60-person company and sell to mid-size customers. Our hosted identity provider’s cost has grown faster than revenue for two years, and three prospects this quarter have asked for enterprise single sign-on that the current plan only offers at a higher tier. The contract renews on [date].
Options. (1) Keep the current provider and move to the higher tier. (2) Run Keycloak ourselves. (3) Move to a managed Keycloak service.
Cost shape. Option 1 grows with monthly active users and with the number of enterprise connections. Option 2 has no license cost, but needs [N] engineering days a month for upgrades and on-call, plus infrastructure. Option 3 has a platform fee and removes most of the operating work. Detailed figures are in Appendix A, dated [date].
Risk. Users locked out at cutover (owner: platform lead; mitigation: migrate gradually and keep the old provider live for 30 days). Enterprise connections breaking (owner: customer success; mitigation: re-test each connection and notify customers two weeks ahead). Project drift (owner: engineering lead; mitigation: decision at the end of each phase).
Timeline and people. Four weeks of discovery and a pilot with one internal application, using one platform engineer and part of one security lead. Then a go or no-go on migrating the remaining [N] applications.
Decision requested. Approve the four-week discovery and pilot by [date]. If we do nothing, the contract renews for another year on [date].
A real memo will be a little longer, but it should still fit on one printed page.
How do you adapt the memo for finance, security and the board?
Keep one memo and change the order and the attachments, not the content. Finance wants the cost shape first and the vendor price attachment. Security wants the risk section first, plus evidence of the new provider’s controls, which for us means the trust page, where our SOC 2 Type II report (shared under NDA) and ISO 27001 certificate can be requested. The board wants the situation, the decision requested and the deadline, and rarely needs more. For the plan prices of a managed option, point readers to the pricing page so the numbers have one source.
Frequently asked questions
How long should the memo be?
One page, or about 500 to 700 words. If a section needs more, move the detail to an appendix and leave a one-sentence summary in the memo. The test is whether a reader who stops after the first half page still knows what you are asking for.
What evidence should be attached?
Attach the price quotes with dates, the inventory of applications and login methods that use the current provider, the vendor’s published statements about any deadline, and any customer requests that triggered the memo. Do not attach material you have not read yourself, since the first question you get will be about the attachments.
What if the answer is to stay where we are?
Then the memo has still done its job, because a recorded decision to stay, with the reasons and a date to revisit, is better than an unresolved debate. Write down what would change your mind, for example a price increase above a threshold or a customer requirement, so the next review has a trigger instead of a vague feeling.