The identity provider decision record: why the federation model you configured determines your enterprise SSO adoption barrier and your stale account accumulation surface

A 29-person SaaS company built a project management tool for architecture and engineering firms — a product for coordinating drawing reviews, RFI workflows, and submittal tracking on commercial construction projects. The product was well-regarded within its niche. Authentication was built with Google OAuth in the founding session: one button, instant login, no password management. For the first two years, every user was either an individual practitioner or a small firm employee who had found the product through word of mouth and signed up with their personal Google account or their firm's Google Workspace account. The Google OAuth integration covered both cases cleanly. It was not a decision — it was the path of least resistance, implemented in an afternoon and never revisited.

In the company's third year, a sales representative began a conversation with a 400-person engineering firm whose IT governance team managed all software procurement centrally. The firm's IT policy required that every third-party SaaS tool used by employees be integrated with the company's identity provider — Okta — via SAML 2.0 SSO. Individual OAuth logins via personal Google accounts were not permitted: all access to company-approved tools must flow through the corporate IdP to enable centralized access control, audit logging, and immediate deprovisioning when employees left the firm. The requirement was not negotiable. It was not a feature preference. It was a security and compliance policy that applied to all third-party software vendors.

The engineering team assessed the SAML integration as a two-sprint effort. The assessment was correct for the SSO mechanism itself — SAML libraries existed, the IdP documentation was clear, and the integration was implementable. What the assessment did not account for was the identity model mismatch. The application's user identifier was the email address returned by Google OAuth. During the enterprise prospect's pilot evaluation, twelve of the firm's architects had been using the product for four months, each signed up with their personal Gmail addresses. The firm's Okta directory used corporate email addresses — first.last@firmname.com — that were in most cases different from the personal addresses the pilot users had registered with. Migrating the twelve pilot accounts to the SAML-authenticated corporate accounts required a database migration that changed the primary identity record for each user, reattached their project memberships and comment history to the new identity, and ensured the old Google OAuth accounts were disabled so that the same person could not authenticate via two paths simultaneously. The migration also revealed that two pilot users had used their corporate email addresses for both their personal Gmail and their Google Workspace accounts — overlapping identity records that required manual resolution with each user.

The SAML integration shipped after eight weeks rather than the projected four. The additional four weeks were spent on the identity migration, on a subtle bug with IdP-initiated SSO that surfaced only when the enterprise's Okta administrator tested the integration from the Okta dashboard rather than from the application's login page, and on a configuration mismatch in the assertion consumer service URL that caused the SAML assertion to fail validation in strict mode. The enterprise deal closed. The firm was a good customer. But the six-week slip — against a prospect who had been willing to wait — cost the sales representative the Q3 booking he had counted on. The federation model had never been recorded as a decision: whether to support only social OAuth logins or to build toward SAML federation was not a choice anyone had made. It was a default that persisted until the first enterprise requirement made it expensive.

A 36-person SaaS company built a developer productivity tool — a shared workspace for engineering teams to store code snippets, runbooks, incident notes, and architecture references. Teams used it as a lightweight internal knowledge base that was faster to search than Confluence and easier to share than Google Docs. Adoption was bottom-up: individual engineers signed up, invited their teammates, and the product spread across organizations one team at a time. The account model was entirely self-service: users created accounts with email and password or with Google OAuth, joined workspaces by invitation, and left workspaces by stopping using them. There was no organizational admin layer in the initial product — no concept of a company managing its employees' accounts.

The product added team workspaces and admin roles eighteen months after launch, in response to users asking for ways to organize their team's content and manage membership. Admins could invite users and remove them from the workspace. What admins could not do — and what the product had never built — was receive automated signals from their company's identity provider when an employee was offboarded. There was no SCIM endpoint. There was no webhook that the company's IT team could configure to fire when an employee was deactivated in Okta or Azure AD. Account deprovisioning required a human action: a workspace admin removing the user, or the user themselves deleting their account. If neither happened, the account remained active.

A software company that had adopted the product as their primary engineering team knowledge base offboarded an infrastructure engineer in their second year of using the tool. The offboarding checklist used by the HR team included accounts in Jira, GitHub, AWS IAM, Slack, and the core SaaS tools provisioned through the company's Okta tenant. The developer productivity tool was not in the Okta tenant — it had been adopted by the engineering team directly, without IT provisioning, and was not on the company's official software inventory. The HR team completed the offboarding checklist. The engineer's access to all listed systems was removed. His account on the developer productivity tool remained active.

Eleven months later, the software company underwent its first SOC 2 Type II audit. The user access review testing required the company to produce a list of all third-party SaaS tools in use and verify that only current employees had active accounts with access to company data. The IT team built the inventory by surveying department heads and reviewing credit card statements for SaaS subscriptions. The developer productivity tool appeared on the list. The IT team logged into the tool's admin panel and ran the member list. Among the active accounts was the former engineer's account, with full access to the workspace, including runbooks containing database connection strings, incident notes with IP addresses and service names, and architecture references with infrastructure diagrams. The account had been active, unchecked, for eleven months after the engineer had left the company. The auditor marked the finding: terminated user access had not been removed in a timely manner for the covered period. The customer submitted a deactivation request to the SaaS support team, who deactivated the account manually. The customer's CISO asked whether SCIM provisioning was available. The answer from the SaaS support team was "on the roadmap." The account lifecycle model had never been documented as a decision: what happens to a user's account when they leave their employer was not a question that came up when the product was built for self-service individuals, and it had never been asked explicitly — until the gap between the informal model and the compliance requirement became visible in a customer's audit.

A 44-person SaaS company had been running its own Google OAuth application since founding. The application was a developer tooling product — a service that processed code repository events and produced automated engineering analytics for team leads. The OAuth client ID was a stable string that appeared in many places: the frontend JavaScript bundle that initiated the authorization flow, the environment variable configuration documented in the self-hosted deployment guide, the curl examples in the API documentation, the sample integration code in the getting-started tutorial, and the configuration files of a community-maintained CLI tool that several enterprise customers had adopted for programmatic access to their analytics data.

In the company's fourth year, the engineering team decided to migrate authentication to Auth0. The motivations were clear: Auth0 supported multiple social providers, had a well-maintained SAML integration module, and eliminated the maintenance burden of managing OAuth callback endpoints directly. The migration was planned carefully for the first-party code. A new Auth0 application was created. The frontend was updated to use Auth0's SDK. The backend session validation was updated to verify Auth0 JWT tokens instead of Google OAuth tokens. A user migration script was written and tested against the staging database. The rollout happened over two weeks, with a transition period during which both the old Google OAuth application and the new Auth0 application were active. The migration went smoothly. On the final day of the transition window, the old Google OAuth application was decommissioned in the Google Cloud console.

Six weeks later, the maintainer of the community CLI tool filed a GitHub issue on the SaaS company's repository: the CLI's OAuth authentication flow had been failing since a date that matched the decommission date exactly. The CLI used the PKCE authorization code flow with the old Google OAuth client ID, which was hardcoded in the CLI's configuration file. The maintainer had not been notified of the migration. The migration announcement had been posted in the company's developer changelog, which the CLI maintainer had not subscribed to. Four enterprise customers who had deployed the CLI internally sent support tickets in the following week reporting that their CI pipelines — which used the CLI to export analytics data — had been failing silently for six weeks, producing empty reports rather than errors, because the CLI's authentication failure was swallowed as a configuration error rather than surfaced as an actionable message.

Two weeks after the CLI issue surfaced, a security alert fired: the monitoring system had flagged repeated OAuth authorization requests originating from an IP address in a residential ISP's range, using a client ID that no longer existed in the Google Cloud console. Investigation revealed that a former engineer — who had left the company eighteen months earlier — had built an internal automation script on a personal server during his time at the company. The script exported weekly analytics summaries to a personal dashboard he used to track the team's engineering metrics. He had forgotten to decommission the script when he left. The script continued to run, attempting OAuth authorization with the decommissioned client ID every Sunday night, generating authorization failures that appeared in the logs as unknown OAuth application requests. The requests had not caused any harm — the client ID was invalid, the authorization failed every time — but the pattern looked like a credential stuffing attempt against an unknown OAuth application, and the security team spent two days investigating before identifying the source. The former engineer was contacted via LinkedIn, confirmed the script existed, and decommissioned it. The identity migration had been carefully executed for the code the team owned and controlled. It had not accounted for the credential consumers the team did not own, did not control, and in two cases did not know existed.

Structural properties set by the identity provider decision

Three structural properties are determined when an engineering team establishes — or fails to establish — an identity provider decision record: how readily the authentication model can be extended to satisfy enterprise SSO requirements without a user identity migration, how completely the account lifecycle model handles deprovisioning when the employing organization terminates an employee's access, and how safely the authentication infrastructure can be migrated to a new identity provider without creating ghost credentials across an ecosystem of integrations. None of these are labeled as decisions when the first OAuth integration is built — they emerge from the defaults of the identity library chosen for the founding sprint, defaults that accumulate their consequences as the customer base grows from self-service individuals to enterprise organizations with IT governance requirements.

Property 1: The authentication protocol selection and the enterprise SSO adoption barrier. The authentication protocol choice at founding determines the migration distance to enterprise SSO — how much needs to change in the user identity model, the session architecture, and the provider integration layer before an enterprise customer's SAML or OIDC requirement can be satisfied. A product built with Google OAuth as the only identity source has established the email address returned by Google OAuth as the primary user identifier. This creates a specific migration challenge when SAML SSO is added: the email addresses in the enterprise IdP may differ from the email addresses used during the pre-SSO trial period, requiring a user identity migration before the SSO integration can be activated for an existing account. A product that stores the provider's subject identifier (the stable, provider-issued user ID) alongside the email address from the beginning — and designs the session model around the subject identifier rather than the email address — can add a second provider without a user identity migration, because the user's identity anchor is the provider-issued ID, not the email. The decisions never written down in the authentication domain include not just which protocol to support but what field to use as the primary user identifier, whether the identifier should be migrateable without breaking existing sessions and associations, and at what customer size or deal stage SAML support will be prioritized. The new CTO onboarding problem in the identity domain is the incoming technical leader who asks "can we support SSO for the enterprise deal in the pipeline?" and discovers that the answer is "yes, but it requires a user identity migration for the twelve pilot users who signed up with personal accounts, and that migration needs to happen before the integration can go live" — which is the identity equivalent of "we know how to do it, but we didn't anticipate this path when we built the model, and the work is more complex than it looks." The authentication strategy decision record connects at the protocol selection layer: the choice between local credentials, social OAuth, and federated enterprise identity is not three separate decisions made sequentially — it is one decision about the authentication surface that should be made at founding with explicit acknowledgment of which enterprise requirements are deferred, what the migration path looks like when they are later needed, and what assumptions in the current model will need to change.

Property 2: The account lifecycle model and the stale access accumulation surface. In self-service B2B products used by teams, the lifecycle of individual user accounts is controlled by the employing organization, not the individual user. An employee who leaves their company should not retain access to their former employer's workspace — but without a mechanism for the organization to deactivate the account automatically, they do. The gap between the individual-user model (account lifecycle is user-controlled) and the enterprise-organization model (account lifecycle is IT-controlled) is the stale access surface. Every day an account exists beyond the user's employment tenure is a day that a former employee has access to company data, shared credentials, and internal documentation. The accumulation surface grows silently — no one sees the stale access until an access review or an audit makes it visible. The access control model decision record connects at the permission layer: the access control model specifies who can access what; the identity provider decision record specifies who has valid accounts and how those accounts are created and terminated; without an automated deprovisioning path, the access control model is accurate at the time of user creation but drifts from reality as accounts accumulate beyond their intended lifecycle. The multi-tenant data isolation decision record connects at the organizational boundary layer: stale accounts in multi-tenant products are not just individual access risks — they are organizational isolation risks; a former employee with a still-active account can access their former employer's tenant, which in a multi-tenant product means they can access data scoped to that organization rather than just their individual user data; the deprovisioning failure is not contained to the individual's own content. The audit log decision record connects at the accountability layer: an audit log of user session activity allows a SOC 2 auditor to scope the impact of a stale account — "this account was active but had not logged in during the eleven months since the user's employment ended" is a different risk exposure than "this account was active and was used to download data three times during the eleven months since the user's employment ended"; the first outcome supports a low-impact finding, the second requires breach notification analysis; without an audit log of user session activity, the scope of the stale access risk cannot be bounded and the worst-case impact must be assumed.

Property 3: The identity provider migration and the credential sprawl failure mode. An OAuth client ID issued at founding becomes a stable reference across every system that authenticates against the product. It appears in frontend code, in configuration files, in developer documentation, in community tools, in customer automation scripts, and in internal tooling built by engineers who may have left the company. When the authentication infrastructure migrates to a new identity provider, the old client ID is decommissioned — and every consumer of the old client ID breaks. The consumer list the product team can control is the first-party code. The consumer list the product team cannot control — and often cannot enumerate — is the ecosystem of integrations built against the public OAuth application over the product's lifetime. The secrets management decision record connects at the credential lifecycle layer: OAuth client IDs are not secrets in the cryptographic sense — the client ID is public — but they are credentials in the operational sense, and their lifecycle (issue, reference, rotate, decommission) requires the same management discipline as other credentials; a credential that cannot be safely decommissioned because it has accumulated unknown consumers is a credential with an open-ended lifetime, which creates a separate class of security risk from the immediate breakage of the decommission; the identity provider decision record must specify the credential lifecycle model, including the transition period during which old and new credentials are simultaneously valid and the inventory process that precedes a decommission. The compliance automation decision record connects at the integration ecosystem layer: SOC 2 vendor management controls require the company to know which external systems access its infrastructure and data; the third-party integration inventory maintained for vendor management is also the consumer inventory required for safe credential rotation; maintaining the integration inventory as a living document — updated when new integrations are built or discovered — makes credential rotations manageable rather than risky; the inventory that is assembled reactively at the moment of a migration is a worse version of the inventory that would have been maintained proactively throughout the product's lifetime. The WhyChose extractor finds the identity model discussions in your AI session history — the conversation where the first OAuth integration was built and someone asked what field to use as the user identifier, the thread where the first enterprise customer asked about SSO and the team had an informal discussion about whether to build SAML support or defer it, the exchange where the authentication migration was planned and someone noted that there were probably external integrations using the old client ID that would need to be accounted for — and surfaces those discussions so you can evaluate which identity model assumptions are still load-bearing as your customer base evolves from self-service individuals to enterprise organizations with IT governance requirements.

The identity provider ADR: five sections

Section 1: Authentication protocol selection and federation model. Specify the authentication protocols the product will support at launch and the criteria that will trigger adding new protocols. At founding, the realistic options are: local credentials (email and password, managed by the application); social OAuth (Google, GitHub, Microsoft — delegated to a third-party identity provider); or a managed identity platform (Auth0, Okta, Cognito — abstracts over multiple providers). Record the choice and the rationale: why this protocol, what it enables, what it defers, and what migration path exists when deferred requirements are later needed. Include in the federation model the primary user identifier — the field that will be used to uniquely identify a user across sessions, across provider migrations, and across team membership changes. If the primary identifier is the email address returned by the OAuth provider, record this explicitly, because this identifier choice is what makes a future provider migration a user identity migration rather than a session migration. Specify the conditions under which SAML 2.0 enterprise SSO will be prioritized: "SAML support will be built when the first enterprise deal with a SAML requirement is in the pipeline, or when the revenue at risk from lack of SAML support in the trailing 90 days exceeds $X." This gives the sales team a clear answer to enterprise SSO questions — "we have a documented threshold for prioritizing it, here's where we are against it" — and gives the engineering team a clear trigger for starting the work. Connect this section to the authentication strategy decision record, which covers the broader authentication surface including local credentials, password policy, and session management; the identity provider decision record covers the federation layer — which external providers are used for identity verification — while the authentication strategy decision record covers the full credential lifecycle.

Section 2: Account lifecycle model: provisioning, deprovisioning, and SCIM support. Specify how user accounts are created, modified, and deactivated, with explicit attention to the organizational case where the employing organization controls the lifecycle rather than the individual user. At founding, the account lifecycle is entirely user-driven: users create accounts, users change their email addresses, users delete their accounts. Record this as the founding model and specify the conditions under which the lifecycle model will be extended to organizational control: "SCIM provisioning will be built when the first enterprise customer requests it, or when the first SOC 2 audit finding involves stale account access." Include in this section the minimum SCIM implementation required for the organizational lifecycle use case: the three endpoints that cover the B2B offboarding case (GET /Users for access review, POST /Users for IT-provisioned account creation, PATCH /Users/{id} with active: false for deprovisioning). These three endpoints cover the auditor's user access review and the IT team's offboarding automation without requiring the full SCIM specification, which is a significantly larger implementation scope. Specify the interim deprovisioning path for customers who ask about offboarding before SCIM is built: "until SCIM is available, workspace admins can deactivate individual user accounts from the admin panel; enterprise customers with offboarding requirements should configure their HR process to include a step for the workspace admin to deactivate accounts of departing employees." Record this interim path explicitly so that support and sales teams have a consistent answer and so that the gap between the interim path (manual, requires a human step) and the full solution (automated SCIM) is visible in the decision record rather than implicit in the product's current behavior. Connect this section to the access control model decision record for the permission model that governs what active accounts can access, and to the audit log decision record for the session activity audit trail that bounds the impact of stale account access when it is discovered.

Section 3: Identity provider migration protocol and credential change management. Specify the migration protocol for changing identity providers before any migration is needed. The credential consumer inventory is the central artifact: a maintained list of all first-party and known third-party consumers of the OAuth client ID, including frontend applications, mobile apps, backend services, developer documentation examples, and any community or ecosystem tools that authenticate against the product's OAuth application. For first-party code, the inventory can be maintained by searching the codebase for the client ID string; for third-party consumers, the inventory requires proactive ecosystem management — a developer registration program, community monitoring, and documentation that specifies the credential lifecycle policy so that integration builders know to register their tools and monitor for credential change announcements. Specify the transition period: the minimum time during which both the old and new OAuth applications are simultaneously active, so that third-party integrations can migrate without immediate breakage. The transition period should be a minimum of 60 days for products with a public API or a developer community; longer for products with known integrations in regulated industries where migration timelines are governed by change management processes. Specify the decommission announcement: where credential change notices are published, what the minimum notice period is, and how integration owners can subscribe to receive notices. The absence of a credential lifecycle policy is what makes the third scenario above predictable — not unusual, not exceptional, but the likely outcome whenever an OAuth application is decommissioned without a consumer inventory and a transition period. Connect this section to the secrets management decision record for the broader credential lifecycle model that covers client secrets, API keys, and other credentials whose consumer inventory must also be maintained before rotation or decommission.

Section 4: Enterprise SSO integration model and supported flows. When SAML 2.0 or OIDC enterprise SSO is built, specify both the flows the integration supports and the flows it does not. The distinction between SP-initiated and IdP-initiated SSO is the most common source of enterprise integration failures that are diagnosed after the integration has been shipped: the SP-initiated flow is tested by the engineering team, passes, and is deployed; the enterprise IT administrator tests from the Okta dashboard using IdP-initiated flow and encounters a validation error or a blank screen. Document the testing protocol: both flows must be tested against a real enterprise IdP (Okta developer account, Azure AD test tenant, or the customer's own IdP in a sandbox configuration) before the integration is declared production-ready. Specify the user identifier matching model for existing accounts: when an enterprise user authenticates via SAML for the first time, how is their SAML identity matched to an existing account if one exists? The options are: match on email address (simplest, breaks when enterprise and personal email addresses differ), match on a provider-issued subject identifier mapped at SAML configuration time, or require explicit account linking via a one-time verification step. Record which model is used and why — this is the decision that determines whether a future enterprise integration requires a user identity migration or not. Specify the just-in-time provisioning model: whether a SAML authentication from a user who has no existing account creates an account automatically, requires an admin pre-provisioning step, or is rejected pending provisioning. The just-in-time provisioning model interacts with the SCIM model from section 2: if both are supported, specify which takes precedence when a user is provisioned by SCIM and then authenticates via SAML before their first login. Connect this section to the multi-tenant data isolation decision record for the organizational boundary model that governs which tenant's data a just-in-time provisioned user has access to based on their SAML identity attributes.

Section 5: Account recovery, emergency credentials, and break-glass access. Specify the account recovery model — what happens when a user loses access to their authentication provider — before the first account recovery request arrives. For products using only social OAuth, account recovery means the user must recover access to their OAuth provider account; the product has no recovery path independent of the provider. This is acceptable for consumer products but is a gap in B2B products where accounts hold organizational data: if an employee's Google account is compromised and locked by Google, the employee loses access to both their Google account and the product simultaneously, at the moment when they most need to retrieve their work. Specify whether the product will maintain a backup authentication path — an email-and-password option, a magic-link fallback, or an organizational admin override — and if so, under what conditions it is available and how it is secured against misuse as a bypass for the primary authentication. Specify the break-glass access model: how the engineering team can access a specific account's data in a genuine emergency (a customer emergency, a regulatory disclosure requirement, a security incident requiring forensic access to a specific user's activity) without the account owner's authentication. Break-glass access requires authorization controls, an audit trail, and a documented scope — access granted for a specific incident, by a named authorizer, for a defined time window. Without a documented break-glass model, emergency access is improvised — either not possible when genuinely needed, or possible through privileged database access that leaves no audit trail and has no authorization controls. Connect this section to the audit log decision record for the audit trail requirements that make break-glass access accountable rather than opaque, and to the compliance automation decision record for the SOC 2 logical access controls evidence that requires both the break-glass access model and the audit trail to be documented before the first audit covers a period during which break-glass access was used.

FAQ